سرد الكائنات الثنائية كبيرة الحجم باستخدام JavaScript

توضح هذه المقالة كيفية سرد الكائنات الثنائية كبيرة الحجم باستخدام مكتبة عميل Azure Storage ل JavaScript.

المتطلبات الأساسية

• تفترض الأمثلة في هذه المقالة أن لديك بالفعل مشروعا تم إعداده للعمل مع مكتبة عميل Azure Blob Storage ل JavaScript. للتعرف على إعداد مشروعك، بما في ذلك تثبيت الحزمة، واستيراد الوحدات النمطية، وإنشاء كائن عميل معتمد للعمل مع موارد البيانات، راجع بدء استخدام Azure Blob Storage وJavaScript.
• يجب أن يكون لآلية التخويل أذونات لسرد الكائنات الثنائية كبيرة الحجم. لمعرفة المزيد، راجع إرشادات التخويل لعملية REST API التالية:
  • إدراج الكائنات الثنائية كبيرة الحجم

حول خيارات إدخال قائمة الكائنات الثنائية كبيرة الحجم

عند سرد الكائنات الثنائية كبيرة الحجم من التعليمات البرمجية الخاصة بك، يمكنك تحديد عدة خيارات لإدارة كيفية إرجاع النتائج من Azure Storage. يمكنك تحديد عدد النتائج المراد إرجاعها في كل مجموعة من النتائج، ثم استرداد المجموعات اللاحقة. يمكنك تحديد بادئة لإرجاع الكائنات الثنائية كبيرة الحجم التي تبدأ أسماؤها بهذا الحرف أو السلسلة. ويمكنك إدراج الكائنات الثنائية كبيرة الحجم في بنية قائمة كاملة أو بشكل هرمي. إعداد القائمة الهرمية يقوم بإرجاع كائن ثنائي كبير كما لو كانت منظمة في مجلدات.

لسرد الكائنات الثنائية كبيرة الحجم في حاوية باستخدام إدخال قائمة مسطحة، قم باستدعاء الأسلوب التالي:

• ContainerClient.listBlobsFlat

لسرد الكائنات الثنائية كبيرة الحجم في حاوية باستخدام قائمة هرمية، قم باستدعاء الأسلوب التالي:

• ContainerClient.listBlobsByHierarchy

إدارة عدد النتائج التي يتم إرجاعها

بشكل افتراضي، تعرض عملية الإدراج حوالي 5000 نتيجة في المرة الواحدة، ولكن يمكنك تحديد عدد النتائج التي ترجع لكل عملية إدراج. توضح لك الأمثلة المعروضة في هذه المقالة كيفية عرض النتائج في الصفحات. لمعرفة المزيد حول مفاهيم ترقيم الصفحات، راجع ترقيم الصفحات باستخدام Azure SDK ل JavaScript.

تصفية النتائج باستخدام البادئة

لتصفية قائمة الكائنات الثنائية كبيرة الحجم، حدد سلسلة للخاصية prefix في ContainerListBlobsOptions. يمكن أن تتضمن سلسلة البادئة حرفاً واحداً أو أكثر. ثم يقوم Azure Storage بإرجاع الكائنات الثنائية كبيرة الحجم التي تبدأ أسماؤها بهذه البادئة فقط. على سبيل المثال، يؤدي تمرير سلسلة sample- البادئة إلى إرجاع الكائنات الثنائية كبيرة الحجم التي تبدأ أسماؤها ب sample-.

تضمين بيانات تعريف الكائن الثنائي كبير الحجم أو معلومات أخرى

لتضمين بيانات تعريف blob مع النتائج، قم بتعيين الخاصية includeMetadata إلى true كجزء من ContainerListBlobsOptions. يمكنك أيضا تضمين لقطات أو علامات أو إصدارات في النتائج عن طريق تعيين الخاصية المناسبة إلى true.

مقارنة بين القائمة المسطحة والقائمة الهرمية

يتم تنظيم الكائنات الثنائية كبيرة الحجم في Azure Storage في نموذج كامل وليس نموذج هرمي (مثل نظام الملفات الكلاسيكي). لكن، يمكنك تنظيم الكائنات الثنائية كبيرة الحجم في أدلة ظاهرية من أجل محاكاة بنية مجلد. يشكل الدليل الظاهري جزءاً من اسم الكائنات الثنائية كبيرة الحجم ويشار إليه بالحرف المحدد.

لتنظيم الكائنات الثنائية كبيرة الحجم في أدلة ظاهرية، استخدم حرف محدد في اسم الكائنات الثنائية كبيرة الحجم. يعد الحرف المحدد الافتراضي هو شرطة مائلة للأمام (/)، ولكن يمكنك تحديد أي حرف كمحدد.

إذا قمت بتسمية الكائنات الثنائية كبيرة الحجم الخاصة بك باستخدام محدد، فيمكنك اختيار الإدراج الهرمي لهذه الكائنات الثنائية كبيرة الحجم. بالنسبة لعملية الإدراج الهرمي، يعمل Azure Storage على إرجاع أي دلائل وكائنات ثنائية كبيرة الحجم ظاهرية أسفل العنصر الأصل. يمكنك استدعاء عملية الإدراج بشكل متكرر لاجتياز التسلسل الهرمي، بنفس الطريقة التي يمكنك بها اجتياز نظام ملفات كلاسيكي برمجياً.

استخدام سرد البيانات المسطح

بشكل افتراضي، تقوم عملية الإدراج بإرجاع الكائنات الثنائية كبيرة الحجم في إدراج بيانات قائمة كاملة. في قائمة مسطحة، لا يتم تنظيم الكائنات الثنائية كبيرة الحجم بواسطة الدليل الظاهري.

يسرد المثال التالي الكائنات الثنائية الكبيرة في الحاوية المحددة باستخدام قائمة مسطحة. يتضمن هذا المثال لقطات الكائنات الثنائية كبيرة الحجم وبيانات تعريف الكائن الثنائي كبير الحجم، إذا كانت موجودة:

async function listBlobsFlat(containerClient) {

  const maxPageSize = 2;

  // Some options for filtering results
  const listOptions = {
    includeMetadata: true,
    includeSnapshots: true,
    prefix: '' // Filter results by blob name prefix
  };

  console.log("Blobs flat list (by page):");
  for await (const response of containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize })) {
    console.log("- Page:");
    if (response.segment.blobItems) {
      for (const blob of response.segment.blobItems) {
        console.log(`  - ${blob.name}`);
      }
    }
  }
}

async function listBlobsFlat(
  containerClient: ContainerClient
): Promise<void> {
  
  const maxPageSize = 2;

  // Some options for filtering results
  const listOptions: ContainerListBlobsOptions = {
    includeMetadata: true,
    includeSnapshots: true,
    prefix: '' // Filter results by blob name prefix
  };

  console.log("Blobs flat list(by page):");
  for await (const response of containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize })) {
    console.log("- Page:");
    if (response.segment.blobItems) {
      for (const blob of response.segment.blobItems) {
        console.log(`  - ${blob.name}`);
      }
    }
  }
}

سيكون إخراج النموذج مشابه لما يلي:

Blobs flat list (by page):
- Page:
  - a1
  - a2
- Page:
  - folder1/b1
  - folder1/b2
- Page:
  - folder2/sub1/c
  - folder2/sub1/d

استخدام إدراج القائمة الهرمية

عند استدعاء عملية إدراج قائمة هرمية، يعمل Azure Storage على إرجاع الكائنات الثنائية كبيرة الحجم والدلائل الظاهرية في المستوى الأول من التسلسل الهرمي.

لسرد الكائنات الثنائية كبيرة الحجم هرميا، استخدم الأسلوب التالي:

• BlobContainerClient.listBlobsByHierarchy

يسرد المثال التالي الكائنات الثنائية كبيرة الحجم في الحاوية المحددة باستخدام قائمة هرمية. في هذا المثال، يتم تعيين معلمة البادئة في البداية إلى سلسلة فارغة لسرد كافة الكائنات الثنائية كبيرة الحجم في الحاوية. ثم يستدعي المثال عملية القائمة بشكل متكرر لاجتياز التسلسل الهرمي للدليل الظاهري وقوائم الكائنات الثنائية كبيرة الحجم.

// Recursively list virtual folders and blobs
async function listBlobHierarchical(containerClient, delimiter='/') {
  
  const maxPageSize = 20;

  // Some options for filtering list
  const listOptions = {
    prefix: '' // Filter results by blob name prefix   
  };

  let i = 1;
  console.log(`Folder ${delimiter}`);

  for await (const response of containerClient
    .listBlobsByHierarchy(delimiter, listOptions)
    .byPage({ maxPageSize })) {

    console.log(`   Page ${i++}`);
    const segment = response.segment;

    if (segment.blobPrefixes) {

      // Do something with each virtual folder
      for await (const prefix of segment.blobPrefixes) {

        // Build new delimiter from current and next
        await listBlobHierarchical(containerClient, `${delimiter}${prefix.name}`);
      }
    }

    for (const blob of response.segment.blobItems) {

      // Do something with each blob
      console.log(`\tBlobItem: name - ${blob.name}`);
    }
  }
}

// Recursively list virtual folders and blobs
async function listBlobHierarchical(
  containerClient: ContainerClient,
  delimiter = '/'
): Promise<void> {

  const maxPageSize = 20;

  // Some options for filtering results
  const listOptions: ContainerListBlobsOptions = {
    prefix: '' // Filter results by blob name prefix
  };

  let i = 1;
  console.log(`Folder ${delimiter}`);

  for await (const response of containerClient
    .listBlobsByHierarchy(delimiter, listOptions)
    .byPage({ maxPageSize })) {
    console.log(`   Page ${i++}`);
    const segment = response.segment;

    if (segment.blobPrefixes) {
      // Do something with each virtual folder
      for await (const prefix of segment.blobPrefixes) {
        // Build new delimiter from current and next
        await listBlobHierarchical(
          containerClient,
          `${delimiter}${prefix.name}`
        );
      }
    }

    for (const blob of response.segment.blobItems) {
      // Do something with each blob
      console.log(`\tBlobItem: name - ${blob.name}`);
    }
  }
}

سيكون إخراج النموذج مشابه لما يلي:

Folder /
   Page 1
        BlobItem: name - a1
        BlobItem: name - a2
   Page 2
Folder /folder1/
   Page 1
        BlobItem: name - folder1/b1
        BlobItem: name - folder1/b2
Folder /folder2/
   Page 1
Folder /folder2/sub1/
   Page 1
        BlobItem: name - folder2/sub1/c
        BlobItem: name - folder2/sub1/d
   Page 2
        BlobItem: name - folder2/sub1/e

الموارد

لمعرفة المزيد حول كيفية سرد الكائنات الثنائية كبيرة الحجم باستخدام مكتبة عميل Azure Blob Storage ل JavaScript، راجع الموارد التالية.

نماذج التعليمات البرمجية

• عرض نماذج التعليمات البرمجية JavaScript وTypeScript من هذه المقالة (GitHub)

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

يحتوي Azure SDK ل JavaScript على مكتبات تستند إلى واجهة برمجة تطبيقات AZURE REST، ما يسمح لك بالتفاعل مع عمليات REST API من خلال نماذج JavaScript المألوفة. تستخدم أساليب مكتبة العميل لإدراج الكائنات الثنائية كبيرة الحجم عملية REST API التالية:

• قائمة الكائنات الثنائية كبيرة الحجم (REST API)

موارد مكتبة العميل

• الوثائق المرجعية لمكتبة العميل
• التعليمات البرمجية لمصدر مكتبة عميل
• الحزمة (npm)

(راجع أيضًا )

• تعداد موارد الكائنات الثنائية كبيرة الحجم
• تعيين إصدار الكائن الثنائي كبير الحجم