Verwalten von Azure-Ressourcen mit Invoke-AzRestMethod

Invoke-AzRestMethod ist ein Azure PowerShell-Cmdlet, das in Version 4.4.0 des Az PowerShell-Moduls eingeführt wurde. Mit diesem Cmdlet können Sie benutzerdefinierte HTTP-Anforderungen unter Verwendung des Az-Kontexts an den ARM-Endpunkt (Azure Resource Manager) senden.

Dieses Cmdlet ist nützlich, wenn Sie Azure-Dienste im Hinblick auf Features verwalten möchten, die im Az PowerShell-Modul noch nicht verfügbar sind.

Verwenden von „Invoke-AzRestMethod“

Sie können beispielsweise Zugriff auf Azure Container Registry (ACR) ausschließlich für bestimmte Netzwerke zulassen oder den öffentlichen Zugriff verweigern. Ab Version 4.5.0 des Az PowerShell-Moduls ist dieses Feature im PowerShell-Modul „Az.ContainerRegistry“ noch nicht verfügbar. Es kann in der Zwischenzeit jedoch mit Invoke-AzRestMethod verwaltet werden.

Verwenden von „Invoke-AzRestMethod“ mit GET-Vorgängen

Im folgenden Beispiel wird die Verwendung des Cmdlets Invoke-AzRestMethod in Verbindung mit einem GET-Vorgang veranschaulicht:

$getParams = @{
  ResourceGroupName = 'myresourcegroup'
  ResourceProviderName = 'Microsoft.ContainerRegistry'
  ResourceType = 'registries'
  Name = 'myacr'
  ApiVersion = '2019-12-01-preview'
  Method = 'GET'
}
Invoke-AzRestMethod @getParams

Um maximale Flexibilität zu ermöglichen, ist der Großteil der Parameter für Invoke-AzRestMethod optional. Wenn Sie jedoch Ressourcen innerhalb einer Ressourcengruppe verwalten, müssen Sie entweder die vollständige ID für die Ressource oder Parameter wie Ressourcengruppe, Ressourcenanbieter und Ressourcentyp angeben.

Die Parameter ResourceType und Name können bei Ressourcen, die mehr als einen Namen erfordern, mehrere Werte annehmen. Zum Bearbeiten einer gespeicherten Suche in einem Log Analytics-Arbeitsbereich sehen die Parameter etwa wie im folgenden Beispiel aus: -ResourceType @('workspaces', 'savedsearches') -Name @('my-la', 'my-search').

Das Cmdlet erstellt mithilfe einer Zuordnung, die auf der Position im Array basiert, die folgende Ressource: Id:'/workspaces/my-la/savedsearches/my-search'.

Mit dem Parameter APIVersion können Sie eine bestimmte API-Version (einschließlich Vorschauversionen) verwenden. Die unterstützten API-Versionen für Azure-Ressourcenanbieter finden Sie im GitHub-Repository azure-rest-api-specs.

Die Definition für die ACR-API-Version 2019-12-01-preview befindet sich an folgendem Speicherort: azure-rest-api-specs/specification/containerregistry/resource-manager/Microsoft.ContainerRegistry/preview/.

Verwenden von „Invoke-AzRestMethod“ mit PATCH-Vorgängen

Sie können den öffentlichen Zugriff auf die vorhandene ACR-Instanz myacr in der Ressourcengruppe myresourcegroup mithilfe des Cmdlets Invoke-AzRestMethod deaktivieren.

Wenn Sie den Zugriff auf das öffentliche Netzwerk deaktivieren möchten, senden Sie einen PATCH-Aufruf an die API, der den Wert des Parameters publicNetwokAccess wie im folgenden Beispiel gezeigt ändert:

$patchParams = @{
  ResourceGroupName = 'myresourcegroup'
  Name = 'myacr'
  ResourceProviderName = 'Microsoft.ContainerRegistry'
  ResourceType = 'registries'
  ApiVersion = '2019-12-01-preview'
  Payload = '{ "properties": {
     "publicNetworkAccess": "Disabled"
     } }'
  Method = 'PATCH'
}
Invoke-AzRestMethod @patchParams

Bei der Eigenschaft Payload handelt es sich um eine JSON-Zeichenfolge, die den Pfad der zu ändernden Eigenschaft zeigt.

Alle Parameter für diese API sind in der Datei rest-api-spec für diese API beschrieben. Die spezifische Definition für den publicNetworkAccess-Parameter finden Sie in der JSON-Datei der Containerregistrierung für die API-Version 2019-12-01-preview.

Wenn Sie den Zugriff auf die Registrierung nur von einer bestimmten IP-Adresse aus zulassen möchten, muss die Nutzlast wie im folgenden Beispiel gezeigt geändert werden:

$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

Vergleich mit „Get-AzResource“, „New-AzResource“ und „Remove-AzResource“

Mit den *-AzResource-Cmdlets können Sie den REST-API-Aufruf an Azure anpassen, indem Sie den Ressourcentyp, die API-Version und die zu aktualisierenden Eigenschaften angeben. Die Eigenschaften müssen jedoch zuerst als PSObject erstellt werden. Dieser Vorgang ist komplex und kann kompliziert werden.

Mit Invoke-AzRestMethod lassen sich Azure-Ressourcen verwalten. Wie im vorherigen Beispiel gezeigt, können Sie eine JSON-Zeichenfolge erstellen und diese zum Anpassen des REST-API-Aufrufs verwenden, ohne vorab PSObjects erstellen zu müssen.

Wenn Sie bereits mit den *-AzResource-Cmdlets vertraut sind, können Sie sie weiterhin verwenden. Es ist nicht geplant, ihre Unterstützung einzustellen. Mit Invoke-AzRestMethod wurde dem Toolkit ein neues Cmdlet hinzugefügt.

Weitere Informationen