المطورون

ابدأ بكازا واحدة

أنشئ اتصالًا ومسودة كازا وعدّلها بأمان وانشرها، كل ذلك ببضعة طلبات.

يستخدم هذا الشرح REST API مع curl. تعمل كل خطوة بالطريقة نفسها عبر MCP، لأن كليهما يُولّد من فهرس عمليات واحد ويمر بفحوص الأذونات نفسها التي يستخدمها التطبيق.

أنشئ اتصالًا

سجّل الدخول وافتح المطورون في لوحة التحكم (لمالكي مساحة العمل ومديريها فقط) واختر اتصال جديد. اختر REST API واحتفظ بالخيارات الافتراضية للقراءة فقط (workspaces:read وcatalog:read وworlds:read) وأضف لهذا الشرح worlds:write وworlds:publish. يظهر الرمز مرة واحدة، لذا انسخه إلى مخزن أسرارك فورًا.

تعرض بطاقة المرجع في الصفحة نفسها عنوان REST الأساسي ونقطة نهاية MCP وعقد OpenAPI.

export BASE="https://<your host>/api/v1"
export TOKEN="sw_rest_..."

اعثر على مساحة عملك

ينتمي الرمز إلى مساحة عمل واحدة فقط. اعرضها للحصول على معرفها ودورك:

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces"
export WS="<data[0].id>"

ثم استعلم عما تستطيع مساحة العمل فعله الآن. توضح كل قدرة ما إذا كانت منفذة أو محاكاة أو متوقفة لنقص بيانات الاعتماد أو في انتظار قرار:

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/capabilities"

أنشئ مسودة كازا

اختر تصميمًا من الفهرس (GET /catalog/templates) ثم أنشئ مسودة. تتطلب كل كتابة Idempotency-Key بطول 16 إلى 128 حرفًا؛ وتعيد المحاولة بالمفتاح والمتن نفسيهما النتيجة الأصلية بدل إنشاء كازا ثانية.

curl -s -X POST "$BASE/workspaces/$WS/worlds" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"handle":"my-first-casa","template_id":"pizza",
       "profile":{"display_name":"My first casa","bio":"Hello from the API.","content_language":"en"}}'

عدّلها بأمان

اقرأ الكازا أولًا. يحمل الرد ترويسة ETag؛ أعد إرسالها بوصفها If-Match مع تغييرك. إذا عدّل شخص المسودة في هذه الأثناء، فستحصل على 412 revision_conflict ولن يتغير شيء.

curl -s -i -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/worlds/$WORLD"

curl -s -X PATCH "$BASE/workspaces/$WS/worlds/$WORLD" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H 'If-Match: W/"<etag>"' \
  -H "Content-Type: application/json" \
  -d '{"profile":{"bio":"Edited over the API."}}'

انشر وانتظر المهمة

يستخدم النشر draft_revision_id وdraft_digest الدقيقين من آخر قراءة، لتنشر ما فحصته. يجيب بالرمز 202 مع مهمة؛ وتبقى النسخة السابقة منشورة حتى ينجح البناء الجديد.

curl -s -X POST "$BASE/workspaces/$WS/worlds/$WORLD/publications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"revision_id":"<draft_revision_id>","expected_digest":"<draft_digest>"}'

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/jobs/$JOB"

لا تستطلع بوتيرة أسرع مما تحدده next_poll_after_seconds. تعيد المهمة بحالة completed قيمة canonical_url للصفحة المنشورة. فضّل خطاف ويب على الاستطلاع عندما يصبح لديك أكثر من بضع مهام.

إلى أين تتجه بعد ذلك

المصادقة ونطاقات الأذونات: الأذونات التي تحتاجها كل عملية.
MCP: اربط عميل وكيل بالعمليات نفسها.
مرجع API: الأعراف والأخطاء وعقد OpenAPI.

آخر تحديث: 10 نوفمبر 2026