Python を使用してコンテナーのプロパティとメタデータを管理する

BLOB コンテナーは、そこに含まれているデータに加えて、システム プロパティとユーザー定義メタデータをサポートしています。 この記事では、Python 用 Azure Storage クライアント ライブラリを使用して、システム プロパティとユーザー定義メタデータを管理する方法について説明します。

非同期 API を使用したプロパティとメタデータの管理については、「コンテナー メタデータを非同期的に設定する」を参照してください。

前提条件

• Azure サブスクリプション - 無料アカウントを作成する
• Azure Storage アカウント - ストレージ アカウントの作成
• python=3.8.10

環境を設定する

既存のプロジェクトがない場合、Python 用 Azure Blob Storage クライアント ライブラリを操作するためのプロジェクトをセットアップする方法についてこのセクションで説明します。 詳細については、「Azure Blob Storage と 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 による認可 (推奨) の場合、get 操作にはストレージ BLOB データ閲覧者以上、set 操作にはストレージ BLOB データ共同作成者以上の Azure RBAC 組み込みロールが必要です。 詳細については、「Get Container Properties (REST API)」、「Set Container Metadata (REST API)」、または「Get Container Metadata (REST API)」の認可のガイダンスを参照してください。

クライアント オブジェクトの作成

アプリを Blob Storage に接続するには、 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)

また、特定のコンテナーまたは BLOB 用のクライアント オブジェクトを、直接または BlobServiceClient オブジェクトから作成することもできます。 クライアント オブジェクトの作成と管理の詳細については、「データ リソースを操作するクライアント オブジェクトを作成および管理する」を参照してください。

プロパティとメタデータについて

• システム プロパティ: システム プロパティは BLOB ストレージ リソースごとに存在します。 このようなプロパティには、読み取りまたは設定可能なものもありますが、読み取り専用のものもあります。 実際には、システムのプロパティの一部は、特定の標準 HTTP ヘッダーに対応しています。 Python 用 Azure Storage クライアント ライブラリは、これらのプロパティをユーザーに代わって維持します。

• ユーザー定義のメタデータ: ユーザー定義メタデータは、BLOB ストレージ リソースに対して指定された 1 つ以上の名前と値のペアで構成されます。 メタデータを使用すると、リソースに関する追加の値を格納できます。 メタデータ値は独自の目的にのみ使用され、リソースの動作には影響しません。

  メタデータ名/値ペアは有効な 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 またはコンテナーのリソースで 1 つ以上の名前と値のペアとして指定できます。 メタデータを設定するには、次のメソッドを使用します。

• 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 Storage クライアント ライブラリでは、コンテナーのプロパティとメタデータの非同期管理がサポートされています。 プロジェクトのセットアップ要件の詳細については、「非同期プログラミング」を参照してください。

非同期 API を使用してコンテナー メタデータを設定するには、次の手順に従います。

1. 次の import ステートメントを追加します。

   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 キーワードを使用してメソッドが宣言され、get_container_properties メソッドと set_container_metadata メソッドを呼び出すときに await キーワードが使用される点が異なります。

   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 Storage クライアント ライブラリを使用してコンテナーのプロパティとメタデータを設定および取得する方法の詳細については、次のリソースをご覧ください。

コード サンプル

• この記事の同期または非同期のサンプル コードを表示する (GitHub)

REST API の操作

Azure SDK for Python には Azure REST API に基づき構築されたライブラリが含まれるため、使い慣れた Python パラダイムを通じて REST API 操作を実施できます。 プロパティとメタデータを設定および取得するためのクライアント ライブラリ メソッドでは、次の REST API 操作が使用されます。

• Get Container Properties (REST API)
• Set Container Metadata (REST API)
• Get Container Metadata (REST API)

get_container_properties メソッドでは、Get Container Properties 操作と Get Container Metadata 操作の両方を呼び出して、コンテナーのプロパティとメタデータを取得します。

クライアント ライブラリのリソース

• クライアント ライブラリのリファレンス ドキュメント
• クライアント ライブラリ ソース コード
• パッケージ (PyPi)

関連するコンテンツ

• この記事は、Python の Blob Storage 開発者ガイドの一部です。 詳細については、「Python アプリの構築」にある開発者ガイドの記事の完全な一覧を参照してください。