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

  • [アーティクル]

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

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

前提条件

環境を設定する

既存のプロジェクトがない場合、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, ContentSettings

承認

認可メカニズムには、コンテナーのプロパティまたはメタデータを操作するための権限が必要です。 Microsoft Entra ID による認可 (推奨) の場合、get 操作にはストレージ BLOB データ閲覧者以上、set 操作にはストレージ BLOB データ共同作成者以上の Azure RBAC 組み込みロールが必要です。 詳細については、BLOB プロパティの設定 (REST API)、BLOB プロパティの取得 (REST API)、BLOB メタデータの設定 (REST API)、BLOB メタデータの取得 (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 ヘッダーに適用されるすべての制約に準拠する必要があります。 メタデータの名前付けの要件について詳しくは、「メタデータ名」をご覧ください。

注意

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

コード サンプル

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

REST API の操作

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

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

関連するコンテンツ

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