Python 用 Azure ライブラリの使用パターン

[アーティクル]
04/15/2024

Azure SDK for Python は、Python SDK パッケージインデックスに一覧表示されている、多数の独立したライブラリで構成されています。

すべてのライブラリは、インストールや、オブジェクト引数に対するインライン JSON の使用など、特定の共通の特性と使用パターンを共有します。

ローカルの開発環境を設定する

まだ行っていない場合は、このコードを実行できる環境を設定します。次のことをお試しください。

Python 仮想環境を構成します。仮想環境は、ローカルまたは Azure Cloud Shell で作成し、そこでコードを実行できます。仮想環境の使用を開始するには、必ず仮想環境をアクティブにします。
Conda 環境を使用します。
Visual Studio Code または GitHub Codespaces で Dev コンテナを使用します。

特定のライブラリパッケージをインストールするには、pip install を使用します。

# Install the management library for Azure Storage
pip install azure-mgmt-storage

# Install the client library for Azure Blob Storage
pip install azure-storage-blob

pip install は、現在の Python 環境にライブラリの最新バージョンを取得します。

また、pip を使用してライブラリをアンインストールしたり、プレビューバージョンを含む特定のバージョンをインストールしたりすることもできます。詳細については、「Python 用 Azure ライブラリパッケージをインストールする方法」を参照してください。

Conda 環境に特定のライブラリパッケージをインストールするには、conda install を使用します。

# Install the Azure management library package
conda install azure-mgmt

# Install the client library for Azure Storage
conda install azure-storage

conda install は、現在の Conda 環境にパッケージの最新バージョンを取得します。

パッケージを削除する方法や特定のバージョンをインストールする方法など、詳細については、「Python 用 Azure ライブラリパッケージをインストールする方法」を参照してください。

非同期操作

非同期ライブラリ

多くのクライアントおよび管理ライブラリでは、非同期バージョン (.aio) が提供されています。 asyncio ライブラリは Python 3.4 以降で使用でき、async/await キーワードは Python 3.5 で導入されました。ライブラリの非同期バージョンは、Python 3.5 以降で使用することを目的としています。

非同期バージョンの Azure Python SDK ライブラリの例として、azure.storage.blob.aio、azure.servicebus.aio、 azure.mgmt.keyvault.aio および azure.mgmt.compute.aio が挙げられます。

これらのライブラリを動作させるには、aiohttp などの非同期トランスポートが必要です。 azure-core ライブラリは非同期トランスポート、AioHttpTransport を提供します。これは、非同期ライブラリが使用します。

次のコードは、非同期バージョンの Azure BLOB ストレージライブラリ用のクライアントを作成する方法を示しています。

credential = DefaultAzureCredential()

async def run():

    async with BlobClient(
        storage_url,
        container_name="blob-container-01",
        blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
        credential=credential,
    ) as blob_client:

        # Open a local file and upload its contents to Blob Storage
        with open("./sample-source.txt", "rb") as data:
            await blob_client.upload_blob(data)
            print(f"Uploaded sample-source.txt to {blob_client.url}")

        # Close credential
        await credential.close()

asyncio.run(run())

完全な例は、use_blob_auth_async.py の GitHub にあります。このコードの同期バージョンについては、「例: BLOB のアップロード」を参照してください。

長時間実行される操作

呼び出す一部の管理操作 (ComputeManagementClient.virtual_machines.begin_create_or_update とWebSiteManagementClient.web_apps.begin_create_or_update が実行時間の長期操作に対してポーラーを返す操作、LROPoller[<type>]、<type> は、該当する操作に固有です。

Note

ライブラリ内のメソッド名の違いは、バージョンの違いによるものです。 azure.core に基づいていない以前のライブラリでは、通常、create_or_update などの名前が使用されます。 azure.core に基づくライブラリは、長期ポーリング操作をより良く示すために、begin_ プレフィックスをメソッド名に追加します。新しい azure.core ベースのライブラリへの以前のコードの移行は、ほとんどのメソッドシグネチャが同じままであるため、通常、メソッド名の前に begin_ を付加することを意味します。

LROPoller 戻り値とは、操作が非同期であることを意味します。したがって、そのポーラーの result メソッドを呼び出して、操作が完了するまで待機し、その結果を取得する必要があります。

「例: Web アプリの作成とデプロイ」に記載されている次のコードは、ポーラーを使用して結果を待機する例を示しています。

poller = app_service_client.web_apps.begin_create_or_update(RESOURCE_GROUP_NAME,
    WEB_APP_NAME,
    {
        "location": LOCATION,
        "server_farm_id": plan_result.id,
        "site_config": {
            "linux_fx_version": "python|3.8"
        }
    }
)

web_app_result = poller.result()

この場合、begin_create_or_update の戻り値は、AzureOperationPoller[Site] 型であり、poller.result() の戻り値がSite オブジェクトであることを示しています。

例外

一般に、Azure ライブラリでは、失敗した Azure REST API への HTTP 要求など、意図したとおりに操作を実行できなかった場合に例外が発生します。アプリコードの場合、try...except ブロックを使用して、ライブラリ操作を囲うことができます。

発生する可能性のある例外の種類の詳細については、該当する操作のドキュメントを参照してください。

ログ機能

最新の Azure ライブラリでは、Python の標準的な logging ライブラリを使用してログ出力が生成されます。個々のライブラリ、ライブラリのグループ、またはすべてのライブラリのログ記録レベルを設定できます。ログ記録ストリームハンドラーを登録したら、特定のクライアントオブジェクトまたは特定の操作のログ記録を有効にすることができます。詳細については、Azure ライブラリでのログ記録に関するページを参照してください。

[プロキシ構成]

プロキシを指定するために、環境変数または省略可能な引数を使用できます。詳細については、プロキシの構成方法に関するページを参照してください。

クライアントオブジェクトおよびメソッドの省略可能な引数

ライブラリリファレンスドキュメントでは、多くの場合、クライアントオブジェクトコンストラクターまたは特定の操作メソッドのシグネチャに、**kwargs または **operation_config 引数が表示されます。これらのプレースホルダーは、該当するオブジェクトまたはメソッドで別の名前付き引数がサポートされる可能性があることを示します。通常、リファレンスドキュメントには、使用できる特定の引数が示されます。次のセクションで説明されているように、多くの場合、いくつかの一般的な引数もサポートされます。

azure.core に基づくライブラリの引数

これらの引数は、「Python」の「新しいライブラリ」に一覧表示されているライブラリに適用されます。 azure-core のキーワード引数のサブセットの例は次のとおりです。完全な一覧については、「azure-coreの GitHub README」を参照してください。

名前	Type	Default	説明
logging_enable	[bool]	False	ログ記録を有効にします。詳細については、Azure ライブラリでのログ記録に関するページを参照してください。
プロキシ	dict	{}	プロキシサーバーの URL。詳細については、プロキシの構成方法に関するページを参照してください。
use_env_settings	[bool]	True	True の場合、`HTTP_PROXY` および `HTTPS_PROXY` 環境変数をプロキシで使用できるようにします。 False の場合、環境変数は無視されます。詳細については、プロキシの構成方法に関するページを参照してください。
connection_timeout	int	300	Azure REST API エンドポイントへの接続を確立するときのタイムアウト (秒)。
read_timeout	int	300	Azure REST API 操作を完了するとき (つまり、応答を待機するとき) のタイムアウト (秒)。
retry_total	int	10	REST API 呼び出しに対して許容される再試行の回数。再試行を無効にするには `retry_total=0` を使用します。
retry_mode	enum	exponential	再試行のタイミングを直線的または指数関数的に適用します。 'single' の場合、再試行は一定の間隔で行われます。 'exponential' の場合、各再試行の待機時間は、前の再試行の 2 倍となります。

個々のライブラリには、これらの引数のいずれかをサポートする義務はありません。したがって、詳細については、各ライブラリのリファレンスドキュメントを常に参照してください。また、各ライブラリが他の引数をサポートしている場合もあります。たとえば、BLOB ストレージ固有のキーワードの場合は、「azure-storage-blob の GitHub README」を参照してください。

オブジェクト引数に対するインライン JSON パターン

Azure ライブラリ内の多くの操作では、オブジェクト引数を個別のオブジェクトまたはインライン JSON として表すことができます。

たとえば、ResourceManagementClient オブジェクトがあり、その create_or_update メソッドを使用してリソースグループを作成するとします。このメソッドの第 2 引数の型は、ResourceGroup です。

create_or_update メソッドを呼び出すために、ResourceGroup の独立したインスタンスを、その必須の引数 (このケースでは location) を使って直接作成することができます。

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonSDKExample-rg",
    ResourceGroup(location="centralus")
)

または、同じパラメーターをインライン JSON として渡すこともできます。

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonAzureExample-rg", {"location": "centralus"}
)

インライン JSON を使用する場合、Azure ライブラリにより、インライン JSON は、目的の引数の適切なオブジェクト型に自動的に変換されます。

オブジェクトの中で、オブジェクト引数を入れ子にすることもできます。その場合、JSON を入れ子にして使用することもできます。

たとえば、KeyVaultManagementClient オブジェクトのインスタンスがあり、その create_or_update メソッドを呼び出すとします。このケースでは、第 3 引数の型が VaultCreateOrUpdateParameters であり、それ自体に VaultProperties 型の引数が含まれます。さらに、VaultProperties には、Sku 型と list[AccessPolicyEntry] 型のオブジェクト引数が含まれます。 Sku には SkuName オブジェクトが含まれ、個々の AccessPolicyEntry には Permissions オブジェクトが含まれています。

埋め込みオブジェクトを使用して begin_create_or_update を呼び出すには、次のようなコードを使用します (tenant_id、object_id および LOCATION は既に定義されているものとします)。また、関数呼び出しの前に、必要なオブジェクトを作成することもできます。

# Provision a Key Vault using inline parameters
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_A,
    VaultCreateOrUpdateParameters(
        location = LOCATION,
        properties = VaultProperties(
            tenant_id = tenant_id,
            sku = Sku(
                name="standard",
                family="A"
            ),            
            access_policies = [
                AccessPolicyEntry(
                    tenant_id = tenant_id,
                    object_id = object_id,
                    permissions = Permissions(
                        keys = ['all'],
                        secrets = ['all']
                    )
                )
            ]
        )
    )
)

key_vault1 = poller.result()

インライン JSON を使用して同じ呼び出しを記述した場合は次のようになります。

# Provision a Key Vault using inline JSON
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_B,
    {
        'location': LOCATION,
        'properties': {
            'sku': {
                'name': 'standard',
                'family': 'A'
            },
            'tenant_id': tenant_id,
            'access_policies': [{
                'tenant_id': tenant_id,
                'object_id': object_id,                
                'permissions': {
                    'keys': ['all'],
                    'secrets': ['all']
                }
            }]
        }
    }
)

key_vault2 = poller.result()

両方の形式は同等であるため、いずれか好きな方を選択できます。また、これらを混在させることもできます。 (これらの例の完全なコードは、GitHub で確認できます)。

JSON の書式が正しくないと、通常、"DeserializationError: Unable to deserialize to object: type, AttributeError: 'str' object has no attribute 'get' (DeserializationError: オブジェクトに逆シリアル化できません: 型、AttributeError: 'str' オブジェクトに属性 'get' がありません)" というエラーが発生します。このエラーの一般的な原因は、ライブラリでは入れ子になった JSON オブジェクトを予期しているのに、プロパティに単一の文字列を指定していることです。たとえば、前の例で 'sku': 'standard' を使用すると、このエラーが発生します。sku パラメーターには、Sku オブジェクトとして、インラインオブジェクトの JSON (このケースでは {'name': 'standard'}) が想定されていて、それが目的の SkuName 型にマッピングされるためです。

次のステップ

Python 用 Azure ライブラリを使用するための一般的なパターンを理解できたので、以下に挙げるそれぞれ独立した例を参照して、管理とクライアントライブラリの具体的なシナリオを検討します。これらの例は連続的でも相互依存的でもないため、任意の順序で試すことができます。

Python 用 Azure ライブラリの使用パターン

ローカルの開発環境を設定する

ライブラリのインストール

非同期操作

非同期ライブラリ

長時間実行される操作

例外

ログ機能

[プロキシ構成]

クライアントオブジェクトおよびメソッドの省略可能な引数

azure.core に基づくライブラリの引数

オブジェクト引数に対するインライン JSON パターン

次のステップ

フィードバック

フィードバック

その他のリソース

Python 用 Azure ライブラリの使用パターン

ローカルの開発環境を設定する

ライブラリのインストール

非同期操作

非同期ライブラリ

長時間実行される操作

例外

ログ機能

[プロキシ構成]

クライアント オブジェクトおよびメソッドの省略可能な引数

azure.core に基づくライブラリの引数

オブジェクト引数に対するインライン JSON パターン

次のステップ

フィードバック

フィードバック

その他のリソース

クライアントオブジェクトおよびメソッドの省略可能な引数