Partilhar via

Gerir recursos do Azure com o Invoke-AzRestMethod

O Invoke-AzRestMethod é um cmdlet do Azure PowerShell que foi introduzido na versão 4.4.0 do módulo Az do PowerShell. 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 o comando 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.

Utilizar o 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 de 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 receber vários valores ao visar recursos que precisem de mais do que um nome. Por exemplo, para manipular uma pesquisa guardada numa área de trabalho do Log Analytics, os parâmetros serão semelhantes ao exemplo seguinte: -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-lhe utilizar uma versão de API específica, incluindo as versões de pré-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.

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

Utilização do 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 de rede pública, tem de fazer uma chamada PATCH à API que altera o valor do parâmetro publicNetwokAccess, conforme demonstrado no exemplo seguinte:

$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 desta API estão descritos no ficheiro rest-api-spec associado a esta API. A definição específica para o parâmetro publicNetworkAccess pode ser encontrada no ficheiro JSON do registo de contentores para a versão da 2019-12-01-preview API.

Para permitir o acesso apenas ao registo a partir de um endereço IP específico, o payload tem de ser modificado, conforme demonstrado no exemplo seguinte:

$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, em primeiro lugar, as propriedades têm de ser criadas como 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, podes criar uma string JSON e usá-la para personalizar a chamada da API REST sem teres de pré-criar qualquer ficheiro 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, adicionámos um novo cmdlet ao seu kit de ferramentas.

Ver também