getObject
يسترد التفاصيل والبيانات الوصفية على السلسلة لكائن Sui واحد من خلال معرف الكائن السداسي العشري المكون من 32 بايت.
استخدم هذه الطريقة لفحص حزم Move وملكية الكائنات. يمكنك أيضًا التحقق من حقول البنية (struct). لا يمكن لعملية القراءة تغيير الكائن. تقرأ getObject من حالة العقدة الكاملة (fullnode). تعمل دون معاملة أو غاز أو توقيع محفظة.
- الفئة:
SuiClient - الحزمة:
@mysten/sui/client
التوقيع
client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>
المعلمات
تقبل هذه الطريقة كائنًا واحدًا. وتتضمن الخصائص التالية.
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
id | string | نعم | معرّف الكائن السداسي العشري المكون من 32 بايت، مثل 0x123.... |
options | SuiObjectDataOptions | لا | علامات لحقول بيانات الاستجابة. القيمة الافتراضية لكل علامة هي 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 │
├──────────────────────────────┬──────────────────────────────┤
│ Success: `response.data` │ Error: `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>",
"content": {
"dataType": "moveObject",
"fields": { "balance": "1000000000" }
},
"owner": {
"AddressOwner": "0xabc..."
}
}
}
استجابة الخطأ: error
تُرجع الخاصية error التفاصيل عندما تحذف معاملة الكائن أو تغلفه في كائن آخر. كما تُرجع التفاصيل عندما لا يكون المعرّف موجودًا.
{
"error": {
"code": "notExists",
"object_id": "0x..."
}
}
أمثلة على الاستخدام
التحقق من وجود كائن
لا يطلب هذا الاستعلام الخفيف حقول البيانات. فهو يُرجع فقط الملخص ورقم الإصدار.
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 لاسترداد أصول واجهة المستخدم.
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);
}
التحقق من ملكية الكائن
استخدم هذا الرمز للتحقق مما إذا كان عنوان حساب معين يتحكم في عنصر ما.
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 وأن طوله صحيح. |
انظر أيضًا
multiGetObjectsتسترد تفاصيل أربعة كائنات في طلب دفعي واحد.getOwnedObjectsتسرد جميع الكائنات المملوكة لعنوان معين.- كيفية استرداد بيانات الكائنات يقدم درسًا تعليميًا يستخدم
getObjectفي برنامج نصي Node.js. - بنية SuiClient تشرح التصميم المفاهيمي لـ
SuiClientوعمليات القراءة.