وصفات

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

المتطلبات السابقة

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

• فهم العمليات
• فئات الأصول المسجلة لنطاقك
• الحاويات التي تم إنشاؤها للمصدر والوجهة

الخطوة 1 - نقل الرصيد القابل للتداول بين الحاويات

نقل كمية قابلة للتبادل من حاوية إلى أخرى باستخدام عمليات الإزالة والإضافة. هذه هي الأنماط الأكثر أمانًا عندما تريد السيطرة الصريحة على كل خطوة.

متى تستخدم: نقل الموارد، تحويل الأرصدة، إعادة توازن المخزون.

العمليات: RemoveFungible, AddFungible

{
  "operations": [
    {
      "op": "RemoveFungible",
      "args": {
        "class_id": 200,
        "key": 1,
        "quantity": 150,
        "from": {
          "container_id": 1001,
          "kind": "balance"
        }
      }
    },
    {
      "op": "AddFungible",
      "args": {
        "class_id": 200,
        "key": 1,
        "quantity": 150,
        "location": {
          "container_id": 1002,
          "kind": "balance"
        }
      }
    }
  ],
  "idempotency_key": "transfer-balance-2026-01-15-1001-1002"
}

بدلاً من ذلك، استخدم TransferFungible لنقل بعملية واحدة:

{
  "operations": [
    {
      "op": "TransferFungible",
      "args": {
        "from_container": 1001,
        "to_container": 1002,
        "class_id": 200,
        "key": 1,
        "quantity": 150
      }
    }
  ]
}

الخطوة 2 - نقل الحالة بين الفتحات

نقل حالة فريدة من فتحة إلى أخرى ضمن نفس الحاويات أو حاويات مختلفة. يحافظ هذا النمط على إمكانية التدقيق ويتجنب الحالة الجزئية أثناء تغييرات المعدات.

متى تستخدم: إعادة تنظيم المخزون، نقل المعدات، إعادة وضع العناصر.

العمليات: RemoveFromSlot, PlaceInSlot

{
  "operations": [
    {
      "op": "RemoveFromSlot",
      "args": {
        "container_id": 1001,
        "slot_index": 1
      }
    },
    {
      "op": "PlaceInSlot",
      "args": {
        "container_id": 1001,
        "slot_index": 2,
        "instance_id": 9001
      }
    }
  ],
  "idempotency_key": "slot-move-2026-01-15-9001"
}

للتبديل بين موقعين مشغولين، استخدم SwapSlots بدلاً من ذلك.

الخطوة 3 - تسجيل الفئة مع الشكل

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

متى تستخدم: إعداد أنواع الأصول الجديدة التي سيتم وضعها في حاويات الشبكة.

العمليات: RegisterClass, RegisterClassShape

{
  "operations": [
    {
      "op": "RegisterClass",
      "args": {
        "request": {
          "class_id": 300,
          "flags": 2,
          "name": "Battle Tank"
        }
      }
    },
    {
      "op": "RegisterClassShape",
      "args": {
        "request": {
          "class_id": 300,
          "stack_key": null,
          "shape": {
            "width": 3,
            "height": 2
          }
        }
      }
    }
  ],
  "idempotency_key": "class-with-shape-2026-01-15-300"
}

الخطوة 4 - إضافة وتحديد المثيل

إنشاء مثيل فريد جديد ووضعه على الفور في فتحة.

متى تستخدم: إنشاء العناصر، إنشاء المعدات، إضافة العينات.

العمليات: AddInstance

{
  "operations": [
    {
      "op": "AddInstance",
      "args": {
        "class_id": 200,
        "key": 1,
        "location": {
          "container_id": 1001,
          "kind": "slot",
          "slot_index": 1
        }
      }
    }
  ]
}

ملاحظة: قائمة استجابة الالتزام تحتوي على معرفات الكيانات التي تم إنشاؤها تحت created_entities.instances، والتي يمكنك استخدامها في العمليات اللاحقة.

الخطوة 5 - إعداد الحاوية مع الرصيد الأولي

إنشاء حاوية وتعبئتها بالموارد الأولية.

متى تستخدم: تهيئة مخزونات اللاعبين، إنشاء تخزين جديد، إعداد التجارب.

العمليات: CreateContainer, AddFungible

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 2001,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "AddFungible",
      "args": {
        "class_id": 100,
        "key": 1,
        "quantity": 1000,
        "location": {
          "container_id": 2001,
          "kind": "balance"
        }
      }
    },
    {
      "op": "AddFungible",
      "args": {
        "class_id": 101,
        "key": 1,
        "quantity": 500,
        "location": {
          "container_id": 2001,
          "kind": "balance"
        }
      }
    }
  ],
  "idempotency_key": "init-container-2026-01-15-2001"
}

الخطوة 6 - ربط المعدات بالشخصية

إنشاء علاقات بين الوالد والطفل بين الحالات للمعدات أو المكونات.

متى تستخدم: تجهيز العناصر، ربط المكونات، بناء الهياكل.

العمليات: Attach

{
  "operations": [
    {
      "op": "Attach",
      "args": {
        "child_instance": 9002,
        "parent_instance": 9001
      }
    }
  ]
}

لإزالة المعدات، استخدم Detach متبوعًا بالمكان المطلوب.

استكشاف الأخطاء وإصلاحها

أهمية الطلب

تُنفذ العمليات بالتسلسل. تأكد من أن العمليات السابقة تخلق الحالة التي تعتمد عليها العمليات اللاحقة.

استخدام مفاتيح التكرار

دائمًا قم بتضمين مفاتيح التكرار للعمليات التي تعدل الحالة. هذا يمنع الالتزامات المكررة عند إعادة المحاولة.

تحقق من أنواع الحاويات

تتطلب عمليات التوازن حاويات توازن أو شبكة. تتطلب عمليات الفتحات حاويات فتحات. تسبب الأنواع غير المتطابقة أخطاء WrongContainerKind.

تحقق من الكميات

تأكد من أن حاويات المصدر تحتوي على رصيد كافٍ قبل التحويلات. يؤدي الرصيد غير الكافي إلى إلغاء المعاملة بالكامل.

الخطوات التالية

• مرجع الإجراء - مرجع العملية الكامل
• نموذج الخطأ - فهم الفشل
• Python SDK - منشئي عمليات آمنة من حيث النوع