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

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

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

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

---

نظرة عامة

يُثبت استدعاء multiGetObjects أنه أكثر كفاءة بكثير من استدعاء getObject في حلقة تكرارية. فهو يقلل من زمن استجابة الشبكة من خلال دمج استعلامات متعددة عن الكائنات في استدعاء إجراء عن بُعد (RPC) واحد.

مقارنة بين المعالجة التسلسلية والمعالجة الدفعية

getObject التسلسلي (N جولات ذهاب وإياب):
App ── getObject(A) ──► Fullnode ──► App ── getObject(B) ──► Fullnode

multiGetObjects الدفعي (رحلة ذهاب وإياب واحدة):
App ──────────── multiGetObjects([A, B, C]) ────────────► Fullnode
App ◄─────────── [ResultA, ResultB, ResultC] ─────────── Fullnode

التوقيع

التوقيع

client.multiGetObjects(input: MultiGetObjectsParams): Promise<SuiObjectResponse[]>

المعلمات

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

المعلمة	النوع	مطلوب	الوصف
ids	string[]	نعم	مصفوفة من معرّفات الكائنات السداسية العشرية بحجم 32 بايت.
options	SuiObjectDataOptions	لا	علامات التكوين لتشغيل أو إيقاف حقول بيانات محددة. تنطبق على جميع الكائنات المطلوبة.

ملاحظة

تفرض معظم عقد RPC العامة حدًا أقصى يبلغ عادةً 50 معرّفًا لكل طلب. بالنسبة للدُفعات الأكبر حجمًا، يجب تقسيم المصفوفة إلى أجزاء (chunks).

---

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

تُرجع Promise يُحل إلى مصفوفة من كائنات SuiObjectResponse.

يتطابق ترتيب عناصر المصفوفة تمامًا مع ترتيب المعرّفات الممررة في الطلب:

الاستجابة

[
  {
    "data": { "objectId": "0xA...", "version": "1" }
  },
  {
    "error": { "code": "notExists", "object_id": "0xB..." }
  },
  {
    "data": { "objectId": "0xC...", "version": "5" }
  }
]

---

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

جلب بيانات NFT الوصفية وخصائص العرض بشكل مجمّع

استعلم عن قائمة بمعرفات الرموز غير القابلة للاستبدال (NFT) لعرض الحقول على السلسلة وعناوين URL للصور:

bulkFetch.js

const objectIds = ['0x123...', '0x456...', '0x789...'];

const results = await client.multiGetObjects({
    ids: objectIds,
    options: {
        showContent: true,
        showDisplay: true
    }
});

// معالجة النتائج
results.forEach((result) => {
    if (result.data) {
        console.log("تم العثور على العنصر:", result.data.display?.data?.name);
    } else {
        console.warn("فشل تحميل العنصر:", result.error);
    }
});

تقسيم قوائم المعرفات الكبيرة لتلبية حدود المعالجة الدفعية

نظرًا لأن معظم عقد RPC العامة تفرض حدًا أقصى قدره 50 عنصرًا لكل طلب، استخدم دالة مساعدة لتقسيم القوائم الكبيرة:

chunking.js

import { chunk } from 'lodash'; // أو دالتك المساعدة الخاصة

const allIds = [/* ... مصفوفة تحتوي على 200 معرف ... */];
const CHUNK_SIZE = 50;
const chunks = chunk(allIds, CHUNK_SIZE);

for (const batch of chunks) {
    const batchResults = await client.multiGetObjects({
        ids: batch,
        options: { showType: true }
    });
    // معالجة batchResults...
}

---

أفضل الممارسات

معالجة حالات الفشل الجزئي لكل عنصر

على عكس استعلامات قواعد البيانات التقليدية التي قد توقف المعالجة بالكامل عند حدوث خطأ، تُرجع multiGetObjects نتيجة لكل معرف. حتى لو فشل جلب كائن معين (على سبيل المثال، إذا تم حذفه بواسطة معاملة)، تظل العناصر المتبقية في الدفعة صالحة. تحقق دائمًا من data و error لكل عنصر في المصفوفة المرجعة.

الاعتماد على الحفاظ على ترتيب الفهرس

يحافظ الـ SDK على ترتيب الفهرس لمصفوفة الإدخال:

• results[0] تتوافق مع ids[0]
• results[1] تتوافق مع ids[1]

يمكنك الاعتماد على هذا الترتيب لربط النتائج مباشرة بمصدر البيانات الأصلي لديك.

---

انظر أيضاً

• getObject: استرداد تفاصيل كائن فردي على السلسلة.
• getOwnedObjects: سرد جميع الكائنات المملوكة لعنوان معين.
• كيفية جلب بيانات الكائنات: دليل تعليمي تفصيلي خطوة بخطوة لتنفيذ عمليات القراءة في برنامج نصي بلغة Node.js.
• بنية SuiClient: نظرة عامة مفاهيمية على SuiClient وعمليات القراءة.