مشاركة عبر

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

  • مقالة

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

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

إعداد بيئتك

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

تثبيت الحزم

من دليل المشروع الخاص بك، قم بتثبيت حزم Azure Blob Storage ومكتبات عميل Azure Identity باستخدام dotnet add package الأمر . حزمة Azure.Identity مطلوبة للاتصالات بدون كلمة مرور بخدمات Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

أضف توجيهات using

أضف هذه using التوجيهات إلى أعلى ملف التعليمات البرمجية:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

قد تتطلب بعض أمثلة التعليمات البرمجية في هذه المقالة توجيهات إضافية using .

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

لتوصيل تطبيق ب Blob Storage، قم بإنشاء مثيل BlobServiceClient. يوضح المثال التالي كيفية إنشاء كائن عميل باستخدام DefaultAzureCredential للتخويل:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

يمكنك تسجيل عميل خدمة لإدخال التبعية في تطبيق .NET.

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

التصريح

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

private static async Task ListBlobsFlatListing(BlobContainerClient blobContainerClient, 
                                               int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = blobContainerClient.GetBlobsAsync()
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobItem> blobPage in resultSegment)
        {
            foreach (BlobItem blobItem in blobPage.Values)
            {
                Console.WriteLine("Blob name: {0}", blobItem.Name);
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

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

Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

إشعار

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

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

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

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

لإدراج الكائنات الثنائية كبيرة الحجم في قائمة بشكل هرمي، استدعِ الأسلوب BlobContainerClient.GetBlobsByHierarchy، أو الأسلوب BlobContainerClient.GetBlobsByHierarchyAsync.

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

private static async Task ListBlobsHierarchicalListing(BlobContainerClient container, 
                                                       string prefix, 
                                                       int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = container.GetBlobsByHierarchyAsync(prefix:prefix, delimiter:"/")
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobHierarchyItem> blobPage in resultSegment)
        {
            // A hierarchical listing may return both virtual directories and blobs.
            foreach (BlobHierarchyItem blobhierarchyItem in blobPage.Values)
            {
                if (blobhierarchyItem.IsPrefix)
                {
                    // Write out the prefix of the virtual directory.
                    Console.WriteLine("Virtual directory prefix: {0}", blobhierarchyItem.Prefix);

                    // Call recursively with the prefix to traverse the virtual directory.
                    await ListBlobsHierarchicalListing(container, blobhierarchyItem.Prefix, null);
                }
                else
                {
                    // Write out the name of the blob.
                    Console.WriteLine("Blob name: {0}", blobhierarchyItem.Blob.Name);
                }
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

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

Virtual directory prefix: FolderA/
Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt

Virtual directory prefix: FolderA/FolderB/
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt

Virtual directory prefix: FolderA/FolderB/FolderC/
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

إشعار

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

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

لإدراج إصدارات أو لقطات الكائنات الثنائية كبيرة الحجم، حدد معلمة BlobStates باستخدام حقل الإصدار أو اللقطة. يتم إدراج الإصدارات واللقطات من الأقدم إلى الأحدث.

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

private static void ListBlobVersions(BlobContainerClient blobContainerClient, 
                                           string blobName)
{
    try
    {
        // Call the listing operation, specifying that blob versions are returned.
        // Use the blob name as the prefix. 
        var blobVersions = blobContainerClient.GetBlobs
            (BlobTraits.None, BlobStates.Version, prefix: blobName)
            .OrderByDescending(version => version.VersionId).Where(blob => blob.Name == blobName);

        // Construct the URI for each blob version.
        foreach (var version in blobVersions)
        {
            BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobContainerClient.Uri)
            {
                BlobName = version.Name,
                VersionId = version.VersionId
            };

            if ((bool)version.IsLatestVersion.GetValueOrDefault())
            {
                Console.WriteLine("Current version: {0}", blobUriBuilder);
            }
            else
            {
                Console.WriteLine("Previous version: {0}", blobUriBuilder);
            }
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

الموارد

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

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

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

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

(راجع أيضًا )

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

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