إنتقل إلى المحتوى الرئيسي

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

يسترد التفاصيل والبيانات الوصفية الموجودة على السلسلة لكائن Sui فردي من خلال معرف الكائن (Object ID) السداسي العشري المكون من 32 بايت.

استخدم هذه الطريقة للاستعلام عن تعريفات حزم Move، وفحص حقول البنية (struct)، والتحقق من ملكية الكائنات. يمكنك أيضًا التحقق مما إذا كانت معاملة ما قد عدلت كائنًا أو حذفته. ونظرًا لأن getObject هي عملية قراءة تُقدم مباشرةً من الحالة المحلية للعقدة الكاملة (fullnode)، فإنها تُنفذ على الفور دون إرسال معاملة أو استهلاك غاز.

  • الفئة: SuiClient
  • الحزمة: @mysten/sui/client
  • نوع العملية: عملية قراءة (بدون رسوم غاز، وبدون توقيع محفظة)

التوقيع​

التوقيع
client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>

المعلمات​

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

المعلمةالنوعمطلوبالوصف
idstringنعممعرف الكائن (Object ID) السداسي العشري المكون من 32 بايت، على سبيل المثال 0x123....
optionsSuiObjectDataOptionsلاعلامات التكوين لتبديل حقول بيانات محددة في الاستجابة. القيمة الافتراضية لجميع الحقول هي false.

SuiObjectDataOptions​

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

الخيارالوصف
showTypeتُرجع نوع Move، على سبيل المثال 0x2::coin::Coin<0x2::sui::SUI>.
showContentتُرجع حقول بيانات Move التي تم تحليلها، والتي تمثل الحالة الداخلية للكائن.
showOwnerتُرجع العنوان أو الكائن الذي يمتلك هذا العنصر.
showDisplayتُرجع البيانات الوصفية القياسية للعرض Display (الأسماء، الأوصاف، عناوين URL للصور) لواجهة المستخدم.
showStorageRebateتُرجع خصم التخزين المرتبط بالكائن.
showBcsتُرجع بايتات BCS (التسلسل الثنائي القياسي) الخام لفك التشفير من جانب العميل.
showPreviousTransactionتُرجع ملخص آخر معاملة تم تعديل هذا الكائن من خلالها.

القيمة المرجعة​

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

غلاف SuiObjectResponse
┌─────────────────────────────────────────────────────────────┐
│                     SuiObjectResponse                       │
├──────────────────────────────┬──────────────────────────────┤
│   النجاح: `response.data`    │    الخطأ: `response.error`   │
│   - objectId, version        │    - code: "notExists"       │
│   - type, digest             │    - code: "deleted"         │
│   - content, owner, display  │    - object_id               │
└──────────────────────────────┴──────────────────────────────┘

استجابة النجاح (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..." 
    }
  }
}

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

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

الاستجابة: خطأ
{
  "error": {
    "code": "notExists",
    "object_id": "0x..."
  }
}

أمثلة الاستخدام​

التحقق من وجود الكائن​

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

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

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

جلب بيانات NFT الوصفية وحقول العرض​

يطلب هذا الطلب content لقراءة الحقول على السلسلة و display لاسترداد أصول واجهة المستخدم.

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

if (nft.data) {
    const name = nft.data.content?.fields?.name;
    const imageUrl = nft.data.display?.data?.image_url;
    console.log(`اسم الـ NFT: ${name}، الصورة: ${imageUrl}`);
} else {
    console.warn("فشل تحميل العنصر:", nft.error);
}

التحقق من ملكية الكائن​

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

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

const owner = item.data?.owner;

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

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

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

انظر أيضاً​