مرجع واجهة برمجة التطبيقات: getObject

استرجاع تفاصيل كائن معين من سلسلة الكتل.

الفئة: SuiClient نوع الطريقة: عملية قراءة، بدون غاز

---

التوقيع

client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>

المعلمات

تقبل الطريقة كائن تكوين واحد يحتوي على الخصائص التالية:

المعلمة	النوع	مطلوب	الوصف
id	string	نعم	معرف الكائن سداسي عشري 32 بايت، على سبيل المثال، 0x123....
options	SuiObjectDataOptions	لا	علامات التكوين لتبديل حقول بيانات محددة في الاستجابة. الإعداد الافتراضي إلى false لجميع الحقول.

SuiObjectDataOptions

افتراضيًا، يُرجع getObject مرجع الكائن فقط، وتحديدًا معرفه وإصداره وخلاصته. لاسترداد البيانات الفعلية، يجب عليك تعيين هذه العلامات صراحةً إلى true.

الخيار	الوصف
showType	إرجاع نوع الحركة، على سبيل المثال، 0x2::coin::Coin<SUI>.
showContent	إرجاع حقول بيانات الحركة التي تم تحليلها، الحالة الداخلية للكائن.
showOwner	إرجاع العنوان أو الكائن الذي يمتلك هذا العنصر.
showDisplay	إرجاع البيانات الوصفية القياسية للعرض، وتحديدًا الصور والأسماء، لعرض واجهة المستخدم.
showStorageRebate	إرجاع خصم التخزين المرتبط بالكائن.

---

قيمة الإرجاع

إرجاع Promise يحل إلى SuiObjectResponse. هذه الاستجابة عبارة عن غلاف قياسي يتعامل مع كل من حالتي النجاح والخطأ.

1. استجابة النجاح (data)

إذا كان الكائن موجودًا وتم الحفاظ على إمكانية الوصول إليه، فإن خاصية data تحتوي على SuiObjectData.

{
  "data": {
    "objectId": "0x...",
    "version": "10",
    "digest": "...",
    "type": "0x2::coin::Coin<0x2::sui::SUI>", // موجود إذا كان showType: true
    "content": {                              // موجود إذا كان showContent: true
       "dataType": "moveObject",
       "fields": { "balance": "1000000000" }
    },
    "owner": {                                // موجود إذا كان showOwner: true
       "AddressOwner": "0xabc..." 
    }
  }
}

2. استجابة الخطأ (error)

إذا قمت بحذف الكائن، أو ملفوفًا في كائن آخر، أو غير موجود، فإن الخاصية error تحمل قيمة.

{
  "error": {
    "code": "notExists",
    "object_id": "0x..."
  }
}

---

أمثلة على الاستخدام

سيناريو أ: التحقق من وجود كائن

هذا هو الاستعلام الأكثر خفة. لا يطلب أي بيانات، فقط الرقم/الإصدار.

const response = await client.getObject({
    id: '0x123...'
});

if (response.error) {
    console.log("الكائن غير موجود.");
} else {
    console.log("الكائن موجود في الإصدار:", response.data.version);
}

سيناريو ب: جلب البيانات الوصفية للرموز غير القابلة للاستبدال

يطلب هذا الطلب content لقراءة الحقول، و display لرؤية عنوان الصورة.

const nft = await client.getObject({
    id: '0x123...',
    options: {
        showContent: true,
        showDisplay: true
    }
});

const name = nft.data.content.fields.name;
const imageUrl = nft.data.display.data.image_url;

سيناريو ج: التحقق من الملكية

استخدم هذا للتحقق مما إذا كان مستخدم معين يمتلك عنصرًا ما.

const item = await client.getObject({
    id: '0x123...',
    options: { showOwner: true }
});

const owner = item.data.owner;

if (owner && owner.AddressOwner === '0xMyAddress...') {
    console.log("أنت تملك هذا العنصر.");
}

---

الأخطاء الشائعة

رمز الخطأ	السبب	الحل
notExists	معرف الكائن سداسي سداسي صحيح ولكن الكائن غير موجود على الشبكة.	تحقق من المعرف أو تأكد من عدم حذف الكائن في معاملة سابقة.
deleted	الكائن موجود من قبل ولكن تم حرقه أو قمت بحذفه.	لا يمكنك جلب بيانات الكائنات المحذوفة.
invalid_param	معرف الكائن المقدم ليس سلسلة سداسية سداسية صحيحة 32 بايت.	تأكد من أن المعرف يبدأ بـ 0x وأنه بالطول الصحيح.

---

انظر أيضًا

• getMultiGetObjects**: جلب العديد من الكائنات في طلب شبكة واحد، من أجل التجميع.
• getOwnedObjects: البحث عن جميع الكائنات المملوكة لعنوان محدد.