Налаштування Content Delivery API Umbraco

Налаштування Umbraco Content Delivery API

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

Базові endpoints

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 дні.