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

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

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

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

まだ実行していない場合は、このコードを実行できる環境を設定できます。 いくつかのオプションを次に示します。

• venvまたは任意のツールを使用して Python 仮想環境を構成します。 仮想環境の使用を開始するには、必ずアクティブ化してください。 Python をインストールするには、「 Python のインストール」を参照してください。

  • バッシュ
  • PowerShellの

  #!/bin/bash
  # Create a virtual environment
  python -m venv .venv
  # Activate the virtual environment
  source .venv/Scripts/activate # only required for Windows (Git Bash)
  

• conda 環境を使用します。 Conda をインストールするには、「 Miniconda のインストール」を参照してください。

• Visual Studio Code または GitHub Codespaces で開発コンテナーを使用します。

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

python 環境管理ツール (pip または conda) に対応するインストール方法を選択します。

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

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

REM Install the azure identity library for Azure authentication
pip install azure-identity

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

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

REM Install the azure identity library for Azure authentication
pip install azure-identity

非同期操作

非同期ライブラリ

多くのクライアントおよび管理ライブラリでは、非同期バージョン (.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が用意されており、非同期ライブラリで使用されるため、aiohttpを個別にインストールする必要がない場合があります。

次のコードは、Azure Blob Storage ライブラリの非同期バージョンのクライアントを作成する方法を示す Python ファイルを作成する方法を示しています。

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 や WebAppsClient.web_apps.begin_create_or_updateなど) は、実行時間の長い操作 ( LROPoller[<type>]) のポーリングを返します。 <type> は対象の操作に固有です。

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

次のコードは、「 例: Web アプリを作成してデプロイする」から取得し、ポーリングツールを使用して結果を待機する例を示しています。

# Step 3: With the plan in place, provision the web app itself, which is the process that can host
# whatever code we want to deploy to it.

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 を参照してください。

個々のライブラリは、これらの引数をサポートする義務がないため、正確な詳細については、各ライブラリのリファレンス ドキュメントを常に参照してください。 また、各ライブラリが他の引数をサポートしている場合もあります。 たとえば、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 オブジェクトが必要な場合に、プロパティに 1 つの文字列を指定することです。 たとえば、前の例で 'sku': 'standard' を使用すると、このエラーが生成されます。これは、 sku パラメーターがインライン オブジェクト JSON を想定する Sku オブジェクトであるためです。この場合、 {'name': 'standard'}は想定される SkuName 型にマップされます。

次のステップ

Python 用 Azure ライブラリを使用するための一般的なパターンを理解したら、次のスタンドアロンの例を参照して、特定の管理とクライアント ライブラリのシナリオを調べます。 これらの例は、シーケンシャルまたは相互依存ではないため、任意の順序で試すことができます。

• 例: リソース グループを作成する

• 例: Azure Storage を使用する

• 例: Web アプリを作成してコードをデプロイする

• 例: データベースを作成してクエリを実行する

• 例: 仮想マシンを作成する

• 仮想マシンで Azure Managed Disks を使用する

• Azure SDK for Python に関する短いアンケートを完了する