Partager via

Gérer les ressources Azure avec Invoke-AzRestMethod

  • Article

Invoke-AzRestMethod est une applet de commande Azure PowerShell introduite dans le module Az PowerShell version 4.4.0. Il vous permet d’effectuer des requêtes HTTP personnalisées sur le point de terminaison Azure Resource Manager (ARM) à l’aide du contexte Az.

Cette applet de commande est utile lorsque vous souhaitez gérer les services Azure pour les fonctionnalités qui ne sont pas encore disponibles dans le module Az PowerShell.

Comment utiliser Invoke-AzRestMethod

Par exemple, vous pouvez autoriser l’accès à Azure Container Registry (ACR) uniquement pour des réseaux spécifiques ou refuser l’accès public. À partir du module Az PowerShell version 4.5.0, cette fonctionnalité n’est pas encore disponible dans le module Az.ContainerRegistry PowerShell. Toutefois, elle peut être gérée pour l’instant avec Invoke-AzRestMethod.

Utilisation de Invoke-AzRestMethod avec des opérations GET

L’exemple suivant montre comment utiliser l’applet de commande Invoke-AzRestMethod avec une opération GET :

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

Pour permettre une flexibilité maximale, la plupart des paramètres de Invoke-AzRestMethod sont facultatifs. Toutefois, lorsque vous gérez des ressources au sein d’un groupe de ressources, vous devez fournir l’ID complet à la ressource ou aux paramètres tels que le groupe de ressources, le fournisseur de ressources et le type de ressource.

Les paramètres ResourceType et Name peuvent prendre plusieurs valeurs lors du ciblage des ressources qui nécessitent plusieurs noms. Par exemple, pour manipuler une recherche enregistrée dans un espace de travail Log Analytics, les paramètres ressemblent à l’exemple suivant : -ResourceType @('workspaces', 'savedsearches') -Name @('my-la', 'my-search').

À l’aide d’un mappage basé sur la position du tableau, l’applet de commande construit la ressource suivante : Id:'/workspaces/my-la/savedsearches/my-search'.

Le paramètre APIVersion vous permet d’utiliser une version d’API spécifique, y compris les préversions. Les versions d’API prises en charge pour les fournisseurs de ressources Azure se trouvent dans le dépôt GitHub azure-rest-api-specs.

Vous trouverez la définition de la version de l’API ACR 2019-12-01-preview à l’emplacement suivant : azure-rest-api-specs/specification/containerregistry/resource-manager/Microsoft.ContainerRegistry/preview/.

Utilisation de l’applet de commande Invoke-AzRestMethod avec des opérations PATCH

Vous pouvez désactiver l’accès public à l’ACR existant nommé myacr dans le groupe de ressources myresourcegroup à l’aide de l’applet de commande Invoke-AzRestMethod.

Pour désactiver l’accès au réseau public, vous devez effectuer un appel PATCH à l’API qui modifie la valeur du paramètre publicNetwokAccess, comme indiqué dans l’exemple suivant :

$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 propriété Payload est une chaîne JSON qui affiche le chemin d’accès de la propriété à modifier.

Tous les paramètres de cette API sont décrits dans le fichier rest-api-spec associé à cette API. Vous trouverez la définition spécifique du paramètre publicNetworkAccess dans le fichier JSON du registre de conteneurs pour la version de l’API 2019-12-01-preview.

Pour autoriser uniquement l’accès au Registre à partir d’une adresse IP spécifique, la charge utile doit être modifiée comme indiqué dans l’exemple suivant :

$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

Comparaison avec Get-AzResource, New-AzResource et Remove-AzResource

Les applets de commande *-AzResource vous permettent de personnaliser l’appel d’API REST vers Azure en spécifiant le type de ressource, la version de l’API et les propriétés à mettre à jour. Toutefois, les propriétés doivent d’abord être créées en tant que PSObject. Ce processus ajoute un niveau de complexité supplémentaire et peut devenir compliqué.

Invoke-AzRestMethod offre un moyen de gérer les ressources Azure. Comme indiqué dans l’exemple précédent, vous pouvez générer une chaîne JSON et l’utiliser pour personnaliser l’appel d’API REST sans avoir à créer une PSObjects.

Si vous connaissez déjà les applets de commande *-AzResource, vous pouvez continuer à les utiliser. Nous n’avons pas l’intention d’arrêter de les soutenir. Avec Invoke-AzRestMethod, nous avons ajouté une nouvelle applet de commande à votre kit de ressources.

Voir aussi