مكتبة عميل Azure Storage Blobs ل Python - الإصدار 12.19.0

مقالة
11/07/2023

تخزين Azure Blob عبارة عن حل تخزين كائن من Microsoft للسحابة. تم تحسين تخزين Blob النقطة لتخزين كميات هائلة من البيانات غير المهيكلة.

يعتبر مخزن البيانات الثنائية الكبيرة مثاليًا لما يلي:

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

الشروع في العمل

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

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

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

قم بتثبيت مكتبة عميل Azure Storage Blobs ل Python باستخدام pip:

pip install azure-storage-blob

إنشاء حساب تخزين

إذا كنت ترغب في إنشاء حساب تخزين جديد، يمكنك استخدام مدخل Microsoft Azure أو Azure PowerShell أو Azure CLI:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

إنشاء العميل

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

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

البحث عن عنوان URL للحساب

يمكنك العثور على عنوان URL لخدمة كائن ثنائي كبير الحجم لحساب التخزين باستخدام مدخل Microsoft Azure أو Azure PowerShell أو Azure CLI:

# Get the blob service account url for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.blob"

أنواع بيانات الاعتماد

credential يمكن توفير المعلمة في عدد من النماذج المختلفة، اعتمادا على نوع التخويل الذي ترغب في استخدامه:

لاستخدام بيانات اعتماد الرمز المميز ل Azure Active Directory (AAD)، قم بتوفير مثيل لنوع بيانات الاعتماد المطلوب الذي تم الحصول عليه من مكتبة هوية azure . على سبيل المثال، يمكن استخدام DefaultAzureCredential لمصادقة العميل.

يتطلب هذا بعض الإعداد الأولي:
- تثبيت azure-identity
- تسجيل تطبيق AAD جديد ومنح أذونات للوصول إلى Azure Storage
- منح حق الوصول إلى بيانات Azure Blob باستخدام RBAC في مدخل Microsoft Azure
- تعيين قيم معرف العميل ومعرف المستأجر وسر العميل لتطبيق AAD كمتغيرات بيئة: AZURE_TENANT_ID AZURE_CLIENT_ID AZURE_CLIENT_SECRET
استخدم بيانات اعتماد الرمز المميز الذي تم إرجاعه لمصادقة العميل:
```
    from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )
```
لاستخدام رمز مميز لتوقيع الوصول المشترك (SAS)، قم بتوفير الرمز المميز كسلسلة. إذا كان عنوان URL لحسابك يتضمن رمز SAS المميز، فاحذف معلمة بيانات الاعتماد. يمكنك إنشاء رمز SAS مميز من مدخل Microsoft Azure ضمن "توقيع الوصول المشترك" أو استخدام إحدى generate_sas() الدالات لإنشاء رمز sas المميز لحساب التخزين أو الحاوية أو الكائن الثنائي كبير الحجم:
```
from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)
```
لاستخدام مفتاح مشترك لحساب التخزين (المعروف أيضا باسم مفتاح الحساب أو مفتاح الوصول)، قم بتوفير المفتاح كسلسلة. يمكن العثور على هذا في مدخل Microsoft Azure ضمن قسم "مفاتيح الوصول" أو عن طريق تشغيل أمر Azure CLI التالي:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

استخدم المفتاح كمعلمة بيانات الاعتماد لمصادقة العميل:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")
```
إذا كنت تستخدم url مخصصا (مما يعني أن عنوان url ليس بهذا التنسيق <my_account_name>.blob.core.windows.net)، يرجى إنشاء مثيل للعميل باستخدام بيانات الاعتماد أدناه:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})
```
لاستخدام الوصول العام المجهول للقراءة، ما عليك سوى حذف معلمة بيانات الاعتماد.

إنشاء العميل من سلسلة الاتصال

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

from azure.storage.blob import BlobServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = BlobServiceClient.from_connection_string(conn_str=connection_string)

يمكن العثور على سلسلة الاتصال إلى حساب التخزين الخاص بك في مدخل Microsoft Azure ضمن قسم "مفاتيح الوصول" أو عن طريق تشغيل أمر CLI التالي:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

المفاهيم الرئيسية

تشكل المكونات التالية خدمة Azure Blob:

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

تتيح لك مكتبة عميل Azure Storage Blobs ل Python التفاعل مع كل مكون من هذه المكونات من خلال استخدام عنصر عميل مخصص.

العملاء

يتم توفير أربعة عملاء مختلفين للتفاعل مع المكونات المختلفة لخدمة Blob:

BlobServiceClient - يمثل هذا العميل التفاعل مع حساب تخزين Azure نفسه، ويسمح لك بالحصول على مثيلات العميل المكونة مسبقا للوصول إلى الحاويات والكائنات الثنائية كبيرة الحجم داخلها. يوفر عمليات لاسترداد وتكوين خصائص الحساب بالإضافة إلى قائمة الحاويات وإنشاءها وحذفها داخل الحساب. لتنفيذ عمليات على حاوية أو كائن ثنائي كبير الحجم معين، قم باسترداد عميل باستخدام الأسلوبين get_container_client أو get_blob_client .
ContainerClient - يمثل هذا العميل التفاعل مع حاوية معينة (والتي لا تحتاج إلى وجود بعد)، ويسمح لك بالحصول على مثيلات العميل المكونة مسبقا للوصول إلى الكائنات الثنائية كبيرة الحجم داخلها. يوفر عمليات لإنشاء حاوية أو حذفها أو تكوينها ويتضمن عمليات لسرد الكائنات الثنائية كبيرة الحجم وتحميلها وحذفها داخلها. لتنفيذ عمليات على كائن ثنائي كبير الحجم معين داخل الحاوية، قم باسترداد عميل باستخدام get_blob_client الأسلوب .
BlobClient - يمثل هذا العميل التفاعل مع كائن ثنائي كبير الحجم معين (والتي لا تحتاج إلى وجود بعد). يوفر عمليات لتحميل لقطات من كائن ثنائي كبير الحجم وتنزيلها وحذفها وإنشاءها، بالإضافة إلى عمليات محددة لكل نوع كائن ثنائي كبير الحجم.
BlobLeaseClient - يمثل هذا العميل تفاعلات الإيجار مع أو ContainerClientBlobClient. يوفر عمليات للحصول على عقد إيجار على مورد محدد وتجديده وإصداره وتغييره وإيقافه.

عملاء غير متزامنين

تتضمن هذه المكتبة واجهة برمجة تطبيقات غير متزامنة كاملة مدعومة على Python 3.5+. لاستخدامه، يجب أولا تثبيت نقل غير متزامن، مثل aiohttp. راجع وثائق azure-core لمزيد من المعلومات.

يجب إغلاق العملاء وبيانات الاعتماد غير المتزامنة عندما لا تكون هناك حاجة إليها. هذه الكائنات هي مديري سياق غير متزامنين وتحدد أساليب غير متزامنة close .

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

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

تقوم الكائنات الثنائية كبيرة الحجم للكتل بتخزين النص والبيانات الثنائية، حتى 4.75 تيرابايت تقريبا. تتكون الكائنات الثنائية كبيرة الحجم للكتلة من كتل من البيانات التي يمكن إدارتها بشكل فردي
تتكون "Append blobs" من كتل مثل الكتل النقطية الكبيرة، ولكنها محسّنة لعمليات الإلحاق. تعد الكائنات الثنائية كبيرة الحجم للإلحاق مثالية لسيناريوهات مثل تسجيل البيانات من الأجهزة الظاهرية
Page blobs تخزن ملفات وصول عشوائي يصل حجمها إلى 8 تيرابايت. تخزن الكائنات الثنائية كبيرة الحجم للصفحة ملفات القرص الثابت الظاهري (VHD) وتعمل كأقراص لأجهزة Azure الظاهرية

أمثلة

توفر الأقسام التالية العديد من القصاصات البرمجية التي تغطي بعض مهام Storage Blob الأكثر شيوعا، بما في ذلك:

إنشاء حاوية
تحميل كائن ثنائي كبير الحجم
تنزيل كائن ثنائي كبير الحجم
تعداد الكائنات الثنائية كبيرة الحجم

لاحظ أنه يجب إنشاء حاوية من قبل لتحميل أو تنزيل كائن ثنائي كبير الحجم.

إنشاء حاوية

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

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

استخدام العميل غير المتزامن لتحميل كائن ثنائي كبير الحجم

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

تحميل كائن ثنائي كبير الحجم

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

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

استخدام العميل غير المتزامن لتحميل كائن ثنائي كبير الحجم

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

تنزيل كائن ثنائي كبير الحجم

تنزيل كائن ثنائي كبير الحجم من الحاوية الخاصة بك

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

تنزيل كائن ثنائي كبير الحجم بشكل غير متزامن

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

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

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

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

سرد الكائنات الثنائية كبيرة الحجم بشكل غير متزامن

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

التكوين الاختياري

وسيطات الكلمات الأساسية الاختيارية التي يمكن تمريرها على مستوى العميل وكل عملية.

إعادة محاولة تكوين النهج

استخدم وسيطات الكلمة الأساسية التالية عند إنشاء مثيل لعميل لتكوين نهج إعادة المحاولة:

retry_total (int): إجمالي عدد عمليات إعادة المحاولة التي يجب السماح بها. له الأسبقية على عدد آخر. قم بتمرير إذا retry_total=0 كنت لا تريد إعادة المحاولة على الطلبات. الإعدادات الافتراضية إلى 10.
retry_connect (int): عدد الأخطاء المتعلقة بالاتصال التي يجب إعادة المحاولة عليها. الإعدادات الافتراضية معينة على 3.
retry_read (int): كم مرة لإعادة المحاولة على أخطاء القراءة. الإعدادات الافتراضية معينة على 3.
retry_status (int): كم مرة لإعادة المحاولة على رموز الحالة السيئة. الإعدادات الافتراضية معينة على 3.
retry_to_secondary (bool): ما إذا كان يجب إعادة محاولة الطلب إلى المستوى الثانوي، إذا كان ذلك قادرا. يجب تمكين هذا فقط من حسابات RA-GRS ويمكن معالجة البيانات القديمة المحتملة. الإعدادات الافتراضية لـ False.

تكوين التشفير

استخدم وسيطات الكلمة الأساسية التالية عند إنشاء مثيل عميل لتكوين التشفير:

require_encryption (bool): إذا تم تعيينه إلى True، فسيفرض تشفير العناصر وفك تشفيرها.
encryption_version (str): يحدد إصدار التشفير المراد استخدامه. الخيارات الحالية هي '2.0' أو '1.0' والقيمة الافتراضية هي '1.0'. تم إهمال الإصدار 1.0، ويوصى بشدة باستخدام الإصدار 2.0.
key_encryption_key (كائن): مفتاح تشفير المفتاح الذي يوفره المستخدم. يجب أن ينفذ المثيل الأساليب التالية:
- wrap_key(key)--يلتف المفتاح المحدد باستخدام خوارزمية من اختيار المستخدم.
- get_key_wrap_algorithm()--إرجاع الخوارزمية المستخدمة لالتفاف المفتاح المتماثل المحدد.
- get_kid()--إرجاع معرف مفتاح سلسلة لمفتاح تشفير المفتاح هذا.
key_resolver_function (قابل للاستدعاء): محلل المفاتيح الذي يوفره المستخدم. يستخدم سلسلة الأطفال لإرجاع مفتاح تشفير المفتاح الذي ينفذ الواجهة المعرفة أعلاه.

تكوين عميل آخر / لكل عملية

وسيطات الكلمة الأساسية للتكوين الاختيارية الأخرى التي يمكن تحديدها على العميل أو لكل عملية.

وسيطات الكلمات الأساسية للعميل:

connection_timeout (int): عدد الثوان التي سينتظرها العميل لإنشاء اتصال بالخادم. الإعدادات الافتراضية إلى 20 ثانية.
read_timeout (int): عدد الثوان التي سينتظرها العميل، بين عمليات القراءة المتتالية، للحصول على استجابة من الخادم. هذه مهلة مستوى مأخذ التوصيل ولا تتأثر بحجم البيانات الإجمالي. ستتم إعادة محاولة مهلات القراءة من جانب العميل تلقائيا. الإعدادات الافتراضية إلى 60 ثانية.
النقل (أي): النقل الذي يوفره المستخدم لإرسال طلب HTTP.

وسيطات الكلمات الأساسية لكل عملية:

raw_response_hook (قابل للاستدعاء): يستخدم رد الاتصال المحدد الاستجابة التي تم إرجاعها من الخدمة.
raw_request_hook (قابل للاستدعاء): يستخدم رد الاتصال المحدد الطلب قبل إرساله إلى الخدمة.
client_request_id (str): تحديد المستخدم الاختياري للطلب.
user_agent (str): إلحاق القيمة المخصصة بعنوان عامل المستخدم ليتم إرسالها مع الطلب.
logging_enable (bool): تمكين التسجيل على مستوى DEBUG. الإعدادات الافتراضية معينة على False. يمكن أيضا تمريره على مستوى العميل لتمكينه لجميع الطلبات.
logging_body (bool): تمكين تسجيل نص الطلب والاستجابة. الإعدادات الافتراضية معينة على False. يمكن أيضا تمريره على مستوى العميل لتمكينه لجميع الطلبات.
الرؤوس (الإملاء): قم بتمرير الرؤوس المخصصة كمفتاح وأزواج قيم. علـى سبيل المثال، headers={'CustomValue': value}.

استكشاف الأخطاء وإصلاحها

عام

يثير عملاء Storage Blob استثناءات محددة في Azure Core.

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

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

وبالمثل، logging_enable يمكن تمكين تسجيل مفصل لعملية واحدة، حتى عندما لا يتم تمكين للعميل:

service_client.get_service_stats(logging_enable=True)

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

وثائق إضافية

للحصول على وثائق أكثر شمولا حول تخزين Azure Blob، راجع وثائق تخزين Azure Blob على docs.microsoft.com.

المساهمة

هذا المشروع يرحب بالمساهمات والاقتراحات. معظم المساهمات تتطلب منك الموافقة على اتفاقية ترخيص المساهم (CLA) التي تعلن أن لديك الحق في منحنا حق استخدام مساهمتك. لمزيد من التفاصيل، قم بزيارة https://cla.microsoft.com.

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

اعتمد هذا المشروع مدونة السلوك من المصادر المفتوحة من Microsoft. لمزيد من المعلومات، راجع الأسئلة المتداولة حول قواعد السلوك أو الاتصال opencode@microsoft.com بأي أسئلة أو تعليقات إضافية.

مشاركة عبر