שילוב API של Contentful: הגדרת CDA, CMA, CPA

הבלבול בין שלושת ממשקי ה-API של Contentful הוא הסיבה הנפוצה ביותר לכך שטיוטות מופיעות בסביבת הייצור או ששינויים של עורכים לא נשמרים. במשך יותר מ-5 שנות עבודה, המהנדסים שלנו ראו עשרות פרויקטים שבהם טוקן שגוי אחד עלה בשעות של דיבוג. בואו נבהיר כיצד להבחין בין ממשקי ה-Delivery, Management ו-Preview, ונספק קונפיגורציות מוכנות עבור Next.js ו-Node.js.

כיצד להבחין בין שלושת ממשקי ה-API של Contentful?

Content Delivery API (CDA) — גישת קריאה בלבד לתוכן שפורסם. כתובת בסיס: https://cdn.contentful.com. טוקן: delivery access token (קריאה בלבד, ניתן להכניס אותו למשתני סביבה). התגובות נשמרות במטמון CDN — זה מספק TTFB מתחת ל-100 אלפיות השנייה כאשר הוא מוגדר כראוי, מהיר פי 5 מאשר ללא מטמון. Content Preview API (CPA) — קריאה בלבד, אך כולל טיוטות (ערכים שלא פורסמו). כתובת בסיס: https://preview.contentful.com. טוקן: preview access token. משמש במצב Draft Mode / מצב תצוגה מקדימה של Next.js. לעולם אל תשתמשו בטוקן זה בסביבת הייצור — אחרת הציבור יראה מאמרים לא גמורים. Content Management API (CMA) — CRUD מלא. כתובת בסיס: https://api.contentful.com. טוקן: personal access token או OAuth. לעולם לא בשימוש בצד הלקוח. רק בסקריפטים של צד השרת, פאנלים ניהוליים ו-CI/CD.

כיצד לבחור את הטוקן עבור כל סביבה?

ב-.env.local, שמרו תמיד שלושה מפתחות: CONTENTFUL_ACCESS_TOKEN_DELIVERY, CONTENTFUL_ACCESS_TOKEN_PREVIEW ו-CONTENTFUL_MANAGEMENT_TOKEN. עבור סביבת הייצור, השתמשו רק ב-Delivery. עבור staging — Preview. Management — רק בסקריפטים מקומיים וב-CI.

כדי למנוע בלבול, צרו קבצים נפרדים .env.production ו-.env.staging. ב-CI/CD, הגדירו החלפת טוקן אוטומטית בהתבסס על שם הענף. זה מפחית את הסיכון לטעויות אנוש. הניסיון מראה: 90% מהתקלות ב-Contentful קשורות לטוקנים שגויים.

הגדרת לקוח

import { createClient } from 'contentful';

// Для продакшена
const deliveryClient = createClient({
  space: process.env.CONTENTFUL_SPACE_ID!,
  accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN!,
});

// Для превью (Next.js Draft Mode)
const previewClient = createClient({
  space: process.env.CONTENTFUL_SPACE_ID!,
  accessToken: process.env.CONTENTFUL_PREVIEW_TOKEN!,
  host: 'preview.contentful.com',
});

// Выбор клиента по флагу
export const getClient = (preview = false) => preview ? previewClient : deliveryClient;

Next.js Draft Mode + Preview API

// app/api/draft/route.ts
import { draftMode } from 'next/headers';
import { redirect } from 'next/navigation';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const secret = searchParams.get('secret');
  const slug = searchParams.get('slug');

  if (secret !== process.env.CONTENTFUL_PREVIEW_SECRET) {
    return new Response('Invalid token', { status: 401 });
  }

  draftMode().enable();
  redirect(`/blog/${slug}`);
}

// В компоненте страницы
import { draftMode } from 'next/headers';

export default async function BlogPost({ params }) {
  const { isEnabled } = draftMode();
  const client = getClient(isEnabled);
  const entry = await client.getEntries({
    content_type: 'blogPost',
    'fields.slug': params.slug,
  });
}

CMA: ניהול תוכן פרוגרמטי

import { createClient } from 'contentful-management';
const cmaClient = createClient({
  accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN!,
});
const space = await cmaClient.getSpace(process.env.CONTENTFUL_SPACE_ID!);
const env = await space.getEnvironment('master');
// Создание записи
const entry = await env.createEntry('blogPost', {
  fields: {
    title: { 'en-US': 'New Post' },
    slug: { 'en-US': 'new-post' },
  },
});
// Публикация
await entry.publish();

מדוע Preview API קריטי עבור עורכים?

ללא Preview API, עורך לא יכול לראות כיצד מאמר ייראה לפני הפרסום. הוא נאלץ לפרסם "בעיוורון" ולבטל שגיאות. בפרויקט אחד, יישמנו CPA והפחתנו את זמן הגהת התוכן ב-40%: עורכים ראו טיוטות ישירות בדומיין ה-staging באמצעות Draft Mode. בהשוואה לייצוא ידני, Preview API מפחית שגיאות פרסום פי 3.

אופטימיזציה של בקשות ל-Contentful API

כדי להימנע משאילתות N+1 ולהפחית זמן השהיה, השתמשו בפרמטרים import { createClient } from 'contentful'; // Для продакшена const deliveryClient = createClient({ space: process.env.CONTENTFUL_SPACE_ID!, accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN!, }); // Для превью (Next.js Draft Mode) const previewClient = createClient({ space: process.env.CONTENTFUL_SPACE_ID!, accessToken: process.env.CONTENTFUL_PREVIEW_TOKEN!, host: 'preview.contentful.com', }); // Выбор клиента по флагу export const getClient = (preview = false) => preview ? previewClient : deliveryClient; ו-// app/api/draft/route.ts import { draftMode } from 'next/headers'; import { redirect } from 'next/navigation'; export async function GET(request: Request) { const { searchParams } = new URL(request.url); const secret = searchParams.get('secret'); const slug = searchParams.get('slug'); if (secret !== process.env.CONTENTFUL_PREVIEW_SECRET) { return new Response('Invalid token', { status: 401 }); } draftMode().enable(); redirect(`/blog/${slug}`); } // В компоненте страницы import { draftMode } from 'next/headers'; export default async function BlogPost({ params }) { const { isEnabled } = draftMode(); const client = getClient(isEnabled); const entry = await client.getEntries({ content_type: 'blogPost', 'fields.slug': params.slug, }); } : import { createClient } from 'contentful-management'; const cmaClient = createClient({ accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN!, }); const space = await cmaClient.getSpace(process.env.CONTENTFUL_SPACE_ID!); const env = await space.getEnvironment('master'); // Создание записи const entry = await env.createEntry('blogPost', { fields: { title: { 'en-US': 'New Post' }, slug: { 'en-US': 'new-post' }, }, }); // Публикация await entry.publish(); . עבור Delivery API, הפעילו מטמון CDN (לדוגמה, Cloudflare) עם TTL של עד שעה — זה ישפר את ה-LCP ב-20%. עבור שאילתות תכופות, השתמשו ב-ISR revalidation ב-Next.js. בעבודה עם טיוטות דרך Draft Mode, עלול להתרחש חוסר התאמה בהידרציה — פתרון: סנכרון הטוקן וה-space בין השרת ללקוח.

טבלת הגדרות סביבות

בשגיאת 401, בדקו שהטוקן תואם לסביבה ולא פג תוקפו. עבור CMA, ודאו של-Personal Access Token יש הרשאות ל-space הנדרש.

תהליך הגדרה מלא

1. ניתוח: איסוף דרישות עבור שפות, סביבות וסוגי תוכן.
2. עיצוב: הגדרת סכמת טוקנים, middleware לבחירת API.
3. יישום: כתיבת לקוחות מבודדים עבור CDA, CPA, CMA.
4. בדיקות: אימות שכל טוקן עובד בסביבתו, ללא דליפת טיוטות לייצור.
5. פריסה: הגדרת CI/CD להחלפת טוקן אוטומטית במהלך קידום.

תיעוד רשמי של Contentful Delivery API.

ציר זמן: בין 3 ל-7 ימים בהתאם למורכבות הפרויקט. העלות מחושבת באופן אישי לאחר ביקורת על האינטגרציה הקיימת. חיסכון בזמן הגהת תוכן — עד 40%.

מה כלול בעבודה

• קוד מקור למודול הלקוח עבור CDA, CPA, CMA (TypeScript)
• תיעוד על משתני סביבה וטוקנים
• הגדרת Draft Mode לעורכים
• המרת שאילתות קיימות ללקוח החדש
• הדרכת צוות (שעה אונליין)
• תמיכה לחודש לאחר האינטגרציה