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

getObject

يسترد التفاصيل والبيانات الوصفية على السلسلة لكائن Sui واحد من خلال معرف الكائن السداسي العشري المكون من 32 بايت.

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

  • الفئة: SuiClient
  • الحزمة: @mysten/sui/client

التوقيع​

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

المعلمات​

تقبل هذه الطريقة كائنًا واحدًا. وتتضمن الخصائص التالية.

المعلمةالنوعمطلوبالوصف
idstringنعممعرّف الكائن السداسي العشري المكون من 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 envelope
┌─────────────────────────────────────────────────────────────┐
│ SuiObjectResponse │
├──────────────────────────────┬──────────────────────────────┤
│ Success: `response.data` │ Error: `response.error` │
│ - objectId, version │ - code: "notExists" │
│ - type, digest │ - code: "deleted" │
│ - content, owner, display │ - object_id │
└──────────────────────────────┴──────────────────────────────┘

استجابة النجاح: data​

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

Response: success
{
"data": {
"objectId": "0x...",
"version": "10",
"digest": "...",
"type": "0x2::coin::Coin<0x2::sui::SUI>",
"content": {
"dataType": "moveObject",
"fields": { "balance": "1000000000" }
},
"owner": {
"AddressOwner": "0xabc..."
}
}
}

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

تُرجع الخاصية error التفاصيل عندما تحذف معاملة الكائن أو تغلفه في كائن آخر. كما تُرجع التفاصيل عندما لا يكون المعرّف موجودًا.

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

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

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

لا يطلب هذا الاستعلام الخفيف حقول البيانات. فهو يُرجع فقط الملخص ورقم الإصدار.

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

if (response.error) {
console.log("Object doesn't exist.");
} else if (response.data) {
console.log("Object exists at version:", response.data.version);
} else {
console.log("The response didn't include object data.");
}

استرداد بيانات تعريف الرمز غير القابل للاستبدال وحقول العرض​

يُعيّن هذا الطلب showContent لقراءة الحقول الموجودة على السلسلة وshowDisplay لاسترداد أصول واجهة المستخدم.

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: ${name}, Image: ${imageUrl}`);
} else {
console.warn("Item failed to load:", 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("You own this item.");
}

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

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

انظر أيضًا​