Invoke-AzRestMethod を使用して Azure リソースを管理する
Invoke-AzRestMethod は Az PowerShell モジュール バージョン 4.4.0 で導入された Azure PowerShell コマンドレットです。 これにより、Az コンテキストを使用して、Azure Resource Manager (ARM) エンドポイントに対してカスタム HTTP 要求を行うことができます。
このコマンドレットは、Azure サービスを管理する際に、Az PowerShell モジュールでまだ利用できない機能が必要な場合に便利です。
Invoke-AzRestMethod の使用方法
たとえば、特定のネットワークに対してのみ Azure Container Registry (ACR) へのアクセスを許可したり、パブリック アクセスを拒否したりすることができます。 PowerShell モジュール バージョン 4.5.0 の時点では、この機能は、Az.ContainerRegistry PowerShell モジュールではまだ利用できません。 ただし、それまでは Invoke-AzRestMethod を使用して管理できます。
Invoke-AzRestMethod と GET 操作の使用
次の例では、Invoke-AzRestMethod コマンドレットと GET 操作を使用する方法を示しています。
$getParams = @{
ResourceGroupName = 'myresourcegroup'
ResourceProviderName = 'Microsoft.ContainerRegistry'
ResourceType = 'registries'
Name = 'myacr'
ApiVersion = '2019-12-01-preview'
Method = 'GET'
}
Invoke-AzRestMethod @getParams
柔軟性を最大限に高めるために、Invoke-AzRestMethod のパラメーターの大部分は省略可能です。
ただし、リソース グループ内のリソースを管理する場合は、リソースに対する完全な ID、またはリソース グループ、リソースプロバイダー、リソースの種類などのパラメーターを指定する必要があります。
複数の名前を必要とするリソースを対象とする場合は、ResourceType パラメーターと Name パラメーターに複数の値を指定できます。 たとえば、Log Analytics ワークスペース内で保存された検索条件を操作する場合、パラメーターは次の例のようになります: -ResourceType @('workspaces', 'savedsearches') -Name @('my-la', 'my-search')。
このコマンドレットは、配列内の位置に基づいたマッピングを使用して、次のリソースを構築します: Id:'/workspaces/my-la/savedsearches/my-search'。
APIVersion パラメーターを使用すると、プレビューのものを含め、特定の API バージョンを使用できます。 Azure リソースプロバイダーによってサポートされている API バージョンについては、azure-rest-api-specs GitHub リポジトリを参照してください。
2019-12-01-preview ACR API バージョンの定義は次の場所にあります: azure-rest-api-specs/specification/containerregistry/resource-manager/Microsoft.ContainerRegistry/preview/。
Invoke-AzRestMethod と PATCH 操作の使用
Invoke-AzRestMethod コマンドレットを使用して、myresourcegroup リソース グループ内の myacr という名前の既存の ACR へのパブリック アクセスを無効にできます。
パブリック ネットワーク アクセスを無効にするには、次の例に示すように、API に対して、publicNetwokAccess パラメーターの値を変更する PATCH 呼び出しを行う必要があります。
$patchParams = @{
ResourceGroupName = 'myresourcegroup'
Name = 'myacr'
ResourceProviderName = 'Microsoft.ContainerRegistry'
ResourceType = 'registries'
ApiVersion = '2019-12-01-preview'
Payload = '{ "properties": {
"publicNetworkAccess": "Disabled"
} }'
Method = 'PATCH'
}
Invoke-AzRestMethod @patchParams
Payload プロパティは、変更するプロパティのパスを示す JSON 文字列です。
この API のすべてのパラメーターについては、この API に関連する rest-api-spec ファイル内で説明されています。
publicNetworkAccess パラメーターの具体的な定義は、2019-12-01-preview API バージョンのコンテナー レジストリ JSON ファイル内で確認できます。
特定の IP アドレスからのレジストリへのアクセスのみを許可するには、次の例に示すようにペイロードを変更する必要があります。
$specificIpParams = @{
ResourceGroupName = 'myresourcegroup'
Name = 'myacr'
ResourceProviderName = 'Microsoft.ContainerRegistry'
ResourceType = 'registries'
ApiVersion = '2019-12-01-preview'
Payload = '{ "properties": {
"networkRuleSet": {
"defaultAction": "Deny",
"ipRules": [ {
"action": "Allow",
"value": "24.22.123.123"
} ]
}
} }'
Method = 'PATCH'
}
Invoke-AzRestMethod @specificIpParams
Get-AzResource、New-AzResource、および Remove-AzResource との比較
*-AzResource コマンドレットを使用し、リソースの種類、API バージョン、および更新するプロパティを指定することで、Azure に対する REST API 呼び出しをカスタマイズできます。 ただし、最初にプロパティを PSObject として作成する必要があります。 この処理により、複雑度が上がり、複雑になってしまう場合があります。
Invoke-AzRestMethod は Azure リソースを管理するための手段を提供します。 前の例で示したとおり、JSON 文字列を作成し、それを使用して、PSObjects を一切事前に作成することなく REST API 呼び出しをカスタマイズすることができます。
*-AzResource コマンドレットを既に使い慣れている場合は、それらを引き続き使用できます。 それらのサポートを停止する予定はありません。 Invoke-AzRestMethod により、新しいコマンドレットがツールキットに追加されました。