Mengelola properti blob dan metadata dengan Python

Selain data yang dikandungnya, blob mendukung properti sistem dan metadata yang ditentukan pengguna. Artikel ini memperlihatkan cara mengelola properti sistem dan metadata yang ditentukan pengguna menggunakan pustaka klien Azure Storage untuk Python.

Untuk mempelajari tentang mengelola properti dan metadata menggunakan API asinkron, lihat Mengatur metadata blob secara asinkron.

Prasyarat

Langganan Azure - buat akun secara gratis
Akun penyimpanan Azure - buat akun penyimpanan
Python 3.8+

Persiapkan 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, ContentSettings

Otorisasi

Mekanisme otorisasi harus memiliki izin yang diperlukan untuk bekerja dengan properti kontainer atau metadata. Untuk otorisasi dengan Microsoft Entra ID (disarankan), Anda memerlukan peran bawaan Azure RBAC Storage Blob Data Reader atau yang lebih tinggi untuk operasi pengambilan, dan Storage Blob Data Contributor atau yang lebih tinggi untuk operasi penetapan. Untuk mempelajari lebih lanjut, lihat panduan otorisasi untuk Mengatur Properti Blob (REST API), Dapatkan Properti Blob (REST API), Atur Metadata Blob (REST API), atau Dapatkan Metadata Blob (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 properti dan metadata

Properti sistem: Properti sistem ada di setiap sumber daya penyimpanan Blob. Beberapa dari mereka dapat dibaca atau diatur, sementara yang lain baca-saja. Di bawah sampul, beberapa properti sistem sesuai dengan header HTTP standar tertentu. Pustaka klien Azure Storage untuk Python mempertahankan properti ini untuk Anda.
Metadata yang ditentukan pengguna: Metadata yang ditentukan pengguna terdiri dari satu atau beberapa pasangan nama-nilai yang Anda tentukan untuk sumber daya penyimpanan Blob. Anda dapat menggunakan metadata untuk menyimpan nilai tambahan dengan sumber daya. Nilai metadata hanya untuk tujuan Anda sendiri, dan tidak memengaruhi perilaku sumber daya.

Pasangan nama/nilai metadata adalah header HTTP yang valid dan harus mematuhi semua batasan yang mengatur header HTTP. Untuk informasi selengkapnya tentang persyaratan penamaan metadata, lihat Nama metadata.

Catatan

Tag indeks blob juga menyediakan kemampuan untuk menyimpan atribut kunci/nilai yang ditentukan pengguna bersama sumber daya penyimpanan Azure Blob. Meskipun mirip dengan metadata, hanya tag indeks blob yang secara otomatis diindeks dan dibuat dapat dicari oleh layanan blob asli. Metadata tidak dapat diindeks dan dikueri kecuali Anda menggunakan layanan terpisah seperti Azure Search.

Untuk mempelajari fitur ini selengkapnya, lihat Kelola dan temukan data di penyimpanan Azure Blob dengan indeks blob (pratinjau).

Atur dan dapatkan properti

Untuk mengatur properti pada blob, gunakan metode berikut:

BlobClient.set_http_headers

Properti apa pun yang tidak disetel secara eksplisit akan dihapus. Untuk mempertahankan properti yang sudah ada, Anda dapat terlebih dahulu mengambil properti blob, lalu menggunakannya untuk melengkapi header yang tidak diperbarui.

Contoh kode berikut mengatur content_type properti sistem dan content_language pada blob, sambil mempertahankan properti yang ada:

def set_properties(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Get the existing blob properties
    properties = blob_client.get_blob_properties()

    # Set the content_type and content_language headers, and populate the remaining headers from the existing properties
    blob_headers = ContentSettings(content_type="text/plain",
                                   content_encoding=properties.content_settings.content_encoding,
                                   content_language="en-US",
                                   content_disposition=properties.content_settings.content_disposition,
                                   cache_control=properties.content_settings.cache_control,
                                   content_md5=properties.content_settings.content_md5)
    
    blob_client.set_http_headers(blob_headers)

Untuk mengambil properti pada blob, gunakan metode berikut:

BlobClient.get_blob_properties

Contoh kode berikut mendapatkan properti sistem blob dan menampilkan beberapa nilai:

def get_properties(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    properties = blob_client.get_blob_properties()

    print(f"Blob type: {properties.blob_type}")
    print(f"Blob size: {properties.size}")
    print(f"Content type: {properties.content_settings.content_type}")
    print(f"Content language: {properties.content_settings.content_language}")

Atur dan ambil metadata

Anda dapat menentukan metadata sebagai satu atau beberapa pasangan nama-nilai pada sumber daya blob atau kontainer. Untuk mengatur metadata, kirim kamus yang berisi pasangan nama-nilai menggunakan metode berikut:

BlobClient.set_blob_metadata

Contoh kode berikut menetapkan metadata pada blob:

def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Retrieve existing metadata, if desired
    blob_metadata = blob_client.get_blob_properties().metadata

    more_blob_metadata = {'docType': 'text', 'docCategory': 'reference'}
    blob_metadata.update(more_blob_metadata)

    # Set metadata on the blob
    blob_client.set_blob_metadata(metadata=blob_metadata)

Untuk mengambil metadata, panggil metode get_blob_properties pada blob Anda untuk mengisi koleksi metadata, lalu baca nilai, seperti yang ditunjukkan pada contoh di bawah ini. Metode ini get_blob_properties mengambil properti blob dan metadata dengan memanggil operasi Get Blob Properties dan operasi Get Blob Metadata.

Contoh kode berikut membaca metadata pada blob dan mencetak setiap pasangan kunci/nilai:

def get_metadata(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Retrieve existing metadata, if desired
    blob_metadata = blob_client.get_blob_properties().metadata

    for k, v in blob_metadata.items():
        print(k, v)

Mengatur metadata pada blob secara asinkronus

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

Ikuti langkah-langkah ini untuk mengatur metadata blob menggunakan API asinkron:

Tambahkan pernyataan import berikut:

import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient

Tambahkan kode untuk menjalankan program menggunakan asyncio.run. Fungsi ini menjalankan coroutine yang diteruskan, main() dalam contoh kami, dan mengelola perulangan acara asyncio. Korutin dinyatakan dengan sintaks async/await. Dalam contoh ini, coroutine pertama-tama main() membuat tingkat BlobServiceClient atas menggunakan async with, lalu memanggil metode yang mengatur metadata blob. Perhatikan bahwa 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.set_metadata(blob_service_client, "sample-container")

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

Tambahkan kode untuk mengatur metadata blob. Kode sama dengan contoh sinkron, kecuali bahwa metode dideklarasikan dengan async kata kunci dan await kata kunci digunakan saat memanggil get_blob_properties metode dan set_blob_metadata .

async def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Retrieve existing metadata, if desired
    properties = await blob_client.get_blob_properties()
    blob_metadata = properties.metadata

    more_blob_metadata = {'docType': 'text', 'docCategory': 'reference'}
    blob_metadata.update(more_blob_metadata)

    # Set metadata on the blob
    await blob_client.set_blob_metadata(metadata=blob_metadata)

Dengan pengaturan dasar ini, Anda dapat menerapkan contoh lain dalam artikel ini sebagai korutin menggunakan sintaks async/await.

Sumber

Untuk mempelajari selengkapnya tentang cara mengelola properti sistem dan metadata yang ditentukan pengguna menggunakan pustaka klien Azure Blob Storage untuk Python, lihat sumber daya berikut ini.

Sampel kode

Lihat sampel kode sinkron atau asinkron dari artikel ini (GitHub)

Operasi REST API

Azure SDK untuk Python berisi pustaka yang dibangun di atas Azure REST API, memungkinkan Anda berinteraksi dengan operasi REST API melalui paradigma Python yang sudah dikenal. Metode pustaka klien untuk mengelola properti sistem dan metadata yang ditentukan pengguna menggunakan operasi REST API berikut:

Sumber daya pustaka klien

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.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-04-08