Partilhar via

Gerenciar recursos do Azure com o Invoke-AzRestMethod

  • Artigo

Invoke-AzRestMethod é um cmdlet do Azure PowerShell que foi introduzido no módulo Az PowerShell versão 4.4.0. Permite que faça solicitações HTTP personalizadas para o endpoint do Azure Resource Manager (ARM) utilizando o contexto Az.

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

Como usar Invoke-AzRestMethod

Como 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 PowerShell. No entanto, pode ser gerido entretanto com Invoke-AzRestMethod.

Usando 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 máxima flexibilidade, a maioria dos parâmetros para Invoke-AzRestMethod são opcionais. No entanto, ao gerenciar recursos dentro de 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 espaço de trabalho do Log Analytics, os parâmetros se parecem com o exemplo a seguir: -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 específica da API, incluindo as de visualização. As versões de API suportadas para provedores de Recursos do Azure podem ser encontradas no repositório azure-rest-api-specs GitHub.

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

Usando Invoke-AzRestMethod com operações PATCH

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

Para desativar o acesso à rede pública, é necessário realizar 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 do arquivo JSON do registro de contêiner para a versão da API .

Para permitir o acesso ao registro somente a partir de um endereço IP específico, a carga precisa ser modificada, conforme mostrado no exemplo a seguir:

$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 da 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. Este processo acrescenta um nível adicional de complexidade e pode tornar-se complicado.

Invoke-AzRestMethod oferece uma maneira de gerenciar recursos do Azure. Como mostrado no exemplo anterior, você pode criar uma cadeia de caracteres JSON e usá-la para personalizar a chamada da API REST sem ter que pré-criar nenhum PSObjects.

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

Ver também