הגדרת Umbraco Content Delivery API: התקנה ואינטגרציה

הגדרת Umbraco Content Delivery API

בעיה: כאשר מנסים להשתמש ב-Umbraco כ-CMS headless, מפתחים נתקלים בהיעדר REST API מובנה עד גרסה 12. ה-Content Delivery API פותר זאת—הוא מחזיר תוכן בפורמט JSON במהירות של 50ms (פי 2.4 מהר יותר מ-GraphQL). אנו מגדירים אותו turnkey: מהקונפיגורציה ועד אינטגרציה עם React, Next.js או Vue. תוך 1–2 ימים מקבלים backend headless מוכן שמשרת תוכן שפורסם דרך REST API לקריאה בלבד. המתודולוגיה המוכחת שלנו, שבה סומכים למעלה מ-50 לקוחות, מבטיחה אספקה אמינה. הניסיון שלנו: 5+ שנים ו-15+ פרויקטים על Umbraco, כולל פורטלי חדשות גדולים ואתרי מסחר אלקטרוני. אינטגרציית CDA אורכת פי 3 פחות זמן מאשר פיתוח REST API מותאם אישית, ועלויות התשתית יורדות בעד 30%. לקוחות בדרך כלל חוסכים €4,000–€6,000 בשנה על אחסון ופיתוח. צרו קשר לייעוץ—נעריך את הפרויקט שלכם תוך יום אחד.

כיצד להגדיר 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
      }
    }
  }
} }

לאחר ההפעלה, נקודות קצה בסיסיות הופכות לזמינות:

• { "Umbraco": { "CMS": { "DeliveryApi": { "Enabled": true, "PublicAccess": true, "ApiKey": "your-api-key-for-preview", "DisallowedContentTypeAliases": [], "RichTextOutputAsJson": false, "Media": { "Enabled": true } } } } } — רשימת תוכן
• 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 — קבצי מדיה

הגדרת CDA שלב אחר שלב

1. הפעלת CDA בקונפיגורציה כפי שמוצג לעיל.
2. הגדרת GET /umbraco/delivery/api/v2/media ל-true לגישה חיצונית.
3. הגדרת DisallowedContentTypeAliases (נדרש עבור Preview API).
4. הגבלת סוגי תוכן דרך contentType:blogPost,createDate>2023-01-01 אם נדרש.
5. אימות אינדוקס—הרצת בקשת GET לבדיקה לנקודת הקצה.
6. הגדרת פילטרים לשאילתות נפוצות.

סינון תוכן גמיש

CDA תומך בסינון גמיש. לדוגמה: properties.tags:javascript מחזיר פוסטים בבלוג אחרי התאריך שצוין. הפילטר sort: 'createDate:desc' מסנן לפי תגית. מיון זמין גם כן: sort: 'properties.sortOrder:asc' או expand. הפרמטר expand: 'properties[heroImage,author]' טוען פריטים קשורים: fields: 'properties[title,slug]'. contentType:blogPost מגביל שדות שמוחזרים: createDate>2023-01-01. כל הפרמטרים משולבים במחרוזת השאילתה.

היקף העבודה להגדרת Headless

אנו מציעים סט עבודות מלא המכסה את כל המחזור:

• אבחון קונפיגורציית Umbraco הנוכחית
• הפעלה והגדרה של CDA (כולל Preview API)
• פיתוח קליינט TypeScript לפרונטאנד
• אינטגרציה עם הפריימוורק הנבחר (Next.js, Vue, React)
• הגדרת פילטרים, מיון ו-expand לפריטים קשורים
• יצירת selectors מותאמים אישית לאינדוקס (אם נדרש)
• תיעוד לכל נקודות הקצה והפילטרים
• חודש תמיכה לאחר ההשקה

קליינט 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,properties.tags:javascript
• sort: 'createDate:desc'
• מיון: sort: 'properties.sortOrder:asc' או expand: 'all'
• Expand: expand: 'properties[heroImage,author]' או fields: 'properties[title,slug,excerpt,heroImage]'
• שדות: Api-Key

כיצד Preview API עובד עבור עורכים?

לצפייה בטיוטות, השתמשו ב-Preview API. הוסיפו את הכותרות האלה לבקשה:

• Preview: true—המפתח מהקונפיגורציה
• publishedDate

זה מאפשר לעורכים לראות שינויים שלא פורסמו לפני הפרסום. ללא המפתח, ה-Preview API אינו נגיש.

יצירת Selectors מותאמים אישית

אם סינון סטנדרטי אינו מספיק, ניתן להרחיב את ה-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, }; } } למיון:

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

לאחר רישום ה-selector ב-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), השתמשו ב-// 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} />; } עם בקשה אסינכרונית ל-CDA כדי לקבל את רשימת הנתיבים.

השוואת CDA לגישות אחרות

CDA מנצח במהירות ובפשטות—אידיאלי לפרויקטים headless טיפוסיים. הלקוחות שלנו מדווחים על 99.9% זמינות עם CDA. Content Delivery API מהיר פי 2.4 מ-GraphQL ב-TTFB (50ms לעומת 120ms).

טעויות נפוצות בהגדרת CDA

• חסר ApiKey ל-Preview—ללא המפתח, Preview לא עובד.
• פורמט פילטר שגוי—רווחים או פסיקים מיותרים מובילים לשגיאת 400.
• שכחת הפעלת PublicAccess—אז ה-API נגיש רק מקומית.
• אי הגדרת expand למדיה קשורה—במקום URLs, מוחזרים רק מזהים.

הצוות שלנו מבטיח שכל הניואנסים האלה מטופלים. צרו קשר לייעוץ—נעזור להגדיר CDA לפרויקט שלכם.

מקור: תיעוד Umbraco CDA