Usare l'API REST di Azure con l'interfaccia della riga di comando di Azure

  • Articolo

Le API REST (Representational State Transfer) sono endpoint di servizio che supportano diversi set di operazioni HTTP (o metodi). Questi metodi HTTP consentono di eseguire azioni diverse per le risorse del servizio. Il az rest comando deve essere usato solo quando non è disponibile un comando dell'interfaccia della riga di comando di Azure esistente.

Questo articolo illustra le richieste HTTP PUT, PATCH, GET, POST e DELETE per gestire le risorse Registro Azure Container. Il Registro Azure Container è un servizio del Registro di sistema gestito che consente di creare e gestire registri contenitori di Azure che archivia le immagini del contenitore e gli artefatti correlati.

Prerequisiti

Suggerimenti per l'uso az rest

Ecco alcune informazioni utili quando si usa az rest:

  • Il az rest comando esegue automaticamente l'autenticazione usando le credenziali registrate.
  • Se l'intestazione authorization non è impostata, allega l'intestazione Authorization: Bearer <token>, dove <token> viene recuperata dall'ID Microsoft Entra.
  • La risorsa di destinazione del token verrà derivata dal --url parametro quando il --url parametro inizia con un endpoint dall'output del az cloud show --query endpoints comando. Parametro --url obbligatorio.
  • Usare il --resource parametro per una risorsa personalizzata.
  • Se l'intestazione Content-Type non è impostata ed --body è una stringa JSON valida, per impostazione predefinita l'intestazione Content-Type sarà "application/json".
  • Quando si usa --uri-parameters per le richieste sotto forma di OData, assicurarsi di eseguire l'escape $ in ambienti diversi: in Bash, escape $ come \$ e in PowerShell, come escape $ come `$.

Usare PUT per creare un Registro Azure Container

Usare il metodo HTTP PUT per creare una nuova Registro Azure Container.

# 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>'}}"

Ecco un esempio con i parametri completati:

# 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'}}"

Output JSON per Bash e 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"
}

Usare PATCH per aggiornare il Registro Azure Container

Aggiornare il Registro Azure Container usando la richiesta HTTP PATCH. Modificare il --body parametro con le proprietà da aggiornare. Questo esempio usa le variabili impostate nella sezione precedente e aggiorna il nome dello SKU ($skuName="Premium") del Registro Azure Container.

#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'}}"

L'output del dizionario JSON seguente contiene campi omessi per brevità:

{
  "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"
}

Usare GET per recuperare i Registro Azure Container

Usare la richiesta HTTP GET per visualizzare i risultati dell'aggiornamento dalla richiesta PATCH. In questo esempio vengono usate le variabili impostate nella sezione precedente.

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

L'output per il metodo GET è uguale a quello mostrato per PUT.

Usare POST per rigenerare le credenziali di Registro Azure Container

Usare la richiesta HTTP POST per rigenerare una delle credenziali di accesso per il Registro Azure Container creato in questo articolo.

# 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'}"

L'output del dizionario JSON seguente contiene campi omessi per brevità:

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

Al termine della richiesta, le credenziali specificate Registro Azure Container verranno rigenerate con una nuova password insieme alla password esistente (password2).

Usare DELETE per eliminare il Registro Azure Container

Usare la richiesta HTTP DELETE per eliminare un Registro Azure Container esistente.

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

Esempio aggiuntivo az rest per Microsoft Graph

A volte è utile visualizzare un esempio per uno scenario diverso, quindi di seguito è riportato un esempio che usa l'API Microsoft Graph. Per aggiornare gli URI di reindirizzamento per un'applicazione, chiamare l'API REST dell'applicazione Di aggiornamento, come nel codice seguente:

# Get the application
az rest --method GET \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001'

# Update `redirectUris` for `web` property
az rest --method PATCH \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001' \
    --body '{"web":{"redirectUris":["https://myapp.com"]}}'

Pulire le risorse

Al termine delle risorse create in questo articolo, è possibile eliminare il gruppo di risorse. Quando si elimina il gruppo di risorse, tutte le risorse in tale gruppo di risorse vengono eliminate.

az group delete --resource-group <resourceGroupName>

Vedi anche