この記事では、Azure Deployment Environment (ADE) 基本イメージを使用してカスタム イメージを構築するために使用できるコマンドについて説明します。
ADE CLI を使用すると、環境と指定された環境定義に関する情報を操作したり、環境に関連する以前にアップロードされたファイルをアップロードしてアクセスしたり、実行操作に関するログ記録を記録したり、環境デプロイの出力をアップロードおよびアクセスしたりできます。
どのようなコマンドを使用できますか?
ADE CLI は現在、次のコマンドをサポートしています。
ADE CLI コマンドを呼び出す方法の詳細については、リンクされたドキュメントを参照してください。
ade definitions コマンド セット
ade definitions コマンドを使用すると、ユーザーは、操作対象の環境に対して選択された定義に関連する情報を表示し、プライマリおよびリンクされた Infrastructure-as-Code (IaC) テンプレートなどの関連ファイルを指定されたファイルの場所にダウンロードできます。
次のコマンドは、このコマンド セット内にあります。
ade 定義の一覧
list コマンドは次のように呼び出されます。
definitionValue=$(ade definitions list)
このコマンドは、環境定義のさまざまなプロパティを記述するデータ オブジェクトを返します。
戻り値の型
このコマンドは、環境定義を記述する JSON オブジェクトを返します。 サンプル環境定義の 1 つに基づく戻りオブジェクトの例を次に示します。
{
"id": "/projects/PROJECT_NAME/catalogs/CATALOG_NAME/environmentDefinitions/appconfig",
"name": "AppConfig",
"catalogName": "CATALOG_NAME",
"description": "Deploys an App Config.",
"parameters": [
{
"id": "name",
"name": "name",
"description": "Name of the App Config",
"type": "string",
"readOnly": false,
"required": true,
"allowed": []
},
{
"id": "location",
"name": "location",
"description": "Location to deploy the environment resources",
"default": "westus3",
"type": "string",
"readOnly": false,
"required": false,
"allowed": []
}
],
"parametersSchema": "{\"type\":\"object\",\"properties\":{\"name\":{\"title\":\"name\",\"description\":\"Name of the App Config\"},\"location\":{\"title\":\"location\",\"description\":\"Location to deploy the environment resources\",\"default\":\"westus3\"}},\"required\":[\"name\"]}",
"templatePath": "CATALOG_NAME/AppConfig/appconfig.bicep",
"contentSourcePath": "CATALOG_NAME/AppConfig"
}
返されるプロパティ値の使用
次の形式を使用して、(ADE で作成されたイメージにプレインストールされている) JQ ライブラリを使用して、返される定義 JSON オブジェクトの特定のプロパティに環境変数を割り当てることができます。
environment_name=$(echo $definitionValue | jq -r ".Name")
高度なフィルター処理とその他の JQ ライブラリの使用方法の詳細については 、こちらをご覧ください。
ade 定義のダウンロード
このコマンドは、次のように呼び出されます。
ade definitions download --folder-path EnvironmentDefinition
このコマンドは、メインおよびリンクされたコードとしてのインフラストラクチャ (IaC) テンプレートと、指定されたテンプレートに関連付けられているその他のファイルをダウンロードします。
オプション
--folder-path: 環境定義ファイルをダウンロードするフォルダー パス。 指定しない場合、コマンドは、実行時に現在のディレクトリ レベルで EnvironmentDefinition という名前のフォルダーにファイルを格納します。
どのファイルにアクセスできますか?
このコマンドを呼び出すと、カタログ リポジトリ内の環境定義マニフェスト ファイル (environment.yaml または manifest.yaml) のレベル以下に格納されているすべてのファイルにアクセスできます。
環境定義とカタログ リポジトリ構造のキュレーションの詳細については、次のリンクを参照してください。
さらに、 /ade/repository/{YOUR_CATALOG_NAME}/{RELATIVE_DIRECTORY_TO_MANIFEST}のコンテナー内でファイルを使用することもできます。 たとえば、Catalog1 という名前のカタログとして接続したリポジトリ内にマニフェスト ファイルが Folder1/Folder2/environment.yaml に格納されている場合、ファイルは /ade/repository/Catalog1/Folder1/Folder2コンテナー内に存在します。 デプロイまたは削除を正常に実行する必要があるため、ADE はこれらのファイルをこのファイルの場所に自動的に追加します。
ade environment コマンド
ade environment コマンドを使用すると、操作が実行されている環境に関連する情報をユーザーに表示できます。
コマンドは次のように呼び出されます。
environmentValue=$(ade environment)
このコマンドは、環境のさまざまなプロパティを記述するデータ オブジェクトを返します。
戻り値の型
このコマンドは、環境を記述する JSON オブジェクトを返します。 戻りオブジェクトの例を次に示します。
{
"uri": "https://TENANT_ID-DEVCENTER_NAME.DEVCENTER_REGION.devcenter.azure.com/projects/PROJECT_NAME/users/USER_ID/environments/ENVIRONMENT_NAME",
"name": "ENVIRONMENT_NAME",
"environmentType": "ENVIRONMENT_TYPE",
"user": "USER_ID",
"provisioningState": "PROVISIONING_STATE",
"resourceGroupId": "/subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP_NAME",
"catalogName": "CATALOG_NAME",
"environmentDefinitionName": "ENVIRONMENT_DEFINITION_NAME",
"parameters": {
"location": "locationInput",
"name": "nameInput"
},
"location": "regionForDeployment"
}
返されるプロパティ値の使用
次の形式を使用して、(ADE で作成されたイメージにプレインストールされている) JQ ライブラリを使用して、返される定義 JSON オブジェクトの特定のプロパティに環境変数を割り当てることができます。
environment_name=$(echo $environment | jq -r ".Name")
高度なフィルター処理とその他の JQ ライブラリの使用方法の詳細については 、こちらをご覧ください。
ade execute コマンド
ade execute コマンドは、コンテナー内で実行されるスクリプトの暗黙的なログ記録を提供するために使用されます。 これにより、コマンド中に生成された標準出力または標準エラー コンテンツは、環境の操作のログ ファイルに記録され、Azure CLI を使用してアクセスできます。
環境エラーの詳細を開発者ポータルで簡単に設定して表示できるように、このコマンドから環境変数 $ADE_ERROR_LOG で指定されたエラー ログ ファイルにパイプする必要があります。
オプション
--operation: コマンドで実行される操作を指定する文字列入力。 通常、この情報は、$ADE_OPERATION_NAME 環境変数を使用して提供されます。
--command: ログ記録を実行して記録するコマンド。
例示
このコマンドは 、deploy.sh を実行します。
ade execute --operation $ADE_OPERATION_NAME --command "./deploy.sh" 2> >(tee -a $ADE_ERROR_LOG)
ade files コマンド セット
ade files コマンド セットを使用すると、お客様は、実行中の操作コンテナー内のファイルをアップロードおよびダウンロードして、コンテナー内の後または後の操作の実行で使用する特定の環境に対して行うことができます。 このコマンド セットは、特定のコードとしてのインフラストラクチャ (IaC) プロバイダー用に生成された状態ファイルをアップロードするためにも使用されます。
次のコマンドは、このコマンド セット内にあります。
ade ファイルの一覧
このコマンドは、環境コンテナー内でダウンロードできるファイルを一覧表示します。
戻り値の型
このコマンドは、ダウンロードできるファイルを文字列の配列として返します。 次に例を示します。
[
"file1.txt",
"file2.sh",
"file3.zip"
]
ade ファイルのダウンロード
このコマンドは、選択したファイルを実行中のコンテナー内の指定されたファイルの場所にダウンロードします。
オプション
--file-name: ダウンロードするファイルの名前。 このファイル名は、 ade files list コマンドから返される使用可能なファイルの一覧内に存在する必要があります。 このオプションは必須です。
--folder-path: コンテナー内にファイルをダウンロードするフォルダー パス。 このパスは必要ありません。CLI は、コマンドの実行時に既定でファイルを現在のディレクトリにダウンロードします。
--unzip: 使用可能なファイルの一覧から zip ファイルをダウンロードし、指定したフォルダーの場所にコンテンツを解凍する場合は、このフラグを設定します。
例示
次のコマンドは、ファイルを現在のディレクトリにダウンロードします。
ade files download --file-name file1.txt
次のコマンドは、 folder1 という名前の下位レベルのフォルダーにファイルをダウンロードします。
ade files download --file-name file1.txt --folder-path folder1
最後のコマンドは zip ファイルをダウンロードし、ファイルの内容を現在のディレクトリに解凍します。
ade files download --file-name file3.zip --unzip
ade ファイルのアップロード
このコマンドは、指定された単一のファイル、または環境がアクセスできるファイルの一覧へのフォルダー パスとして指定された zip フォルダーをアップロードします。
オプション
--file-path: アップロードする現在のディレクトリからファイルが存在する場所のパス。 このコマンドを実行するには、このオプションまたは --folder-path オプションが必要です。
--folder-path: zip ファイルとしてアップロードする現在のディレクトリからフォルダーが存在する場所のパス。 結果として得られるアクセス可能なファイルには、最も低いフォルダーの名前でアクセスできます。 このコマンドを実行するには、このオプションまたは --file-path オプションが必要です。
ヒント
このコマンドの環境に対して、既存のアクセス可能なファイルと同じ名前のファイルまたはフォルダーを指定すると、以前に保存したファイルが上書きされます (つまり、file1.txt が既存のアクセス可能なファイルである場合、 ade files --file-path file1.txt 実行すると、以前に保存したファイルが上書きされます)。
例示
次のコマンドは、file1.txtという名前の現在のディレクトリからファイル を アップロードします。
ade files upload --file-path "file1.txt"
このファイルは、後で次を実行してアクセスできます。
ade files download --file-name "file1.txt"
次のコマンドは、 folder1 という名前の現在のディレクトリより 1 レベル低いフォルダーを 、folder1.zipという名前の zip ファイルとしてアップロードします。
ade files upload --folder-path "folder1"
最後に、次のコマンドは、フォルダー 1/folder2 の現在のディレクトリより 2 レベル低いフォルダーを 、folder2.zipという名前の zip ファイルとしてアップロードします。
ade files upload --folder-path "folder1/folder2"
ade init コマンド
ade init コマンドは、必要な環境変数を設定し、デプロイ用に指定された環境定義をダウンロードすることによって、ADE のコンテナーを初期化するために使用されます。 コマンド自体はシェル コマンドを出力し、次のコマンドを使用してコア エントリポイント内で評価されます。
eval $(ade init)
このコマンドは 1 回だけ実行する必要があります。 ADE で作成されたイメージのいずれかにカスタム イメージを基にしている場合は、このコマンドを再実行する必要はありません。
ade log コマンド セット
ade log コマンドは、コンテナー内での環境での操作の実行に関する詳細を記録するために使用されます。 このコマンドは、さまざまなログ記録レベルを提供します。このレベルは、操作の分析が完了した後にアクセスでき、お客様はログ記録のシナリオごとに異なるファイルを指定できます。
ADE は、コンテナー内の標準出力または標準エラー ストリームに出力されるすべてのステートメントをログに記録します。 この機能を使用すると、メイン操作ログとは別に表示できる、お客様が指定したファイルにログをアップロードできます。
オプション
--content: ログに記録する情報を含む文字列入力。 このオプションは、このコマンドに必要です。
--type: コンテンツをログに記録するログのレベル (詳細、ログ、またはエラー)。 指定しない場合、CLI はログ レベルでコンテンツをログに記録します。
--file: コンテンツをログに記録するファイル。 指定しない場合、CLI は、実行中の操作の一意の操作 ID で指定された.log ファイルにログを記録します。
例示
このコマンドは、文字列を既定のログ ファイルに記録します。
ade log --content "This is a log"
このコマンドは、既定のログ ファイルにエラーを記録します。
ade log --type error --content "This is an error."
このコマンドは、specialLogFile.txtという名前の指定されたファイルに文字列 を 記録します。
ade log --content "This is a special log." --file "specialLogFile.txt"
ade operation-result コマンド
ade operation-result コマンドを使用すると、操作が失敗した場合に、操作対象の環境にエラーの詳細を追加し、実行中の操作を更新できます。
コマンドは次のように呼び出されます。
ade operation-result --code "ExitCode" --message "The operation failed!"
オプション
--code: 操作の失敗の原因となった終了コードの詳細を示す文字列
--message: 操作エラーのエラー メッセージを詳細に示す文字列。
Von Bedeutung
この操作は、操作を失敗状態に設定しても他の CLI コマンドが正常に完了することはできないため、コンテナーを終了する直前にのみ使用する必要があります。
ade outputs コマンド セット
ade outputs コマンドを使用すると、ADE の Outputs API からアクセスするコードとしてのインフラストラクチャ (IaC) テンプレートのデプロイから出力をアップロードできます。
ade outputs upload
このコマンドは、ADE EnvironmentOutput 形式で指定された JSON ファイルの内容を環境にアップロードし、後で ADE 用 Outputs API を使用してアクセスします。
オプション
--file: アップロードする JSON オブジェクトを含むファイルの場所。
例示
このコマンドは、outputs.jsonという名前 の .json ファイルを環境にアップロードし、正常なデプロイの出力として機能します。
ade outputs upload --file outputs.json
EnvironmentOutputs 形式
受信 JSON ファイルを適切にシリアル化し、環境のデプロイ出力として受け入れるためには、送信されるオブジェクトは次の構造に従う必要があります。
{
"outputs": {
"output1": {
"type": "string",
"value": "This is output 1!",
"sensitive": false
},
"output2": {
"type": "int",
"value": 22,
"sensitive": false
},
"output3": {
"type": "string",
"value": "This is a sensitive output",
"sensitive" true
}
}
}
この形式は、ARM テンプレートのデプロイで展開の出力を報告する方法と、 機密性の高いプロパティに合わせて調整されます。 機密性の高いプロパティは省略可能ですが、環境の作成者など、特権アクセス権を持つユーザーへの出力の表示を制限します。
出力に使用できる型は、"string"、"int"、"boolean"、"array"、および "object" です。
出力にアクセスする方法
コンテナー内または実行後に出力にアクセスするには、API エンドポイントを呼び出すか AZ CLI を使用してアクセスできる ADE 用 Outputs API を使用できます。
コンテナー内の出力にアクセスするには、(ADE で作成されたイメージにプレインストールされている) イメージに Azure CLI をインストールし、次のコマンドを実行する必要があります。
az login
az devcenter dev environment show-outputs --dev-center-name DEV_CENTER_NAME --project-name PROJECT_NAME --environment-name ENVIRONMENT_NAME