مشاركة عبر

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

  • مقالة

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

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

إعداد بيئتك

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

تثبيت الوحدات النمطية

تثبيت الوحدة النمطية azblob باستخدام الأمر التالي:

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

للمصادقة باستخدام معرف Microsoft Entra (مستحسن)، قم بتثبيت الوحدة النمطية azidentity باستخدام الأمر التالي:

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

إضافة مسارات الاستيراد

في ملف التعليمات البرمجية، أضف مسارات الاستيراد التالية:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

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

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

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

func getServiceClientTokenCredential(accountURL string) *azblob.Client {
    // Create a new service client with token credential
    credential, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(accountURL, credential, nil)
    handleError(err)

    return client
}

التصريح

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

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

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

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

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

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

بشكل افتراضي، تعرض عملية السرد ما يصل إلى 5000 نتيجة في المرة الواحدة. لإرجاع مجموعة أصغر من النتائج، قم بتوفير قيمة غير صفرية للحقل MaxResults في ListBlobsFlatOptions أو ListBlobsHierarchyOptions.

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

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

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

لتضمين بيانات تعريف الكائن الثنائي كبير الحجم مع النتائج، قم بتعيين Metadata الحقل إلى true كجزء من ListBlobsInclude. يتضمن Azure Storage بيانات التعريف مع كل كائن ثنائي كبير الحجم يتم إرجاعه، لذلك لا تحتاج إلى إحضار بيانات تعريف الكائن الثنائي كبير الحجم بشكل منفصل.

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

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

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

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

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

إشعار

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

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

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

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

func listBlobsFlat(client *azblob.Client, containerName string) {
    // List the blobs in the container
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
    })

    fmt.Println("List blobs flat:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

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

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

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

func listBlobsFlatOptions(client *azblob.Client, containerName string, prefix string) {
    // List the blobs in the container with a prefix
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Prefix: to.Ptr(prefix),
    })

    fmt.Println("List blobs with prefix:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

عند تمرير سلسلة بادئة من "عينة"، يكون الإخراج مشابها لما يلي:

List blobs with prefix:
sample-blob1.txt
sample-blob2.txt
sample-blob3.txt

إشعار

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

للحصول على خيار إدخال قائمة بديل عند العمل مع مساحة اسم هرمية، راجع NewListPathsPager.

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

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

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

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

func listBlobsHierarchy(client *azblob.Client, containerName string, prefix string) {
    // Reference the container as a client object
    containerClient := client.ServiceClient().NewContainerClient(containerName)

    pager := containerClient.NewListBlobsHierarchyPager("/", &container.ListBlobsHierarchyOptions{
        Prefix:     to.Ptr(prefix),
        MaxResults: to.Ptr(int32(1)), // MaxResults set to 1 for demonstration purposes
    })

    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        if resp.Segment.BlobPrefixes != nil {
            for _, prefix := range resp.Segment.BlobPrefixes {
                fmt.Println("Virtual directory prefix:", *prefix.Name)

                // Recursively list blobs in the prefix
                listBlobsHierarchy(client, containerName, *prefix.Name)
            }
        }

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println("Blob:", *blob.Name)
        }
    }
}

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

Virtual directory prefix: folderA/
Blob: folderA/file1.txt
Blob: folderA/file2.txt
Blob: folderA/file3.txt
Virtual directory prefix: folderA/folderB/
Blob: folderA/folderB/file1.txt
Blob: folderA/folderB/file2.txt
Blob: folderA/folderB/file3.txt

إشعار

تهدف نماذج التعليمات البرمجية في هذا الدليل إلى مساعدتك في البدء في Azure Blob Storage وGo. يجب تعديل معالجة Context الأخطاء والقيم لتلبية احتياجات التطبيق الخاص بك.

الموارد

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

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

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

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

موارد وحدة العميل

(راجع أيضًا )

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

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