Gerenciar recursos do Azure com Invoke-AzRestMethod

  • Artigo

Invoke-AzRestMethod é um cmdlet do Azure PowerShell que foi introduzido no módulo Az do PowerShell versão 4.4.0. Ele permite que você faça solicitações HTTP personalizadas para o ponto de extremidade do ARM (Azure Resource Manager) usando o contexto Az.

Esse cmdlet é útil quando você deseja gerenciar os serviços do Azure para recursos que ainda não estão disponíveis no módulo Az do PowerShell.

Como usar Invoke-AzRestMethod

Por exemplo, você pode permitir o acesso ao ACR (Registro de Contêiner do Azure) somente para redes específicas ou negar o acesso público. A partir da versão 4.5.0 do módulo Az PowerShell, esse recurso ainda não está disponível no módulo Az.ContainerRegistry do PowerShell. No entanto, ele pode ser gerenciado, enquanto isso, com Invoke-AzRestMethod.

Usar Invoke-AzRestMethod com operações GET

O seguinte exemplo demonstra como usar o cmdlet Invoke-AzRestMethod com uma operação GET:

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

Para permitir a máxima flexibilidade, a maioria dos parâmetros para Invoke-AzRestMethod é opcional. No entanto, quando você estiver gerenciando recursos em um grupo de recursos, você precisará fornecer a ID completa para o recurso ou parâmetros como o grupo de recursos, o provedor de recursos e o tipo de recurso.

Os parâmetros ResourceType e Name podem receber vários valores ao direcionar recursos que exigem mais de um nome. Por exemplo, para manipular uma pesquisa salva em um workspace do Log Analytics, os parâmetros são semelhantes ao seguinte exemplo: -ResourceType @('workspaces', 'savedsearches') -Name @('my-la', 'my-search').

Usando um mapeamento com base na posição na matriz, o cmdlet constrói o seguinte recurso: Id:'/workspaces/my-la/savedsearches/my-search'.

O parâmetro APIVersion permite que você use uma versão de API específica, incluindo versões prévias. As versões de API com suporte para provedores de recursos do Azure podem ser encontradas no repositório GitHub azure-rest-api-specs.

Você pode encontrar a definição para a versão API do ACR 2019-12-01-preview no seguinte local: azure-rest-api-specs/specification/containerregistry/resource-manager/Microsoft.ContainerRegistry/preview/.

Usar Invoke-AzRestMethod com operações PATCH

Desabilite o acesso público ao ACR existente chamado myacr no grupo de recursos myresourcegroup usando o cmdlet Invoke-AzRestMethod.

Para desabilitar o acesso à rede pública, você precisa fazer uma chamada PATCH à API que altera o valor do parâmetro publicNetwokAccess, conforme mostrado no seguinte exemplo:

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

A propriedade Payload é uma cadeia de caracteres JSON que mostra o caminho da propriedade a ser modificada.

Todos os parâmetros dessa API são descritos no arquivo rest-api-spec associado a essa API. A definição específica do parâmetro publicNetworkAccess pode ser encontrada no arquivo JSON de registro de contêiner para a versão API do 2019-12-01-preview.

Para permitir o acesso somente ao registro de um endereço IP específico, o conteúdo precisa ser modificado, conforme mostrado no seguinte exemplo:

$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

Comparação com Get-AzResource, New-AzResource e Remove-AzResource

Os cmdlets *-AzResource permitem que você personalize a chamada à API REST para o Azure especificando o tipo de recurso, a versão da API e as propriedades a serem atualizadas. No entanto, as propriedades precisam ser criadas primeiro como um PSObject. Esse processo adiciona um nível extra de complexidade e pode se tornar complicado.

Invoke-AzRestMethod oferece uma forma de gerenciar os recursos do Azure. Conforme mostrado no exemplo anterior, você pode criar uma cadeia de caracteres JSON e usá-la para personalizar a chamada à API REST sem precisar criar nenhum PSObjects.

Se você já conhece os cmdlets *-AzResource, pode continuar usando-os. Não temos planos para interromper o suporte a eles. Com Invoke-AzRestMethod, adicionamos um novo cmdlet ao kit de ferramentas.

Consulte Também