Налаштування Umbraco Content Delivery API: конфігурація та інтеграція

Налаштування Content Delivery API Umbraco

Проблема: при спробі використовувати Umbraco як headless CMS розробники стикаються з відсутністю вбудованого REST API до версії 12. Content Delivery API вирішує це завдання — він повертає контент у форматі JSON зі швидкістю 50ms (у 2.4 раза швидше за GraphQL). Ми налаштовуємо його під ключ: від конфігурації до інтеграції з React, Next.js або Vue. За 1–2 дні отримуєте готовий headless-бекенд, який віддає опублікований контент через REST API лише для читання. Наш досвід — 5+ років і 15+ проєктів на Umbraco, включаючи великі новинні портали та інтернет-магазини. Економія трудовитрат: інтеграція CDA займає в 3 рази менше часу, ніж розробка власного REST API, а витрати на інфраструктуру знижуються до 30%. Зв'яжіться з нами для консультації — оцінимо ваш проєкт за один день.

Як налаштувати Content Delivery API в Umbraco?

Увімкнення CDA — це зміна одного файлу конфігурації. Потрібно додати блок Umbraco.CMS.DeliveryApi в appsettings.json:

{ "Umbraco": { "CMS": { "DeliveryApi": { "Enabled": true, "PublicAccess": true, "ApiKey": "your-api-key-for-preview", "DisallowedContentTypeAliases": [], "RichTextOutputAsJson": false, "Media": { "Enabled": true } } } } } 

Після ввімкнення стануть доступні базові endpoint'и:

• GET /umbraco/delivery/api/v2/content — список контенту
• GET /umbraco/delivery/api/v2/content/item/{id} — за ID
• GET /umbraco/delivery/api/v2/content/item/{path} — за шляхом
• GET /umbraco/delivery/api/v2/content?filter=contentType:blogPost — з фільтром
• GET /umbraco/delivery/api/v2/media — медіафайли

Покрокове налаштування CDA

1. Увімкніть CDA в конфігурації як показано вище.
2. Налаштуйте PublicAccess — для зовнішнього доступу встановіть true.
3. Встановіть ApiKey (обов'язково для Preview API).
4. Обмежте типи контенту через DisallowedContentTypeAliases (при необхідності).
5. Перевірте індексацію — виконайте тестовий GET-запит до ендпоінту.
6. Налаштуйте фільтри для часто використовуваних вибірок.

Гнучка фільтрація контенту

CDA підтримує гнучку фільтрацію. Наприклад: contentType:blogPost,createDate>2023-01-01 поверне пости блогу після зазначеної дати. Фільтр properties.tags:javascript відфільтрує за тегом. Також доступне сортування: sort: 'createDate:desc' або sort: 'properties.sortOrder:asc'. Параметр expand дозволяє підвантажити пов'язані елементи: expand: 'properties[heroImage,author]'. Fields обмежує повернуті поля: fields: 'properties[title,slug]'. Усі параметри комбінуються в рядку запиту.

Обсяг робіт з налаштування Headless-рішення

Ми надаємо готовий набір робіт, який покриває повний цикл:

• Діагностика поточної конфігурації Umbraco
• Увімкнення та налаштування CDA (включаючи Preview API)
• Розробка TypeScript-клієнта для фронтенду
• Інтеграція з обраним фреймворком (Next.js, Vue, React)
• Налаштування фільтрів, сортування та expand для пов'язаних елементів
• Створення кастомних селекторів для індексації (якщо потрібно)
• Документація по всіх endpoint'ах і фільтрах
• Підтримка протягом місяця після запуску

Типовий TypeScript-клієнт

const UMBRACO_URL = process.env.UMBRACO_URL!; async function getContent(params: { filter?: string; sort?: string; take?: number; skip?: number; expand?: string; fields?: string; }) { const query = new URLSearchParams(); if (params.filter) query.set('filter', params.filter); if (params.sort) query.set('sort', params.sort); if (params.take) query.set('take', String(params.take)); if (params.skip) query.set('skip', String(params.skip)); if (params.expand) query.set('expand', params.expand); if (params.fields) query.set('fields', params.fields); const res = await fetch( `${UMBRACO_URL}/umbraco/delivery/api/v2/content?${query}`, { next: { revalidate: 3600 } } ); return res.json(); } // Отримання постів блогу const { items, total } = await getContent({ filter: 'contentType:blogPost', sort: 'createDate:desc', take: 12, expand: 'properties[author,categories]', }); 

Фільтри комбінуються через кому. Приклади:

• contentType:blogPost,createDate>2023-01-01
• contentType:blogPost,properties.tags:javascript
• Сортування: sort: 'createDate:desc' або sort: 'properties.sortOrder:asc'
• Expand: expand: 'all' або expand: 'properties[heroImage,author]'
• Fields: fields: 'properties[title,slug,excerpt,heroImage]'

Як працює Preview API для редакторів?

Для перегляду чернеток використовується Preview API. У заголовки запиту додаються:

• Api-Key — ключ з конфігурації
• Preview: true

Це дозволяє редакторам бачити неопубліковані зміни до публікації. Без ключа Preview API недоступний.

Створення кастомних селекторів

Якщо стандартної фільтрації недостатньо, можна розширити API через C#. Наприклад, додати поле publishedDate для сортування:

using Umbraco.Cms.Core.DeliveryApi; public class PublishedDateSelector : IContentIndexHandler { public IEnumerable<IndexFieldValue> GetFieldValues(IContent content, string? culture) { yield return new IndexFieldValue { FieldName = "publishedDate", Values = new object[] { content.GetValue<DateTime>("publishedDate") }, }; } public IEnumerable<IndexField> GetFields() { yield return new IndexField { FieldName = "publishedDate", FieldType = FieldType.Date, VariesByCulture = false, }; } } 

Після реєстрації селектора в DI поле publishedDate стане доступним для сортування та фільтрації через API.

Інтеграція з Next.js (App Router)

// app/blog/page.tsx export const revalidate = 3600; export default async function BlogPage() { const { items, total } = await getContent({ filter: 'contentType:blogPost', sort: 'createDate:desc', take: 12, expand: 'properties[heroImage]', }); return <BlogGrid posts={items} total={total} />; } 

Для статичної генерації (SSG) використовуйте generateStaticParams з async запитом до CDA для отримання списку маршрутів.

Порівняння CDA з іншими підходами

CDA виграє у швидкості та простоті — ідеально для типових Headless-проєктів. Content Delivery API швидший за GraphQL в 2.4 раза по TTFB (50ms vs 120ms).

Типові помилки при налаштуванні CDA

• Відсутність ApiKey для Preview — без ключа Preview не працює.
• Неправильний формат фільтра — пробіли або зайві коми призводять до помилки 400.
• Забули ввімкнути PublicAccess — тоді API доступний лише локально.
• Не налаштували expand для пов'язаних медіа — замість URL прийдуть лише ID.

Наша команда гарантує, що всі ці нюанси будуть враховані. Замовте консультацію — ми допоможемо налаштувати CDA під ваш проєкт.

Джерело: Документація Umbraco CDA