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 により、新しいコマンドレットがツールキットに追加されました。

関連項目