Python を使用した BLOB プロパティとメタデータの管理

  • [アーティクル]

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

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

前提条件

  • この記事では、Python 用の Azure Blob Storage クライアント ライブラリを操作するための設定が済んだプロジェクトが、既にあることを前提としています。 パッケージのインストール、import ステートメントの追加、認可されたクライアント オブジェクトの作成を含むプロジェクトの設定については、「Azure Blob Storage と Python で作業を開始する」を参照してください。
  • この認可メカニズムには、BLOB のプロパティまたはメタデータを操作するためのアクセス許可が必要です。 詳細については、次の REST API 操作の認可ガイダンスを参照してください。

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

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

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

    メタデータ名/値ペアは有効な HTTP ヘッダーであり、HTTP ヘッダーに適用されるすべての制約に準拠する必要があります。 メタデータの名前付けの要件について詳しくは、「メタデータ名」をご覧ください。

注意

また、BLOB インデックス タグを使用して、ユーザー定義の任意のキーまたは値の属性を Azure Blob Storage リソースと共に格納することもできます。 メタデータに似ていますが、BLOB インデックス タグにのみ自動的にインデックスが付けられて、ネイティブの BLOB サービスによって検索可能になります。 Azure Search などの別のサービスを使用する場合を除き、メタデータにインデックスを付けてクエリを実行することはできません。

この機能の詳細については、「BLOB インデックスを使用して Azure Blob Storage でデータを管理および検索する (プレビュー)」を参照してください。

プロパティを設定および取得する

BLOB でプロパティを設定するには、次のメソッドを使います。

明示的に設定されていないプロパティは消去されます。 既存のプロパティを保持するには、まず BLOB のプロパティを取得し、その後それらを使用して更新されていないヘッダーを設定します。

次のコード例では、既存のプロパティを保持しながら、content_type と content_language のシステム プロパティを BLOB に設定します。

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

次のコード例では、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 メソッドは、Get Blob Properties 操作と Get Blob Metadata 操作の両方を呼び出すことによって、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 Storage クライアント ライブラリでは、BLOB のプロパティとメタデータを非同期的に管理できます。 プロジェクトのセットアップ要件の詳細については、「非同期プログラミング」を参照してください。

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

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

    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 Storage クライアント ライブラリを使用して、システム プロパティとユーザー定義メタデータを管理する方法の詳細については、次のリソースを参照してください。

REST API の操作

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

コード サンプル

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

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