HTTP API

يقدم Asset Core واجهات برمجة التطبيقات HTTP من خلال خادمين: خادم الكتابة للالتزامات وخادم القراءة للاستعلامات. تحافظ هذه الفصلية على تحديد الكتابات وسرعة القراءة مع الحفاظ على مصدر واحد للحقيقة.

نظرة عامة

واجهة برمجة التطبيقات (API) تعتمد على REST مع حمولات JSON ومصادقة باستخدام رمز الحامل الإلزامي. كلا الخادمين يوفران نقاط نهاية صحية للمراقبة، وتشتمل الاستجابات على بيانات تعريفية عن الحداثة حيثما كان ذلك مناسبًا. تلخص هذه الصفحة مساحة السطح بينما يوفر مرجع OpenAPI العقد الكامل.

جميع نقاط بيانات API تحت نطاقات /v1/write/namespaces/{namespace_id} و /v1/read/namespaces/{namespace_id}. تعتبر النطاقات حدود العزل، لذا يجب تضمين النطاق الصحيح في كل طلب.

المواصفات الكاملة متاحة في OpenAPI reference.

الهيكل

التحكم في الطائرة الخاصة بالمصادقة والمساحة الاسمية

تتيح هذه النقاط للمشغلين فحص الجهات الرئيسية، وتعداد الأذونات، وإدارة بيانات التعريف الخاصة بالمساحة. استخدمها لعمليات الحوكمة وللتحقق من الوصول قبل إرسال الالتزامات.

الطريقة	المسار	الوصف
GET	/v1/write/auth/whoami	فحص الشخص الحالي
GET	/v1/write/auth/permissions	قائمة الأذونات للتوكن الحالي
GET	/v1/write/namespaces	قائمة المساحات
GET	/v1/write/namespaces/{namespace_id}	جلب تفاصيل المساحة
GET	/v1/write/namespaces/changes	استعلام عن تغييرات المساحة
GET	/v1/write/namespaces/status	قائمة لقطات حالة المساحة
GET	/v1/write/namespaces/{namespace_id}/status	الحصول على حالة المساحة
POST	/v1/write/namespaces/{namespace_id}/lifecycle	توفير أو حذف مساحة
POST	/v1/write/namespaces/{namespace_id}/operational_state	تعيين وضع التشغيل للمساحة
POST	/v1/write/namespaces/{namespace_id}/placement	تحديث بيانات التوزيع
POST	/v1/write/namespaces/fork_from_snapshot	إنشاء نسخة من مساحة من لقطة

نقاط نهاية الكتابة ذات نطاق الاسم

تتعامل هذه النقاط النهائية مع الكتابات. commit/preflight لا يغير البيانات ولكنه يستخدم نفس قواعد التحقق مثل الالتزام الحقيقي. استخدم دائمًا مفاتيح عدم التكرار لعمليات الالتزام في الإنتاج حتى تظل المحاولات آمنة.

الطريقة	المسار	الوصف
POST	/v1/write/namespaces/{namespace_id}/commit	تقديم معاملة
POST	/v1/write/namespaces/{namespace_id}/commit/preflight	التحقق من معاملة بدون تغيير
POST	/v1/write/namespaces/{namespace_id}/commits/{commit_id}/reverse	تطبيق خطة عكسية مخزنة من جانب التراجع (تم التحقق من النزاع)
POST	/v1/write/namespaces/{namespace_id}/register_class	تسجيل فئة أصل جديدة
POST	/v1/write/namespaces/{namespace_id}/register_class_shape	تسجيل شكل لفئة
POST	/v1/write/namespaces/{namespace_id}/register_class_continuous_shape_1d	تسجيل شكل مستمر بعدد أبعاد 1D
POST	/v1/write/namespaces/{namespace_id}/register_class_continuous_shape_2d	تسجيل شكل مستمر بعدد أبعاد 2D

نقاط نهاية القراءة ذات نطاق الاسم

تقوم نقاط النهاية الخاصة بالقراءة بكشف التوقعات المستمدة من سجل الالتزام وتضمين بيانات التعريف الخاصة بالحداثة حتى تتمكن من التفكير في القدم.

تم إدراج نقاط النهاية المختارة للقراءة أدناه؛ راجع مرجع OpenAPI للحصول على الكتالوج الكامل.

الطريقة	المسار	الوصف
GET	/v1/read/namespaces/{namespace_id}/containers	قائمة الحاويات
GET	/v1/read/namespaces/{namespace_id}/containers/{id}	الحصول على بيانات الحاوية
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/balances	الحصول على أرصدة الحاوية
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/slots	الحصول على فتحات الحاوية
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/grid/cells	الحصول على مواضع الشبكة
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/grid/free	العثور على مساحة فارغة في الشبكة
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/contents	محتويات الحاوية الموحدة
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/continuous_1d/placements	مواضع مستمرة 1D
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/continuous_2d/placements	مواضع مستمرة 2D
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/commits	تاريخ التزام الحاوية
GET	/v1/read/namespaces/{namespace_id}/commits	تاريخ الالتزام
GET	/v1/read/namespaces/{namespace_id}/classes	قائمة الفئات المسجلة
GET	/v1/read/namespaces/{namespace_id}/classes/stats	إحصائيات سجل الفئات
GET	/v1/read/namespaces/{namespace_id}/classes/{id}	الحصول على تفاصيل الفئة
GET	/v1/read/namespaces/{namespace_id}/classes/{id}/shapes	الحصول على أشكال الفئة
GET	/v1/read/namespaces/{namespace_id}/instances	قائمة الحالات
GET	/v1/read/namespaces/{namespace_id}/instances/{id}	الحصول على تفاصيل الحالة
GET	/v1/read/namespaces/{namespace_id}/owners/{id}/summary	ملخص المالك
GET	/v1/read/namespaces/{namespace_id}/freshness	الحصول على بيانات النضارة
GET	/v1/read/namespaces/{namespace_id}/replay	إعادة تشغيل أحداث سجل الالتزام
GET	/v1/read/namespaces/{namespace_id}/stream	بث الالتزامات عبر SSE

نقاط نهاية الصحة العالمية

نقاط نهاية الصحة والقياسات مصممة لموازني الحمل وأنظمة المراقبة. يجب أن تكون جزءًا من فحوصات النشر القياسية الخاصة بك.

الطريقة	المسار	الوصف
GET	/v1/write/health	كتابة حالة صحة الـ daemon
GET	/v1/read/health	قراءة حالة صحة الـ daemon
GET	/v1/write/livez	كتابة اختبار حيوية الـ daemon
GET	/v1/read/livez	قراءة اختبار حيوية الـ daemon
GET	/v1/write/readyz	كتابة اختبار جاهزية الـ daemon
GET	/v1/read/readyz	قراءة اختبار جاهزية الـ daemon
GET	/v1/write/startupz	كتابة اختبار بدء تشغيل الـ daemon
GET	/v1/read/startupz	قراءة اختبار بدء تشغيل الـ daemon
GET	/v1/write/metrics	كتابة مقاييس Prometheus للـ daemon (المستمع عند التمكين)
GET	/v1/read/metrics	قراءة مقاييس Prometheus للـ daemon (المستمع عند التمكين)

حقول

رؤوس الطلبات

العنوان	مطلوب	الوصف
Authorization	نعم	رمز الحامل للمستخدم الحالي
Content-Type	نعم	يجب أن يكون application/json لطلبات POST
x-assetcore-namespace	شرطي	مساحة الاسم لنقاط نهاية قراءة الصحة/التحقق عند عدم التكوين
x-assetcore-min-world-seq	لا	يتطلب إسقاطًا للوصول إلى تسلسل عالمي أدنى
x-correlation-id	لا	معرف ارتباط العميل للتتبع

رؤوس الاستجابة

العنوان	الوصف
x-asset-idempotency	hit إذا كانت الاستجابة قد تم تقديمها من ذاكرة التخزين المؤقت للمعاملات المتكررة
Content-Type	دائمًا application/json

حقول الاستجابة الشائعة

استجابات النجاح تشمل:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 42,
  "world_seq_end": 42,
  "event_count": 2,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "client_correlation_id": "doc-example-2026-01-15",
  "echo": { ... }
}

استجابات ما قبل الطيران تشمل: status, executed_ops, failed_op_index, op_outcomes, و validated_world_seq. انظر ما قبل الطيران والالتزام العكسي للمعاني.

استجابات الاستعلام تشمل الحداثة:

{
  "server_correlation_id": "rd-0000000000000001-0000000000000042",
  "client_correlation_id": "doc-example-2026-01-15",
  "freshness": {
    "namespace": 5001,
    "world_seq": 42,
    "commit_log_world_seq": 45,
    "lag": 3,
    "lag_ms": 125
  }
}

أمثلة

تقديم معاملة

curl -X POST http://localhost:8080/v1/write/namespaces/5001/commit \
  -H "Authorization: Bearer $ASSETCORE_WRITE_TOKEN" \
  -H "x-correlation-id: doc-example-2026-01-15" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": { "type": "balance" },
          "owner": null,
          "policies": null
        }
      }
    ],
    "idempotency_key": "create-container-2026-01-15"
  }'

استجابة:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 1,
  "world_seq_end": 1,
  "event_count": 1,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "client_correlation_id": "doc-example-2026-01-15",
  "echo": {
    "idempotency_key": "create-container-2026-01-15"
  },
  "created_entities": {
    "containers": [1001]
  }
}

استعلام عن أرصدة الحاويات

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  http://localhost:8081/v1/read/namespaces/5001/containers/1001/balances

استجابة:

{
  "container_id": 1001,
  "balances": [
    {
      "class_id": 100,
      "key": 1,
      "quantity": 500
    }
  ],
  "server_correlation_id": "rd-0000000000000001-0000000000000042",
  "freshness": {
    "namespace": 5001,
    "world_seq": 1,
    "commit_log_world_seq": 1,
    "lag": 0,
    "lag_ms": 0
  }
}

تحقق من الصحة

curl -H "Authorization: Bearer $ASSETCORE_ADMIN_TOKEN" \
  http://localhost:8080/v1/write/health

استجابة:

{
  "status": "healthy",
  "version": "0.1.0",
  "api_version": "0.1.0",
  "build_git_sha": "abc123",
  "uptime_secs": 3600
}

المراجع ذات الصلة

• المعاملات - هيكل جسم الطلب
• نموذج الخطأ - رموز الحالة واستجابات الخطأ
• التحقق المسبق والالتزام العكسي - التحقق غير المتغير ودلالات التراجع
• OpenAPI Specification - عقد HTTP القياسي