Налаштування 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