Python 用Azure App Configuration クライアント ライブラリ - バージョン 1.5.0

  • [アーティクル]

Azure App Configuration は、開発者がアプリケーション構成を単純かつ安全に一元化するのに役立つマネージド サービスです。

近年のプログラム、特にクラウドで実行されるプログラムは、その性質上、分散されたコンポーネントが多数存在するのが一般的です。 これらのコンポーネント全体に構成設定を分散させることは、トラブルシューティングすることの難しいエラーがアプリケーションのデプロイ中に発生する原因となります。 App Configurationを使用して、アプリケーションのすべての設定を 1 か所に安全に格納します。

App Configuration用のクライアント ライブラリを使用して、アプリケーション構成設定を作成および管理します。

ソースコード | パッケージ (Pypi) | パッケージ (Conda) | API リファレンス ドキュメント | 製品ドキュメント

免責事項

Python 2.7 の Azure SDK Python パッケージのサポートは、2022 年 1 月 1 日に終了しました。 詳細と質問については、このパッケージを使用するには https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 以降が必要ですを参照してください。詳細については、 Azure SDK for Python バージョンのサポート ポリシーに関するページを参照してください。

作業の開始

パッケージをインストールする

pip を使用して Python 用Azure App Configuration クライアント ライブラリをインストールします。

pip install azure-appconfiguration

前提条件

構成ストアを作成するには、Azure Portal または Azure CLI を使用できます。

その後、構成ストアを作成します。

az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastus

クライアントを認証する

App Configuration サービスと対話するには、AzureAppConfigurationClient クラスのインスタンスを作成する必要があります。 これを可能にするには、構成ストアの接続文字列を使用するか、AAD トークンを使用します。

接続文字列の使用

資格情報の取得

次の Azure CLI スニペットを使用して、構成ストアから接続文字列を取得します。

az appconfig credential list --name <config-store-name>

または、Azure Portal から接続文字列を取得します。

クライアントの作成

接続文字列の値を取得したら、AzureAppConfigurationClient を作成できます。

import os
from azure.appconfiguration import AzureAppConfigurationClient

CONNECTION_STRING = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

# Create app config client
client = AzureAppConfigurationClient.from_connection_string(CONNECTION_STRING)

AAD トークンを使用する

ここでは、 DefaultAzureCredential を使用してサービス プリンシパルとして認証する方法を示します。 ただし、 AzureAppConfigurationClient は 任意の azure-identity 資格情報を 受け入れます。 その他の資格情報の詳細については、 azure-identity のドキュメントを参照してください。

サービス プリンシパルを作成する (省略可能)

この Azure CLI スニペットは、新しいサービス プリンシパルを作成する方法を示しています。 使用する前に、"your-application-name" をサービス プリンシパルの適切な名前に置き換えます。

サービス プリンシパルを作成します。

az ad sp create-for-rbac --name http://my-application --skip-assignment

出力:

{
    "appId": "generated app id",
    "displayName": "my-application",
    "name": "http://my-application",
    "password": "random password",
    "tenant": "tenant id"
}

出力を使用して 、AZURE_CLIENT_ID (上記の "appId")、AZURE_CLIENT_SECRET (上記 の " パスワード")、および AZURE_TENANT_ID (上記 の "テナント" ) 環境変数を設定します。 次の例は、Bash でこれを行う方法を示しています。

export AZURE_CLIENT_ID="generated app id"
export AZURE_CLIENT_SECRET="random password"
export AZURE_TENANT_ID="tenant id"

該当するApp Configurationロールの 1 つをサービス プリンシパルに割り当てます。

クライアントの作成

AZURE_CLIENT_ID、AZURE_CLIENT_SECRET、AZURE_TENANT_ID環境変数が設定されると、DefaultAzureCredential は AzureAppConfigurationClient を認証できるようになります。

クライアントを構築するには、構成ストアの URL も必要です。構成ストアの URL は、Azure CLI または Azure Portal から取得できます。 Azure Portal で、URL がサービス "エンドポイント" として一覧表示されます

from azure.identity import DefaultAzureCredential
from azure.appconfiguration import AzureAppConfigurationClient

credential = DefaultAzureCredential()

client = AzureAppConfigurationClient(base_url="your_endpoint_url", credential=credential)

主要な概念

構成設定

構成設定は、構成ストア内の基本的なリソースです。 最も単純な形式では、キーと値です。 ただし、変更可能なコンテンツ タイプやタグ フィールドなどの追加のプロパティがあり、値をさまざまな方法で解釈または関連付けることができます。

構成設定の Label プロパティを使用すると、構成設定を異なるディメンションに分割できます。 これらのディメンションはユーザー定義であり、任意の形式を使用できます。 ラベルに使用するディメンションの一般的な例としては、リージョン、セマンティック バージョン、環境などがあります。 多くのアプリケーションには、異なるディメンション間でアプリケーションが存在する場合に、さまざまな値を持つ必要な構成キーのセットがあります。

たとえば、MaxRequests は "NorthAmerica" では 100、"WestEurope" では 200 にすることができます。 "NorthAmerica" というラベルを持つ MaxRequests という名前の構成設定を作成し、別の構成設定を "WestEurope" ラベルの別の値のみを使用して作成すると、アプリケーションはこれら 2 つのディメンションで実行される構成設定をシームレスに取得できます。

構成設定のプロパティ:

key : str
label : str
content_type : str
value : str
last_modified : str
read_only : bool
tags : dict
etag : str

スナップショット

Azure App Configurationを使用すると、ユーザーは構成ストアのポイントインタイム スナップショットを作成して、設定を 1 つの一貫性のあるバージョンとして扱うことができます。 この機能により、アプリケーションは構成の一貫性のあるビューを保持し、更新が行われた時点での読み取りによる個々の設定に対するバージョンの不一致がないことを確認できます。 スナップショットは不変であるため、問題が発生した場合に構成を最後に既知の良好な構成に確実にロールバックできます。

例

次のセクションでは、次のような最も一般的な Configuration Service タスクをカバーするいくつかのコード スニペットを示します。

構成設定を作成する

構成ストアに格納する構成設定を作成します。 構成設定を格納するには、次の 2 つの方法があります。

  • add_configuration_setting設定がストアにまだ存在しない場合にのみ、設定を作成します。
config_setting = ConfigurationSetting(
    key="MyKey", label="MyLabel", value="my value", content_type="my content type", tags={"my tag": "my tag value"}
)
added_config_setting = client.add_configuration_setting(config_setting)
  • set_configuration_settingは、設定が存在しない場合、または既存の設定をオーバーライドする場合に作成します。
added_config_setting.value = "new value"
added_config_setting.content_type = "new content type"
updated_config_setting = client.set_configuration_setting(added_config_setting)

構成設定を取得する

以前に格納された構成設定を取得します。

fetched_config_setting = client.get_configuration_setting(key="MyKey", label="MyLabel")

構成設定を削除する

既存の構成設定を削除します。

client.delete_configuration_setting(
    key="MyKey",
    label="MyLabel",
)

リストの構成設定

label_filterやkey_filterでフィルター処理されたすべての構成設定を一覧表示します。

config_settings = client.list_configuration_settings(label_filter="MyLabel")
for item in config_settings:
    print_configuration_setting(item)

スナップショットを作成する

from azure.appconfiguration import ConfigurationSettingsFilter

filters = [ConfigurationSettingsFilter(key="my_key1", label="my_label1")]
response = client.begin_create_snapshot(name=snapshot_name, filters=filters)
created_snapshot = response.result()
print_snapshot(created_snapshot)

スナップショットを取得する

received_snapshot = client.get_snapshot(name=snapshot_name)

スナップショットをアーカイブする

archived_snapshot = client.archive_snapshot(name=snapshot_name)
print_snapshot(archived_snapshot)

スナップショットを回復する

recovered_snapshot = client.recover_snapshot(name=snapshot_name)
print_snapshot(recovered_snapshot)

スナップショットの一覧表示

for snapshot in client.list_snapshots():
    print_snapshot(snapshot)

スナップショットの構成設定を一覧表示する

for config_setting in client.list_configuration_settings(snapshot_name=snapshot_name):
    print_configuration_setting(config_setting)

非同期 API

非同期クライアントがサポートされています。 非同期クライアント ライブラリを使用するには、azure.appconfiguration ではなくパッケージ azure.appconfiguration.aio から AzureAppConfigurationClient をインポートします

import os
from azure.appconfiguration.aio import AzureAppConfigurationClient

CONNECTION_STRING = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

# Create app config client
client = AzureAppConfigurationClient.from_connection_string(CONNECTION_STRING)

この非同期 AzureAppConfigurationClient は、非同期である点を除き、同期シグネチャと同じメソッド シグネチャを持ちます。 たとえば、構成設定を非同期的に取得するには、async_clientを使用できます。

fetched_config_setting = await client.get_configuration_setting(key="MyKey", label="MyLabel")

list_configuration_settingsを使用するには、同期的に呼び出し、返された非同期反復子を非同期的に反復処理します

config_settings = client.list_configuration_settings(label_filter="MyLabel")
async for item in config_settings:
    print_configuration_setting(item)

from azure.appconfiguration import ConfigurationSettingsFilter

filters = [ConfigurationSettingsFilter(key="my_key1", label="my_label1")]
response = await client.begin_create_snapshot(name=snapshot_name, filters=filters)
created_snapshot = await response.result()
print_snapshot(created_snapshot)

received_snapshot = await client.get_snapshot(name=snapshot_name)

archived_snapshot = await client.archive_snapshot(name=snapshot_name)
print_snapshot(archived_snapshot)

recovered_snapshot = await client.recover_snapshot(name=snapshot_name)
print_snapshot(recovered_snapshot)

async for snapshot in client.list_snapshots():
    print_snapshot(snapshot)

async for config_setting in client.list_configuration_settings(snapshot_name=snapshot_name):
    print_configuration_setting(config_setting)

トラブルシューティング

さまざまな障害シナリオを診断する方法の詳細については、 トラブルシューティング ガイド を参照してください。

次のステップ

その他のサンプル コード

この GitHub リポジトリには、いくつかのApp Configurationクライアント ライブラリ サンプルが用意されています。 具体的な内容は次のとおりです。

詳細については、 README のサンプルを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳細については、倫理規定についてよくあるご質問を参照するか、opencode@microsoft.com 宛てにご質問またはコメントをお送りください。