تحميل كائن ثنائي كبير الحجم للكتلة باستخدام Python
توضح هذه المقالة كيفية تحميل كائن ثنائي كبير الحجم باستخدام مكتبة عميل Azure Storage ل Python. يمكنك تحميل البيانات إلى كائن ثنائي كبير الحجم للكتلة من مسار ملف أو دفق أو كائن ثنائي أو سلسلة نصية. يمكنك أيضا تحميل الكائنات الثنائية كبيرة الحجم باستخدام علامات الفهرس.
لمعرفة المزيد حول تحميل الكائنات الثنائية كبيرة الحجم باستخدام واجهات برمجة التطبيقات غير المتزامنة، راجع تحميل الكائنات الثنائية كبيرة الحجم بشكل غير متزامن.
المتطلبات الأساسية
- اشتراك Azure - إنشاء اشتراك مجاني
- حساب تخزين Azure - إنشاء حساب تخزين
- Python 3.8+
إعداد بيئتك
إذا لم يكن لديك مشروع موجود، يوضح لك هذا القسم كيفية إعداد مشروع للعمل مع مكتبة عميل Azure Blob Storage ل Python. لمزيد من التفاصيل، راجع بدء استخدام Azure Blob Storage وPython.
لاستخدام أمثلة التعليمات البرمجية في هذه المقالة، اتبع هذه الخطوات لإعداد مشروعك.
تثبيت الحزم
قم بتثبيت الحزم التالية باستخدام pip install
:
pip install azure-storage-blob azure-identity
إضافة عبارات الاستيراد
أضف عبارات import
التالية:
import io
import os
import uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobBlock, BlobClient, StandardBlobTier
التصريح
يجب أن يكون لآلية التخويل الأذونات اللازمة لتحميل كائن ثنائي كبير الحجم. للحصول على تخويل باستخدام معرف Microsoft Entra (مستحسن)، تحتاج إلى دور Azure RBAC المضمن في Storage Blob Data Contributor أو أعلى. لمعرفة المزيد، راجع إرشادات التخويل ل Put Blob (REST API) و Put Block (REST API).
إنشاء كائن عميل
لتوصيل تطبيق ب Blob Storage، قم بإنشاء مثيل BlobServiceClient. يوضح المثال التالي كيفية إنشاء كائن عميل باستخدام DefaultAzureCredential
للتخويل:
# 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)
يمكنك أيضا إنشاء كائنات العميل لحاويات أو كائنات ثنائية كبيرة الحجم معينة، إما مباشرة أو من BlobServiceClient
العنصر. لمعرفة المزيد حول إنشاء كائنات العميل وإدارتها، راجع إنشاء كائنات العميل التي تتفاعل مع موارد البيانات وإدارتها.
تحميل البيانات إلى كائن ثنائي كبير الحجم للكتلة
لتحميل كائن ثنائي كبير الحجم باستخدام دفق أو كائن ثنائي، استخدم الأسلوب التالي:
ينشئ هذا الأسلوب كائنا ثنائيا جديدا من مصدر بيانات مع تقسيم تلقائي، ما يعني أنه قد يتم تقسيم مصدر البيانات إلى مجموعات أصغر وتحميله. لتنفيذ التحميل، قد تستخدم مكتبة العميل إما Put Blob أو سلسلة من استدعاءات Put Block متبوعة ب Put Block List. يعتمد هذا السلوك على الحجم الإجمالي للكائن وكيفية تعيين خيارات نقل البيانات.
تحميل كائن ثنائي كبير الحجم للكتلة من مسار ملف محلي
يقوم المثال التالي بتحميل ملف إلى كتلة كائن ثنائي كبير الحجم باستخدام كائن BlobClient
:
def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
container_client = blob_service_client.get_container_client(container=container_name)
with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)
تحميل كائن ثنائي كبير الحجم للكتلة من دفق
ينشئ المثال التالي وحدات بايت عشوائية من البيانات ويحمل كائنا BytesIO
إلى كائن ثنائي كبير الحجم للكتلة باستخدام كائن BlobClient
:
def upload_blob_stream(self, blob_service_client: BlobServiceClient, container_name: str):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
input_stream = io.BytesIO(os.urandom(15))
blob_client.upload_blob(input_stream, blob_type="BlockBlob")
تحميل البيانات الثنائية إلى كائن ثنائي كبير الحجم للكتلة
يقوم المثال التالي بتحميل البيانات الثنائية إلى كائن ثنائي كبير الحجم للكتلة باستخدام كائن BlobClient
:
def upload_blob_data(self, blob_service_client: BlobServiceClient, container_name: str):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
data = b"Sample data for blob"
# Upload the blob data - default blob type is BlockBlob
blob_client.upload_blob(data, blob_type="BlockBlob")
تحميل كائن ثنائي كبير الحجم للكتلة باستخدام علامات الفهرس
يقوم المثال التالي بتحميل كائن ثنائي كبير الحجم للكتلة مع علامات الفهرس:
def upload_blob_tags(self, blob_service_client: BlobServiceClient, container_name: str):
container_client = blob_service_client.get_container_client(container=container_name)
sample_tags = {"Content": "image", "Date": "2022-01-01"}
with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, tags=sample_tags)
تحميل كائن ثنائي كبير الحجم للكتلة مع خيارات التكوين
يمكنك تحديد خيارات تكوين مكتبة العميل عند تحميل كائن ثنائي كبير الحجم. يمكن ضبط هذه الخيارات لتحسين الأداء وتحسين الموثوقية وتحسين التكاليف. توضح أمثلة التعليمات البرمجية التالية كيفية تعريف خيارات التكوين للتحميل على مستوى الأسلوب، وعلى مستوى العميل عند إنشاء مثيل BlobClient. يمكن أيضا تكوين هذه الخيارات لمثيل ContainerClient أو مثيل BlobServiceClient .
تحديد خيارات نقل البيانات للتحميل
يمكنك تعيين خيارات التكوين عند إنشاء مثيل لعميل لتحسين الأداء لعمليات نقل البيانات. يمكنك تمرير وسيطات الكلمة الأساسية التالية عند إنشاء كائن عميل في Python:
max_block_size
- الحد الأقصى لحجم المجموعة لتحميل كتلة كائن ثنائي كبير الحجم في مجموعات. الافتراضيات إلى 4 ميبي بايت.max_single_put_size
- إذا كان حجم الكائن الثنائي كبير الحجم أقل من أو يساويmax_single_put_size
، يتم تحميل الكائن الثنائي كبير الحجم بطلب واحدPut Blob
. إذا كان حجم الكائن الثنائي كبير الحجم أكبر منmax_single_put_size
أو غير معروف، يتم تحميل الكائن الثنائي كبير الحجم في مجموعات باستخدامPut Block
وتثبيته باستخدامPut Block List
. الافتراضيات إلى 64 ميبي بايت.
لمزيد من المعلومات حول حدود حجم النقل لتخزين Blob، راجع أهداف المقياس لتخزين Blob.
لعمليات التحميل، يمكنك أيضا تمرير الوسيطة max_concurrency
عند استدعاء upload_blob. تحدد هذه الوسيطة الحد الأقصى لعدد الاتصالات المتوازية التي يجب استخدامها عندما يتجاوز حجم الكائن الثنائي كبير الحجم 64 ميجابايت.
يوضح مثال التعليمات البرمجية التالي كيفية تحديد خيارات نقل البيانات عند إنشاء كائن BlobClient
، وكيفية تحميل البيانات باستخدام كائن العميل هذا. لا يقصد بالقيم المقدمة في هذه العينة أن تكون توصية. لضبط هذه القيم بشكل صحيح، تحتاج إلى مراعاة الاحتياجات المحددة لتطبيقك.
def upload_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
# Create a BlobClient object with data transfer options for upload
blob_client = BlobClient(
account_url=account_url,
container_name=container_name,
blob_name=blob_name,
credential=DefaultAzureCredential(),
max_block_size=1024*1024*4, # 4 MiB
max_single_put_size=1024*1024*8 # 8 MiB
)
with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
blob_client = blob_client.upload_blob(data=data, overwrite=True, max_concurrency=2)
لمعرفة المزيد حول خيارات ضبط نقل البيانات، راجع ضبط الأداء للتحميلات والتنزيلات باستخدام Python.
تعيين طبقة وصول كائن ثنائي كبير الحجم عند التحميل
يمكنك تعيين طبقة وصول كائن ثنائي كبير الحجم عند التحميل عن طريق تمرير وسيطة standard_blob_tier
الكلمة الأساسية إلى upload_blob. يوفر Azure Storage مستويات وصول مختلفة بحيث يمكنك تخزين بيانات الكائن الثنائي كبير الحجم بطريقة أكثر فعالية من حيث التكلفة استنادا إلى كيفية استخدامها.
يوضح مثال التعليمات البرمجية التالي كيفية تعيين طبقة الوصول عند تحميل كائن ثنائي كبير الحجم:
def upload_blob_access_tier(self, blob_service_client: BlobServiceClient, container_name: str, blob_name: str):
blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
#Upload blob to the cool tier
with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
blob_client = blob_client.upload_blob(data=data, overwrite=True, standard_blob_tier=StandardBlobTier.COOL)
يسمح بتعيين طبقة الوصول فقط لكتل الكائنات الثنائية كبيرة الحجم. يمكنك تعيين طبقة الوصول لكتلة كائن ثنائي كبير الحجم إلى Hot
أو Cool
Cold
أو أو Archive
. لتعيين مستوى الوصول إلى Cold
، يجب استخدام الحد الأدنى لإصدار مكتبة العميل من 12.15.0.
لمعرفة المزيد حول مستويات الوصول، راجع نظرة عامة على مستويات الوصول.
تحميل كائن ثنائي كبير الحجم للكتلة عن طريق التقسيم المرحلي والتزم
يمكنك التحكم بشكل أكبر في كيفية تقسيم التحميلات إلى كتل عن طريق التقسيم المرحلي للكتل الفردية من البيانات يدويا. عندما يتم تنظيم جميع الكتل التي تشكل كائناً ثنائياً كبير الحجم، يمكنك تنفيذها في مخزن البيانات الثنائية الكبيرة.
استخدم الأسلوب التالي لإنشاء كتلة جديدة ليتم تثبيتها كجزء من كائن ثنائي كبير الحجم:
استخدم الأسلوب التالي لكتابة كائن ثنائي كبير الحجم عن طريق تحديد قائمة معرفات الكتلة التي تشكل الكائن الثنائي كبير الحجم:
يقرأ المثال التالي البيانات من ملف ويرحل كتل ليتم الالتزام بها كجزء من كائن ثنائي كبير الحجم:
def upload_blocks(self, blob_container_client: ContainerClient, local_file_path: str, block_size: int):
file_name = os.path.basename(local_file_path)
blob_client = blob_container_client.get_blob_client(file_name)
with open(file=local_file_path, mode="rb") as file_stream:
block_id_list = []
while True:
buffer = file_stream.read(block_size)
if not buffer:
break
block_id = uuid.uuid4().hex
block_id_list.append(BlobBlock(block_id=block_id))
blob_client.stage_block(block_id=block_id, data=buffer, length=len(buffer))
blob_client.commit_block_list(block_id_list)
تحميل الكائنات الثنائية كبيرة الحجم بشكل غير متزامن
تدعم مكتبة عميل Azure Blob Storage ل Python تحميل الكائنات الثنائية كبيرة الحجم بشكل غير متزامن. لمعرفة المزيد حول متطلبات إعداد المشروع، راجع البرمجة غير المتزامنة.
اتبع هذه الخطوات لتحميل كائن ثنائي كبير الحجم باستخدام واجهات برمجة التطبيقات غير المتزامنة:
إضافة عبارات الاستيراد التالية:
import asyncio from azure.identity.aio import DefaultAzureCredential from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient
أضف التعليمات البرمجية لتشغيل البرنامج باستخدام
asyncio.run
. تقوم هذه الدالة بتشغيل coroutine الذي تم تمريره،main()
في مثالنا، وتديرasyncio
حلقة الحدث. يتم الإعلان عن Coroutines باستخدام بناء الجملة غير المتزامن/انتظار. في هذا المثال،main()
يقوم coroutine أولا بإنشاء المستوىBlobServiceClient
الأعلى باستخدامasync with
، ثم يستدعي الأسلوب الذي يقوم بتحميل الكائن الثنائي كبير الحجم. لاحظ أن عميل المستوى الأعلى فقط يحتاج إلى استخدامasync with
، حيث يشارك العملاء الآخرون الذين تم إنشاؤهم منه نفس تجمع الاتصال.async def main(): sample = BlobSamples() # 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: await sample.upload_blob_file(blob_service_client, "sample-container") if __name__ == '__main__': asyncio.run(main())
إضافة تعليمة برمجية لتحميل الكائن الثنائي كبير الحجم. يقوم المثال التالي بتحميل كائن ثنائي كبير الحجم من مسار ملف محلي باستخدام كائن
ContainerClient
. التعليمات البرمجية هي نفس المثال المتزامن، باستثناء أن الأسلوب يتم تعريفه باستخدامasync
الكلمة الأساسية ويتمawait
استخدام الكلمة الأساسية عند استدعاءupload_blob
الأسلوب .async def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str): container_client = blob_service_client.get_container_client(container=container_name) with open(file=os.path.join('filepath', 'filename'), mode="rb") as data: blob_client = await container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)
مع هذا الإعداد الأساسي في مكانه، يمكنك تنفيذ أمثلة أخرى في هذه المقالة ك coroutines باستخدام بناء الجملة غير المتزامن/انتظار.
الموارد
لمعرفة المزيد حول تحميل الكائنات الثنائية كبيرة الحجم باستخدام مكتبة عميل Azure Blob Storage ل Python، راجع الموارد التالية.
نماذج التعليمات البرمجية
- عرض نماذج التعليمات البرمجية المتزامنة أو غير المتزامنة من هذه المقالة (GitHub)
عمليات واجهة برمجة تطبيقات REST
يحتوي Azure SDK ل Python على مكتبات تستند إلى واجهة برمجة تطبيقات AZURE REST، مما يسمح لك بالتفاعل مع عمليات REST API من خلال نماذج Python المألوفة. تستخدم أساليب مكتبة العميل لتحميل الكائنات الثنائية كبيرة الحجم عمليات واجهة برمجة تطبيقات REST التالية:
- وضع كائن ثنائي كبير الحجم (واجهة برمجة تطبيقات REST)
- وضع كتلة (واجهة برمجة تطبيقات REST)
موارد مكتبة العميل
(راجع أيضًا )
- إدارة بيانات Azure Blob والعثور عليها باستخدام علامات فهرس كائن ثنائي كبير الحجم
- استخدام علامات فهرسة الكائنات الثنائية كبيرة الحجم لإدارة البيانات والعثور عليها في مساحة تخزين Azure Blob
المحتوى ذو الصلة
- هذه المقالة هي جزء من دليل مطور Blob Storage ل Python. لمعرفة المزيد، راجع القائمة الكاملة لمقالات دليل المطور في إنشاء تطبيق Python.