التشغيل السريع: مكتبة عميل مساحة تخزين Azure Blob ل Python

إشعار

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

إشعار

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

ابدأ مع مكتبة عميل مساحة تخزين Azure Blob ل Python لإدارة الكائنات الثنائية كبيرة الحجم والحاويات.

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

في هذه المقالة، يمكنك استخدام Azure Developer CLI لنشر موارد Azure وتشغيل تطبيق وحدة تحكم مكتملة مع بعض الأوامر فقط.

الوثائق | |

يوضح لك هذا الفيديو كيفية البدء في استخدام مكتبة عميل مساحة تخزين Azure Blob ل Python.

يتم أيضا وصف الخطوات الواردة في الفيديو في الأقسام التالية.

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

الإعداد

يرشدك هذا القسم خلال إعداد مشروع للعمل مع مكتبة عميل مساحة تخزين Azure Blob ل Python.

إنشاء مشروع

إنشاء تطبيق Python يسمى blob-quickstart.

  1. في نافذة وحدة التحكم (مثل PowerShell أو Bash)، قم بإنشاء دليل جديد للمشروع:

    mkdir blob-quickstart

  2. قم بالتبديل إلى دليل blob-quickstart الذي تم إنشاؤه حديثا:

    cd blob-quickstart

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

من دليل المشروع، قم بتثبيت حزم مكتبات عملاء مساحة تخزين Azure Blob و Azure Identity باستخدام أمر pip install. تحتاج إلى حزمة azure-identity للاتصالات بدون كلمة مرور بخدمات Azure.

pip install azure-storage-blob azure-identity

إعداد إطار عمل التطبيق

من دليل المشروع، اتبع هذه الخطوات لإنشاء البنية الأساسية للتطبيق:

  1. افتح ملفا نصيا جديدا في محرر التعليمات البرمجية.
  2. أضف import عبارات، وأنشئ هيكل البرنامج، وأضف التعامل الأساسي مع الاستثناءات، كما هو موضح في المثال التالي.
  3. احفظ الملف الجديد كما blob_quickstart.py في دليل blob-quickstart .
import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

try:
    print("Azure Blob Storage Python quickstart sample")

    # Quickstart code goes here

except Exception as ex:
    print('Exception:')
    print(ex)

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

تهيئة قالب Azure Developer CLI ونشر الموارد

من دليل فارغ، اتبع هذه الخطوات لتهيئة القالب azd وتوفير موارد Azure والبدء في استخدام التعليمات البرمجية:

  • استنساخ أصول مستودع التشغيل السريع من GitHub وتهيئة القالب محليا:

    azd init --template blob-storage-quickstart-python

    يتم طلب منك تقديم المعلومات التالية:

    • Environment name: Azure يستخدم واجهة المطور هذه القيمة كبادئة لكل الموارد Azure التي تنشئها. يجب أن يكون الاسم فريدا في جميع اشتراكات Azure وأن يتراوح طوله بين 3 و24 حرفا. يمكن أن يحتوي الاسم على أرقام وأحرف صغيرة فقط.

  • تسجيل الدخول إلى Azure:

    azd auth login

  • توفير الموارد ونشرها في Azure:

    azd up

    يتم طلب منك تقديم المعلومات التالية:

    • الاشتراك: اشتراك Azure الذي يتم نشر مواردك إليه.
    • الموقع: منطقة Azure حيث يتم نشر مواردك.

    قد يستغرق انتهاء النشر بضع دقائق. المخرجات من azd up الأمر تتضمن اسم حساب التخزين الذي تم إنشاؤه حديثا، والذي تحتاجه لاحقا لتشغيل الكود.

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

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

  • تثبيت الحزم: في الدليل المحلي، قم بتثبيت حزم مكتبات عملاء مساحة تخزين Azure Blob و Azure Identity عن طريق تشغيل الأمر التالي: pip install azure-storage-blob azure-identity
  • تحديث اسم حساب التخزين: في الدليل المحلي، قم بتحرير الملف المسمى blob_quickstart.py. ابحث عن <storage-account-name> العنصر النائب واستبدله بالاسم الفعلي لحساب التخزين الذي أنشأه azd up الأمر . ا‏‏حفظ التغييرات.
  • تشغيل المشروع: شغل الأمر التالي لتشغيل التطبيق: python blob_quickstart.py.
  • مراقبة الإخراج: ينشئ هذا التطبيق ملف اختبار في مجلد البيانات المحلي الخاص بك ويحمله إلى حاوية في حساب التخزين. ثم يسرد المثال النقط في الحاوية ثم يقوم بتحميل الملف باسم جديد بحيث يمكنك مقارنة الملفات القديمة والجديدة.

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

عند الانتهاء من اختبار التعليمات البرمجية، راجع قسم تنظيف الموارد لحذف الموارد التي أنشأها azd up الأمر.

نموذج الكائن

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

  • حساب التخزين
  • حاوية في حساب التخزين
  • كائن تخزين بيانات ثنائية كبيرة في الحاوية

يوضح الرسم التخطيطي التالي العلاقة بين هذه الموارد:

لقطة شاشة لبنية تخزين Blob تظهر حساب تخزين، وحاوية، وكتل.

استخدم فئات Python التالية للتفاعل مع هذه الموارد:

  • BlobServiceClient: استخدم فئة BlobServiceClient للعمل مع موارد تخزين Azure وحاويات blob.
  • ContainerClient: استخدم فئة ContainerClient للعمل مع الحاويات تخزين Azure وكتلها.
  • BlobClient: استخدم فئة BlobClient للعمل مع تخزين Azure blobs.

أمثلة على التعليمات البرمجية

توضح لك أمثلة أجزاء التعليمات البرمجية هذه كيفية القيام بالمهام التالية باستخدام مكتبة عميل مساحة تخزين Azure Blob لـ Python:

إشعار

يتضمن قالب Azure Developer CLI ملفا مع نموذج التعليمات البرمجية في مكانه بالفعل. توفر الأمثلة التالية تفاصيل لكل جزء من نموذج التعليمات البرمجية. ينفذ القالب أسلوب المصادقة بدون كلمة مرور الموصى بها، كما هو موضح في قسم Authenticate to Azure . يتم عرض أسلوب سلسلة الاتصال كبديل، ولكن لا يتم استخدامه في القالب ولا يوصى به للتعليمات البرمجية للإنتاج.

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

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

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

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

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

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

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

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

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

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

هام

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

  1. في مدخل Microsoft Azure، حدد موقع حساب التخزين الخاص بك باستخدام شريط البحث الرئيسي أو شريط التنقل الأيسر.

  2. في صفحة نظرة عامة على حساب التخزين، حدد التحكم بالوصول (IAM) من القائمة اليسرى.

  3. حدد صفحة التحكم بالوصول (IAM)، وحدد علامة تبويب تعيينات الدور.

  4. حدد + إضافة من القائمة العلوية ثم إضافة تعيين الدور من القائمة المنسدلة الناتجة.

    لقطة شاشة توضح كيفية تعيين دور.

  5. استخدم مربع البحث لتصفية النتائج إلى الدور المطلوب. في هذا المثال، ابحث عن مساهم بيانات Storage Blob وحدد النتيجة المطابقة ثم اختر التالي.

  6. ضمن تعيين الوصول إلى، حدد المستخدم أو المجموعة أو كيان الخدمة، ثم اختر + تحديد الأعضاء.

  7. في مربع الحوار، ابحث عن اسم مستخدم Microsoft Entra (عنوان بريدك الإلكتروني user@domain عادة) ثم اختر تحديد في أسفل مربع الحوار.

  8. حدد مراجعة + تعيين للانتقال إلى الصفحة النهائية، ثم مراجعة + تعيين مرة أخرى لإكمال العملية.

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

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

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

    تسجيل الدخول إلى Azure عبر Azure CLI باستخدام الأمر التالي:

    az login

  2. لاستخدام DefaultAzureCredential، تأكد من تثبيت حزمة azure-identity، واستيراد الفئة:

    from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

  3. أضف هذه التعليمة البرمجية try داخل الكتلة. عندما يعمل الكود على محطة العمل المحلية لديك، يستخدم DefaultAzureCredential بيانات اعتماد المطور للأداة ذات الأولوية التي سجلت دخولك فيها للمصادقة مع Azure. تتضمن أمثلة هذه الأدوات Azure CLI أو تعليمة Visual Studio برمجية.

    account_url = "https://<storageaccountname>.blob.core.windows.net"
default_credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=default_credential)

  4. قم بتحديث اسم حساب التخزين في رابط المستخدمين الخاص بكائنك BlobServiceClient . يمكنك العثور على اسم حساب التخزين في صفحة النظرة العامة على بوابة Azure.

    لقطة شاشة لصفحة بوابة Azure تبرز اسم حساب التخزين.

    إشعار

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

إنشاء حاوية

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

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

# Create a unique name for the container
container_name = str(uuid.uuid4())

# Create the container
container_client = blob_service_client.create_container(container_name)

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

هام

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

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

رفع كتلة إلى حاوية باستخدام upload_blob. ينشئ مثال التعليمات البرمجية ملفا نصيا في دليل البيانات المحلي لتحميله إلى الحاوية.

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

# Create a local directory to hold blob data
local_path = "./data"
os.mkdir(local_path)

# Create a file in the local data directory to upload and download
local_file_name = str(uuid.uuid4()) + ".txt"
upload_file_path = os.path.join(local_path, local_file_name)

# Write text to the file
file = open(file=upload_file_path, mode='w')
file.write("Hello, World!")
file.close()

# Create a blob client using the local file name as the name for the blob
blob_client = blob_service_client.get_blob_client(container=container_name, blob=local_file_name)

print("\nUploading to Azure Storage as blob:\n\t" + local_file_name)

# Upload the created file
with open(file=upload_file_path, mode="rb") as data:
    blob_client.upload_blob(data)

لمعرفة المزيد عن رفع الكتل واستكشاف المزيد من عينات الكود، راجع رفع كتلة تحتوي على Python.

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

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

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

print("\nListing blobs...")

# List the blobs in the container
blob_list = container_client.list_blobs()
for blob in blob_list:
    print("\t" + blob.name)

للمزيد من المعلومات حول قائمة الكتل واستكشاف المزيد من عينات الكود، راجع List blobs مع Python.

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

نزّل الكائن الثنائي كبير الحجم الذي تم إنشاؤه مسبقاً عن طريق استدعاء الأسلوب download_blob. يضيف مثال التعليمات البرمجية اللاحقة "DOWNLOAD" إلى اسم الملف حتى يمكنك مشاهدة كلا الملفين في نظام الملفات المحلية.

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

# Download the blob to a local file
# Add 'DOWNLOAD' before the .txt extension so you can see both files in the data directory
download_file_path = os.path.join(local_path, str.replace(local_file_name ,'.txt', 'DOWNLOAD.txt'))
container_client = blob_service_client.get_container_client(container= container_name) 
print("\nDownloading blob to \n\t" + download_file_path)

with open(file=download_file_path, mode="wb") as download_file:
 download_file.write(container_client.download_blob(blob.name).readall())

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

احذف حاوية

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

يتوقف التطبيق مؤقتا المستخدم عن طريق الاتصال input() قبل أن يحذف النقطة والحاوية والملفات المحلية. تحقق من إنشاء الموارد بشكل صحيح قبل حذفها.

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

# Clean up
print("\nPress the Enter key to begin clean up")
input()

print("Deleting blob container...")
container_client.delete_container()

print("Deleting the local source and downloaded files...")
os.remove(upload_file_path)
os.remove(download_file_path)
os.rmdir(local_path)

print("Done")

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

تشغيل التعليمات البرمجية

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

اذهب إلى الدليل الذي يحتوي على ملف blob_quickstart.py ، وشغل الأمر التالي python لتشغيل التطبيق:

python blob_quickstart.py

يشبه إخراج التطبيق المثال التالي (حذف قيم UUID لسهولة القراءة):

Azure Blob Storage Python quickstart sample

Uploading to Azure Storage as blob:
        quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

قبل البدء في عملية التنظيف، تحقق من مجلد البيانات للملفين. يمكنك مقارنتها ورؤية أنهما متطابقان.

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

بعد التحقق من الملفات وإنهاء الاختبار، اضغط Enter لحذف ملفات الاختبار مع الحاوية التي أنشأتها في حساب التخزين. يمكنك أيضا استخدام Azure CLI لحذف الموارد.

عندما تنتهي من البدء السريع، قم بتنظيف الموارد التي أنشأتها بتنفيذ الأمر التالي:

azd down

ستتم مطالبتك بتأكيد حذف الموارد. أدخل y للتأكيد.

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

نماذج تخزين Azure وأدلة المطور ل Python

  • Last updated on