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

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

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

إعداد بيئتك

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

لاستخدام أمثلة التعليمات البرمجية في هذه المقالة، اتبع هذه الخطوات لإعداد مشروعك.

إشعار

تستخدم هذه المقالة أداة بناء Maven لإنشاء التعليمات البرمجية المثال وتشغيلها. تعمل أدوات البناء الأخرى، مثل Gradle، أيضا مع Azure SDK ل Java.

تثبيت الحزم

افتح الملف pom.xml في محرر النصوص الخاص بك. قم بتثبيت الحزم عن طريق تضمين ملف BOM، أو تضمين تبعية مباشرة.

إضافة عبارات الاستيراد

أضف عبارات import التالية:

import com.azure.core.http.rest.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;

التصريح

يجب أن يكون لآلية التخويل الأذونات اللازمة لسرد كائن ثنائي كبير الحجم. للحصول على تفويض باستخدام Microsoft Entra ID (موصى به)، تحتاج إلى Azure RBAC المدمج Storage Blob Data Reader أو أعلى. لمعرفة المزيد، راجع إرشادات التخويل ل List Blobs (REST API).

إنشاء كائن عميل

لتوصيل تطبيق ب مخزن البيانات الثنائية الكبيرة، قم بإنشاء مثيل BlobServiceClient.

يستخدم المثال التالي BlobServiceClientBuilder لإنشاء كائن BlobServiceClient باستخدام DefaultAzureCredential، ويوضح كيفية إنشاء عملاء الحاوية والكائنات الثنائية كبيرة الحجم، إذا لزم الأمر:

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

لمعرفة المزيد حول إنشاء كائنات العميل وإدارتها، راجع إنشاء كائنات العميل التي تتفاعل مع موارد البيانات وإدارتها.

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

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

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

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

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

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

لتصفية قائمة الكائنات الثنائية كبيرة الحجم، مرر سلسلة كمعلمة prefix إلى ListBlobsOptions.setPrefix(String prefix). يمكن أن تتضمن سلسلة البادئة حرفاً واحداً أو أكثر. ثم يقوم تخزين Azure بإرجاع الكائنات الثنائية كبيرة الحجم التي تبدأ أسماؤها بهذه البادئة فقط.

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

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

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

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

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

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

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

public void listBlobsFlat(BlobContainerClient blobContainerClient) {
    System.out.println("List blobs flat:");

    blobContainerClient.listBlobs()
            .forEach(blob -> System.out.printf("Name: %s%n", blob.getName()));
}

عينة الإخراج مشابهة ل:

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

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

public void listBlobsFlatWithOptions(BlobContainerClient blobContainerClient) {
    ListBlobsOptions options = new ListBlobsOptions()
            .setMaxResultsPerPage(2) // Low number for demonstration purposes
            .setDetails(new BlobListDetails()
                    .setRetrieveDeletedBlobs(true));

    System.out.println("List blobs flat:");

    int i = 0;
    Iterable<PagedResponse<BlobItem>> blobPages = blobContainerClient.listBlobs(options, null).iterableByPage();
    for (PagedResponse<BlobItem> page : blobPages) {
        System.out.printf("Page %d%n", ++i);
        page.getElements().forEach(blob -> {
            System.out.printf("Name: %s, Is deleted? %b%n",
                    blob.getName(),
                    blob.isDeleted());
        });
    }
}

عينة الإخراج مشابهة ل:

List blobs flat:
Page 1
Name: file4.txt, Is deleted? false
Name: file5-deleted.txt, Is deleted? true
Page 2
Name: folderA/file1.txt, Is deleted? false
Name: folderA/file2.txt, Is deleted? false
Page 3
Name: folderA/folderB/file3.txt, Is deleted? false

إشعار

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

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

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

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

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

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

public void listBlobsHierarchicalListing(BlobContainerClient blobContainerClient, String prefix/* ="" */) {
    String delimiter = "/";
    ListBlobsOptions options = new ListBlobsOptions()
            .setPrefix(prefix);

    blobContainerClient.listBlobsByHierarchy(delimiter, options, null)
            .forEach(blob -> {
                if (blob.isPrefix()) {
                    System.out.printf("Virtual directory prefix: %s%n", delimiter + blob.getName());
                    listBlobsHierarchicalListing(blobContainerClient, blob.getName());
                } else {
                    System.out.printf("Blob name: %s%n", blob.getName());
                }
            });
}

عينة الإخراج مشابهة ل:

List blobs hierarchical:
Blob name: file4.txt
Virtual directory prefix: /folderA/
Blob name: folderA/file1.txt
Blob name: folderA/file2.txt
Virtual directory prefix: /folderA/folderB/
Blob name: folderA/folderB/file3.txt

إشعار

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

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

مهم

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

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

Warning

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

لطلب نتائج منسقة ب Apache Arrow، قم بتعيين تنسيق تسلسل الاستجابة في ListBlobsOptions إلى StorageResponseSerializationFormat.ARROW عن طريق استدعاء setStorageResponseSerializationFormat، ثم تمرير الخيارات إلى BlobContainerClient.listBlobs. عند استخدام مخرجات Apache Arrow، يمكنك أيضا الاتصال setStartFrom والتحكم setEndBefore في نطاق المسارات التي تم إرجاعها.

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

ListBlobsOptions options = new ListBlobsOptions()
    .setPrefix("folderA/")
    .setStorageResponseSerializationFormat(StorageResponseSerializationFormat.ARROW);

for (BlobItem blobItem : containerClient.listBlobs(options, null)) {
    System.out.println("Blob name: " + blobItem.getName());
}

الموارد

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

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

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

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

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

(راجع أيضًا )

المحتوى ذو الصلة

  • هذه المقالة هي جزء من دليل مطور مخزن البيانات الثنائية الكبيرة ل Java. لمعرفة المزيد، راجع القائمة الكاملة لمقالات دليل المطور في إنشاء تطبيق Java الخاص بك.
  • تاريخ آخر تحديث في