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

Azure CLI は、多くのシェル環境から Azure リソースを構成および管理できるコマンド ライン ツールです。 好みのシェル環境を選択して Azure CLI をインストールした後、この記事を使用して、一般的な落とし穴を回避し、Azure CLI を正常に使用する方法に関する有用なヒントを見つけ出します。

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

出力の形式

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

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

    • JSON を使用すると、最も包括的な情報が得られます。
    • この形式が既定ですが、--output パラメーターを使用して別のオプションを指定することもできます。
    • az config を使用して (例: az config set core.output=table)、グローバルな既定の形式を個人設定のいずれかに変更します。
    • 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 回しか使用されない場合は、パイプを検討してください。 (パイプ処理では、1 つのコマンドの出力が 2 番目のコマンドに入力として渡されます)。

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\"}" と同等です。

  • PowerShell で値が空の文字列の場合は、'""' を使用します。

  • Bash または PowerShell で値が空の引用符文字列 '' の場合は、"''" を使用します。

  • ファイルから読み込み、シェルの解釈メカニズムをバイパスするには、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 32 ビット C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem
Windows (64 ビット) C:\Program Files\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 コマンドを同時に実行した場合、複数の Azure CLI コマンドが同じ MSAL トークン キャッシュに書き込むと、書き込みの競合が発生する可能性があります。

潜在的な障害を回避するために、各スクリプトの環境変数 AZURE_CONFIG_DIR を個別のディレクトリに設定することで、各スクリプトの Azure CLI 構成フォルダーを分離できます。 そのスクリプトの Azure CLI コマンドは、既定の ~/.azure フォルダーではなく構成された場所に構成とトークン キャッシュを保存します。

export AZURE_CONFIG_DIR=/my/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
)

関連項目