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

تسترد قائمة مقسمة إلى صفحات من الكائنات الموجودة على السلسلة والمملوكة لعنوان محفظة Sui محدد مكون من 32 بايت.

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

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

---

نظرة عامة

يؤدي استدعاء getOwnedObjects إلى الاستعلام عن فهرس العقدة الكاملة بحثًا عن الكائنات المملوكة للعنوان المستهدف (AddressOwner). لتجنب زمن الوصول الطويل ومهلة انتظار الشبكة، تقوم العقد الكاملة بتقسيم النتائج إلى صفحات بدلاً من إرجاع المخزون بالكامل في استجابة واحدة.

تصور حلقة تقسيم الصفحات

Mermaid (صورة)

Mermaid (كود)

flowchart TD
    Start([بدء ترقيم الصفحات]) --> Init["تهيئة cursor = null<br/>allObjects = []"]
    Init --> Query["استدعاء getOwnedObjects<br/>(cursor, limit: 50)"]
    Query --> Resp["تلقي الرد:<br/>data[], hasNextPage, nextCursor"]
    Resp --> Append["إضافة العناصر إلى<br/>مصفوفة allObjects"]
    Append --> Check{"هل hasNextPage == true؟"}
    Check -->|نعم| Update["تحديث cursor = nextCursor"]
    Check -->|لا| Done([إرجاع جميع الكائنات المتراكمة])
    Update -.->|الصفحة التالية| Query

ASCII

تدفق تقسيم الصفحات (حلقة المؤشر):

العميل                                    العقدة الكاملة
  │                                            │
  │── getOwnedObjects(cursor: null) ──────────►│ (الصفحة 1: الحد الأقصى 50)
  │◄── { data: [50 items], nextCursor } ───────│
  │                                            │
  │── getOwnedObjects(cursor: nextCursor) ────►│ (الصفحة 2: الحد الأقصى 50)
  │◄── { data: [12 items], hasNextPage: false }

التوقيع البرمجي

التوقيع البرمجي

client.getOwnedObjects(input: GetOwnedObjectsParams): Promise<PaginatedObjectsResponse>

المعلمات

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

المعلمة	النوع	مطلوب	الوصف
owner	string	نعم	العنوان السداسي العشري المكون من 32 بايت للمحفظة المستهدفة.
filter	SuiObjectDataFilter	لا	معايير لتصفية النتائج حسب النوع أو الحزمة أو الوحدة النمطية.
options	SuiObjectDataOptions	لا	علامات لتضمين تفاصيل إضافية (على سبيل المثال، showType, showContent, showDisplay).
cursor	string | null	لا	رمز nextCursor من استجابة سابقة لجلب الصفحة التالية.
limit	number	لا	الحد الأقصى للعناصر المراد إرجاعها في كل صفحة (القيمة الافتراضية والحد الأقصى عادةً ما يكون 50 في عقد RPC العامة).

SuiObjectDataFilter

تعمل معلمة filter على تضييق نطاق الاستعلامات على العقدة الكاملة، مما يوفر النطاق الترددي والمعالجة من جانب العميل:

مفتاح التصفية	نوع القيمة	الوصف
MatchAll	SuiObjectDataFilter[]	المنطق AND. يجب أن يستوفي الكائن جميع معايير التصفية المحددة.
MatchAny	SuiObjectDataFilter[]	المنطق OR. يمكن للكائن أن يستوفي أيًا من معايير التصفية المحددة.
StructType	string	المطابقة التامة لنوع Move Struct المؤهل بالكامل (على سبيل المثال، 0x2::coin::Coin<0x2::sui::SUI>).
Package	string	تطابق أي كائن تم إنشاء مثيل له من الوحدات النمطية ضمن معرّف الحزمة المحدد.
MoveModule	{ package: string, module: string }	تطابق أي كائن تم تعريفه ضمن وحدة نمطية محددة من حزمة ما.

---

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

تُرجع وعدًا (Promise) يُحل إلى كائن PaginatedObjectsResponse:

الاستجابة

{
  "data": [
    { "data": { "objectId": "0xA...", "version": "1", "type": "0x2::coin::Coin<0x2::sui::SUI>" } },
    { "data": { "objectId": "0xB...", "version": "4", "type": "0x2::coin::Coin<0x2::sui::SUI>" } }
  ],
  "hasNextPage": true,
  "nextCursor": "0x12345...ResultCursor"
}

يحتوي غلاف الاستجابة على الحقول التالية:

الحقل	النوع	الوصف
data	SuiObjectResponse[]	مصفوفة من أغلفة استجابة الكائنات للصفحة الحالية.
hasNextPage	boolean	يشير إلى وجود صفحات إضافية من الكائنات أم لا.
nextCursor	string | null	رمز ترقيم الصفحات غير الشفاف الذي يتم تمريره كمؤشر (cursor) في الاستدعاء التالي. عندما تكون قيمة hasNextPage هي false، تكون هذه القيمة null.

---

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

جلب الصفحة الأولى من قائمة الأصول

استرداد أول 5 كائنات يمتلكها عنوان ما:

basicInventory.js

const response = await client.getOwnedObjects({
    owner: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    limit: 5,
    options: { showType: true }
});

response.data.forEach((item) => {
    if (item.data) {
        console.log(`ID: ${item.data.objectId}, Type: ${item.data.type}`);
    }
});

تصفية الأصول حسب نوع بنية Move

الاستعلام فقط عن كائنات عملة SUI التي يمتلكها مستخدم، باستثناء الرموز الأخرى و NFTs:

filterCoins.js

const response = await client.getOwnedObjects({
    owner: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    filter: {
        StructType: '0x2::coin::Coin<0x2::sui::SUI>'
    },
    options: { showContent: true }
});

console.log(`تم العثور على ${response.data.length} من كائنات عملة SUI`);

التنقل بين جميع الكائنات المملوكة

استخدام حلقة while للتنقل عبر كل كائن يمتلكه عنوان:

pagination.js

let hasNextPage = true;
let nextCursor = null;
const allObjects = [];

while (hasNextPage) {
    const response = await client.getOwnedObjects({
        owner: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
        cursor: nextCursor,
        limit: 50
    });

    allObjects.push(...response.data);
    
    hasNextPage = response.hasNextPage;
    nextCursor = response.nextCursor;
}

console.log(`إجمالي الكائنات التي تم جلبها: ${allObjects.length}`);

---

أخطاء شائعة

رمز الخطأ	السبب	الحل
cursor_invalid	السلسلة التي تم تمريرها إلى cursor منتهية الصلاحية، أو غير صحيحة، أو تنشأ من استعلام مختلف.	قم بتمرير السلسلة الدقيقة التي تم إرجاعها في nextCursor من الاستعلام السابق.
limit_exceeded	الحد المطلوب يتجاوز الحد الأقصى المسموح به لحجم الصفحة في العقدة الكاملة (عادةً 50).	قلل معلمة limit إلى 50 عنصرًا أو أقل.

---

انظر أيضًا

• getObject يسترد تفاصيل كائن فردي على السلسلة.
• multiGetObjects يسترد تفاصيل عدة كائنات محددة في طلب دفعي واحد.
• كيفية جلب بيانات الكائن يقدم دليلًا تعليميًا تفصيليًّا لتنفيذ عمليات القراءة في Node.js.
• بنية SuiClient يشرح التصميم المفاهيمي لـ SuiClient وعمليات القراءة.