المعاملات

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

نظرة عامة

تتدفق جميع تغييرات الحالة عبر نقطة النهاية /v1/write/namespaces/{namespace_id}/commit كمعاملات. يقوم برنامج الكتابة بالتحقق من صحة العمليات وتنفيذها وإضافتها إلى سجل الالتزام قبل إرجاع استجابة النجاح. وهذا يعني أن كل تغيير يمكن تدقيقه وإعادة تشغيله حسب التصميم.

الهيكل

طلب الالتزام

{
  "actor_id": "lab-operator-17",
  "policy_id": null,
  "operations": [
    { "op": "OperationName", "args": { ... } },
    { "op": "AnotherOperation", "args": { ... } }
  ],
  "idempotency_key": "optional-unique-key",
  "metadata": {
    "custom_field": "optional user metadata"
  },
  "origin": {
    "client": "assetcore-sdk",
    "source": "batch-import"
  }
}

عملية الظرف

كل عملية لها نفس هيكل الظرف. هذه الوحدة هي ما يجعل التحقق والأدوات موثوقة عبر جميع المجالات.

{
  "op": "OperationName",
  "args": {
    "field1": "value1",
    "field2": 123
  }
}

حقول

حقول الطلب

الحقل	النوع	مطلوب	الوصف
operations	مصفوفة	نعم	قائمة العمليات التي سيتم تنفيذها
actor_id	سلسلة	لا	معرف الممثل لتتبع التدقيق
policy_id	سلسلة	لا	معرف السياسة (للاستخدام المستقبلي)
idempotency_key	سلسلة	لا	مفتاح فريد لإزالة التكرار
metadata	كائن	لا	بيانات تعريف المستخدم المنعكسة في الاستجابة
origin	كائن	لا	بيانات تعريف الأصل الاختيارية المنعكسة في الاستجابة

حقول مظروف العملية

الحقل	النوع	مطلوب	الوصف
op	سلسلة	نعم	معرف العملية
args	كائن	نعم	معلمات محددة للعملية

حقول الاستجابة

الحقل	النوع	الوصف
namespace	عدد صحيح	مساحة الأسماء التي تم تنفيذ المعاملة فيها
commit_id	سلسلة	معرف الالتزام غير الشفاف المستخدم للالتزامات العكسية
outcome	سلسلة	Committed أو RolledBack
world_seq_start	عدد صحيح	رقم تسلسل العالم الأول في الالتزام
world_seq_end	عدد صحيح	رقم تسلسل العالم النهائي في الالتزام
event_count	عدد صحيح	عدد الأحداث المنبعثة
start_time_ms	عدد صحيح	وقت بدء المعاملة (بالملي ثانية منذ البداية)
commit_time_ms	عدد صحيح	وقت الالتزام للمعاملة (بالملي ثانية منذ البداية)
server_correlation_id	سلسلة	معرف الترابط المعين من قبل الخادم للتتبع
client_correlation_id	سلسلة	معرف الترابط المقدم من العميل عند توفيره
origin	كائن	صدى بيانات التعريف المقدمة من المتصل
echo	كائن	صدى بيانات التعريف الخاصة بالطلب بما في ذلك idempotency_key
created_entities	كائن	ملخص للكيانات التي تم إنشاؤها أثناء الالتزام

أمثلة

الحد الأدنى من المعاملة

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1001,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    }
  ]
}

المعاملة مع الاستقلالية

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1002,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    }
  ],
  "idempotency_key": "create-container-2026-01-15-001"
}

معاملة متعددة العمليات

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 2001,
        "kind": { "type": "slots", "count": 8 },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "RegisterClass",
      "args": {
        "request": {
          "class_id": 200,
          "flags": 2,
          "name": "SampleClass"
        }
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 200,
        "key": 1,
        "location": {
          "container_id": 2001,
          "kind": "slot",
          "slot_index": 1
        }
      }
    }
  ],
  "metadata": {
    "experiment_id": "exp-001",
    "operator": "system"
  }
}

استجابة:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 5,
  "world_seq_end": 5,
  "event_count": 3,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "echo": {
    "metadata": {
      "experiment_id": "exp-001",
      "operator": "system"
    }
  },
  "created_entities": {
    "classes": [200],
    "containers": [2001],
    "instances": [9001]
  }
}

استجابة إعادة المحاولة غير القابلة للتغيير

عند إرسال نفس مفتاح التكرار مرة أخرى:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 5,
  "world_seq_end": 5,
  "event_count": 3,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "echo": {
    "idempotency_key": "create-sample-2026-01-15-001",
    "metadata": {
      "experiment_id": "exp-001",
      "operator": "system"
    }
  },
  "created_entities": {
    "classes": [200],
    "containers": [2001],
    "instances": [9001]
  }
}

رأس x-asset-idempotency: hit يشير إلى استجابة مخزنة.

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

• مرجع الإجراء - مرجع العملية الكامل
• الوصفات - أنماط العمليات المتعددة الشائعة
• نموذج الخطأ - التعامل مع فشل المعاملات