Azure CLI を正しく使用するためのヒント

Azure CLI は、多くのシェル環境から Azure リソースを構成および管理できるコマンド ライン ツールです。 まず、適切なコマンド ライン ツールを選択し、Azure CLI をインストールします。 次に、この記事を参照して、一般的な問題を回避し、Azure CLI を正しく使用するための方法に関する有用なヒントを見つけます。

特定の Azure CLI コマンドの詳細については、Azure CLI リファレンスの一覧を参照してください。

出力の形式

Azure CLI コマンドでは、次の 3 つの一般的な出力形式が使用されます。

  1. json 形式では、情報が JSON 文字列として表示されます。

    • JSON を使用すると、最も包括的な情報が得られます。
    • この形式が既定ですが、--output パラメーターを使用して別のオプションを指定することもできます。
    • az config set core.output=table のように az config を使用して、グローバルな既定の形式を個人設定のいずれかに変更します。
    • JSON 形式では二重引用符が保持されるため、通常はスクリプトの目的には適さないことに注意してください。
  2. table 形式では、出力は判読できるテーブルとして表示されます。 テーブルに表示される値を指定し、クエリを使用して出力をカスタマイズできます。次に例を示します。

    # command
    az vm show --resource-group myResourceGroup --name myVMname --query "{name: name, os:storageProfile.imageReference.offer}" --output table
    
    # output
    Name    Os
    ------  ------------
    myVMname   UbuntuServer
    
  3. tsv 形式では、追加の形式設定、キー、その他の記号なしで、タブと改行で区切られた値が返されます。

    • TSV 形式は、簡潔な出力とスクリプトの目的に役立ちます。
    • TSV を使用すると、JSON 形式で保持される二重引用符が除去されます。
    • TSV に使用する形式を指定するには、--query パラメーターを使用します。
    export vm_ids=$(az vm list --show-details --resource-group myResourceGroup --query "[?powerState=='VM running'].id" --output tsv)
    az vm stop --ids $vm_ids
    

これらおよびその他の形式の詳細については、「Azure CLI コマンドの出力形式」を参照してください。

別のコマンドへ値を渡す

値が複数回使用される場合は、それを変数に代入します。 変数を使用すると、値を複数回使用したり、より一般的なスクリプトを作成したりすることができます。 この例では、az vm list コマンドによって検出された ID を変数に割り当てています。

# assign the list of running VMs to a variable
running_vm_ids=$(az vm list --resource-group MyResourceGroup --show-details \
    --query "[?powerState=='VM running'].id" --output tsv)

# verify the value of the variable
echo $running_vm_ids

値が 1 回しか使用されない場合は、パイプを検討してください。

az vm list --query "[?powerState=='VM running'].name" --output tsv | grep my_vm

複数値の一覧の場合は、次のオプションを検討してください。

  1. 結果をさらに制御する必要がある場合は、"for" ループを使用します。

    #!/usr/bin/env bash
    for vmList in $(az vm list --resource-group MyResourceGroup --show-details --query "[?powerState=='VM running'].id"   --output tsv); do
        echo stopping $vmList
        az vm stop --ids $vmList
        if [ $? -ne 0 ]; then
            echo "Failed to stop $vmList"
            exit 1
        fi
        echo $vmList stopped
    done
    
  2. または、xargs を使用し、-P フラグを使用して、パフォーマンスを向上させるために操作を並列に実行することを検討してください。

    az vm list --resource-group MyResourceGroup --show-details \
      --query "[?powerState=='VM stopped'].id" \
      --output tsv | xargs -I {} -P 10 az vm start --ids "{}"
    
  3. 最後に、Azure CLI には、xargs と同じ効果を得るために、複数の --ids を使って並列にコマンドを処理するためのサポートが組み込まれています。 パイプから値を取得するために @- が使用されていることに注意してください。

    az vm list --resource-group MyResourceGroup --show-details \
      --query "[?powerState=='VM stopped'].id" \
      --output tsv | az vm start --ids @-
    

ループ、case ステートメント、if..then..else、エラー処理を含む Bash コンストラクトを Azure CLI で使用する方法の詳細については、Bash を Azure CLI で使用する方法に関するページを参照してください。

パラメーターでの引用符の使用

Azure CLI コマンドを操作するときは、シェルでの引用符とエスケープ文字の使用方法に注意してください。 別のシェルで使用されるスクリプトをサポートする場合は、それらの違いを理解しておく必要があります。

注意

PowerShell の既知の問題のため、いくつかの追加のエスケープ規則が適用されます。 詳細については、「PowerShell での引用符の問題」を参照してください。

予期しない結果を避けるために、いくつかの推奨事項を示します。

  • 空白を含むパラメーターを指定する場合は、引用符で囲みます。

  • Bash または PowerShell では、一重引用符と二重引用符の両方が正しく解釈されます。 Windows コマンド プロンプトでは、二重引用符のみが正しく解釈されます。一重引用符は値の一部として扱われます。

  • コマンドを Bash (または Zsh) でのみ実行する場合は、一重引用符を使用して JSON 文字列内の内容を保持します。 これは、インライン JSON 値を指定する場合に必要です。 たとえば、JSON '{"key": "value"}' は Bash では正しいです。

  • コマンドを Windows コマンド プロンプトで実行する場合は、二重引用符を使用する必要があります。 値に二重引用符が含まれている場合は、エスケープする必要があります。 上記の JSON 文字列は "{\"key\": \"value\"}" と同等です。

  • ファイルから読み込み、シェルの解釈メカニズムをバイパスするには、Azure CLI の @<file> 規約を使用します。

    az ad app create --display-name myName --native-app --required-resource-accesses @manifest.json
    
  • Bash では、エクスポートされた変数の二重引用符が評価されます。 この動作が必要ではない場合は、"\$variable" のように変数をエスケープします。

  • 一部の Azure CLI コマンドは、スペースで区切られた値の一覧を取ります。

    • キー名または値にスペースが含まれている場合は、ペア全体を "my key=my value" のように囲みます。 たとえば、次のように入力します。

      az web app config app settings set --resource-group myResourceGroup --name myWebAppName --settings "client id=id1" "my name=john"
      
    • CLI パラメーターがスペース区切りのリストを受け入れる場合は、次の 2 つの形式のいずれかが考えられます。

      1. 引用符で囲まれていないスペース区切りのリスト --parameterName firstValue secondValue
      2. 引用符で囲まれたスペース区切りのリスト --parameterName "firstValue" "secondValue"

      次の例は、スペースを含む文字列です。 これはスペース区切りのリストではありません。--parameterName "firstValue secondValue"

  • PowerShell には、@ などの特殊文字があります。 PowerShell で Azure CLI を実行するには、特殊文字の前に ` を追加してエスケープします。 値を一重引用符または二重引用符で囲むこともできます ("/")。

    # The following three examples will work in PowerShell
    --parameterName `@parameters.json
    --parameterName '@parameters.json'
    --parameterName "@parameters.json"
    
    # This example will not work in PowerShell
    --parameterName @parameters.json
    
  • コマンドで --query パラメーターを使用する場合、JMESPath の一部の文字をシェルでエスケープする必要があります。

    Bash では、次の 3 つのコマンドは正しく、同等です。

    az version --query '"azure-cli"'
    az version --query \"azure-cli\"
    az version --query "\"azure-cli\""
    

    Bash では、次の 2 つのコマンドの例は正しくありません。

    # Wrong, as the dash needs to be quoted in a JMESPath query
    az version --query azure-cli
    az version: error: argument --query: invalid jmespath_type value: 'azure-cli'
    
    # Wrong, as the dash needs to be quoted in a JMESPath query, but quotes are interpreted by Bash
    az version --query "azure-cli"
    az version: error: argument --query: invalid jmespath_type value: 'azure-cli'
    

    Bash、PowerShell、Cmd でのその他の例の比較については、「Azure CLI コマンドの出力のクエリ」を参照してください。


  • 引用符の問題のトラブルシューティングを行う最善の方法は、--debug フラグを指定してコマンドを実行することです。 このフラグにより、Python の構文で Azure CLI が受け取る実際の引数が明らかになります。

    # Correct
    $ az '{"key":"value"}' --debug
    Command arguments: ['{"key":"value"}', '--debug']
    
    # Correct
    $ az "{\"key\":\"value\"}" --debug
    Command arguments: ['{"key":"value"}', '--debug']
    
    # Wrong, as quotes and spaces are interpreted by Bash
    $ az {"key": "value"} --debug
    Command arguments: ['{key:', 'value}', '--debug']
    
    # Wrong, as quotes are interpreted by Bash
    $ az {"key":"value"} --debug
    Command arguments: ['{key:value}', '--debug']
    

パラメーターでのハイフン文字の使用

パラメーターの値がハイフンで始まる場合、Azure CLI はそれをパラメーター名として解析しようとします。 値として解析するには、--password="-VerySecret" のように、= を使用してパラメーター名と値を連結します。

非同期操作

Azure での操作には、かなりの時間がかかることがあります。 たとえば、データ センターで仮想マシンを構成することは瞬時にはできません。 Azure CLI は、コマンドが終了するまで待機してから、他のコマンドを受け入れます。 したがって、多くのコマンドは、次に示すように --no-wait パラメーターを提供します。

az group delete --name MyResourceGroup --no-wait

リソース グループを削除すると、リソース グループに属しているすべてのリソースも削除されます。 これらのリソースを削除するのには、長い時間がかかることがあります。 --no-wait パラメーターを指定してコマンドを実行すると、コンソールは削除を中断することなく新しいコマンドを受け入れることができます。

多くのコマンドは wait オプションを提供し、何らかの条件が満たされるまでコンソールを一時停止します。 次の例では、az vm wait コマンドを使用して、独立したリソースの並列作成をサポートしています。

az vm create --resource-group VMResources --name virtual-machine-01 --image centos --no-wait
az vm create --resource-group VMResources --name virtual-machine-02 --image centos --no-wait

subscription=$(az account show --query "id" -o tsv)
vm1_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-01"
vm2_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-02"
az vm wait --created --ids $vm1_id $vm2_id

両方の ID が作成されたら、コンソールを再度使用できます。

プロキシの背後での処理

自己署名証明書を使用するプロキシ サーバーで Azure CLI を使用している場合、Azure CLI で使用される Python 要求ライブラリが原因で、次のエラーが発生する可能性がありますSSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",)。 このエラーに対処するには、環境変数 REQUESTS_CA_BUNDLE を PEM 形式の CA バンドル証明書ファイルのパスに設定します。

OS 既定の証明機関バンドル
Windows C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem
Ubuntu/Debian Linux /opt/az/lib/python<version>/site-packages/certifi/cacert.pem
CentOS/RHEL/SUSE Linux /usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem
macOS /usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem

CA バンドル証明書ファイルにプロキシ サーバーの証明書を追加するか、内容を別の証明書ファイルにコピーします。 次に、REQUESTS_CA_BUNDLE を新しいファイルの場所に設定します。 たとえば次のようになります。

<Original cacert.pem>

-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----

一部のプロキシでは認証が必要です。 HTTP_PROXY または HTTPS_PROXY 環境変数の形式には、HTTPS_PROXY="https://username:password@proxy-server:port" のような認証を含める必要があります。 詳細については、「Azure ライブラリ用にプロキシを構成する方法」を参照してください。

同時ビルド

複数のジョブを並行して実行できるビルド コンピューターで Azure CLI を実行すると、同じ OS ユーザーとして実行される 2 つのビルド ジョブ間でアクセス トークンが共有される可能性があります。 混乱を避けるには、AZURE_CONFIG_DIR を、アクセス トークンが保管されるディレクトリに設定します。

汎用 update パラメーター

Azure CLI コマンド グループでは多くの場合、update コマンドが備わっています。 たとえば、Azure Virtual Machines には az vm update コマンドが含まれています。 ほとんどの update コマンドには、--add--set、および --remove の 3 つの汎用パラメーターが用意されています。

--set および --add パラメーターは、key1=value1 key2=value2 のようにスペースで区切られたキーと値のペアのリストを受け取ります。 更新できるプロパティを確認するには、az vm show などの show コマンドを使用します。

az vm show --resource-group VMResources --name virtual-machine-01

コマンドを簡略化するには、JSON 文字列の使用を検討してください。 たとえば、仮想マシンに新しいデータ ディスクを接続するには、次の値を使用します。

az vm update --resource-group VMResources --name virtual-machine-01 \
--add storageProfile.dataDisks "{\"createOption\": \"Attach\", \"managedDisk\":
   {\"id\":
   \"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/yg/providers/Microsoft.Compute/disks/yg-disk\"},
   \"lun\": 1}"

汎用 resource コマンド (az resource)

操作するサービスが Azure CLI をサポートしていない可能性があります。 az resource コマンドを使用して、これらのリソースを操作できます。

create または update コマンドのみが必要な場合は、az deployment group create を使用します。 実際の例については、「Azure のクイックスタート テンプレート」を参照してください。

REST API コマンド (az rest)

汎用 update パラメーターと az resource がニーズを満たさない場合は、az rest コマンドを使用して REST API を呼び出すことができます。 このコマンドより、ログインされた資格情報を使用して自動的に認証が行われ、ヘッダー Content-Type: application/json が設定されます。 詳細については、「Azure REST API リファレンス」を参照してください。

この例では、Microsoft Graph API を操作します。 アプリケーションのリダイレクト URI を更新するには、このコードのようにアプリケーションの更新 REST API を呼び出します。

# Get the application
az rest --method GET \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001'

# Update `redirectUris` for `web` property
az rest --method PATCH \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001' \
    --body '{"web":{"redirectUris":["https://myapp.com"]}}'

OData の形式の要求に対して --uri-parameters を使用する場合は、Bash では $\$ として、PowerShell では $ `$ として、異なる環境で $ を必ずエスケープしてください。

スクリプトの例

Azure Virtual Machines を操作するときに、変数を使用し、リストをループ処理する例を次に示します。 ループ、case ステートメント、if..then..else、エラー処理を含む Bash コンストラクトを Azure CLI で使用する方法の詳細な例については、Bash を Azure CLI で使用する方法に関するページを参照してください。

ID を変数に保存するには、次のスクリプトを使用します。

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
   `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    SET "vm_ids=%%F %vm_ids%"  :: construct the id list
)
az vm stop --ids %vm_ids% :: CLI stops all VMs in parallel

リストをループ処理するには、次のスクリプトを使用します。

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
    `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    ECHO Stopping %%F
    az vm stop --ids %%F
)

PowerShell でのAzure CLI のエラー処理

適切なコマンド ライン ツールの選択に関する記事の説明に従って、PowerShell で Azure CLI コマンドを実行できます。 その場合は、PowerShell での Azure CLI のエラー処理方法を理解しておいてください。 特に、Azure CLI では、PowerShell によってキャッチされる例外は作成されません。

代わりに、$? 自動変数を使用します。 この変数には、最新のコマンドの状態が含まれています。 前のコマンドが失敗した場合、$? の値は $False になります。 詳細については、「about_Automatic_Variables」を参照してください。

次の例では、この自動変数がエラー処理でどのように機能するかを示します。

az group create --name MyResourceGroup
if ($? -eq $false) {
    Write-Error "Error creating resource group."
}

az コマンドは、必要な --location パラメーターが指定されていないために失敗します。 条件ステートメントは、$? が false であることを検出して、エラーを書き込みます。

trycatch キーワードを使用する場合は、throw を使用して、try ブロックでキャッチされる例外を作成できます。

$ErrorActionPreference = "Stop"
try {
    az group create --name MyResourceGroup
    if ($? -eq $false) {
        throw 'Group create failed.'
    }
}
catch {
    Write-Error "Error creating the resource group."
}
$ErrorActionPreference = "Continue"

既定で、PowerShell では強制終了エラーのみがキャッチされます。 この例では、PowerShell でエラーを処理できるように、$ErrorActionPreference グローバル変数が Stop に設定されています。

条件ステートメントは、$? をテストして、前のコマンドが失敗したかどうかを確認します。 そうである場合は、throw キーワードによって、キャッチする例外が作成されます。 catch ブロックを使用して、エラー メッセージを書き込んだり、エラーを処理したりできます。

この例では、$ErrorActionPreference が既定値に復元されます。

PowerShell のエラー処理については、「例外について知りたかったことのすべて」を参照してください。

関連項目