ربط موقع بواجهة برمجة تطبيقات نظام إدارة المحتوى
تتيح لك واجهة برمجة تطبيقات نظام إدارة المحتوى (CMS) لموقعك جلب المحتوى المنشور من Profound CMS وعرضه. يمكنك استخدامها لتشغيل صفحات التوثيق، وصفحات التسويق، والمدونات، ومراكز المساعدة، أو أي تجربة أخرى تعتمد على المحتوى.
يتكون التكامل النموذجي من ثلاثة أجزاء:
لربط تطبيقك بنظام إدارة المحتوى، قدّم عنوان واجهة برمجة تطبيقات CMS، ومعرّف موقع الويب، ومفتاح واجهة البرمجة.
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
لا تُفصح عن مفاتيح واجهة البرمجة الخاصة في شفرة الواجهة الأمامية. يجب استخدام مفاتيح الواجهة على الخادم لديك، في عملية البناء، أو في مسارات الواجهة الخلفية.
يُنظَّم المحتوى في نظام إدارة المحتوى وفق المخططات. على سبيل المثال، قد يحتوي مشروعك على مخططات مثل 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');
بالنسبة إلى المواقع التي تستخدم صفحات يديرها نظام إدارة المحتوى، يمكنك جلب المحتوى استنادًا إلى مسار عنوان 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,
};
}
يمكنك استخدام الكتل المعادة لعرض الصفحة باستخدام نظام المكونات في تطبيقك.
المحتوى المنشور في نظام إدارة المحتوى آمن للتخزين المؤقت. بالنسبة لمعظم المواقع، خزّن استجابات واجهة البرمجة مؤقتًا لفترة قصيرة وأعد التحقق منها عند تغيّر المحتوى.
إعداد شائع هو:
const content = await cache(
() => cms.schema('post').fetchAll(),
{
revalidate: 60,
tags: ['cms-posts'],
}
);
سلوك التخزين المؤقت الموصى به:
يتيح وضع المعاينة للمحررين رؤية التغييرات غير المنشورة قبل نشرها.
نمط شائع هو استخدام مسار معاينة منفصل، على سبيل المثال:
/docs/getting-started
/cms-preview/docs/getting-started
يجب أن تجلب صفحات الإنتاج المحتوى المنشور فقط. يمكن لصفحات المعاينة قبول معلمات المعاينة، مثل:
?edit_mode=true
يُفترض عادةً أن تكون مسارات المعاينة ديناميكية وألا تُخزَّن بشكل ساكن في الذاكرة المؤقتة.
قد لا يتوفر محتوى نظام إدارة المحتوى أثناء عملية البناء أو أثناء الطلب. يجب أن يتعامل تطبيقك مع هذا الأمر بسلاسة.
السلوك الموصى به:
404 عندما لا يكون المسار موجودًا.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;
}
}
حافظ على خصوصية مفاتيح واجهة البرمجة واستخدمها على الخادم فقط. لا تدرج بيانات اعتماد خاصة في حزم المتصفح أو في JavaScript العام.
استخدم متغيرات بيئة عامة فقط للقيم غير الحساسة مثل:
استخدم متغيرات بيئة خاصة لـ:
استخدم واجهة برمجة تطبيقات نظام إدارة المحتوى عندما يحتاج موقعك إلى جلب محتوى منظم، أو عرض مسارات يديرها النظام، أو دعم سير عمل المعاينة للمحرر.
يجب أن يتضمن التكامل القياسي ما يلي: