Настройка Content Delivery API Umbraco

Настройка Content Delivery API Umbraco

Content Delivery API появился в Umbraco 12 как встроенный headless-механизм. REST API только для чтения опубликованного контента. Версия 13 добавила Preview API для черновиков.

Включение

// 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}
GET /umbraco/delivery/api/v2/content/item/{path}
GET /umbraco/delivery/api/v2/content?filter=contentType:blogPost
GET /umbraco/delivery/api/v2/media

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]',
});

Фильтры и сортировка

// Фильтр по типу контента и дате
filter: 'contentType:blogPost,createDate>2024-01-01'

// Фильтр по тегу (если используется Umbraco Tags)
filter: 'contentType:blogPost,properties.tags:javascript'

// Сортировка
sort: 'createDate:desc'
sort: 'properties.sortOrder:asc'

// Expand для связанных элементов
expand: 'all'
expand: 'properties[heroImage,author]'

// Выборка конкретных полей
fields: 'properties[title,slug,excerpt,heroImage]'

Preview API

// Headers для Preview Mode
headers: {
  'Api-Key': process.env.UMBRACO_PREVIEW_API_KEY!,
  'Preview': 'true',
}

Кастомный Content Delivery Selector

// Расширение API через C# для фильтрации
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,
        };
    }
}

Next.js интеграция

// 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} />;
}

Настройка Content Delivery API с Next.js фронтендом — 1–2 дня.