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

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

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

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

نظرة عامة​

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

التوقيع​

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

المعلمات​

يقبل الأسلوب كائن تهيئة مع الخصائص التالية:

المعلمةالنوعمطلوبالوصف
idsstring[]نعممصفوفة من معرفات الكائنات سداسية عشرية سداسية البايت.
optionsSuiObjectDataOptionsلاعلامات التكوين لتبديل حقول بيانات محددة. ينطبق على جميع الكائنات المطلوبة.

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

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

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

يتوافق ترتيب المصفوفة تمامًا مع ترتيب ids التي تم تمريرها في الطلب.

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

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

السيناريو أ: جلب البيانات الوصفية بالجملة​

تخيل أن لديك قائمة بمعرفات الرموز غير القابلة للاستبدال (NFT) وتحتاج إلى عرض أسمائها.

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);
    }
});

سيناريو ب: التعامل مع القوائم الكبيرة عن طريق التقطيع​

نظرًا لتطبيق حد 50 عنصرًا على سبيل المثال لكل طلب، استخدم مساعد التقطيع للقوائم الكبيرة.

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 }
    });
    // معالجة النتائج الدفعية....
}

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

1. التعامل دائمًا مع حالات الفشل الجزئي​

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

2. الحفاظ على الترتيب​

تضمن SDK أن مصفوفة الإخراج تطابق فهرس مصفوفة الإدخال.

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

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