Uso de la API REST de Azure con la CLI de Azure

  • Artículo

Las API de transferencia de estado representacional (REST) son puntos de conexión de servicio que admiten diferentes conjuntos de operaciones HTTP (o métodos). Estos métodos HTTP permiten realizar diferentes acciones para los recursos del servicio. El az rest comando solo se debe usar cuando un comando de la CLI de Azure existente no está disponible.

Tras completar este artículo, sabrá cómo usar las solicitudes HTTP PUT, PATCH, GET, POST y DELETE para administrar los recursos de Azure Container Registry. Azure Container Registry es un servicio de registro administrado que permite crear y mantener registros de contenedor de Azure que almacenan imágenes de contenedor y artefactos relacionados.

Requisitos previos

Configure la solicitud de API REST de Azure personalizada:

Para invocar una solicitud de API REST de Azure personalizada con la CLI de Azure, use el az rest comando seguido del --url parámetro . El --url parámetro define la dirección URL del recurso solicitado y es el único parámetro necesario.

Nota:

  • El az rest comando se autentica automáticamente mediante la credencial de inicio de sesión. Si no se establece el encabezado authorization, adjunta el encabezado Authorization: Bearer <token>, donde <token> se recupera de Microsoft Entra ID. El recurso de destino del token se derivará del --url parámetro cuando el --url parámetro comience con un punto de conexión de la salida del az cloud show --query endpoints comando. Use el --resource parámetro para un recurso personalizado.
  • Si el encabezado Content-Type no está establecido y --body es una cadena JSON válida, el encabezado Content-Type tendrá como valor predeterminado "application/json".

Uso de PUT para crear una instancia de Azure Container Registry

Use el método HTTP PUT para crear una instancia de Azure Container Registry.

# Command format example
az rest --method put \
    --url https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.ContainerRegistry/registries/<containerRegistryName>?api-version=2023-01-01-preview \
    --body "{'location': '<locationName>', 'sku': {'name': '<skuName>'}, 'properties': {'adminUserEnabled': '<propertyValue>'}}"

Este es un ejemplo con parámetros completados:

# Variable block
let "randomIdentifier=$RANDOM*$RANDOM"
subscriptionId="00000000-0000-0000-0000-000000000000"
resourceGroup="msdocs-app-rg$randomIdentifier"
containerRegistryName="msdocscr$randomIdentifier"
locationName="westus"
skuName="Standard"
propertyValue="true"

# Create resource group
az group create --name $resourceGroup --location $locationName --output json

# Invoke request
az rest --method put \
    --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview \
    --body "{'location': '$locationName', 'sku': {'name': '$skuName'}, 'properties': {'adminUserEnabled': '$propertyValue'}}"

Salida JSON para Bash y PowerShell:

{
  "id": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.ContainerRegistry/registries/<containerRegistryName>",
  "location": "<location>",
  "name": "<containerRegistryName>",
  "properties": {
    "adminUserEnabled": true,
    "anonymousPullEnabled": false,
    "creationDate": "2024-01-03T18:38:36.7089583Z",
    "dataEndpointEnabled": false,
    "dataEndpointHostNames": [],
    "encryption": {
      "status": "disabled"
    },
    "loginServer": "<containerRegistryName>.azurecr.io",
    "networkRuleBypassOptions": "AzureServices",
    "policies": {
      "azureADAuthenticationAsArmPolicy": {
        "status": "enabled"
      },
      "exportPolicy": {
        "status": "enabled"
      },
      "quarantinePolicy": {
        "status": "disabled"
      },
      "retentionPolicy": {
        "days": 7,
        "lastUpdatedTime": "2024-01-03T19:44:53.9770581+00:00",
        "status": "disabled"
      },
      "softDeletePolicy": {
        "lastUpdatedTime": "2024-01-03T19:44:53.9771117+00:00",
        "retentionDays": 7,
        "status": "disabled"
      },
      "trustPolicy": {
        "status": "disabled",
        "type": "Notary"
      }
    },
    "privateEndpointConnections": [],
    "provisioningState": "Succeeded",
    "publicNetworkAccess": "Enabled",
    "zoneRedundancy": "Disabled"
  },
  "sku": {
    "name": "Standard",
    "tier": "Standard"
  },
  "systemData": {
    "createdAt": "2024-01-03T18:38:36.7089583+00:00",
    "createdBy": "<username>@microsoft.com",
    "createdByType": "User",
    "lastModifiedAt": "2024-01-03T19:44:53.684342+00:00",
    "lastModifiedBy": "<username>@microsoft.com",
    "lastModifiedByType": "User"
  },
  "tags":{},
  "type": "Microsoft.ContainerRegistry/registries"
}

Ahora ha creado correctamente la nueva instancia de Azure Container Registry mediante az rest!

Uso de PATCH para actualizar Azure Container Registry

Actualice Azure Container Registry mediante la solicitud HTTP PATCH. Edite el --body parámetro con las propiedades que desea actualizar. En este ejemplo se usan las variables establecidas en la sección anterior y se actualiza el nombre de la SKU ($skuName="Premium") de Azure Container Registry.

#Variable Block
$skuName="Premium"

az rest --method patch \
    --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview \
    --body "{'location': '$locationName', 'sku': {'name': '$skuName'}, 'properties': {'adminUserEnabled': '$propertyValue'}}"

La siguiente salida del diccionario JSON tiene campos omitidos para mayor brevedad:

{
  "id": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.ContainerRegistry/registries/<containerRegistryName>",
  "location": "westus",
  "name": "<containerRegistryName>",
  "properties": {...},
  "sku": {
    "name": "Premium",
    "tier": "Premium"
  },
  "systemData": {...},
  "type": "Microsoft.ContainerRegistry/registries"
}

Uso de GET para recuperar Azure Container Registry

Use la solicitud HTTP GET para ver los resultados de la actualización de la solicitud PATCH. En este ejemplo se usan las variables establecidas en la sección anterior.

az rest --method get \
    --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview

La salida del método GET es la misma que la que se muestra para PUT.

Uso de POST para regenerar las credenciales de Azure Container Registry

Use la solicitud HTTP POST para volver a generar una de las credenciales de inicio de sesión de Azure Container Registry creadas en este artículo.

# Variable block
$passwordValue="password"

az rest --method post \
    --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName/regenerateCredential?api-version=2023-01-01-preview \
    --body "{'name': '$passwordValue'}"

La siguiente salida del diccionario JSON tiene campos omitidos para mayor brevedad:

{
  "passwords": [
    {
      "name": "password",
      "value": "<passwordValue>"
    },
    {
      "name": "password2",
      "value": "<passwordValue2>"
    }
  ],
  "username": "<containerRegistryName>"
}

Una vez completada la solicitud, las credenciales de Azure Container Registry especificadas se regenerarán con una nueva contraseña junto con la contraseña existente (password2).

Uso de DELETE para eliminar Azure Container Registry

Use la solicitud HTTP DELETE para eliminar una instancia de Azure Container Registry existente.

az rest --method delete \
    --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview

Limpieza de recursos

Cuando haya terminado con los recursos creados en este artículo, puede eliminar el grupo de recursos. Al eliminar el grupo de recursos, se eliminan todos los recursos de ese grupo de recursos.

az group delete --resource-group <resourceGroupName>