Mendaftar blob dengan Python

Artikel ini menunjukkan cara mencantumkan blob menggunakan pustaka klien Azure Storage untuk Python.

Untuk mempelajari cara mencantumkan blob menggunakan API asinkron, lihat Daftar blob secara asinkron.

Prasyarat

Menyiapkan lingkungan Anda

Jika Anda tidak memiliki proyek yang sudah ada, bagian ini menunjukkan kepada Anda cara menyiapkan proyek untuk bekerja dengan pustaka klien Azure Blob Storage untuk Python. Untuk detail selengkapnya, lihat Mulai menggunakan Azure Blob Storage dan Python.

Untuk bekerja dengan contoh kode dalam artikel ini, ikuti langkah-langkah ini untuk menyiapkan proyek Anda.

Memasang paket

Instal paket berikut menggunakan pip install:

pip install azure-storage-blob azure-identity

Menambahkan pernyataan impor

Tambahkan pernyataan import berikut:

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

Otorisasi

Mekanisme otorisasi harus memiliki izin yang diperlukan untuk mencantumkan blob. Untuk otorisasi dengan Microsoft Entra ID (disarankan), Anda memerlukan peran bawaan Azure RBAC Storage Blob Data Reader atau lebih tinggi. Untuk mempelajari lebih lanjut, lihat panduan otorisasi untuk List Blobs (REST API).

Membuat objek klien

Untuk menyambungkan aplikasi ke Blob Storage, buat instans BlobServiceClient. Contoh berikut menunjukkan cara membuat objek klien menggunakan DefaultAzureCredential untuk otorisasi:

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

Anda juga dapat membuat objek klien untuk kontainer atau blob tertentu, baik secara langsung atau dari BlobServiceClient objek. Untuk mempelajari selengkapnya tentang membuat dan mengelola objek klien, lihat Membuat dan mengelola objek klien yang berinteraksi dengan sumber daya data.

Tentang pilihan daftar blob

Saat Anda membuat daftar blob melalui kode Anda, Anda dapat menentukan berbagai opsi untuk mengatur bagaimana hasil dikembalikan dari Azure Storage. Anda dapat menentukan jumlah hasil yang akan dikembalikan di setiap set hasil, lalu mengambil set berikutnya. Anda dapat menentukan awalan untuk mengembalikan blob yang namanya dimulai dengan karakter atau string tersebut. Anda bisa mencantumkan blob dalam struktur listing datar, atau secara hierarkis. Daftar hierarki mengembalikan blob seolah-olah disusun ke dalam folder.

Untuk mencantumkan blob dalam kontainer menggunakan daftar datar, panggil salah satu metode berikut:

  • ContainerClient.list_blobs (bersama dengan nama, secara opsional menyertakan metadata, tag, dan informasi lain yang terkait dengan setiap blob)
  • ContainerClient.list_blob_names (hanya mengembalikan nama blob)

Untuk mencantumkan blob dalam sebuah kontainer menggunakan daftar hierarkis, panggil metode berikut:

  • ContainerClient.walk_blobs (bersama dengan nama, opsional menyertakan metadata, tag, dan informasi lain yang terkait dengan setiap blob)

Memfilter hasil dengan prefiks

Untuk memfilter daftar blob, tentukan string untuk name_starts_with argumen kata kunci. String awalan dapat menyertakan satu atau lebih karakter. Azure Storage hanya mengembalikan blob yang namanya diawali dengan awalan tersebut.

Daftar datar dibandingkan dengan daftar hierarkis

Blob di Azure Storage diatur dalam paradigma datar, bukan paradigma hierarkis (seperti sistem file klasik). Namun, Anda dapat mengatur blob ke dalam direktori virtual untuk meniru struktur folder. Direktori virtual merupakan bagian dari nama blob dan ditunjukkan oleh karakter pemisah.

Untuk mengatur blob ke dalam direktori virtual, gunakan karakter pemisah dalam nama blob. Karakter pemisah default adalah garis miring (/), tetapi Anda dapat menentukan karakter apa pun sebagai pemisah.

Jika Anda menamai blob Anda menggunakan delimiter, Anda dapat memilih untuk mencantumkan blob secara hierarkis. Untuk operasi daftar hierarkis, Azure Storage mengembalikan direktori dan blob virtual di bawah objek induk. Anda dapat memanggil operasi daftar secara rekursif untuk melintasi hierarki, mirip dengan cara Anda melintasi sistem file klasik secara terprogram.

Menggunakan daftar datar

Secara bawaan, operasi pencantuman mengembalikan data blob dalam format daftar rata. Dalam daftar datar, blob tidak diatur oleh direktori virtual.

Contoh berikut mencantumkan blob dalam kontainer yang ditentukan menggunakan daftar datar:

def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs()

    for blob in blob_list:
        print(f"Name: {blob.name}")

Contoh keluaran mirip dengan:

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

Anda juga dapat menentukan opsi untuk memfilter hasil daftar atau menampilkan informasi lebih lanjut. Contoh berikut mencantumkan blob dan tag blob:

def list_blobs_flat_options(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs(include=['tags'])

    for blob in blob_list:
        print(f"Name: {blob['name']}, Tags: {blob['tags']}")

Contoh keluaran mirip dengan:

List blobs flat:
Name: file4.txt, Tags: None
Name: folderA/file1.txt, Tags: None
Name: folderA/file2.txt, Tags: None
Name: folderA/folderB/file3.txt, Tags: {'tag1': 'value1', 'tag2': 'value2'}

Catatan

Contoh output yang ditampilkan mengasumsikan bahwa Anda memiliki akun penyimpanan dengan namespace datar. Jika Anda mengaktifkan fitur namespace hierarkis untuk akun penyimpanan Anda, direktori tidak bersifat virtual. Sebaliknya, mereka adalah objek konkret yang independen. Akibatnya, direktori muncul dalam daftar sebagai blob panjang nol.

Untuk opsi daftar alternatif saat bekerja dengan namespace hierarkis, lihat Mencantumkan konten direktori (Azure Data Lake Storage).

Menggunakan daftar hierarkis

Saat Anda memanggil operasi daftar secara hierarkis, Azure Storage mengembalikan direktori dan blob virtual di tingkat hierarki pertama.

Untuk mencantumkan blob secara hierarkis, gunakan metode berikut:

Contoh berikut mencantumkan blob dalam kontainer yang ditentukan menggunakan daftar hierarkis:

depth = 0
indent = "  "
def list_blobs_hierarchical(self, container_client: ContainerClient, prefix):
    for blob in container_client.walk_blobs(name_starts_with=prefix, delimiter='/'):
        if isinstance(blob, BlobPrefix):
            # Indentation is only added to show nesting in the output
            print(f"{self.indent * self.depth}{blob.name}")
            self.depth += 1
            self.list_blobs_hierarchical(container_client, prefix=blob.name)
            self.depth -= 1
        else:
            print(f"{self.indent * self.depth}{blob.name}")

Contoh keluaran mirip dengan:

folderA/
  folderA/folderB/
    folderA/folderB/file3.txt
  folderA/file1.txt
  folderA/file2.txt
file4.txt

Catatan

Snapshot blob tidak dapat ditampilkan dalam operasi pembuatan daftar hierarkis.

Mendaftarkan blob secara asinkron

Pustaka klien Azure Blob Storage untuk Python mendukung daftar blob secara asinkron. Untuk mempelajari selengkapnya tentang persyaratan penyiapan proyek, lihat Pemrograman asinkron.

Ikuti langkah-langkah berikut untuk mencantumkan blob menggunakan API asinkron:

  1. Tambahkan pernyataan import berikut:

    import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, ContainerClient, BlobPrefix

  2. Tambahkan kode untuk menjalankan program menggunakan asyncio.run. Fungsi ini menjalankan coroutine yang diberikan, main() dalam contoh ini, dan mengelola loop peristiwa asyncio. Korutin dideklarasikan menggunakan sintaks async/await. Dalam contoh ini, korutina main() pertama-tama membuat objek BlobServiceClient tingkat atas dengan menggunakan async with, lalu memanggil metode yang menampilkan daftar blob. Hanya klien tingkat atas yang perlu menggunakan async with, karena klien lain yang dibuat darinya berbagi kumpulan koneksi yang sama.

    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.list_blobs_flat(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())

  3. Tambahkan kode untuk mencantumkan blob. Contoh kode berikut mencantumkan blob menggunakan daftar datar. Kode sama dengan contoh sinkron, kecuali metode dideklarasikan menggunakan async kata kunci dan async for digunakan saat memanggil list_blobs metode.

    async def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    async for blob in container_client.list_blobs():
        print(f"Name: {blob.name}")

Dengan penyiapan dasar ini, Anda dapat menerapkan contoh-contoh lain dalam artikel ini dalam bentuk coroutine menggunakan sintaks async/await.

Daftar blob dalam format Apache Arrow (pratinjau)

Important

Pencantuman blob dalam format Apache Arrow saat ini masih dalam PREVIEW. Skenario ini memerlukan versi beta (pratinjau) dari pustaka klien Azure Blob Storage untuk Python (misalnya, azure-storage-blobrilis preview 12.31.0b1 atau lebih baru). Fitur pratinjau disediakan tanpa perjanjian tingkat layanan dan tidak disarankan untuk beban kerja produksi. Beberapa fitur mungkin tidak didukung, atau memiliki kemampuan yang terbatas. Untuk informasi lebih lanjut, lihat Supplemental Terms of Use for Microsoft Azure Previews.

Kemampuan ini dibangun di atas API yang sudah ada List Blobs . Alih-alih menggunakan XML default, format Apache Arrow yang ringkas dan kolom digunakan sebagai format respons pada kabel. Anda mengaktifkannya dengan menetapkan satu opsi pada pemanggilan daftar kontainer. Python SDK mendekode Apache Arrow di belakang layar dan tetap mengembalikan objek yang samaBlobProperties. Pendekatan ini meningkatkan throughput listing dan mengurangi CPU sisi klien saat melakukan enumerasi kontainer besar. Ini mempertahankan kontrak respons yang menjadi dasar aplikasi.

Warning

Mencantumkan blob dalam format Apache Arrow tidak didukung pada akun penyimpanan yang memiliki namespace hierarkis (Azure Data Lake Storage) diaktifkan.

Untuk meminta hasil berformat Apache Arrow, atur argumen kata kunci response_format ke "arrow" saat Anda memanggil ContainerClient.list_blobs atau ContainerClient.list_blob_names. Saat menggunakan output Apache Arrow, Anda juga dapat mengatur argumen kata kunci start_from dan end_before untuk mengontrol kisaran jalur yang dikembalikan.

Catatan

Penggunaan response_format="arrow" memerlukan paket nanoarrow terpasang.

Contoh berikut mencantumkan blob dalam kontainer dan meminta hasilnya dalam format Apache Arrow:

# response_format="arrow" requires the nanoarrow package to be installed
blob_list = container_client.list_blobs(
    name_starts_with="folderA/",
    response_format="arrow",
)

for blob in blob_list:
    print("Name: " + blob.name)

Sumber

Untuk mempelajari lebih lanjut tentang cara mencantumkan blob menggunakan pustaka klien Azure Blob Storage untuk Python, lihat sumber daya berikut.

Sampel kode

Operasi REST API

Azure SDK untuk Python berisi pustaka yang dibangun di atas Azure REST API. Dengan menggunakan pustaka ini, Anda dapat berinteraksi dengan operasi REST API melalui paradigma Python yang sudah dikenal. Metode pustaka klien untuk mencantumkan blob menggunakan operasi REST API berikut:

Sumber daya pustaka klien

Lihat juga

Konten terkait

  • Artikel ini adalah bagian dari panduan pengembang Blob Storage untuk Python. Untuk mempelajari lebih lanjut, lihat daftar lengkap artikel panduan pengembang di Membangun aplikasi Python Anda.
  • Last updated on