Administración de los recursos de Azure con Invoke-AzRestMethod

  • Artículo

Invoke-AzRestMethod es un cmdlet de Azure PowerShell que se incorporó en la versión 4.4.0 del módulo Az de PowerShell. Permite realizar solicitudes HTTP personalizadas al punto de conexión de Azure Resource Manager (ARM) mediante el contexto Az.

Este cmdlet es útil cuando desea administrar los servicios de Azure para las características que aún no están disponibles en el módulo Az de PowerShell.

Cómo usar Invoke-AzRestMethod

Por ejemplo, puede permitir el acceso a Azure Container Registry (ACR) solo para redes específicas o para denegar el acceso público. Hasta la versión 4.5.0 del módulo Az de PowerShell, esta característica no está disponible todavía en el módulo de PowerShell Az.ContainerRegistry. Sin embargo, se puede administrar con Invoke-AzRestMethod provisionalmente.

Uso de Invoke-AzRestMethod con operaciones GET

En el ejemplo siguiente se muestra cómo usar el cmdlet Invoke-AzRestMethod con una operación GET:

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

Para permitir la máxima flexibilidad, la mayoría de los parámetros de Invoke-AzRestMethod son opcionales. Sin embargo, cuando se administran recursos dentro de un grupo de recursos, tendrá que proporcionar el identificador completo del recurso o parámetros como el grupo de recursos, el proveedor de recursos y el tipo de recurso.

Los parámetros ResourceType y Name pueden tomar varios valores cuando se aplican a recursos que requieran más de un nombre. Por ejemplo, para manipular una búsqueda guardada en un área de trabajo de Log Analytics, los parámetros son similares al ejemplo siguiente: -ResourceType @('workspaces', 'savedsearches') -Name @('my-la', 'my-search').

El cmdlet construye el siguiente recurso mediante una asignación basada en la posición de la matriz: Id:'/workspaces/my-la/savedsearches/my-search'.

El parámetro APIVersion le permite usar una versión específica de la API, incluidas las versiones preliminares. Las versiones de API admitidas para los proveedores de recursos de Azure se pueden encontrar en el repositorio de GitHub azure-rest-api-specs.

Encontrará la definición de la versión 2019-12-01-preview ACR API en la siguiente ubicación: azure-rest-api-specs/specification/containerregistry/resource-manager/Microsoft.ContainerRegistry/preview/.

Uso de Invoke-AzRestMethod con operaciones PATCH

Puede deshabilitar el acceso público al ACR existente llamado myacr en el grupo de recursos myresourcegroup mediante el cmdlet Invoke-AzRestMethod.

Para deshabilitar el acceso a la red pública, debe realizar una llamada PATCH a la API que cambia el valor del parámetro publicNetwokAccess, como se muestra en el ejemplo siguiente:

$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 propiedad Payload es una cadena JSON que muestra la ruta de acceso de la propiedad que se va a modificar.

Todos los parámetros de esta API se describen en el archivo rest-api-spec asociado a esta API. La definición específica del parámetro publicNetworkAccess se puede encontrar en el archivo JSON del registro de contenedor para la versión 2019-12-01-preview de la API.

Para permitir el acceso al registro solo desde una dirección IP específica, la carga debe modificarse tal y como se muestra en el ejemplo siguiente:

$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

Comparación con Get-AzResource, New-AzResource y Remove-AzResource

Los cmdlets *-AzResource permiten personalizar la llamada de la API REST a Azure especificando el tipo de recurso, la versión de la API y las propiedades que se van a actualizar. Sin embargo, las propiedades deben crearse primero como PSObject. Este proceso agrega un nivel de complejidad adicional y puede resultar complicado.

Invoke-AzRestMethod ofrece una manera de administrar los recursos de Azure. Como se muestra en el ejemplo anterior, puede compilar una cadena JSON y usarla para personalizar la llamada API REST sin tener que crear previamente ningún objeto PSObjects.

Si ya está familiarizado con los cmdlets de *-AzResource, puede seguir utilizándolos. No está previsto que dejen de ser compatibles. Con Invoke-AzRestMethod, se ha agregado un nuevo cmdlet al kit de herramientas.

Vea también