Gerir recursos do Azure com o Invoke-AzRestMethod

  • Artigo

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

Este cmdlet é útil quando quer gerir os serviços do Azure no que respeita funcionalidades que ainda não estão disponíveis no módulo Az do PowerShell.

Como utilizar o Invoke-AzRestMethod

A título de exemplo, pode permitir o acesso ao Azure Container Registry (ACR) apenas para redes específicas ou recusar o acesso público. Com o lançamento da versão 4.5.0 do módulo Az PowerShell, esta funcionalidade ainda não está disponível no módulo Az.ContainerRegistry do PowerShell. No entanto, pode geri-la provisoriamente com o Invoke-AzRestMethod.

Utilizar o Invoke-AzRestMethod com operações GET

O exemplo seguinte demonstra como utilizar 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').

Através de um mapeamento baseado 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 Fornecedores de recursos do Azure podem ser encontradas no repositório do GitHub azure-rest-api-specs.

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/.

Utilizar o Invoke-AzRestMethod com operações PATCH

Pode desativar o acesso público ao ACR existente com o nome myacr no grupo de recursos myresourcegroup com 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 carateres 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 arquivo JSON do registro de contêiner 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 o Get-AzResource, New-AzResource e Remove-AzResource

Os cmdlets *-AzResource permitem-lhe personalizar a chamada à API REST para o Azure ao especificar 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, você pode criar uma cadeia de caracteres JSON e usá-la para personalizar a chamada da API REST sem ter que pré-criar nenhum PSObjectsarquivo .

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

Consulte Também