Pustaka klien Azure Storage Blobs untuk Python - versi 12.19.0

Artikel
11/07/2023

Azure Blob Storage adalah solusi penyimpanan objek Microsoft untuk cloud. Penyimpanan Blob dioptimalkan untuk menyimpan data tidak terstruktur dalam jumlah besar, seperti teks atau data biner.

Penyimpanan blob sangat ideal untuk:

Menyajikan gambar atau dokumen langsung ke browser
Menyimpan file untuk akses terdistribusi
Mengalirkan video dan audio
Menyimpan data untuk cadangan dan pemulihan, pemulihan bencana, dan pengarsipan
Menyimpan data untuk analisis oleh layanan lokal atau yang dihosting Azure

Memulai

Prasyarat

Python 3.7 atau yang lebih baru diharuskan untuk menggunakan paket ini. Untuk detail selengkapnya, silakan baca halaman kami di Azure SDK untuk kebijakan dukungan versi Python.
Anda harus memiliki langganan Azure dan akun penyimpanan Azure untuk menggunakan paket ini.

Instal paketnya

Instal pustaka klien Azure Storage Blobs untuk Python dengan pip:

pip install azure-storage-blob

Buat akun penyimpanan

Jika Anda ingin membuat akun penyimpanan baru, Anda dapat menggunakan Portal Microsoft Azure, Azure PowerShell, atau 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

Membuat klien

Pustaka klien Azure Storage Blobs untuk Python memungkinkan Anda berinteraksi dengan tiga jenis sumber daya: akun penyimpanan itu sendiri, kontainer penyimpanan blob, dan blob. Interaksi dengan sumber daya ini dimulai dengan instans klien. Untuk membuat objek klien, Anda memerlukan URL akun blob service akun penyimpanan dan kredensial yang memungkinkan Anda mengakses akun penyimpanan:

from azure.storage.blob import BlobServiceClient

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

Mencari URL akun

Anda dapat menemukan URL layanan blob akun penyimpanan menggunakan Portal Microsoft Azure, Azure PowerShell, atau 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"

Jenis kredensial

Parameter credential dapat disediakan dalam sejumlah formulir yang berbeda, tergantung pada jenis otorisasi yang ingin Anda gunakan:

Untuk menggunakan kredensial token Azure Active Directory (AAD), berikan instans jenis kredensial yang diinginkan yang diperoleh dari pustaka identitas azure . Misalnya, DefaultAzureCredential dapat digunakan untuk mengautentikasi klien.

Ini memerlukan beberapa penyiapan awal:
- Menginstal azure-identity
- Mendaftarkan aplikasi AAD baru dan memberikan izin untuk mengakses Azure Storage
- Memberikan akses ke data Azure Blob dengan RBAC di Portal Microsoft Azure
- Atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi AAD sebagai variabel lingkungan: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
Gunakan kredensial token yang dikembalikan untuk mengautentikasi klien:
```
    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
    )
```

Untuk menggunakan token tanda tangan akses bersama (SAS), berikan token sebagai string. Jika URL akun Anda menyertakan token SAS, hilangkan parameter kredensial. Anda dapat membuat token SAS dari Portal Microsoft Azure di bawah "Tanda tangan akses bersama" atau menggunakan salah generate_sas() satu fungsi untuk membuat token sas untuk akun penyimpanan, kontainer, atau blob:

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)

Untuk menggunakan kunci bersama akun penyimpanan (kunci akun atau kunci akses), berikan kunci sebagai string. Ini dapat ditemukan di Portal Microsoft Azure di bawah bagian "Kunci Akses" atau dengan menjalankan perintah Azure CLI berikut:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Gunakan kunci sebagai parameter kredensial untuk mengautentikasi klien:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")
```
Jika Anda menggunakan url yang disesuaikan (yang berarti url tidak dalam format <my_account_name>.blob.core.windows.netini ), silakan buat instans klien menggunakan kredensial di bawah ini:
```
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>"})
```
Untuk menggunakan akses baca publik anonim, cukup hilangkan parameter kredensial.

Membuat klien dari string koneksi

Bergantung pada kasus penggunaan dan metode otorisasi, Anda mungkin lebih suka menginisialisasi instans klien dengan string koneksi penyimpanan alih-alih memberikan URL akun dan kredensial secara terpisah. Untuk melakukan ini, teruskan string koneksi penyimpanan ke metode kelas klienfrom_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)

string koneksi ke akun penyimpanan Anda dapat ditemukan di Portal Microsoft Azure di bagian "Kunci Akses" atau dengan menjalankan perintah CLI berikut:

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

Konsep utama

Komponen berikut membentuk Azure Blob Service:

Akun penyimpanan itu sendiri
Kontainer dalam akun penyimpanan
Blob dalam kontainer

Pustaka klien Azure Storage Blobs untuk Python memungkinkan Anda berinteraksi dengan masing-masing komponen ini melalui penggunaan objek klien khusus.

Klien

Empat klien yang berbeda disediakan untuk berinteraksi dengan berbagai komponen Blob Service:

BlobServiceClient - klien ini mewakili interaksi dengan akun penyimpanan Azure itu sendiri, dan memungkinkan Anda memperoleh instans klien yang telah dikonfigurasi sebelumnya untuk mengakses kontainer dan blob di dalamnya. Ini menyediakan operasi untuk mengambil dan mengonfigurasi properti akun serta mencantumkan, membuat, dan menghapus kontainer dalam akun. Untuk melakukan operasi pada kontainer atau blob tertentu, ambil klien menggunakan get_container_client metode atau get_blob_client .
ContainerClient - klien ini mewakili interaksi dengan kontainer tertentu (yang belum ada), dan memungkinkan Anda memperoleh instans klien yang telah dikonfigurasi sebelumnya untuk mengakses blob di dalamnya. Ini menyediakan operasi untuk membuat, menghapus, atau mengonfigurasi kontainer dan menyertakan operasi untuk mencantumkan, mengunggah, dan menghapus blob di dalamnya. Untuk melakukan operasi pada blob tertentu dalam kontainer, ambil klien menggunakan metode .get_blob_client
BlobClient - klien ini mewakili interaksi dengan blob tertentu (yang belum ada). Ini menyediakan operasi untuk mengunggah, mengunduh, menghapus, dan membuat rekam jepret blob, serta operasi tertentu per jenis blob.
BlobLeaseClient - klien ini mewakili interaksi sewa dengan ContainerClient atau BlobClient. Ini menyediakan operasi untuk memperoleh, memperbarui, merilis, mengubah, dan memutuskan sewa pada sumber daya tertentu.

Klien Asinkron

Pustaka ini mencakup API asinkron lengkap yang didukung pada Python 3.5+. Untuk menggunakannya, Anda harus menginstal transportasi asinkron terlebih dahulu, seperti aiohttp. Lihat dokumentasi azure-core untuk informasi selengkapnya.

Klien dan kredensial asinkron harus ditutup ketika tidak lagi diperlukan. Objek ini adalah manajer konteks asinkron dan menentukan metode asinkron close .

Jenis Blob

Setelah menginisialisasi Klien, Anda dapat memilih dari berbagai jenis blob:

Blob blok menyimpan teks dan data biner, hingga sekitar 4,75 TiB. Blob blok terdiri dari blok data yang dapat dikelola secara individual
Blob tambahan terdiri dari blok seperti blob blok, tetapi dioptimalkan untuk operasi tambahan. Blob penambahan sangat ideal untuk skenario seperti mencatat data dari komputer virtual
Blob halaman menyimpan file akses acak yang berukuran hingga 8 TiB. Blob halaman menyimpan file hard drive virtual (VHD) dan berfungsi sebagai disk untuk komputer virtual Azure

Contoh

Bagian berikut menyediakan beberapa cuplikan kode yang mencakup beberapa tugas Blob Penyimpanan yang paling umum, termasuk:

Membuat kontainer
Mengunggah blob
Mengunduh blob
Menghitung blob

Perhatikan bahwa kontainer harus dibuat sebelum mengunggah atau mengunduh blob.

Buat kontainer

Buat kontainer tempat Anda dapat mengunggah atau mengunduh blob.

from azure.storage.blob import ContainerClient

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

container_client.create_container()

Menggunakan klien asinkron untuk mengunggah blob

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()

Mengunggah blob

Mengunggah blob ke kontainer Anda

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)

Menggunakan klien asinkron untuk mengunggah 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("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Mengunduh blob

Mengunduh blob dari kontainer Anda

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)

Mengunduh blob secara asinkron

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)

Menghitung blob

Mencantumkan blob dalam kontainer Anda

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')

Mencantumkan blob secara asinkron

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)

Konfigurasi Opsional

Argumen kata kunci opsional yang dapat diteruskan di tingkat klien dan per operasi.

Konfigurasi Kebijakan Coba Lagi

Gunakan argumen kata kunci berikut saat membuat instans klien untuk mengonfigurasi kebijakan coba lagi:

retry_total (int): Jumlah total percobaan ulang yang diizinkan. Lebih diutamakan daripada hitungan lain. retry_total=0 Teruskan jika Anda tidak ingin mencoba kembali permintaan. Default ke 10.
retry_connect (int): Berapa banyak kesalahan terkait koneksi yang akan diulang. Default ke 3.
retry_read (int): Berapa kali untuk mencoba kembali kesalahan baca. Default ke 3.
retry_status (int): Berapa kali untuk mencoba kembali kode status yang buruk. Default ke 3.
retry_to_secondary (bool): Apakah permintaan harus dicoba kembali ke sekunder, jika dapat. Ini hanya boleh diaktifkan dari akun RA-GRS yang digunakan dan data yang berpotensi kedaluarsa dapat ditangani. Default ke False.

Konfigurasi Enkripsi

Gunakan argumen kata kunci berikut saat membuat instans klien untuk mengonfigurasi enkripsi:

require_encryption (bool): Jika diatur ke True, akan memberlakukan bahwa objek dienkripsi dan mendekripsinya.
encryption_version (str): Menentukan versi enkripsi yang akan digunakan. Opsi saat ini adalah '2.0' atau '1.0' dan nilai defaultnya adalah '1.0'. Versi 1.0 tidak digunakan lagi, dan sangat disarankan untuk menggunakan versi 2.0.
key_encryption_key (objek): Kunci enkripsi kunci yang disediakan pengguna. Instans harus menerapkan metode berikut:
- wrap_key(key)--membungkus kunci yang ditentukan menggunakan algoritma pilihan pengguna.
- get_key_wrap_algorithm()--mengembalikan algoritma yang digunakan untuk membungkus kunci simetris yang ditentukan.
- get_kid()--mengembalikan id kunci string untuk kunci-enkripsi-kunci ini.
key_resolver_function (dapat dipanggil): Pemecah masalah kunci yang disediakan pengguna. Menggunakan string anak untuk mengembalikan kunci-enkripsi-kunci yang mengimplementasikan antarmuka yang ditentukan di atas.

Konfigurasi klien/per operasi lainnya

Argumen kata kunci konfigurasi opsional lainnya yang dapat ditentukan pada klien atau per operasi.

Argumen kata kunci klien:

connection_timeout (int): Jumlah detik klien akan menunggu untuk membuat koneksi ke server. Default ke 20 detik.
read_timeout (int): Jumlah detik klien akan menunggu, antara operasi baca berturut-turut, untuk respons dari server. Ini adalah batas waktu tingkat soket dan tidak terpengaruh oleh ukuran data keseluruhan. Batas waktu baca sisi klien akan dicoba ulang secara otomatis. Default ke 60 detik.
transport (Any): Transportasi yang disediakan pengguna untuk mengirim permintaan HTTP.

Argumen kata kunci per operasi:

raw_response_hook (dapat dipanggil): Panggilan balik yang diberikan menggunakan respons yang dikembalikan dari layanan.
raw_request_hook (dapat dipanggil): Panggilan balik yang diberikan menggunakan permintaan sebelum dikirim ke layanan.
client_request_id (str): Identifikasi permintaan yang ditentukan pengguna opsional.
user_agent (str): Menambahkan nilai kustom ke header agen pengguna untuk dikirim dengan permintaan.
logging_enable (bool): Mengaktifkan pengelogan di tingkat DEBUG. Default ke False. Juga dapat diteruskan di tingkat klien untuk mengaktifkannya untuk semua permintaan.
logging_body (bool): Memungkinkan pengelogan isi permintaan dan respons. Default ke False. Juga dapat diteruskan di tingkat klien untuk mengaktifkannya untuk semua permintaan.
header (dict): Meneruskan header kustom sebagai kunci, pasangan nilai. Misalnya headers={'CustomValue': value}

Pemecahan Masalah

Umum

Klien Blob Penyimpanan meningkatkan pengecualian yang ditentukan dalam Azure Core.

Daftar ini dapat digunakan untuk referensi untuk menangkap pengecualian yang dilemparkan. Untuk mendapatkan kode kesalahan tertentu dari pengecualian, gunakan error_code atribut , yaitu, exception.error_code.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaktifkan, dapat diaktifkan pada klien dengan logging_enable argumen :

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)

Demikian pula, logging_enable dapat mengaktifkan pengelogan mendetail untuk satu operasi, meskipun tidak diaktifkan untuk klien:

service_client.get_service_stats(logging_enable=True)

Langkah berikutnya

Lebih banyak kode sampel

Mulai menggunakan sampel Blob kami.

Beberapa sampel Storage Blobs Python SDK tersedia untuk Anda di repositori GitHub SDK. Sampel ini menyediakan kode contoh untuk skenario tambahan yang umum ditemui saat bekerja dengan Blob Penyimpanan:

blob_samples_container_access_policy.py (versi asinkron) - Contoh untuk mengatur kebijakan Akses:
- Menyiapkan Kebijakan Akses untuk kontainer
blob_samples_hello_world.py (versi asinkron) - Contoh untuk tugas Blob Penyimpanan umum:
- Menyiapkan kontainer
- Membuat blok, halaman, atau menambahkan blob
- Unggah blob
- Unduh blob
- Hapus blob
blob_samples_authentication.py (versi asinkron) - Contoh untuk mengautentikasi dan membuat klien:
- Dari string koneksi
- Dari kunci akses bersama
- Dari token tanda tangan akses bersama
- Dari direktori aktif
blob_samples_service.py (versi asinkron) - Contoh untuk berinteraksi dengan layanan blob:
- Mendapatkan informasi akun
- Mendapatkan dan mengatur properti layanan
- Mendapatkan statistik layanan
- Membuat, mencantumkan, dan menghapus kontainer
- Mendapatkan klien Blob atau Kontainer
blob_samples_containers.py (versi asinkron) - Contoh untuk berinteraksi dengan kontainer:
- Membuat kontainer dan menghapus kontainer
- Mengatur metadata pada kontainer
- Mendapatkan properti kontainer
- Memperoleh sewa pada kontainer
- Menetapkan kebijakan akses pada kontainer
- Mengunggah, mencantumkan, menghapus blob dalam kontainer
- Mendapatkan klien blob untuk berinteraksi dengan blob tertentu
blob_samples_common.py (versi asinkron) - Contoh umum untuk semua jenis blob:
- Membuat rekam jepret
- Menghapus rekam jepret blob
- Penghapusan sementara blob
- Membatalkan penghapusan blob
- Memperoleh sewa pada blob
- Menyalin blob dari URL
blob_samples_directory_interface.py - Contoh untuk berinteraksi dengan penyimpanan Blob seolah-olah itu adalah direktori pada sistem file:
- Menyalin (mengunggah atau mengunduh) satu file atau direktori
- Mencantumkan file atau direktori pada satu tingkat atau secara rekursif
- Menghapus satu file atau menghapus direktori secara rekursif

Dokumentasi tambahan

Untuk dokumentasi yang lebih luas tentang penyimpanan Azure Blob, lihat dokumentasi penyimpanan Azure Blob di docs.microsoft.com.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.