Налаштування 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
- Увімкніть CDA в конфігурації як показано вище.
- Налаштуйте PublicAccess — для зовнішнього доступу встановіть
true. - Встановіть ApiKey (обов'язково для Preview API).
- Обмежте типи контенту через
DisallowedContentTypeAliases(при необхідності). - Перевірте індексацію — виконайте тестовий GET-запит до ендпоінту.
- Налаштуйте фільтри для часто використовуваних вибірок.
Гнучка фільтрація контенту
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]'. Усі параметри комбінуються в рядку запиту.
| Тип фільтра | Приклад | Опис |
|---|---|---|
| За типом контенту | contentType:blogPost |
Вибірка певних типів |
| За датою | createDate>2023-01-01 |
Фільтр за датою створення |
| За властивостями | properties.tags:javascript |
Фільтр за значенням властивості |
| За культурою | culture=en-US |
Для багатомовних сайтів |
Обсяг робіт з налаштування 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 з іншими підходами
| Критерій | Content Delivery API | GraphQL (через Content Service) | Кастомний REST |
|---|---|---|---|
| Швидкість (TTFB) | ~50ms (індекс Examine) | ~120ms (парсинг запиту) | ~80ms (прямі запити) |
| Підтримка | Вбудована, оновлюється з CMS | Через пакети Umbraco | Ручна реалізація |
| Гнучкість фільтрації | Стандартні фільтри + кастомні селектори | Повний GraphQL-запит | Будь-яка логіка |
| Простота налаштування | Мінімальна (конфіг) | Середня (схема, хуки) | Висока (написання контролерів) |
CDA виграє у швидкості та простоті — ідеально для типових Headless-проєктів. Content Delivery API швидший за GraphQL в 2.4 раза по TTFB (50ms vs 120ms).
Деталі налаштування для багатомовності
Якщо сайт багатомовний, в CDA потрібно враховувати культуру. Для цього в запит додається query-параметр culture (наприклад, ?culture=en-US). За замовчуванням API повертає контент для культури за замовчуванням. Також можна використовувати VariesByCulture в кастомних селекторах.
Типові помилки при налаштуванні CDA
- Відсутність ApiKey для Preview — без ключа Preview не працює.
- Неправильний формат фільтра — пробіли або зайві коми призводять до помилки 400.
- Забули ввімкнути PublicAccess — тоді API доступний лише локально.
- Не налаштували expand для пов'язаних медіа — замість URL прийдуть лише ID.
Наша команда гарантує, що всі ці нюанси будуть враховані. Замовте консультацію — ми допоможемо налаштувати CDA під ваш проєкт.
Джерело: Документація Umbraco CDA