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
前提条件
- このパッケージを使用するには、Python 3.7 以降が必要です。
- このパッケージを使用するには、 Azure サブスクリプションと 構成ストア が必要です。
構成ストアを作成するには、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 タスクをカバーするいくつかのコード スニペットを示します。
- 構成設定を作成する
- 構成設定を取得する
- 構成設定を削除する
- リストの構成設定
- スナップショットを作成する
- スナップショットを取得する
- スナップショットをアーカイブする
- スナップショットを回復する
- スナップショットの一覧表示
- スナップショットの構成設定を一覧表示する
- 非同期 API
構成設定を作成する
構成ストアに格納する構成設定を作成します。 構成設定を格納するには、次の 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クライアント ライブラリ サンプルが用意されています。 具体的な内容は次のとおりです。
- ハローワールド / 非同期バージョン
- ラベル / 付きの Hello world非同期バージョン
- 構成設定を読み取り専用にする / 非同期バージョン
- リビジョン履歴 / の読み取り非同期バージョン
- 変更 / された場合に設定を取得する非同期バージョン
- 構成設定の状態を作成、取得、更新スナップショット / Async バージョン
詳細については、 README のサンプルを参照してください。
共同作成
このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。
pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。
このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳細については、倫理規定についてよくあるご質問を参照するか、opencode@microsoft.com 宛てにご質問またはコメントをお送りください。
Azure SDK for Python