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