חיבור-אתר-ל-API-של-CMS

ממשק ה-API של ה-CMS מאפשר לאתר שלך להביא ולהציג תוכן שפורסם מ-Profound CMS. ניתן להשתמש בו כדי להפעיל דפי תיעוד, דפי שיווק, בלוגים, מרכזי עזרה או כל חוויית תוכן אחרת.

האינטגרציה הטיפוסית כוללת שלושה חלקים:

1. הגדרת החיבור ל-CMS שלך
2. משיכת תוכן שפורסם
3. הצגת התוכן ביישום שלך

תצורה

כדי לחבר את היישום שלך ל-CMS, ספק את כתובת ה-URL של ה-API של ה-CMS, מזהה האתר ומפתח ה-API.

const cmsConfig = {
  cmsUrl: 'https://cms.dev.tryprofoun.com',
  websiteId: 'your-website-id',
  apiKey: process.env.PROFOUND_API_KEY,
};

השתמש במשתני סביבה עבור ערכים שמשתנים בין סביבות:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=your-website-id
PROFOUND_API_KEY=your-api-key

אל תחשוף מפתחות API פרטיים בקוד צד הלקוח. יש להשתמש במפתחות API בשרת שלך, בתהליך הבנייה שלך או בנתיבי ה-backend שלך.

משיכת תוכן

התוכן ב-CMS מאורגן לפי סכימה. לדוגמה, ייתכן שלפרויקט שלך יש סכימות כגון post, category, page או section.

השתמש בשם הסכימה כדי למשוך תוכן:

const posts = await cms.schema('post').fetchAll();

כדי למשוך מסמך בודד לפי מזהה:

const post = await cms.schema('post').fetchSingleById('document-id');

כדי למשוך תוכן מתורגם, בקש את הגרסה המתורגמת של הסכימה:

const frenchPost = await cms
  .schema('post')
  .translation('fr')
  .fetchSingleById('document-id');

עיבוד נתיבים

עבור אתרים המשתמשים בדפים שמנוהלים על ידי ה-CMS, ניתן למשוך תוכן על בסיס נתיב ה-URL הנוכחי.

const route = await cms.route.getByPath({
  websiteId: 'your-website-id',
  path: '/docs/getting-started',
});

תגובת הנתיב מזהה את הדף ואת הבלוקים שיש לעבד. היישום שלך יכול לאחר מכן למשוך את הבלוקים ולעבד אותם באמצעות הרכיבים שלך.

const blocks = await cms.block.getByIds({
  websiteId: 'your-website-id',
  ids: route.blockIds,
});

דוגמה: עיבוד דף תיעוד

async function getDocsPage(path: string) {
  const route = await cms.route.getByPath({
    websiteId: process.env.WEBSITE_ID,
    path,
  });

  const blocks = await cms.block.getByIds({
    websiteId: process.env.WEBSITE_ID,
    ids: route.blockIds,
  });

  return {
    title: route.label,
    path: route.path,
    blocks,
  };
}

באפשרותך להשתמש בבלוקים שהוחזרו כדי לעבד את הדף באמצעות מערכת הרכיבים של היישום שלך.

מטמון

תוכן ה-CMS שפורסם בטוח לאחסון במטמון. עבור רוב האתרים, אחסן במטמון תגובות API לפרק זמן קצר ואמת אותן מחדש כאשר התוכן משתנה.

הגדרה נפוצה היא:

const content = await cache(
  () => cms.schema('post').fetchAll(),
  {
    revalidate: 60,
    tags: ['cms-posts'],
  }
);

התנהגות מטמון מומלצת:

• אחסן במטמון קריאות שפורסמו.
• השתמש בחלונות מטמון קצרים יותר עבור תוכן שמתעדכן לעיתים קרובות.
• השתמש בתגי מטמון אם המסגרת שלך תומכת בביטול לפי דרישה.
• הימנע מאחסון במטמון של תוכן תצוגה מקדימה או טיוטה.

מצב תצוגה מקדימה

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

דפוס נפוץ הוא להשתמש בנתיב תצוגה מקדימה נפרד, לדוגמה:

/docs/getting-started
/cms-preview/docs/getting-started

דפי פרודקשן צריכים למשוך תוכן שפורסם בלבד. דפי תצוגה מקדימה יכולים לקבל פרמטרים של תצוגה מקדימה, כגון:

?edit_mode=true

נתיבי תצוגה מקדימה צריכים בדרך כלל להיות דינמיים ולא להישמר במטמון סטטי.

טיפול בשגיאות

ייתכן שתוכן ה-CMS לא יהיה זמין במהלך בנייה או בקשה. היישום שלך צריך להתמודד עם זה באופן חינני.

התנהגות מומלצת:

• להחזיר 404 כאשר נתיב לא קיים.
• להחזיר רשימה ריקה כאשר לא ניתן לטעון תוכן ניווט אופציונלי.
• לרשום ביומן שגיאות משיכה בצד השרת.
• להימנע מחשיפה של שגיאות API פנימיות למבקרים.

דוגמה:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Failed to fetch CMS post', error);
    return null;
  }
}

אבטחה

שמור על מפתחות ה-API פרטיים והשתמש בהם רק בצד השרת. אל תכלול אישורי גישה פרטיים בחבילות דפדפן או ב-JavaScript ציבורי.

השתמש במשתני סביבה ציבוריים רק עבור ערכים שאינם רגישים כגון:

• כתובת URL ציבורית של ה-CMS
• מזהה אתר
• תצורת שפה

השתמש במשתני סביבה פרטיים עבור:

• מפתחות API
• אסימוני תצוגה מקדימה
• אישורי מנהל
• סודות פריסה

סיכום

השתמש ב-API של ה-CMS כאשר האתר שלך צריך למשוך תוכן מובנה, לעבד נתיבים המנוהלים על ידי ה-CMS או לתמוך בתהליכי תצוגה מקדימה לעורכים.

אינטגרציה סטנדרטית צריכה:

• להגדיר את כתובת ה-CMS, מזהה האתר ומפתח ה-API.
• למשוך מסמכים לפי סכימה.
• למשוך דפים לפי נתיב.
• לעבד בלוקים של CMS באמצעות הרכיבים שלך.
• לאחסן במטמון תוכן שפורסם.
• לשמור על תוכן התצוגה המקדימה דינמי.
• לשמור אישורים פרטיים בשרת.