Skip to Content
توثيق المطورين

استدعاء API المحتوى العام

قراءة المحتوى المنشور عبر API v1 مع تقسيم الصفحات واللغة البديلة والنشر headless.

استدعاء API المحتوى العام

استخدم API العام لواجهة خارجية أو نظام يستهلك المحتوى. لا تحتاج المدخلات المنشورة مفتاح API. تُخفى المسودات والأرشيفات وتبقى التعديلات اللاحقة خاصة حتى النشر.

اختيار المعرّفات ونقاط الاتصال

اضبط QOKIT_API_URL على أصل API أو التثبيت، وQOKIT_PROJECT_SLUG على slug المشروع، وQOKIT_COLLECTION_KEY على مفتاح المجموعة. تستخدم هذه المسارات slugs ومفاتيح؛ تستخدم الإدارة معرّفات الموارد.

GET /v1/projects/slug/{slug}/cms/collections/{collectionKey}/entries?locale=en&page=1&pageSize=24
GET /v1/projects/slug/{slug}/cms/collections/{collectionKey}/entries/{entrySlug}?locale=en
GET /v1/projects/slug/{slug}/runtime?locale=en

قراءة جميع الصفحات ومدخل واحد

نزّل العميل وفق الإعداد في استخدام API الموقع / CMS.

import { createSiteApiClient } from './sdk/client.mjs';

const api = createSiteApiClient({ baseUrl: process.env.QOKIT_API_URL });
const projectSlug = process.env.QOKIT_PROJECT_SLUG;
const collectionKey = process.env.QOKIT_COLLECTION_KEY;
const entries = [];
let page = 1;
let result;
do {
  result = await api.publicEntries(projectSlug, collectionKey, {
    locale: 'en', page, pageSize: 24
  });
  entries.push(...result.entries);
  page++;
} while (page <= result.totalPages);

if (entries.length) {
  const detail = await api.publicEntry(projectSlug, collectionKey, entries[0].slug, {
    locale: result.locale
  });
  console.log(detail.entry.title);
}
console.log(entries.length, result.locale, result.localeFallback);

فهم الاستجابة

تعيد القوائم entries وpage وpageSize وtotal وtotalPages؛ والتفاصيل تعيد entry. الحجم الافتراضي 24 والأقصى 100. الصفحة الأولى لا تشمل المجموعة كلها.

استخدم locale المعاد للروابط. يتضمن localeFallback الحقول requestedLocale وresolvedLocale وusedFallback. الترتيب: اللغة الإقليمية ثم الأساسية ثم افتراضية المشروع ثم الإنجليزية. يعتمد الحقل العلوي requestedLocale على النشر.

راجع العقد للحقول search وcategory وbrand وminPrice وmaxPrice وfeatured وsort؛ يعتمد تطبيقها على المجموعة. fieldQuery المتحقق منه امتداد للمنصة، وتعيد التثبيتات المستقلة 400 عند استخدامه.

النشر والأصول والتوافق

يقرأ runtime العام للمنصة إصدار الموقع المنشور. يدعم CMS-managed وCMS-only قراءة المحتوى العام الحالي. يحتوي site-only على HTML وموارد ثابتة فقط، دون API للمحتوى. لا يحتوي CMS-only عارض موقع. لا تضع مفتاح إدارة في كود الواجهة.

تبقى مسارات المنصة /projects/slug/{slug} متاحة. تبقى المسارات المستقلة /api/content/collections/{collectionKey}/entries متاحة مع بيانات متداخلة داخل pagination. تستخدم التكاملات الجديدة v1 وعقد OpenAPI.

تعامل مع 404 للمحتوى المنشور المفقود و400 للمرشحات غير الصحيحة. عند 429 التزم بـ Retry-After. اضبط أصول الواجهة المسموحة وفق دليل الإدارة.

للمصادقة وCORS والكتابة واختلافات النشر، راجع استخدام API الموقع / CMS.

هل كان هذا الدليل مفيداً؟

آخر تحديث في

في هذه الصفحة