共用方式為

使用 Python 管理 Blob 屬性和中繼資料

  • 發行項

除了包含的資料之外，Blob 還支援系統屬性和使用者定義的中繼資料。 本文說明如何使用適用於 Python 的 Azure 儲存體用戶端程式庫，來管理系統屬性和使用者定義的中繼資料。

若要了解如何使用非同步 API 管理屬性和中繼資料，請參閱以非同步方式設定 Blob 中繼資料。

必要條件

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫。 如需詳細資訊，請參閱開始使用 Azure Blob 儲存體和 Python。

若要使用本文中的程式碼範例，請遵循下列步驟來設定您的專案。

安裝套件

使用 pip install 安裝下列套件：

pip install azure-storage-blob azure-identity

新增 import 陳述式

加入下列 import 陳述式：

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContentSettings

授權

授權機制必須含有處理容器屬性或中繼資料的必要權限。 若要使用 Microsoft Entra ID 進行授權 (建議)，您需要 Azure RBAC 內建角色儲存體體 Blob 資料讀取器或更新版本，才能取得作業，以及儲存體 Blob 資料參與者或更新版本，才能設定作業。 若要深入了解，請參閱設定 Blob 屬性 (REST API) 的授權指引、取得 Blob 屬性、設定 Blob 中繼資料 (REST API)，或取得 Blob 中繼資料 (REST API)。

建立用戶端物件

若要將應用程式連線至 Blob 儲存體，請建立 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 物件建立特定容器或 Blob 的用戶端物件。 若要深入了解如何建立及管理用戶端物件，請參閱建立和管理與資料資源互動的用戶端端物件 (部分機器翻譯)。

關於屬性和中繼資料

  • 系統屬性：系統屬性存在於每個 Blob 儲存體資源上。 其中一些可以讀取或設定，另一些則是唯讀的。 實際上，某些系統屬性會對應至特定標準 HTTP 標頭。 適用於 Python 的 Azure 儲存體用戶端程式庫會為您維護這些屬性。

  • 使用者定義的中繼資料：使用者定義的中繼資料是由您為 Blob 儲存體資源所指定一或多個成對的名稱和數值所組成。 您可以使用中繼資料來儲存資源的額外值。 中繼資料值僅供您自己使用，並不會影響資源的運作方式。

    中繼資料名稱/值組是有效的 HTTP 標頭，所以應該遵守控管 HTTP 標頭的所有限制。 如需有關中繼資料命名需求的詳細資訊，請參閱中繼資料名稱。

注意

Blob 索引標記也提供將任意使用者定義索引鍵/值屬性與 Azure Blob 儲存體資源一起儲存的功能。 雖然與中繼資料類似，但是只有 Blob 索引標記會自動編製索引，並且可讓原生 Blob 服務進行搜尋。 除非您利用個別服務 (例如 Azure 搜尋服務)，否則中繼資料無法進行編製索引和查詢。

若要深入了解此功能，請參閱使用 Blob 索引 (預覽) 來管理和尋找 Azure Blob 儲存體上的資料。

設定和擷取屬性

若要在 Blob 上設定屬性，請使用下列方法：

未明確設定的任何屬性都會被清除。 若要保留任何現有的屬性，您可以首先擷取 Blob 屬性，然後使用這些屬性填入未更新的標頭。

下列程式碼範例會在 Blob 上設定 content_type 和 content_language 系統屬性，同時保留現有的屬性：

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)

若要擷取 Blob 上的屬性，請使用下列方法：

下列程式碼範例會取得 Blob 的系統屬性，並顯示部分值：

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}")

設定及擷取中繼資料

您可以將中繼資料指定為 blob 或容器資源上的一個或多個成對的名稱和數值。 若要設定中繼資料，請使用下列方法傳送字典，其中包含成對的名稱和數值：

下列程式碼範例會在 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)

若要擷取中繼資料，請在您的 Blob 上呼叫 get_blob_properties 方法，以填入中繼資料集合，然後讀取這些值，如以下範例所示。 get_blob_properties 方法會藉由呼叫取得 Blob 屬性作業和取得 Blob 中繼資料作業來擷取 Blob 屬性和中繼資料。

下列程式碼範例會讀取 Blob 上的中繼資料，並列印每個索引鍵/值組：

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)

以非同步方式設定 Blob 中繼資料

適用於 Python 的 Azure Blob 儲存體用戶端程式庫支援以非同步方式管理 Blob 屬性。 若要深入了解專案設定需求，請參閱非同步程式設計。

請遵循下列步驟來使用非同步 API 設定 Blob 中繼資料：

  1. 新增下列匯入陳述式：

    import asyncio

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

  2. 新增程式碼以使用 asyncio.run 執行程式。 此函式會執行傳遞的協同程式 (在我們的範例中為 main())，並管理 asyncio 事件迴圈。 協同程式會以 async/await 語法宣告。 在此範例中，main() 協同程式會先使用 async with 建立最上層 BlobServiceClient，然後呼叫設定 Blob 中繼資料的方法。 請注意，只有最上層用戶端需要使用 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.set_metadata(blob_service_client, "sample-container")

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

  3. 新增程式碼以設定 Blob 中繼資料。 程式碼與同步範例相同，不同之處在於方法是以 async 關鍵字宣告，而且 await 關鍵字是在呼叫 get_blob_properties 和 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)

完成這個基本設定後，您可以使用 async/await 語法，將本文中的其他範例實作為協同程式。

資源

若要深入了解如何使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫，來管理系統屬性和使用者定義的中繼資料，請參閱下列資源。

程式碼範例

REST API 操作

Azure SDK for Python 包含建置在 Azure REST API 之上的程式庫，可讓您透過熟悉的 Python 範例與 REST API 作業進行互動。 用於管理系統屬性與使用者定義中繼資料的用戶端程式庫方法會使用下列 REST API 作業：

用戶端程式庫資源

相關內容

  • 本文是適用於 Python 的 Blob 儲存體開發人員指南的一部分。 若要深入了解，請參閱位於建置 Python 應用程式的完整開發人員指南文章清單。