Creare, eseguire ed eliminare risorse di Azure Machine Learning tramite REST

Esistono diversi modi per gestire le risorse di Azure Machine Learning. È possibile usare il portale, l'interfaccia della riga di comandoo Python SDK. In alternativa, è possibile scegliere l'API REST. L'API REST usa verbi HTTP in modo standard per creare, recuperare, aggiornare ed eliminare le risorse. L'API REST funziona con qualsiasi linguaggio o strumento in grado di effettuare richieste HTTP. La struttura semplice di REST lo rende spesso una scelta ottimale negli ambienti di scripting e per l'automazione MLOps.

In questo articolo vengono illustrate le operazioni seguenti:

Prerequisiti

• Una sottoscrizione di Azure della quale si dispone dei diritti amministrativi. Se non si dispone di una sottoscrizione di questo tipo, provare la sottoscrizione personale gratuita o a pagamento
• Un'area di lavoro di Azure Machine Learning.
• Le richieste amministrative REST usano l'autenticazione dell'entità servizio. Seguire la procedura descritta in Configurare l'autenticazione per le risorse e i flussi di lavoro di Azure Machine Learning per creare un'entità servizio nell'area di lavoro
• L'utilità curl. Il programma curl è disponibile nel sottosistema Windows per Linux o in qualsiasi distribuzione UNIX. In PowerShell curl è un alias per Invoke-WebRequest e curl -d "key=val" -X POST uri diventa Invoke-WebRequest -Body "key=val" -Method POST -Uri uri.

Recuperare un token di autenticazione dell'entità servizio

Le richieste REST amministrative vengono autenticate con un flusso implicito OAuth2. Questo flusso di autenticazione usa un token fornito dall'entità servizio della sottoscrizione. Per recuperare questo token, è necessario:

• ID tenant (identificazione dell'organizzazione a cui appartiene la sottoscrizione)
• ID client (che verrà associato al token creato)
• Il segreto client (che è necessario proteggere)

Questi valori dovrebbero essere presenti nella risposta alla creazione dell'entità servizio. Per ottenere questi valori, vedere Configurare l'autenticazione per le risorse e i flussi di lavoro di Azure Machine Learning. Se si usa la sottoscrizione aziendale, è possibile che non si abbia l'autorizzazione a creare un'entità servizio. In tal caso, è consigliabile usare una sottoscrizione personale gratuita o a pagamento.

Per recuperare un token:

1. Aprire una finestra del terminale
2. Immettere il codice seguente nella riga di comando
3. Sostituire i valori personalizzati di <YOUR-TENANT-ID>, <YOUR-CLIENT-ID> e <YOUR-CLIENT-SECRET>. In questo articolo, le stringhe racchiuse tra parentesi angolari sono variabili da sostituire con i vostri valori appropriati.
4. Eseguire il comando

curl -X POST https://login.microsoftonline.com/<YOUR-TENANT-ID>/oauth2/token \
-d "grant_type=client_credentials&resource=https%3A%2F%2Fmanagement.azure.com%2F&client_id=<YOUR-CLIENT-ID>&client_secret=<YOUR-CLIENT-SECRET>" \

La risposta deve fornire un token di accesso valido per un'ora:

{
    "token_type": "Bearer",
    "expires_in": "3599",
    "ext_expires_in": "3599",
    "expires_on": "1578523094",
    "not_before": "1578519194",
    "resource": "https://management.azure.com/",
    "access_token": "YOUR-ACCESS-TOKEN"
}

Prendere nota del token, perché verrà usato per autenticare tutte le richieste amministrative. A tale scopo, impostare un'intestazione di autorizzazione in tutte le richieste:

curl -h "Authorization:Bearer <YOUR-ACCESS-TOKEN>" ...more args...

Ottenere un elenco di gruppi di risorse associati alla sottoscrizione

Per recuperare l'elenco dei gruppi di risorse associati alla sottoscrizione, eseguire:

curl https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups?api-version=2022-04-01 -H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

In Azure vengono pubblicate molte API REST. Ogni provider di servizi aggiorna le API in base alla propria frequenza, ma lo fa senza interrompere i programmi esistenti. Il provider di servizi usa l'argomento api-version per garantire la compatibilità.

Tutte le chiamate REST devono impostare l'argomento api-version sul valore previsto. Si può fare affidamento sulla sintassi e sulla semantica della versione specificata, anche se l'API continua a evolversi. Se si invia una richiesta a un provider senza l'argomento api-version, la risposta conterrà un elenco leggibile di valori supportati.

La chiamata precedente genererà una risposta JSON compattata del modulo:

{
    "value": [
        {
            "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/RG1",
            "name": "RG1",
            "type": "Microsoft.Resources/resourceGroups",
            "location": "westus2",
            "properties": {
                "provisioningState": "Succeeded"
            }
        },
        {
            "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/RG2",
            "name": "RG2",
            "type": "Microsoft.Resources/resourceGroups",
            "location": "eastus",
            "properties": {
                "provisioningState": "Succeeded"
            }
        }
    ]
}

Eseguire il drill-down nelle aree di lavoro e nelle relative risorse

Per recuperare il set di aree di lavoro in un gruppo di risorse, eseguire le operazioni seguenti, sostituendo <YOUR-SUBSCRIPTION-ID>, <YOUR-RESOURCE-GROUP>e <YOUR-ACCESS-TOKEN>:

curl https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/providers/Microsoft.MachineLearningServices/workspaces/?api-version=2023-10-01 \
-H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

Anche in questo caso, si riceverà un elenco JSON, questa volta contenente un elenco, ogni elemento del quale descrive un'area di lavoro:

{
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/DeepLearningResourceGroup/providers/Microsoft.MachineLearningServices/workspaces/my-workspace",
    "name": "my-workspace",
    "type": "Microsoft.MachineLearningServices/workspaces",
    "location": "centralus",
    "tags": {},
    "etag": null,
    "properties": {
        "friendlyName": "",
        "description": "",
        "creationTime": "2023-01-03T19:56:09.7588299+00:00",
        "storageAccount": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/DeepLearningResourceGroup/providers/microsoft.storage/storageaccounts/myworkspace0275623111",
        "containerRegistry": null,
        "keyVault": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/DeepLearningResourceGroup/providers/microsoft.keyvault/vaults/myworkspace2525649324",
        "applicationInsights": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/DeepLearningResourceGroup/providers/microsoft.insights/components/myworkspace2053523719",
        "hbiWorkspace": false,
        "workspaceId": "cba12345-abab-abab-abab-ababab123456",
        "subscriptionState": null,
        "subscriptionStatusChangeTimeStampUtc": null,
        "discoveryUrl": "https://centralus.experiments.azureml.net/discovery"
    },
    "identity": {
        "type": "SystemAssigned",
        "principalId": "abcdef1-abab-1234-1234-abababab123456",
        "tenantId": "1fedcba-abab-1234-1234-abababab123456"
    },
    "sku": {
        "name": "Basic",
        "tier": "Basic"
    }
}

Per usare le risorse all'interno di un'area di lavoro, passare dal server management.azure.com generale a un server API REST specifico per la posizione dell'area di lavoro. Si noti il valore della chiave discoveryUrl nella risposta JSON precedente. Se si OTTIENE tale URL, si riceverà una risposta simile alla seguente:

{
  "api": "https://centralus.api.azureml.ms",
  "catalog": "https://catalog.cortanaanalytics.com",
  "experimentation": "https://centralus.experiments.azureml.net",
  "gallery": "https://gallery.cortanaintelligence.com/project",
  "history": "https://centralus.experiments.azureml.net",
  "hyperdrive": "https://centralus.experiments.azureml.net",
  "labeling": "https://centralus.experiments.azureml.net",
  "modelmanagement": "https://centralus.modelmanagement.azureml.net",
  "pipelines": "https://centralus.aether.ms",
  "studiocoreservices": "https://centralus.studioservice.azureml.com"
}

Il valore della risposta api è l'URL del server che verrà usato per più richieste. Per elencare gli esperimenti, ad esempio, inviare il comando seguente. Sostituire REGIONAL-API-SERVER con il valore della risposta api ( ad esempio, centralus.api.azureml.ms). Sostituire anche YOUR-SUBSCRIPTION-ID, YOUR-RESOURCE-GROUP, YOUR-WORKSPACE-NAMEe YOUR-ACCESS-TOKEN come di consueto:

curl https://<REGIONAL-API-SERVER>/history/v1.0/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.MachineLearningServices/workspaces/<YOUR-WORKSPACE-NAME>/experiments?api-version=2023-10-01 \
-H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

Analogamente, per recuperare i modelli registrati nell'area di lavoro, inviare:

curl https://<REGIONAL-API-SERVER>/modelmanagement/v1.0/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.MachineLearningServices/workspaces/<YOUR-WORKSPACE-NAME>/models?api-version=2023-10-01 \
-H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

Si noti che per elencare gli esperimenti il percorso inizia con history/v1.0 mentre per elencare i modelli il percorso inizia con modelmanagement/v1.0. L'API REST è suddivisa in diversi gruppi operativi, ognuno con un percorso distinto.

È possibile esplorare l'API REST tramite il modello generale di:

Creare e modificare le risorse usando le richieste PUT e POST

Oltre al recupero delle risorse con il verbo GET, l'API REST supporta la creazione di tutte le risorse necessarie per eseguire il training, la distribuzione e il monitoraggio delle soluzioni ML.

Il training e l'esecuzione di modelli di Machine Learning richiedono risorse di calcolo. È possibile elencare le risorse di calcolo di un'area di lavoro con:

curl https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.MachineLearningServices/workspaces/<YOUR-WORKSPACE-NAME>/computes?api-version=2023-10-01 \
-H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

Per creare o sovrascrivere una risorsa di calcolo denominata, si userà una richiesta PUT. Nell'esempio seguente, oltre alle sostituzioni ormai note di YOUR-SUBSCRIPTION-ID, YOUR-RESOURCE-GROUP, YOUR-WORKSPACE-NAME e YOUR-ACCESS-TOKEN, sostituire YOUR-COMPUTE-NAMEe i valori per location, vmSize, vmPriority e scaleSettings. Il comando seguente crea un nodo singolo dedicato Standard_D1 (una risorsa di calcolo della CPU di base) che si riduce dopo 30 minuti:

curl -X PUT \
  'https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/providers/Microsoft.MachineLearningServices/workspaces/<YOUR-WORKSPACE-NAME>/computes/<YOUR-COMPUTE-NAME>?api-version=2023-10-01' \
  -H 'Authorization:Bearer <YOUR-ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "eastus",
    "properties": {
        "computeType": "AmlCompute",
        "properties": {
            "vmSize": "Standard_D1",
            "vmPriority": "Dedicated",
            "scaleSettings": {
                "maxNodeCount": 1,
                "minNodeCount": 0,
                "nodeIdleTimeBeforeScaleDown": "PT30M"
            }
        }
    }
}'

Se la richiesta ha esito positivo, si otterrà una risposta 201 Created, ma si noti che questa risposta indica semplicemente che il processo di provisioning è stato avviato. È necessario eseguire il polling (o usare il portale) per confermarne il completamento.

Creare un'area di lavoro usando REST

Ogni area di lavoro di Azure Machine Learning dipende da altre quattro risorse di Azure: una risorsa del Registro Azure Container, Azure Key Vault, Azure Application Insights e un account di Archiviazione di Azure. Non è possibile creare un'area di lavoro finché non esistono queste risorse. Per informazioni dettagliate sulla creazione di ogni risorsa, vedere le informazioni di riferimento sull'API REST.

Per creare un'area di lavoro, ESEGUIRE una chiamata simile alla seguente a management.azure.com. Anche se questa chiamata richiede di impostare un numero elevato di variabili, è strutturalmente identica ad altre chiamate descritte in questo articolo.

curl -X PUT \
  'https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.MachineLearningServices/workspaces/<YOUR-NEW-WORKSPACE-NAME>?api-version=2023-10-01' \
  -H 'Authorization: Bearer <YOUR-ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "AZURE-LOCATION>",
    "identity" : {
        "type" : "systemAssigned"
    },
    "properties": {
        "friendlyName" : "<YOUR-WORKSPACE-FRIENDLY-NAME>",
        "description" : "<YOUR-WORKSPACE-DESCRIPTION>",
        "containerRegistry" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.ContainerRegistry/registries/<YOUR-REGISTRY-NAME>",
        keyVault" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.Keyvault/vaults/<YOUR-KEYVAULT-NAME>",
        "applicationInsights" : "subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.insights/components/<YOUR-APPLICATION-INSIGHTS-NAME>",
        "storageAccount" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.Storage/storageAccounts/<YOUR-STORAGE-ACCOUNT-NAME>"
    }
}'

Si dovrebbe ricevere una risposta 202 Accepted e, nelle intestazioni restituite, un URI Location. È possibile OTTENERE questo URI per informazioni sulla distribuzione, incluse informazioni utili per il debug in caso di problemi con una delle risorse dipendenti (ad esempio, se si è dimenticato di abilitare l'accesso dell'amministratore nel registro dei contenitori).

Creare un'area di lavoro usando un'identità gestita assegnata dall'utente

Quando si crea un'area di lavoro, è possibile specificare un'identità gestita assegnata dall'utente che verrà usata per accedere alle risorse associate: Registro Azure Container, KeyVault, Archiviazione e App Insights. Per creare un'area di lavoro con identità gestita assegnata dall'utente, usare il corpo della richiesta seguente.

curl -X PUT \
  'https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.MachineLearningServices/workspaces/<YOUR-NEW-WORKSPACE-NAME>?api-version=2023-10-01' \
  -H 'Authorization: Bearer <YOUR-ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "AZURE-LOCATION>",
    "identity": {
      "type": "SystemAssigned,UserAssigned",
      "userAssignedIdentities": {
        "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.ManagedIdentity/userAssignedIdentities/<YOUR-MANAGED-IDENTITY>": {}
      }
    },
    "properties": {
        "friendlyName" : "<YOUR-WORKSPACE-FRIENDLY-NAME>",
        "description" : "<YOUR-WORKSPACE-DESCRIPTION>",
        "containerRegistry" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.ContainerRegistry/registries/<YOUR-REGISTRY-NAME>",
        keyVault" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.Keyvault/vaults/<YOUR-KEYVAULT-NAME>",
        "applicationInsights" : "subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.insights/components/<YOUR-APPLICATION-INSIGHTS-NAME>",
        "storageAccount" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.Storage/storageAccounts/<YOUR-STORAGE-ACCOUNT-NAME>"
    }
}'

Creare un'area di lavoro usando una chiave gestita dal cliente

Per impostazione predefinita, i metadati per l'area di lavoro vengono archiviati in un'istanza di Azure Cosmos DB gestita da Microsoft. Questi dati vengono crittografati tramite chiavi gestite da Microsoft. Anziché usare la chiave gestita da Microsoft, è anche possibile fornire la propria chiave. In questo modo viene creato un set aggiuntivo di risorse nella propria sottoscrizione di Azure per archiviare i dati.

Per creare un'area di lavoro che usa le chiavi per la crittografia, è necessario soddisfare i prerequisiti seguenti:

• L'entità servizio di Azure Machine Learning deve avere accesso come collaboratore alla sottoscrizione di Azure.
• È necessario che l’insieme di credenziali delle chiavi esistenti contenga una chiave di crittografia.
• Azure Key Vault deve esistere nella stessa area di Azure in cui si intende creare l'area di lavoro di Azure Machine Learning.
• Azure Key Vault deve avere abilitata la protezione dall'eliminazione temporanea e dall'eliminazione per proteggersi dalla perdita di dati in caso di eliminazione accidentale.
• È necessario disporre di un criterio di accesso in Azure Key Vault che concede l'accesso get, wrap e unwrap all'applicazione Azure Cosmos DB.

Per creare un'area di lavoro che usa un'identità gestita assegnata dall'utente e chiavi gestite dal cliente per la crittografia, usare il corpo della richiesta seguente. Quando si usa un'identità gestita assegnata dall'utente per l'area di lavoro, impostare anche la proprietà userAssignedIdentity sull'ID risorsa dell'identità gestita.

curl -X PUT \
  'https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.MachineLearningServices/workspaces/<YOUR-NEW-WORKSPACE-NAME>?api-version=2023-10-01' \
  -H 'Authorization: Bearer <YOUR-ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "eastus2euap",
    "identity": {
      "type": "SystemAssigned"
    },
    "properties": {
      "friendlyName": "<YOUR-WORKSPACE-FRIENDLY-NAME>",
      "description": "<YOUR-WORKSPACE-DESCRIPTION>",
      "containerRegistry" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.ContainerRegistry/registries/<YOUR-REGISTRY-NAME>",
      "keyVault" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.Keyvault/vaults/<YOUR-KEYVAULT-NAME>",
      "applicationInsights" : "subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.insights/components/<YOUR-APPLICATION-INSIGHTS-NAME>",
      "storageAccount" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.Storage/storageAccounts/<YOUR-STORAGE-ACCOUNT-NAME>",
      "encryption": {
        "status": "Enabled",
        "identity": {
          "userAssignedIdentity": null
        },      
        "keyVaultProperties": {
           "keyVaultArmId": "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.KeyVault/vaults/<YOUR-VAULT>",
           "keyIdentifier": "https://<YOUR-VAULT>.vault.azure.net/keys/<YOUR-KEY>/<YOUR-KEY-VERSION>",
           "identityClientId": ""
        }
      },
      "hbiWorkspace": false
    }
}'

Eliminare le risorse non più necessarie

Alcune risorse, ma non tutte, supportano il verbo DELETE. Controllare le Informazioni di riferimento sulle API prima di eseguire il commit nell'API REST per i casi d'uso per l'eliminazione. Per eliminare un modello, ad esempio, è possibile usare:

curl
  -X DELETE \
'https://<REGIONAL-API-SERVER>/modelmanagement/v1.0/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/providers/Microsoft.MachineLearningServices/workspaces/<YOUR-WORKSPACE-NAME>/models/<YOUR-MODEL-ID>?api-version=2022-05-01' \
  -H 'Authorization:Bearer <YOUR-ACCESS-TOKEN>' 

Risoluzione dei problemi

Errori del provider di risorse

Quando si crea un'area di lavoro di Azure Machine Learning o una risorsa usata dall'area di lavoro, è possibile che venga visualizzato un errore simile ai messaggi seguenti:

• No registered resource provider found for location {location}
• The subscription is not registered to use namespace {resource-provider-namespace}

Molti provider di risorse vengono registrati automaticamente, ma non tutti. Se si riceve questo messaggio, è necessario registrare il provider indicato.

La tabella seguente contiene un elenco dei provider di risorse richiesti da Azure Machine Learning:

Se si prevede di usare una chiave gestita dal cliente con Azure Machine Learning, è necessario registrare i provider di servizi seguenti:

Se si prevede di usare una rete virtuale gestita con Azure Machine Learning, è necessario registrare il provider di risorse Microsoft.Network. Questo provider di risorse viene usato dall'area di lavoro quando si creano endpoint privati per la rete virtuale gestita.

Per informazioni sulla registrazione dei provider di risorse, vedere Risoluzione degli errori di registrazione del provider di risorse.

Spostamento dell'area di lavoro

Eliminazione del Registro Azure Container

L'area di lavoro di Azure Machine Learning usa il Registro Azure Container (ACR) per alcune operazioni. Verrà creata automaticamente un'istanza di ACR quando è necessaria per la prima volta.

Passaggi successivi

• Esplorare le Informazioni di riferimento sulle API REST di Azure Machine Learning complete.
• Esplorare Azure Machine Learning con Jupyter notebook.