التشغيل السريع: وحدة عميل Azure Blob Storage ل Go

ابدأ مع وحدة عميل Azure Blob Storage ل Go لإدارة الكائنات الثنائية كبيرة الحجم والحاويات. يُرجى اتباع هذه الخطوات لتثبيت الحزمة وتجربة التعليمات البرمجية للمهام الأساسية.

حزمة التعليمات البرمجية | المصدر لمكتبة الوثائق المرجعية | لواجهة برمجة التطبيقات (pkg.go.dev)

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

• اشتراك Azure - إنشاء اشتراك مجاني
• حساب تخزين Azure - إنشاء حساب تخزين
• Go 1.18+

الإعداد

يرشدك هذا القسم خلال إعداد مشروع للعمل مع وحدة عميل Azure Blob Storage ل Go.

قم بتنزيل نموذج الطلب

يُعد نموذج التطبيق المستخدم في التشغيل السريع أحد تطبيقات Go الأساسية.

استخدم git لتنزيل نسخة من التطبيق إلى بيئة التطوير الخاصة بك.

git clone https://github.com/Azure-Samples/storage-blobs-go-quickstart 

يستنسخ هذا الأمر المستودع إلى مجلد git المحلي. لفتح نموذج Go ل Blob Storage، ابحث عن الملف المسمى storage-quickstart.go.

قم بتثبيت الحِزَم

للعمل مع blob وموارد الحاوية في حساب تخزين، قم بتثبيت حزمة 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

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

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

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

DefaultAzureCredential هو تنفيذ سلسلة بيانات اعتماد مقدمة من مكتبة عميل Azure Identity ل Go. DefaultAzureCredential يدعم أساليب مصادقة متعددة ويحدد الطريقة التي يجب استخدامها في وقت التشغيل. يمكن هذا النهج تطبيقك من استخدام أساليب مصادقة مختلفة في بيئات مختلفة (البيئة المحلية مقابل بيئة التشغيل) دون تنفيذ التعليمات البرمجية الخاصة بالبيئة.

لمعرفة المزيد حول الترتيب والمواقع التي DefaultAzureCredential تبحث عن بيانات الاعتماد فيها، راجع نظرة عامة على مكتبة Azure Identity.

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

تعيين أدوار لحساب مستخدم Microsoft Entra

عند التطوير محليًا، تأكد من أن حساب المستخدم الذي يصل إلى بيانات الكائن الثنائي كبير الحجم لديه الأذونات الصحيحة. ستحتاج إلى Storage Blob Data Contributor لقراءة بيانات الكائن الثنائي كبير الحجم وكتابتها. لتعيين هذا الدور لنفسك، ستحتاج إلى تعيين دور مسؤول وصول المستخدم، أو دور آخر يتضمن إجراء Microsoft.Authorization/roleAssignments/write . يمكنك تعيين أدوار Azure RBAC لمستخدم باستخدام مدخل Microsoft Azure أو Azure CLI أو Azure PowerShell. يمكنك معرفة المزيد حول النطاقات المتوفرة لتعيينات الأدوار في صفحة نظرة عامة على النطاق.

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

سيقوم المثال التالي بتعيين دور Storage Blob Data Contributor إلى حساب المستخدم الخاص بك، والذي يوفر حق الوصول للقراءة والكتابة إلى بيانات blob في حساب التخزين الخاص بك.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

تسجيل الدخول وتوصيل التعليمات البرمجية لتطبيقك بـ Azure باستخدام DefaultAzureCredential

يمكنك تخويل الوصول إلى البيانات في حساب التخزين الخاص بك باستخدام الخطوات التالية:

1. تأكد من مصادقتك باستخدام نفس حساب Microsoft Entra الذي قمت بتعيين الدور له على حساب التخزين الخاص بك. يوضح المثال التالي كيفية المصادقة عبر Azure CLI:

   az login
   

2. للاستخدام DefaultAzureCredential في تطبيق Go، قم بتثبيت الوحدة النمطية azidentity باستخدام الأمر التالي:

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

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

لمعرفة المزيد حول أساليب المصادقة المختلفة، راجع مصادقة Azure باستخدام Azure SDK لـ Go.

تشغيل تطبيق العرض التوضيحي

يقوم مثال التعليمات البرمجية بتنفيذ الإجراءات التالية:

• إنشاء كائن عميل معتمد للوصول إلى البيانات عبر DefaultAzureCredential
• إنشاء حاوية في حساب تخزين
• تحميل كائن ثنائي كبير الحجم إلى الحاوية
• يسرد الكائنات الثنائية كبيرة الحجم في الحاوية
• تنزيل بيانات الكائن الثنائي كبير الحجم في مخزن مؤقت
• حذف كائن ثنائي كبير الحجم وموارد الحاوية التي أنشأها التطبيق

قبل تشغيل النموذج، افتح ملف storage-quickstart.go . استبدل <storage-account-name> باسم حساب Azure Storage الخاص بك.

ثم قم بتشغيل التطبيق باستخدام الأمر التالي:

go run storage-quickstart.go

يتشابه إخراج التطبيق مع المثال التالي:

Azure Blob storage quick start sample
Creating a container named quickstart-sample-container
Uploading a blob named sample-blob
Listing the blobs in the container:
sample-blob
Blob contents:

Hello, world! This is a blob.

Press enter key to delete resources and exit the application.

Cleaning up.
Deleting the blob sample-blob
Deleting the container quickstart-sample-container

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

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

بعد ذلك، نستعرض نموذج التعليمات البرمجية لفهم كيفية عملها.

تخويل الوصول وإنشاء كائن عميل

يبدأ العمل مع أي مورد Azure باستخدام SDK بإنشاء كائن عميل. لإنشاء كائن العميل، يستدعي نموذج التعليمات البرمجية azblob. NewClient بالقيم التالية:

• serviceURL - عنوان URL لحساب التخزين
• cred - بيانات اعتماد Microsoft Entra التي تم الحصول عليها عبر الوحدة النمطية azidentity
• options - خيارات العميل؛ تمرير nil لقبول القيم الافتراضية

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

// TODO: replace <storage-account-name> with your actual storage account name
url := "https://<storage-account-name>.blob.core.windows.net/"
ctx := context.Background()

credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)

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

إنشاء حاوية

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

ينشئ مثال التعليمات البرمجية التالي حاوية جديدة تسمى quickstart-sample-container في حساب التخزين:

// Create the container
containerName := "quickstart-sample-container"
fmt.Printf("Creating a container named %s\n", containerName)
_, err = client.CreateContainer(ctx, containerName, nil)
handleError(err)

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

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

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

يقوم مثال التعليمات البرمجية التالي بتحميل بيانات الكائن الثنائي كبير الحجم إلى الحاوية المحددة باستخدام أسلوب UploadBuffer :

data := []byte("\nHello, world! This is a blob.\n")
blobName := "sample-blob"

// Upload to data to blob storage
fmt.Printf("Uploading a blob named %s\n", blobName)
_, err = client.UploadBuffer(ctx, containerName, blobName, data, &azblob.UploadBufferOptions{})
handleError(err)

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

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

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

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

// List the blobs in the container
fmt.Println("Listing the blobs in the container:")

pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
	Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
})

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

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

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

تنزيل كائنات البيانات الثنائية

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

يقوم مثال التعليمات البرمجية التالي بتنزيل كائن ثنائي كبير الحجم وكتابة المحتويات إلى وحدة التحكم:

// Download the blob
get, err := client.DownloadStream(ctx, containerName, blobName, nil)
handleError(err)

downloadedData := bytes.Buffer{}
retryReader := get.NewRetryReader(ctx, &azblob.RetryReaderOptions{})
_, err = downloadedData.ReadFrom(retryReader)
handleError(err)

err = retryReader.Close()
handleError(err)

// Print the contents of the blob we created
fmt.Println("Blob contents:")
fmt.Println(downloadedData.String())

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

تنظيف الموارد

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

// Delete the blob
fmt.Printf("Deleting the blob " + blobName + "\n")

_, err = client.DeleteBlob(ctx, containerName, blobName, nil)
handleError(err)

// Delete the container
fmt.Printf("Deleting the container " + containerName + "\n")
_, err = client.DeleteContainer(ctx, containerName, nil)
handleError(err)

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

الخطوة التالية