مشاركة عبر

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

  • مقالة

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

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

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

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

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

لسرد الكائنات الثنائية كبيرة الحجم في حساب تخزين، قم بإنشاء ContainerClient ثم استدعاء إحدى هذه الطرق:

يمكن العثور على الوظائف المتعلقة بها في الطرق التالية:

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

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

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

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

const listOptions: ContainerListBlobsOptions = {
    includeCopy: false,                 // include metadata from previous copies
    includeDeleted: false,              // include deleted blobs 
    includeDeletedWithVersions: false,  // include deleted blobs with versions
    includeLegalHost: false,            // include legal host id  
    includeMetadata: true,              // include custom metadata
    includeSnapshots: true,             // include snapshots
    includeTags: true,                  // include indexable tags
    includeUncommittedBlobs: false,     // include uncommitted blobs
    includeVersions: false,             // include all blob version
    prefix: ''                          // filter by blob name prefix
};

إرجاع بيانات التعريف

يمكنك إرجاع بيانات تعريف كائن ثنائي كبير مع النتائج عن طريق تحديد خاصية includeMetadata في خيارات القائمة.

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

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

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

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

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

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

يسرد المثال التالي الكائنات الثنائية الكبيرة في الحاوية المحددة باستخدام قائمة مسطحة.

async function listBlobsFlatWithPageMarker(
  containerClient: ContainerClient
): Promise<void> {
  // page size
  const maxPageSize = 2;

  let i = 1;

  // some options for filtering list
  const listOptions: ContainerListBlobsOptions = {
    includeCopy: false, // include metadata from previous copies
    includeDeleted: false, // include deleted blobs
    includeDeletedWithVersions: false, // include deleted blobs with versions
    includeLegalHold: false, // include legal hold
    includeMetadata: true, // include custom metadata
    includeSnapshots: false, // include snapshots
    includeTags: true, // include indexable tags
    includeUncommitedBlobs: false, // include uncommitted blobs
    includeVersions: false, // include all blob version
    prefix: '' // filter by blob name prefix
  };

  let iterator = containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize });
  let response = (await iterator.next()).value;

  // Prints blob names
  for (const blob of response.segment.blobItems) {
    console.log(`Flat listing: ${i++}: ${blob.name}`);
  }

  // Gets next marker
  const marker = response.continuationToken;

  // Passing next marker as continuationToken
  iterator = containerClient
    .listBlobsFlat({
      includeMetadata: true,
      includeSnapshots: false,
      includeTags: true,
      includeVersions: false,
      prefix: ''
    })
    .byPage({
      continuationToken: marker,
      maxPageSize: maxPageSize * 2
    });
  response = (await iterator.next()).value;

  // Prints next blob names
  for (const blob of response.segment.blobItems) {
    console.log(`Flat listing: ${i++}: ${blob.name}`);
  }
}

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

Flat listing: 1: a1
Flat listing: 2: a2
Flat listing: 3: folder1/b1
Flat listing: 4: folder1/b2
Flat listing: 5: folder2/sub1/c
Flat listing: 6: folder2/sub1/d

إشعار

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

للحصول على خيار إدخال قائمة بديل عند العمل مع مساحة اسم هرمية، راجع سرد محتويات الدليل (Azure Data Lake Storage Gen2).

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

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

لسرد الكائنات الثنائية الكبيرة بشكل هرمي، اتصل بأسلوب BlobContainerClient.listBlobsByHierarchy.

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

// Recursively list virtual folders and blobs
async function listBlobHierarchical(
  containerClient: ContainerClient,
  virtualHierarchyDelimiter = '/'
): Promise<void> {
  // page size - artificially low as example
  const maxPageSize = 2;

  // some options for filtering list
  const listOptions: ContainerListBlobsOptions = {
    includeCopy: false, // include metadata from previous copies
    includeDeleted: false, // include deleted blobs
    includeDeletedWithVersions: false, // include deleted blobs with versions
    includeLegalHold: false, // include legal hold
    includeMetadata: true, // include custom metadata
    includeSnapshots: false, // include snapshots
    includeTags: true, // include indexable tags
    includeUncommitedBlobs: false, // include uncommitted blobs
    includeVersions: false, // include all blob version
    prefix: '' // filter by blob name prefix
  };

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

  for await (const response of containerClient
    .listBlobsByHierarchy(virtualHierarchyDelimiter, 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 virtualHierarchyDelimiter from current and next
        await listBlobHierarchical(
          containerClient,
          `${virtualHierarchyDelimiter}${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، راجع الموارد التالية.

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

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

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

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

(راجع أيضًا )