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

• .NET
• Java
• JavaScript
• Python
• Go

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

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

必要條件

• Azure 訂用帳戶 - 建立免費帳戶
• Azure 儲存體帳戶 - 建立儲存體帳戶
• Python 3.8+

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 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

授權

授權機制必須含有處理容器屬性或中繼資料的必要權限。 若要使用 Microsoft Entra ID 進行授權 (建議)，您需要 Azure RBAC 內建角色儲存體 Blob 資料讀者或更高權限，才能「取得」作業，以及儲存體 Blob 資料參與者或更新版本，才能「設定」作業。 若要深入了解，請參閱取得容器屬性 (REST API)、設定容器中繼資料 (REST API) 或取得容器中繼資料 (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 標頭的所有限制。 如需中繼資料命名需求的詳細資訊，請參閱中繼資料名稱。

擷取容器屬性

若要擷取容器屬性，請使用下列其中一種方法：

• ContainerClient.get_container_properties

下列程式碼範例會擷取容器的系統屬性，並將屬性值寫入主控台視窗：

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

    properties = container_client.get_container_properties()

    print(f"Public access type: {properties.public_access}")
    print(f"Lease status: {properties.lease.status}")
    print(f"Lease state: {properties.lease.state}")
    print(f"Has immutability policy: {properties.has_immutability_policy}")

設定及擷取中繼資料

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

• ContainerClient.set_container_metadata

設定容器中繼資料會覆寫與容器相關聯的所有現有中繼資料。 您無法修改個別名稱/值組。

下列程式碼範例會在容器上設定中繼資料：

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

    # Retrieve existing metadata, if desired
    metadata = container_client.get_container_properties().metadata

    more_metadata = {'docType': 'text', 'docCategory': 'reference'}
    metadata.update(more_metadata)

    # Set metadata on the container
    container_client.set_container_metadata(metadata=metadata)

若要擷取中繼資料，請呼叫下列方法：

• ContainerClient.get_container_properties

下列範例會在中繼資料值中讀取：

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

    # Retrieve existing metadata, if desired
    metadata = container_client.get_container_properties().metadata

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

非同步設定容器中繼資料

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

請遵循下列步驟，使用非同步 API 設定容器中繼資料：

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，然後呼叫設定容器中繼資料的方法。 請注意，只有最上層用戶端需要使用 async with，因為從中建立的其他用戶端會共用相同的連線集區。

   async def main():
       sample = ContainerSamples()
   
       # 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. 新增程式碼以設定容器中繼資料。 該程式碼與同步範例相同，不同之處在於該方法是以 async 關鍵字宣告，而 await 關鍵字是在呼叫 get_container_properties 和 set_container_metadata 方法時使用。

   async def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
       container_client = blob_service_client.get_container_client(container=container_name)
   
       # Retrieve existing metadata, if desired
       metadata = (await container_client.get_container_properties()).metadata
   
       more_metadata = {'docType': 'text', 'docCategory': 'reference'}
       metadata.update(more_metadata)
   
       # Set metadata on the container
       await container_client.set_container_metadata(metadata=metadata)
   

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

資源

若要深入了解如何使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫來設定和擷取容器屬性和中繼資料，請參閱下列資源。

程式碼範例

• 檢視本文中的同步或非同步程式碼範例 (GitHub)

REST API 操作

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

• 取得容器屬性 (REST API)
• 設定容器中繼資料 (REST API)
• 取得容器中繼資料 (REST API)

get_container_properties 方法會藉由呼叫取得容器屬性作業和取得容器中繼資料作業來擷取容器屬性和中繼資料。

用戶端程式庫資源

• 用戶端程式庫參考文件
• 用戶端程式庫原始程式碼
• 套件 (Pypi) (英文)

相關內容

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