PowerShell スクリプト言語での Azure CLI の実行に関する考慮事項

  • [アーティクル]

Azure CLI は、Bash と PowerShell の両方のスクリプト言語で実行される Azure CLI リファレンス コマンドを使用して Azure リソースを管理するツールです。 ただし、スクリプト言語間でパラメーターの書式設定にわずかな構文の違いがあり、予期しない結果になる可能性があります。 この記事の目的は、PowerShell スクリプト言語で作業するときの Azure CLI 構文エラーの解決に役立ちます。

この記事では、次のスクリプト言語で実行される Azure CLI コマンドの構文の違いを比較します。

  • Azure Cloud Shell を使用して Linux オペレーティング システムで実行されている Bash。
  • PowerShell Azure Cloud Shell を使用して Linux オペレーティング システムで実行されます。
  • Windows PowerShell PowerShell 5 ターミナルを使用して Windows 11 で実行されます。
  • PowerShell 7 ターミナルを使用して Windows 11 で実行されている PowerShell。

CLI を初めて使用する場合は、 tool と スクリプト言語を区別すると 混乱が発生する可能性があります。 適切なコマンド ライン ツールを選択する方法 良い比較を提供します。

前提条件

この記事は、読んで学ぶことを目的としています。 ただし、例を実行する場合は、[ Prepare your environments ] タブを選択して、この記事で使用するスクリプト言語をインストールします。

重要

エラーが発生している Azure CLI スクリプトがある場合は、 作業しているスクリプト言語が Azure CLI コマンド構文を解析する方法を考えます。

Azure CLI パラメーターでスペースを渡す

Azure CLI では、スペースを含むパラメーター値を渡す必要がある場合、オペレーティング システムとスクリプト言語の間に違いがあります。 この例では、 az ストレージ アカウントリスト を使用し、出力列の名前をスペースを含む単語で名前を変更します。

この例では、二重引用符 ("...") が埋め込まれた単一引用符 ('...') ラッパーに注目してください。 この例は、Linux の PowerShell でも機能します。

az storage account list --query '[].{"SA Name":name, "Primary endpoint":primaryEndpoints.blob}' --output table

フィルターを追加する場合は、構文が変更されます。 この例では、 --query パラメーター値を二重引用符 ("...") でラップし、円記号 (\) エスケープ文字を使用する方法に注目してください。 このスクリプトは PowerShell では実行されません。

 az storage account list --query "[?creationTime >='2024-02-01'].{\"SA Name\":name,\"Primary endpoint\":primaryEndpoints.blob}" --output table

PowerShell スクリプト言語でフィルター構文を実行しようとすると、エラー メッセージ argument --query: invalid jmespath_type value: "[?creationTime >=..."が表示されます。 ただし、Linux 環境内の Bash では、出力は次のようになります。

SA Name           Primary Endpoint
-----------       -----------------
msdocssa00000000  https://msdocssa000000000.blob.core.windows.net/

クエリ文字列を含む URL にパラメーターを渡す

URL の疑問符は、URL の末尾とクエリ文字列の先頭を示します。 Azure CLI を使用するために Learn で手順 3 を開く例を次に示します。

https://video2.skills-academy.com/en-us/cli/azure/account?view=azure-cli-2020-09-01-hybrid.

?view=azure-cli-2020-09-01-hybridは、Azure CLI 参照コンテンツの目的のバージョンになります。

PowerShell スクリプト言語で Azure CLI コマンドを実行すると、PowerShell では疑問符を変数名の一部にすることができます。 これにより、Azure CLI のパラメーター値が混乱する可能性があります。

Azure REST API の使用記事の例を次に示します。

$containerRegistryName?api-versionが Bash でエラーなく連結される方法に注目してください。

# Script for a Bash scripting language

# Variable block
let "randomIdentifier=$RANDOM*$RANDOM"
subscriptionId="00000000-0000-0000-0000-000000000000"
resourceGroup="msdocs-app-rg$randomIdentifier"
containerRegistryName="msdocscr$randomIdentifier"

# prior to this GET example, the resource group and container registry were created in the article.

az rest --method get --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview

アンパサンド記号を含むパラメーターを渡す

パラメーター値にアンパサンドを渡す必要があるシナリオがある場合は、アンパサンド (&) 記号が PowerShell によって解釈されていることに注意してください。 これは、 --debug パラメーターを使用して発生することがわかります。

az "a&b" --debug

# output
'a' is misspelled or not recognized by the system.
'b' is not recognized as an internal or external command

ただし、この同じテストを使用してリソース グループにタグを追加した場合、タグ値のアンパサンドでエラーは発生しません。

az group create --location eastus2 --name "msdocs-rg-test"
az group update --name "msdocs-rg-test" --tags "company name=Contoso & Sons"

# output
{
  "id": "/subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourceGroups/msdocs-rg-test",
  "location": "eastus2",
  "managedBy": null,
  "name": "msdocs-rg-test",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": {
    "company name": "Contoso & Sons"
  },
  "type": "Microsoft.Resources/resourceGroups"
}

パラメーター値のアンパサンドがエラーを引き起こしているシナリオがある場合は、次のような解決策があります。

# When quoted by single quotes ('), double quotes (") are preserved by PowerShell and sent
# to Command Prompt, so that ampersand (&) is treated as a literal character
> az '"a&b"' --debug
Command arguments: ['a&b', '--debug']

# Escape double quotes (") with backticks (`) as required by PowerShell
> az "`"a&b`"" --debug
Command arguments: ['a&b', '--debug']

# Escape double quotes (") by repeating them
> az """a&b""" --debug
Command arguments: ['a&b', '--debug']

# With a whitespace in the argument, double quotes (") are preserved by PowerShell and
# sent to Command Prompt
> az "a&b " --debug
Command arguments: ['a&b ', '--debug']

# Use --% to stop PowerShell from parsing the argument
> az --% "a&b" --debug
Command arguments: ['a&b', '--debug']

at (@) 記号を含むパラメーターを渡す

PowerShell には、スプラッティング演算子である at (@) 記号などの特殊文字があります。 特殊文字の前にバックティック ` を追加してエスケープします。 値は、単一引用符 (') または二重引用符 (") で囲むこともできます。

PowerShell では、次の 3 つの例が機能します。

  • parameterName '@parameters.json
  • parameterName '@parameters.json'
  • parameterName "@parameters.json"

この例は PowerShell では機能しません。

  • parameterName @parameters.json

az ad app create コマンドのもう 1 つの例を次に示します。PowerShell スクリプト言語で必要な JSON ファイル名の二重引用符 ("...") に注目してください。

# Script for a PowerShell scripting language

az ad app create --display-name myTestAppName `
    --is-fallback-public-client `
    --required-resource-accesses "@manifest.json"

JSON を含むパラメーターを渡す

JSON 文字列のような複雑な引数の場合、ベスト プラクティスは、Azure CLI の @<file> 規則を使用してファイルから読み込み、シェルの解釈をバイパスすることです。 Bash、PowerShell、Cmd.exeの JSON 構文の例については、「スクリプト言語の違いを引用符 で囲む - JSON 文字列」を参照してください。

キーと値のペアを含むパラメーターを渡す

Azure リソース タグなどの一部の Azure CLI パラメーター値には、キーと値のペアが必要です。 keyまたはvalueにスペースまたは特殊文字が含まれている場合、Bash と PowerShell の構文は常に同じとは限りません。

Bash、PowerShell、Cmd の構文例については、azure CLI を使用するための Learn の違いを引用符で囲む方法をタグを作成するを参照してください。 このチュートリアルの手順では、次のキーと値のペアのシナリオの例を示します。

  • スペース
  • 空の値
  • 特殊文字
  • variables

停止解析シンボル

PowerShell 3.0 で導入された停止解析シンボル (--%) は、PowerShell で入力を PowerShell コマンドまたは式として解釈しないように指示します。 停止解析シンボルが検出されると、PowerShell は行の残りの文字をリテラルとして扱います。

az --% vm create --name xxx

PowerShell でのAzure CLI のエラー処理

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

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

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

# Script for a PowerShell scripting language

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

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

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

# Script for a PowerShell scripting language

$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 のエラー処理については、「例外について知りたかったことのすべて」を参照してください。

PowerShell でタブ補完を有効にする

タブ補完 ("Azure CLI の補完機能" とも呼ばれます) は、ヒントを示したり、検出を有効にしたり、入力エントリを高速化したりするための入力の補完機能を提供します。 Tab キーを押すことによって、コマンド名、コマンド グループ名、パラメーターや特定のパラメーター値をコマンド ラインに自動的に挿入できます。

タブ補完は、Azure Cloud Shell や、ほとんどの Linux ディストリビューションで既定で有効になります。 Azure CLI バージョン 2.49 以降では、PowerShell で Azure CLI のタブ補完を有効にできます。 次の手順のようにします。

  1. 変数 $PROFILE に格納されているプロファイルを作成または編集します。 最も簡単な方法は、PowerShell で notepad $PROFILE を実行することです。 詳細については、プロファイルの作成方法とプロファイルと実行ポリシーのトピックを参照してください。

  2. PowerShell プロファイルに次のコードを追加します。

    Register-ArgumentCompleter -Native -CommandName az -ScriptBlock {
    param($commandName, $wordToComplete, $cursorPosition)
    $completion_file = New-TemporaryFile
    $env:ARGCOMPLETE_USE_TEMPFILES = 1
    $env:_ARGCOMPLETE_STDOUT_FILENAME = $completion_file
    $env:COMP_LINE = $wordToComplete
    $env:COMP_POINT = $cursorPosition
    $env:_ARGCOMPLETE = 1
    $env:_ARGCOMPLETE_SUPPRESS_SPACE = 0
    $env:_ARGCOMPLETE_IFS = "`n"
    $env:_ARGCOMPLETE_SHELL = 'powershell'
    az 2>&1 | Out-Null
    Get-Content $completion_file | Sort-Object | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)
    }
    Remove-Item $completion_file, Env:\_ARGCOMPLETE_STDOUT_FILENAME, Env:\ARGCOMPLETE_USE_TEMPFILES, Env:\COMP_LINE, Env:\COMP_POINT, Env:\_ARGCOMPLETE, Env:\_ARGCOMPLETE_SUPPRESS_SPACE, Env:\_ARGCOMPLETE_IFS, Env:\_ARGCOMPLETE_SHELL
}

  3. メニューで使用可能なすべてのオプションを表示するには、PowerShell プロファイルに Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete を追加します。

関連項目