Delivery API

Delivery API هي الطريقة التي يقرأ بها موقعك المحتوى المنشور. استدعِها من شيفرة الخادم فقط.

عنوان URL الأساسي والمصادقة

https://<delivery host>/v1/delivery/environments/{environmentId}
Authorization: PublishedConsumer <delivery token>

• ينتمي كل رمز إلى بيئة واحدة. للتطوير والإنتاج رمزان منفصلان.
• الرموز من 43 حرفًا عشوائيًا، تُعرض مرة واحدة، وصالحة من يوم إلى 365 يومًا، ويمكن إلغاؤها في أي وقت في Studio. ويخزّن Atlas بصمة فقط.
• يقرأ رمز الإنتاج الإصدار الحي لتلك البيئة فقط.

التخزين المؤقت

تحمل الاستجابات المنشورة:

Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300
ETag: W/"…"
X-Atlas-Content-Version: …
Vary: Authorization, Accept-Encoding

أرسل If-None-Match مع آخر ETag؛ فيردّ Atlas بـ304 Not Modified عندما لا يتغير شيء. اجمع ذلك مع webhooks للتحديث عند النشر. استجابات المعاينة والنشر هي private, no-store.

نقاط النهاية

GET /site

البيئة، وإصدارها الحي (في الإنتاج)، ونسخة المحتوى، وبصمة العقد النشط (digest) ونسخته.

GET /routes

كل مسار منشور، لخريطة موقعك والتوليد الثابت: route وpageType وentryId وtitle وlastModified وnoindex وlocales. حتى 5,000 مسار.

GET /pages?route=/about&locale=en

صفحة منشورة واحدة.

الحقل	المحتوى
page	id وroute وtitle وpageType وpublishedAt وentryId
document	pageType وpageFields وregions: كل منطقة قائمة مرتبة من الأقسام
document.regions[key][n]	id وcomponent { id, version } وprops وhidden
entry	العنصر المرتبط بالصفحة، إن كان لنوع صفحتها عنصر
seo	title وdescription وnoindex وstructuredDataType وcanonicalPath وfaq
head	title وmeta[] وlinks[] وjsonLd[] جاهزة للطباعة، أو null مع headProblem
assets	كل صورة تستخدمها الصفحة، بمعرّف الأصل: url وrenditions وalt وfocalPoint
locale, direction, translation, alternates	لغة الاستجابة، وltr/rtl، وهل كانت الترجمة مفقودة، واللغات الأخرى
etag	ETag للمراجعة

404 عندما لا يوجد شيء منشور في ذلك المسار. تخطَّ الأقسام التي تكون فيها hidden صحيحة. انظر البحث وإجابات الذكاء الاصطناعي لاستخدام head.

GET /preview/pages?token=…&locale=en

صفحة مسودة لرابط معاينة. للتطوير فقط (404 في الإنتاج). لا تخزّنها مؤقتًا أبدًا. 403 PREVIEW_INVALID لرمز غير صالح، و410 PREVIEW_EXPIRED بعد 15 دقيقة.

GET /entries?collection=projects

عناصر مجموعة.

المعامل	مثال	ملاحظات
collection	projects	مطلوب
locale	ar
filter	category:water,featured:true	أزواج field:value مفصولة بفواصل
sort	-publishedAt, title, slug, featured, field.year	البادئة - للترتيب التنازلي
fields	title,slug,image	إعادة هذه الحقول فقط
limit	20	حتى 100. اضبطه دائمًا؛ فبدونه قد تكون الاستجابة كبيرة
page	2

تعيد entries وassets وmeta.pagination.

GET /feed?collection=news&limit=20

أحدث عناصر مجموعة تحريرية، لـRSS وقوائم الأخبار. 404 FEED_NOT_EDITORIAL للمجموعات الأخرى.

GET /globals?locale=en

المحتوى المشترك مثل site-header وsite-footer: { globals: { key: { data, revision, publishedAt } }, assets }.

GET /redirects

{ redirects: [{ from, to, status }] }. طبّقها في middleware لديك أو في إعادات التوجيه ضمن next.config.

GET /media/{assetId}?rendition=…

يعيد التوجيه (302) إلى رابط صورة موقّع صالح لمدة 15 دقيقة. لا يحتاج إلى رمز، فيمكنك استخدامه في <img src>.

GET /sitemap.xml وGET /robots.txt وGET /llms.txt

ملفات لجذر موقعك، تُبنى من الإصدار الحي (الإنتاج) أو تكون مقفلة (التطوير: خريطة موقع فارغة، وDisallow: /، وX-Robots-Tag: noindex, nofollow). مرّرها من نطاقك الخاص لتبقى الرموز على خادمك؛ انظر البحث وإجابات الذكاء الاصطناعي. 409 SITE_ADDRESS_MISSING إلى أن يكون للبيئة عنوان موقع.

الإبلاغ عن نشر

POST /deployments، يستدعيه موقعك عند بدء تشغيله:

{
  "bundleDigest": "<sha256 hex of the contract bundle this build renders>",
  "bundleVersion": "1.4.0",
  "commit": "a1b2c3d",
  "components": [{ "id": "acme.home.hero", "version": "1.0.0" }],
  "runtime": "node",
  "siteOrigin": "https://dev.example.com"
}

قيمة state في الاستجابة هي in-sync أو missing-components أو different-contract أو unknown-contract أو no-contract، مع البصمة النشطة وأي مكوّنات مفقودة. وruntime هو node أو cloudflare-workers. حتى 500 مكوّن.

الأخطاء

الأخطاء JSON برمز code ثابت. انظر الحدود والأخطاء.