Настройка 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