Arxi بوابة القرار أصل أساسي
Docs
وثائق أصول Core

توثيق محرك حالة العالم الحتمي ومراجع API.

وثائق بوابة القرار

استخدام SDK بايثون

هذا الدليل يوضح كيفية تحقيق نفس النتيجة كما في بدء استخدام HTTP السريع باستخدام Asset Core Python SDK مع العمليات المخصصة. إنه المسار الموصى به للفرق التي ترغب في الحصول على أمان نوع قوي مع البقاء متماشية مع العقد العام لـ HTTP.

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

تأكد من أن الخدمات تعمل وأن لديك رموز صالحة للوصول للقراءة والكتابة. لا يتجاوز SDK أي فحوصات تفويض؛ بل يقوم ببساطة بتغليف نفس نقاط نهاية HTTP.

  • Python 3.11+
  • تعمل خوادم Asset Core محليًا مع توفر رموز الحامل (انظر First Commit and Read)
  • pip أو uv لتثبيت الحزم

الخطوة 1 - تثبيت SDK

من جذر مستودع Asset Core:

cd sdk-python
pip install -e .

أو مع uv:

uv venv --seed .venv-sdk
source .venv-sdk/bin/activate
cd sdk-python
uv pip install -e .

الخطوة 2 - إنشاء العميل

import os
from assetcore_sdk import AssetCoreClient

write_client = AssetCoreClient(
    base_url="http://127.0.0.1:8080",
    api_key=os.environ["ASSETCORE_WRITE_TOKEN"],
)

read_client = AssetCoreClient(
    base_url="http://127.0.0.1:8081",
    api_key=os.environ["ASSETCORE_READ_TOKEN"],
)

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

الخطوة 3 - عمليات البناء

استخدم بناة العمليات المكتوبة:

from assetcore_sdk.operations import CreateContainer, AddFungible

operations = [
    CreateContainer(
        container_id=1001,
        kind={"type": "balance"},
        owner=None,
        policies=None,
    ),
    AddFungible(
        class_id=100,
        key=1,
        quantity=500,
        location={"container_id": 1001, "kind": "balance"},
    ),
]

ينتج كل مُنشئ عملية مُعينة يقوم العميل بتحويلها إلى ظرف JSON. وهذا يسهل اكتشاف الحقول غير الصالحة قبل أن تصل إلى الـ daemon.

الخطوة 4 - إرسال الالتزام

result = await write_client.commit_operations(
    operations,
    idempotency_key="sdk-first-commit-2026-01-15",
    namespace_id=5001,
)

print(f"Committed at world seq {result.world_seq_start}")

أو استخدم النسخة المتزامنة:

result = write_client.commit_operations_sync(
    operations,
    idempotency_key="sdk-first-commit-2026-01-15",
    namespace_id=5001,
)

الخطوة 5 - قراءة الحالة

container = await read_client.get_container_balances(1001, namespace_id=5001)

for balance in container.balances:
    print(f"Class {balance.class_id}: {balance.quantity}")

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

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

”ModuleNotFoundError: assetcore_sdk”

لم يتم تثبيت SDK في بيئتك الحالية. تأكد من أنك قمت بتفعيل البيئة الافتراضية الصحيحة وتشغيل pip install -e . من دليل sdk-python.

أخطاء الاتصال

الخدمات غير قيد التشغيل أو تعمل على منافذ مختلفة. يقوم SDK بإثارة assetcore_sdk.errors.HttpError مع تفاصيل النقل.

أخطاء التحقق

تؤدي معايير العملية غير الصالحة إلى رفع assetcore_sdk.errors.ValidationError مع الحقل المحدد الذي فشل. تحقق من مرجع العملية للحصول على الحقول المطلوبة.

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