Gestire le risorse di Azure con Invoke-AzRestMethod

  • Articolo

Invoke-AzRestMethod è un cmdlet di Azure PowerShell introdotto nella versione 4.4.0 del modulo Az PowerShell. Consente di effettuare richieste HTTP personalizzate all'endpoint di Azure Resource Manager (ARM) usando il contesto Az.

Questo cmdlet è utile quando si vuole gestire i servizi di Azure per le funzionalità non ancora disponibili nel modulo Az PowerShell.

Come usare Invoke-AzRestMethod

Ad esempio, è possibile consentire l'accesso a Registro Azure Container (ACR) solo per reti specifiche o per negare l'accesso pubblico. A partire dalla versione 4.5.0 del modulo Az PowerShell, questa funzionalità non è ancora disponibile nel modulo PowerShell Az.ContainerRegistry. Tuttavia, può essere gestita provvisoriamente con Invoke-AzRestMethod.

Uso di Invoke-AzRestMethod con operazioni GET

L'esempio seguente illustra come usare il cmdlet Invoke-AzRestMethod con un'operazione GET:

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

Per garantire la massima flessibilità, quasi tutti i parametri di Invoke-AzRestMethod sono facoltativi. Tuttavia, quando si gestiscono le risorse all'interno di un gruppo di risorse, è necessario fornire l'ID completo alla risorsa o ai parametri, ad esempio gruppo di risorse, provider di risorse e tipo di risorsa.

I parametri ResourceType e Name possono assumere più valori se sono destinati a risorse per le quali è necessario specificare più nomi. Ad esempio, per modificare una ricerca salvata in un'area di lavoro Log Analytics, i parametri sono simili all'esempio seguente: -ResourceType @('workspaces', 'savedsearches') -Name @('my-la', 'my-search').

Usando un mapping basato sulla posizione nella matrice, il cmdlet crea la risorsa seguente: Id:'/workspaces/my-la/savedsearches/my-search'.

Il parametro APIVersion consente di usare una versione API specifica, incluse quelle di anteprima. Le versioni API supportate per i provider di risorse di Azure sono disponibili nel repository GitHub azure-rest-api-specs.

È possibile trovare la definizione per la versione dell'API 2019-12-01-preview ACR nel percorso seguente: azure-rest-api-specification/specification/containerregistry/resource-manager/Microsoft.ContainerRegistry/preview/.

Uso di Invoke-AzRestMethod con operazioni PATCH

Con il cmdlet Invoke-AzRestMethod è possibile disabilitare l'accesso pubblico all'istanza di Registro Azure Container esistente denominata myacr nel gruppo di risorse myresourcegroup.

Per disabilitare l'accesso alla rete pubblica, è necessario eseguire una chiamata PATCH all'API che modifichi il valore del parametro publicNetwokAccess come illustrato nell'esempio seguente:

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

La proprietà Payload è una stringa JSON che mostra il percorso della proprietà da modificare.

Tutti i parametri dell'API sono descritti nel file rest-api-spec associato a questa API. La definizione specifica per il parametro publicNetworkAccess è disponibile nel file JSON del registro contenitori per la versione dell'API2019-12-01-preview.

Per consentire l'accesso al Registro di sistema solo da uno specifico indirizzo IP, il payload deve essere modificato come illustrato nell'esempio seguente:

$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

Confronto con Get-AzResource, New-AzResource e Remove-AzResource

I cmdlet *-AzResource consentono di personalizzare la chiamata API REST ad Azure specificando il tipo di risorsa, la versione dell'API e le proprietà da aggiornare. È però prima necessario creare le proprietà come PSObject. Questo processo aggiunge un ulteriore livello di complessità e può diventare complicato.

Invoke-AzRestMethod offre un modo per gestire le risorse di Azure. Come illustrato nell'esempio precedente, è possibile compilare una stringa JSON e usarla per personalizzare la chiamata API REST senza dover creare in precedenza alcun oggetto PSObjects.

Se si ha già familiarità con i cmdlet *-AzResource, è possibile continuare a usarli. Non abbiamo intenzione di smettere di sostenerli. Con Invoke-AzRestMethodè stato aggiunto un nuovo cmdlet al toolkit.

Vedi anche