Gérer les ressources Azure avec Invoke-AzRestMethod

  • Article

Invoke-AzRestMethod est une applet de commande Azure PowerShell qui a été introduite dans le module Az PowerShell version 4.4.0. Elle vous permet d’effectuer des requêtes HTTP personnalisées sur le point de terminaison ARM (Azure Resource Manager) en utilisant le contexte Az.

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

Guide pratique pour 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. Depuis la version 4.5.0 du module Az PowerShell, cette fonctionnalité n’est pas encore disponible dans le module PowerShell Az.ContainerRegistry. Toutefois, elle peut être gérée pour l’instant avec Invoke-AzRestMethod.

Utilisation de l’applet de commande 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 une flexibilité maximale, la plupart des paramètres de Invoke-AzRestMethod sont facultatifs. Toutefois, quand vous gérez des ressources au sein d’un groupe de ressources, vous devez fournir l’ID complet à la ressource, ou des paramètres comme 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 de ressources qui requièrent plusieurs noms. Par exemple, pour manipuler une recherche enregistrée dans un espace de travail Log Analytics, les paramètres doivent ressembler à l’exemple suivant : -ResourceType @('workspaces', 'savedsearches') -Name @('my-la', 'my-search').

À l’aide d’un mappage basé sur la position dans le 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, notamment une API en préversion. 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 2019-12-01-preview de l’API ACR à 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’instance ACR existante nommée 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 indique 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. La définition spécifique du paramètre publicNetworkAccess se trouve dans le fichier JSON du registre de conteneurs pour la version 2019-12-01-preview de l’API.

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 entre AzResource, New-AzResource et Remove-AzResource

Les applets de commande *-AzResource vous permettent de personnaliser l’appel de l’API REST à 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 simple de gérer les ressources Azure. Comme nous l’avons vu 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 à précréer de PSObjects.

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

Voir aussi