بدء استخدام Azure Blob Storage وPython

مقالة
10/02/2024

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

إذا كنت تبحث عن البدء بمثال كامل، فشاهد التشغيل السريع: مكتبة عميل Azure Blob Storage ل Python.

حزمة مرجع | واجهة برمجة التطبيقات (PyPi) | التعليمات | البرمجية | المصدر للمكتبة عينات تقدم ملاحظات

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

اشتراك Azure - إنشاء اشتراك مجاني
حساب تخزين Azure - إنشاء حساب تخزين
Python 3.8+

إعداد مشروعك

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

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

pip install azure-storage-blob azure-identity

ثم افتح ملف التعليمات البرمجية وأضف عبارات الاستيراد الضرورية. في هذا المثال، نضيف ما يلي إلى ملف .py :

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

معلومات مكتبة عميل Blob:

azure.storage.blob: يحتوي على الفئات الأساسية (كائنات العميل) التي يمكنك استخدامها للعمل على الخدمة والحاويات والكائنات الثنائية كبيرة الحجم.

برمجة غير متزامنة

تدعم مكتبة عميل Azure Blob Storage ل Python واجهات برمجة التطبيقات المتزامنة وغير المتزامنة. تستند واجهات برمجة التطبيقات غير المتزامنة إلى مكتبة Asyncio الخاصة ب Python.

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

تثبيت نقل غير متزامن، مثل aiohttp. يمكنك التثبيت aiohttp مع azure-storage-blob باستخدام أمر تثبيت تبعية اختياري. في هذا المثال، نستخدم الأمر التالي pip install :
```
pip install azure-storage-blob[aio]
```
افتح ملف التعليمات البرمجية وأضف عبارات الاستيراد الضرورية. في هذا المثال، نضيف ما يلي إلى ملف .py :
```
import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient
```
العبارة import asyncio مطلوبة فقط إذا كنت تستخدم المكتبة في التعليمات البرمجية الخاصة بك. تمت إضافته هنا للوضوح، حيث تستخدم الأمثلة في مقالات دليل المطور المكتبة asyncio .
إنشاء كائن عميل باستخدام async with لبدء العمل مع موارد البيانات. يحتاج عميل المستوى الأعلى فقط إلى استخدام async with، حيث يشارك العملاء الآخرون الذين تم إنشاؤهم منه نفس تجمع الاتصال. في هذا المثال، نقوم بإنشاء كائن BlobServiceClient باستخدام async with، ثم إنشاء كائن ContainerClient :
```
async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    container_client = blob_service_client.get_container_client(container="sample-container")
```
لمعرفة المزيد، راجع الأمثلة غير المتزامنة في تخويل الوصول والاتصال ب Blob Storage.

معلومات مكتبة عميل Blob غير المتزامنة:

azure.storage.blob.aio: يحتوي على الفئات الأساسية التي يمكنك استخدامها للعمل على الخدمة والحاويات والكائنات الثنائية كبيرة الحجم بشكل غير متزامن.

تخويل الوصول والاتصال ب Blob Storage

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

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

يمكنك تخويل كائن BlobServiceClient باستخدام رمز تخويل Microsoft Entra المميز أو مفتاح الوصول إلى الحساب أو توقيع وصول مشترك (SAS). للحصول على الأمان الأمثل، توصي Microsoft باستخدام معرف Microsoft Entra مع الهويات المدارة لتخويل الطلبات مقابل بيانات الكائن الثنائي كبير الحجم. لمزيد من المعلومات، راجع تخويل الوصول إلى الكائنات الثنائية كبيرة الحجم باستخدام معرف Microsoft Entra.

للتخويل باستخدام معرف Microsoft Entra، تحتاج إلى استخدام أساس أمان. يعتمد نوع أساس الأمان الذي تحتاجه على مكان تشغيل تطبيقك. استخدم الجدول التالي كدليل:

مكان تشغيل التطبيق	أساس الأمان	الإرشاد
جهاز محلي (تطوير واختبار)	كيان الخدمة	لمعرفة كيفية تسجيل التطبيق وإعداد مجموعة Microsoft Entra وتعيين الأدوار وتكوين متغيرات البيئة، راجع تخويل الوصول باستخدام أساسيات خدمة المطور
جهاز محلي (تطوير واختبار)	هوية المستخدم	لمعرفة كيفية إعداد مجموعة Microsoft Entra وتعيين الأدوار وتسجيل الدخول إلى Azure، راجع تخويل الوصول باستخدام بيانات اعتماد المطور
مستضاف في Azure	الهوية المُدارة	لمعرفة كيفية تمكين الهوية المدارة وتعيين الأدوار، راجع تخويل الوصول من التطبيقات المستضافة من Azure باستخدام هوية مدارة
مستضاف خارج Azure (على سبيل المثال، التطبيقات المحلية)	كيان الخدمة	لمعرفة كيفية تسجيل التطبيق وتعيين الأدوار وتكوين متغيرات البيئة، راجع تخويل الوصول من التطبيقات المحلية باستخدام كيان خدمة التطبيق

تخويل الوصول باستخدام DefaultAzureCredential

طريقة سهلة وآمنة لتخويل الوصول والاتصال ب Blob Storage هي الحصول على رمز OAuth المميز عن طريق إنشاء مثيل DefaultAzureCredential . يمكنك بعد ذلك استخدام بيانات الاعتماد هذه لإنشاء كائن BlobServiceClient .

ينشئ المثال التالي كائنا BlobServiceClient باستخدام DefaultAzureCredential:

def get_blob_service_client_token_credential(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

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

    return blob_service_client

إذا كان مشروعك يستخدم واجهات برمجة التطبيقات غير المتزامنة، قم بإنشاء BlobServiceClient مثيل باستخدام async with:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    # Work with data resources in the storage account

لاستخدام رمز مميز لتوقيع الوصول المشترك (SAS)، قم بتوفير الرمز المميز كسلسلة وتهيئة كائن BlobServiceClient . إذا كان عنوان URL لحسابك يتضمن رمز SAS المميز، فاحذف معلمة بيانات الاعتماد.

def get_blob_service_client_sas(self, sas_token: str):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    # The SAS token string can be assigned to credential here or appended to the account URL
    credential = sas_token

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

    return blob_service_client

إذا كان مشروعك يستخدم واجهات برمجة التطبيقات غير المتزامنة، قم بإنشاء BlobServiceClient مثيل باستخدام async with:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

# Replace <sas_token_str> with your actual SAS token
sas_token: str = "<sas_token_str>"

async with BlobServiceClient(account_url, credential=sas_token) as blob_service_client:
    # Work with data resources in the storage account

لمعرفة المزيد حول إنشاء رموز SAS المميزة وإدارتها، راجع المقالات التالية:

إشعار

بالنسبة للسيناريوهات التي يتم فيها استخدام توقيعات الوصول المشترك (SAS)، توصي Microsoft باستخدام SAS لتفويض المستخدم. يتم تأمين SAS لتفويض المستخدم باستخدام بيانات اعتماد Microsoft Entra بدلا من مفتاح الحساب.

لاستخدام مفتاح مشترك لحساب تخزين، قم بتوفير المفتاح كسلسلة وتهيئة كائن BlobServiceClient .

def get_blob_service_client_account_key(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")
    credential = shared_access_key

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

    return blob_service_client

يمكنك أيضا إنشاء كائن BlobServiceClient باستخدام سلسلة الاتصال.

def get_blob_service_client_connection_string(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    connection_string = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient.from_connection_string(connection_string)

    return blob_service_client

إذا كان مشروعك يستخدم واجهات برمجة التطبيقات غير المتزامنة، قم بإنشاء BlobServiceClient مثيل باستخدام async with:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")

async with BlobServiceClient(account_url, credential=shared_access_key) as blob_service_client:
    # Work with data resources in the storage account

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

هام

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

بناء تطبيقك

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

توضح لك الدلائل التالية كيفية الوصول إلى البيانات وتنفيذ إجراءات محددة باستخدام مكتبة عميل Azure Storage ل Python:

الدليل:	‏‏الوصف
تكوين نهج إعادة المحاولة	تنفيذ نهج إعادة المحاولة لعمليات العميل.
نسخ الكائنات الثنائية كبيرة الحجم	انسخ كائن ثنائي كبير الحجم من موقع إلى آخر.
إنشاء حاوية	إنشاء حاويات كائن ثنائي كبير الحجم.
إنشاء توقيعات الوصول المشترك لتفويض المستخدم	إنشاء SAS لتفويض مستخدم لحاوية أو كائن ثنائي كبير الحجم.
إنشاء إيجارات الكائن الثنائي كبير الحجم وإدارتها	إنشاء تأمين على كائن ثنائي كبير الحجم وإدارته.
إنشاء عقود إيجار الحاوية وإدارتها	إنشاء تأمين على حاوية وإدارته.
حذف الكائنات الثنائية كبيرة الحجم واستعادتها	حذف الكائنات الثنائية كبيرة الحجم واستعادة الكائنات الثنائية كبيرة الحجم المحذوفة بشكل مبدئي.
حذف الحاويات واستعادتها	حذف الحاويات واستعادة الحاويات المحذوفة مبدئيا.
تنزيل كائنات تخزين البيانات الثنائية الكبيرة	قم بتنزيل الكائنات الثنائية الكبيرة باستخدام السلاسل وتدفق البيانات ومسارات الملفات.
البحث عن الكائنات الثنائية كبيرة الحجم باستخدام العلامات	قم بتعيين العلامات واستردادها، واستخدم العلامات للعثور على الكائنات الثنائية كبيرة الحجم.
سرد الكيانات الثنائية كبيرة الحجم	سرد الكائنات الثنائية الكبيرة بطرق مختلفة.
قوائم الحاويات	سرد الحاويات في الحساب وكذلك الخيارات المختلفة المتاحة لتخصيص قائمة.
إدارة الخصائص وبيانات التعريف (الكائنات الثنائية كبيرة الحجم)	احصل على الخصائص وبيانات التعريف وقم بتعيينها للكائنات الثنائية كبيرة الحجم.
إدارة الخصائص وبيانات التعريف (الحاويات)	احصل على الخصائص وبيانات تعريف الحاويات وقم بتعيينها.
ضبط الأداء لنقل البيانات	تحسين الأداء لعمليات نقل البيانات.
تعيين مستوى الوصول إلى كائن ثنائي كبير الحجم أو تغييره	تعيين أو تغيير طبقة الوصول لكتلة كائن ثنائي كبير الحجم.
تحميل الكائنات الثنائية كبيرة الحجم	تعرف على كيفية تحميل الكائنات الثنائية الكبيرة باستخدام السلاسل ودفق البيانات ومسارات الملفات والطرق الأخرى.

مشاركة عبر

بدء استخدام Azure Blob Storage وPython

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

إعداد مشروعك

برمجة غير متزامنة

تخويل الوصول والاتصال ب Blob Storage

تخويل الوصول باستخدام DefaultAzureCredential

بناء تطبيقك

الملاحظات

الموارد الإضافية