Compartilhar via

Gerenciar recursos do Azure com Invoke-AzRestMethod

  • Artigo

Invoke-AzRestMethod é um cmdlet do Azure PowerShell que foi introduzido no módulo 4.4.0 do Az PowerShell. 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 do Az PowerShell.

Como usar Invoke-AzRestMethod

Por exemplo, você pode permitir o acesso ao Registro de Contêiner do Azure (ACR) somente para redes específicas ou negar 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 exemplo a seguir 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 flexibilidade máxima, a maioria dos parâmetros para Invoke-AzRestMethod são opcionais. No entanto, ao gerenciar recursos em um grupo de recursos, você precisará fornecer a ID completa para o recurso ou parâmetros como grupo de recursos, provedor de recursos e tipo de recurso.

Os parâmetros ResourceType e Name podem ter 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 se parecem com o 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 a versão prévia. As versões de API com suporte para provedores de Recursos do Azure podem ser encontradas no azure-rest-api-specs repositório GitHub.

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

Você pode desabilitar o acesso público ao ACR existente denominado myacr no grupo de recursos myresourcegroup usando o cmdlet Invoke-AzRestMethod.

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

$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 para essa API são descritos no arquivo rest-api-spec associado a essa API. A definição específica para o parâmetro publicNetworkAccess pode ser encontrada no arquivo JSON do registro de contêiner para a versão da API 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 personalizar 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 adicional de complexidade e pode se tornar complicado.

Invoke-AzRestMethod oferece uma maneira de gerenciar 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 previamente qualquer PSObjects.

Se você já estiver familiarizado com os cmdlets *-AzResource, poderá continuar usando-os. Não temos planos de parar de apoiá-los. Com Invoke-AzRestMethod, adicionamos um novo cmdlet ao seu kit de ferramentas.

Consulte Também