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

• NET.
• Java
• JavaScript
• Python
• ذهب

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

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

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

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

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

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

• ContainerClient.listBlobsFlat

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

• ContainerClient.listBlobsByHierarchy

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

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

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

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

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

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

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

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

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

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

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

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

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

JavaScript

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

TypeScript

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 Data Lake Storage).

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

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

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

• BlobContainerClient.listBlobsByHierarchy

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

JavaScript

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

TypeScript

// 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

إشعار

لا يمكن إدراج لقطات الكتلة في عملية إدراج هرمية.

قائمة الكتل بصيغة Apache Arrow (معاينة)

مهم

قائمة الكتل بصيغة Apache Arrow موجودة حاليا في المعاينة. يتطلب هذا السيناريو نسخة تجريبية (معاينة) من مكتبة عميل مساحة تخزين Azure Blob لجافا سكريبت (على سبيل المثال، @azure/storage-blobإصدار 12.34.0-beta.1 أو إصدار معاينة لاحق). يتم توفير ميزات المعاينة دون اتفاقية على مستوى الخدمة ولا ينصح بها لأعباء العمل الإنتاجية. قد لا تكون بعض الميزات مدعومة، أو قد تكون ذات قدرات محدودة. لمزيد من المعلومات، راجع شروط الاستخدام الإضافية لمعاينات Microsoft Azure.

هذه القدرة مبنية على واجهة برمجة التطبيقات الحالية List Blobs . بدلا من استخدام XML الافتراضي، يستخدم تنسيق Apache Arrow المدمج والعمودي كصيغة استجابة على السلك. تقوم بتفعيله عن طريق تعيين خيار واحد في استدعاء قائمة الحاويات. يقوم ملف تطوير تطوير جافاسكريبت بفك تشفير سهم Apache خلف الكواليس ولا يزال يعيد نفس كائنات العناصر النقطية. هذا النهج يحسن معدل نقل الإدراج ويقلل من وحدة المعالجة المركزية على جانب العميل عند تعداد الحاويات الكبيرة. يحافظ على عقد الاستجابة الذي تعتمد عليه التطبيقات.

Warning

إدراج الكتل بصيغة Apache Arrow غير مدعوم في حسابات التخزين التي تحتوي على مساحة أسماء هرمية (Azure Data Lake Storage).

لطلب نتائج منسقة ب Apache Arrow، قم بتعيين responseFormat خاصية خيارات القائمة على StorageResponseFormat.Arrow، ثم مرر الخيارات إلى ContainerClient.listBlobsFlat. استورد الإينوم StorageResponseFormat من @azure/storage-blob.

المثال التالي يسرد الكتل في حاوية ويطلب النتائج بصيغة Apache Arrow:

const { StorageResponseFormat } = require("@azure/storage-blob");

const options = {
  prefix: "FolderA/",
  responseFormat: StorageResponseFormat.Arrow,
};

for await (const blob of containerClient.listBlobsFlat(options)) {
  console.log("Blob name: " + blob.name);
}

الموارد

لمعرفة المزيد حول كيفية إدراج الكتل باستخدام مكتبة عملاء مساحة تخزين Azure Blob لجافا سكريبت، راجع الموارد التالية.

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

• شاهد عينات من كود JavaScriptوTypeScript من هذا المقال على GitHub.

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

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

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

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

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

(راجع أيضًا )

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