Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
SI APPLICA A:
Estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)
SDK Python azure-ai-ml v2 (corrente)
Questo articolo illustra come autenticare i client per gli endpoint online di Azure Machine Learning. È possibile configurare le autorizzazioni, creare un endpoint, recuperare token o chiavi e assegnare un punteggio ai dati usando una delle tre modalità di autenticazione: chiave, token di Azure Machine Learning (aml_token) o token Microsoft Entra (aad_token).
L'autenticazione degli endpoint online prevede due tipi di operazioni:
- Un'operazione del piano di controllo controlla un endpoint e lo modifica. Queste operazioni includono creazione, lettura, aggiornamento ed eliminazione (CRUD) su endpoint online e distribuzioni online.
- Un'operazione del piano dati usa i dati per interagire con un endpoint online senza modificarlo. Ad esempio, un'operazione del piano dati consiste nell'inviare una richiesta di assegnazione dei punteggi a un endpoint online e ottenere una risposta.
Scegliere una modalità di autenticazione
Gli endpoint online supportano tre modalità di autenticazione per le operazioni del piano dati. Scegliere la modalità più adatta ai requisiti di sicurezza e al tipo di endpoint.
| Chiave | Token di Azure Machine Learning (aml_token) |
Token Microsoft Entra (aad_token) |
|
|---|---|---|---|
| Livello di sicurezza | Più basso: le chiavi statiche non scadono | Medio : breve durata, aggiornamento automatico | Massimo — basato sull'identità, con ambito determinato dal ruolo |
| Tipi di endpoint | Servizi Gestiti e Kubernetes | Servizi gestiti e Kubernetes | Solo gestito |
| RBAC richiesto per il punteggio | No | No | Sì (score/action ruolo) |
| Durata dei token | Nessuna scadenza (ruotare manualmente) | Breve durata con aggiornamento | Breve durata (per i criteri di Microsoft Entra) |
| Ideale per | Sviluppo e test | Pipeline automatizzate | Carichi di lavoro di produzione |
Per i carichi di lavoro di produzione negli endpoint online gestiti, usare l'autenticazione token Microsoft Entra (aad_token) per la sicurezza più avanzata. Per gli endpoint di sviluppo o Kubernetes, l'autenticazione basata su chiave è l'opzione più semplice.
Importante
L'autenticazione del token Microsoft Entra (aad_token) è supportata solo per gli endpoint online gestiti. Per gli endpoint online Kubernetes, usare l'autenticazione con chiave o token di Azure Machine Learning (aml_token). Per altre informazioni, vedere Autenticazione e autorizzazione per gli endpoint online.
Prerequisiti
Un'area di lavoro di Azure Machine Learning. Per istruzioni sulla creazione di un'area di lavoro, vedere Creare l'area di lavoro.
Interfaccia della riga di comando di Azure e l'estensione
mlo Azure Machine Learning Python SDK v2:Per installare l'interfaccia della riga di comando di Azure e l'estensione
ml, vedere Installare e configurare l'interfaccia della riga di comando (v2).Gli esempi in questo articolo presuppongono che si usi una shell Bash o una shell compatibile. Ad esempio, è possibile usare una shell in un sistema Linux o in un sottosistema Windows per Linux.
-
Python SDK:
azure-ai-mleazure-identitypacchetti (pip install azure-ai-ml azure-identity) -
Interfaccia della riga di comando di Azure: estensione
ml(az extension add -n ml) - Identità utente in Microsoft Entra ID. Per informazioni sulla creazione di un'identità utente, vedere Configurare l'autenticazione. È necessario l'ID identità in un passaggio successivo.
-
Ruolo di controllo degli accessi in base al ruolo necessario per le operazioni del piano di controllo e del piano dati: assegnare uno dei ruoli seguenti all'identità utente nell'ambito dell'area di lavoro:
- Data Scientist di AzureML (predefinito): include le autorizzazioni per le operazioni CRUD sugli endpoint e l'assegnazione dei punteggi. Vedere Ruolo data scientist di AzureML.
- Proprietario o Collaboratore : accesso completo per gestire gli endpoint.
- Ruolo personalizzato con
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*azioni.
- (Facoltativo) Lettore segreti connessione dell'area di lavoro di Azure Machine Learning : obbligatorio solo se è necessario accedere ai segreti dalle connessioni all'area di lavoro.
Verificare la configurazione
Esegui questo snippet per verificare che le credenziali e le autorizzazioni RBAC (controllo degli accessi basato sui ruoli) siano configurate correttamente:
az login
az ml online-endpoint list --resource-group <RESOURCE_GROUP> --workspace-name <WORKSPACE_NAME>
Output previsto: matrice JSON di endpoint (vuota [] se non esistono ancora endpoint).
Riferimento: az ml online-endpoint list
Assegnare autorizzazioni all'identità
Se hai già assegnato il ruolo RBAC richiesto (come indicato in Prerequisiti), procedi a Crea un endpoint. Questa sezione fornisce informazioni dettagliate sulla creazione di ruoli personalizzati, se necessario.
Visualizzare i dettagli del ruolo predefiniti
Il AzureML Data Scientistruolo predefinito include queste azioni di controllo degli accessi in base al ruolo del piano di controllo:
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/writeMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/deleteMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/readMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/token/actionMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/actionMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action
E questa azione di controllo degli accessi in base al ruolo del piano dati:
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/score/action
Il Azure Machine Learning Workspace Connection Secrets Reader ruolo predefinito include:
Microsoft.MachineLearningServices/workspaces/connections/listsecrets/actionMicrosoft.MachineLearningServices/workspaces/metadata/secrets/read
(Facoltativo) Creare un ruolo personalizzato
Ignorare questo passaggio se si usano ruoli predefiniti o altri ruoli personalizzati predefiniti.
Definire l'ambito e le azioni per i ruoli personalizzati creando le relative definizioni JSON. Ad esempio, la definizione di ruolo seguente ,custom-role-for-control-plane.json, consente all'utente di eseguire operazioni CRUD su un endpoint online in un'area di lavoro specificata.
{ "Name": "Custom role for control plane operations - online endpoint", "IsCustom": true, "Description": "Can CRUD against online endpoints.", "Actions": [ "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/write", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/delete", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/read", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/action", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action" ], "NotActions": [ ], "AssignableScopes": [ "/subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>" ] }La definizione di ruolo seguente ,custom-role-for-scoring.json, consente all'utente di inviare richieste di assegnazione dei punteggi a un endpoint online in un'area di lavoro specificata.
{ "Name": "Custom role for scoring - online endpoint", "IsCustom": true, "Description": "Can score against online endpoints.", "Actions": [ "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*/action" ], "NotActions": [ ], "AssignableScopes": [ "/subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>" ] }Usare le definizioni JSON per creare ruoli personalizzati:
az role definition create --role-definition custom-role-for-control-plane.json --subscription <subscriptionID> az role definition create --role-definition custom-role-for-scoring.json --subscription <subscriptionID>Note
Per creare ruoli personalizzati è necessario uno di questi tre ruoli:
- Proprietario
- Amministratore dell'accesso utente
- Un ruolo personalizzato con
Microsoft.Authorization/roleDefinitions/writeautorizzazione (per creare/aggiornare/eliminare ruoli personalizzati) eMicrosoft.Authorization/roleDefinitions/readl'autorizzazione (per visualizzare i ruoli personalizzati).
Per altre informazioni sulla creazione di ruoli personalizzati, vedere Ruoli personalizzati di Azure.
Verificare la definizione del ruolo:
az role definition list --custom-role-only -o table az role definition list -n "Custom role for control plane operations - online endpoint" az role definition list -n "Custom role for scoring - online endpoint" export role_definition_id1=`(az role definition list -n "Custom role for control plane operations - online endpoint" --query "[0].id" | tr -d '"')` export role_definition_id2=`(az role definition list -n "Custom role for scoring - online endpoint" --query "[0].id" | tr -d '"')`
Assegnare il ruolo all'identità
Se si usa il ruolo predefinito
AzureML Data Scientist, usare il codice seguente per assegnarlo all'identità utente.az role assignment create --assignee <identityID> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>Facoltativamente, se si usa il ruolo predefinito
Azure Machine Learning Workspace Connection Secrets Reader, usare il codice seguente per assegnarlo all'identità utente.az role assignment create --assignee <identityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>Se si usa un ruolo personalizzato, usare il codice seguente per assegnarlo all'identità utente.
az role assignment create --assignee <identityID> --role "Custom role for control plane operations - online endpoint" --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName> az role assignment create --assignee <identityID> --role "Custom role for scoring - online endpoint" --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>Note
Per assegnare ruoli personalizzati all'identità utente, è necessario uno dei tre ruoli seguenti:
- Proprietario
- Amministratore dell'accesso utente
- Ruolo personalizzato che consente l'autorizzazione
Microsoft.Authorization/roleAssignments/write(per assegnare ruoli personalizzati) eMicrosoft.Authorization/roleAssignments/read(per visualizzare le assegnazioni di ruolo).
Per altre informazioni sui ruoli di Azure e sulle relative autorizzazioni, vedere Ruoli di Azure e Assegnare ruoli di Azure tramite il portale di Azure.
Confermare l'assegnazione del ruolo:
az role assignment list --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
Ottenere un token del control plane
Completare questo passaggio se si prevede di eseguire operazioni del piano di controllo usando l'API REST, che usa direttamente il token.
Se si prevede di usare altri metodi, ad esempio l'interfaccia della riga di comando di Azure con l'estensione ml v2, Python SDK v2 o Azure Machine Learning Studio, non è necessario ottenere manualmente il token Microsoft Entra. L'identità utente viene autenticata durante l'accesso e il token viene recuperato e passato automaticamente.
È possibile recuperare dall'endpoint della risorsa di Azure il token Microsoft Entra per le operazioni del piano di controllo: https://management.azure.com.
Accedere ad Azure.
az loginSe si vuole usare un'identità specifica, usare il codice seguente per accedere con l'identità:
az login --identity --username <identityID>Usare questo contesto per ottenere il token:
export CONTROL_PLANE_TOKEN=$(az account get-access-token \ --resource https://management.azure.com \ --query accessToken -o tsv)
Riferimento: az login, az account get-access-token
Verificare il token del piano di controllo (facoltativo)
Dopo aver recuperato il token Microsoft Entra, è possibile verificare che il token sia per l'endpoint di risorsa di Azure corretto (management.azure.com) e l'ID client corretto decodificando il token tramite jwt.ms.
Suggerimento
Il sito jwt.ms è uno strumento di proprietà di Microsoft che decodifica completamente i token nel browser. Nessun dato viene inviato a un server. Non incollare mai i token in strumenti di decodifica non attendibili.
Il token decodificato restituisce una risposta JSON contenente le informazioni seguenti:
{
"aud": "https://management.azure.com",
"oid": "<your-object-id>"
}
Creare un endpoint
L'esempio seguente crea l'endpoint con un'identità assegnata dal sistema (SAI) come identità dell'endpoint. SAI è il tipo di identità predefinito per gli endpoint e alcuni ruoli di base vengono assegnati automaticamente. Per altre informazioni, vedere Assegnazione automatica dei ruoli per l'identità dell'endpoint.
L'interfaccia della riga di comando non richiede di fornire esplicitamente il token del piano di controllo. Al contrario, il comando dell'interfaccia a riga di comando az login autentica l'utente durante l'accesso e il token viene recuperato e passato automaticamente.
Creare un file YAML di definizione dell'endpoint denominato endpoint.yml:
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json name: my-endpoint auth_mode: aad_tokenÈ possibile impostare
auth_modesukeyper l'autenticazione della chiave oaml_tokenper l'autenticazione del token di Azure Machine Learning. Questo esempio usaaad_tokenper l'autenticazione del token Microsoft Entra.Note
La
aad_tokenmodalità di autenticazione è supportata solo per gli endpoint online gestiti. Per gli endpoint online Kubernetes, impostareauth_modesukeyoaml_token.Creare l'endpoint:
az ml online-endpoint create -f endpoint.ymlControllare lo stato dell'endpoint:
az ml online-endpoint show -n my-endpointSe si vuole eseguire l'override del valore di
auth_mode(ad esempio sostituendolo conaad_token) durante la creazione di un endpoint, eseguire il codice seguente:az ml online-endpoint create -n my-endpoint --auth-mode aad_tokenSe si vuole aggiornare l'endpoint esistente e specificare
auth_mode(ad esempio, comeaad_token), eseguire il codice seguente:az ml online-endpoint update -n my-endpoint --set auth_mode=aad_token
Riferimento: az ml online-endpoint create, az ml online-endpoint show, az ml online-endpoint update
Creare una distribuzione
Per creare una distribuzione, vedere Distribuire un modello di Machine Learning con un endpoint online o Usare REST per distribuire un modello come endpoint online. Non esiste alcuna differenza nel modo in cui si creano distribuzioni per diverse modalità di autenticazione.
Il codice seguente è un esempio di come creare una distribuzione. Per altre informazioni sulla distribuzione di endpoint online, vedere Distribuire un modello di Machine Learning con un endpoint online (tramite l'interfaccia della riga di comando).
Creare un file YAML di definizione della distribuzione denominato blue-deployment.yml:
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json name: blue endpoint_name: my-aad-auth-endp1 model: path: ../../model-1/model/ code_configuration: code: ../../model-1/onlinescoring/ scoring_script: score.py environment: conda_file: ../../model-1/environment/conda.yml image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu22.04:latest instance_type: Standard_DS3_v2 instance_count: 1Creare la distribuzione usando il file YAML. Per questo esempio, impostare tutto il traffico sulla nuova distribuzione.
az ml online-deployment create -f blue-deployment.yml --all-traffic
Riferimento: az ml online-deployment create
Ottenere l'URI di assegnazione dei punteggi
Se si usa az ml online-endpoint invoke per chiamare l'endpoint, l'interfaccia della riga di comando risolve automaticamente l'URI di assegnazione dei punteggi, quindi non è necessario recuperarlo manualmente.
Tuttavia, se è necessario l'URI di assegnazione dei punteggi per l'uso con altri strumenti ,ad esempio l'API REST o i client HTTP personalizzati, è possibile recuperarlo con il comando seguente:
scoringUri=$(az ml online-endpoint show -n my-endpoint --query "scoring_uri")
Riferimento: az ml online-endpoint show
Ottenere una chiave o un token per il piano dati
È possibile usare una chiave o un token per le operazioni del piano dati, anche se il processo di recupero della chiave o del token è un'operazione del piano di controllo. In altre parole, si usa un token del piano di controllo per ottenere la chiave o il token usato in un secondo momento per le operazioni del piano dati.
La durata dei token varia in base alla modalità di autenticazione:
-
Chiave: le chiavi non scadono ma devono essere ruotate regolarmente per la sicurezza. Usare l'azione
regenerateKeysper ruotare le chiavi. -
Token di Azure Machine Learning (
aml_token): token di breve durata che includono unrefreshAfterTimeUtccampo. Richiedere un nuovo token dopo questa volta per evitare la scadenza. -
Token Microsoft Entra (
aad_token): segue i criteri di durata del token ID di Microsoft Entra (in genere da 60 a 90 minuti). Aggiornare il token prima diexpiryTimeUtc.
Per ottenere la chiave o il token di Azure Machine Learning, l'identità utente che la richiede deve avere il ruolo corretto assegnato, come descritto in Autorizzazione per le operazioni del piano di controllo. L'identità utente non richiede ruoli aggiuntivi per ottenere il token Microsoft Entra.
Se si prevede di usare l'interfaccia della riga di comando per richiamare l'endpoint, non è necessario ottenere le chiavi o il token per le operazioni del piano dati in modo esplicito perché l'interfaccia della riga di comando lo fornisce automaticamente. Tuttavia, è comunque possibile usare l'interfaccia della riga di comando per ottenere le chiavi o il token per le operazioni del piano dati in modo che sia possibile usarlo con altri canali, ad esempio l'API REST.
Per ottenere le chiavi o il token per le operazioni del piano dati, usare il comando az ml online-endpoint get-credentials. Questo comando restituisce l'output JSON che contiene chiavi, token e/o informazioni aggiuntive.
Suggerimento
Nel comando seguente il --query parametro viene usato per estrarre informazioni specifiche dall'output JSON. Tuttavia, è possibile usare qualsiasi strumento adatto a tale scopo.
Quando l'oggetto auth_mode dell'endpoint è key
Le chiavi vengono restituite nei campi
primaryKeyesecondaryKey.export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey) export DATA_PLANE_TOKEN2=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query secondaryKey)
Quando l'oggetto auth_mode dell'endpoint è aml_token
Il token viene restituito nel
accessTokencampo .L'ora di scadenza del
expiryTimeUtctoken viene restituita nel campo .L'ora di aggiornamento del token viene restituita nel campo
refreshAfterTimeUtc.export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken) export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc) export REFRESH_AFTER_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query refreshAfterTimeUtc)
Quando l'oggetto auth_mode dell'endpoint è aad_token
Il token viene restituito nel
accessTokencampo .L'ora di scadenza del
expiryTimeUtctoken viene restituita nel campo .export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken) export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc)
Riferimento: az ml online-endpoint get-credentials
Verificare il token del piano dati (facoltativo)
Dopo aver ottenuto il token Entra, è possibile verificare che il token sia per l'endpoint di risorsa di Azure corretto, ml.azure.come l'ID client corretto decodificando il token tramite jwt.ms, che restituisce una risposta JSON con le informazioni seguenti:
Suggerimento
Il sito jwt.ms è uno strumento di proprietà di Microsoft che decodifica completamente i token nel browser. Nessun dato viene inviato a un server. Non incollare mai i token in strumenti di decodifica non attendibili.
{
"aud": "https://ml.azure.com",
"oid": "<your-object-id>"
}
Assegnare un punteggio ai dati
È possibile usare az ml online-endpoint invoke per gli endpoint con una chiave, un token di Azure Machine Learning o un token Microsoft Entra. L'interfaccia della riga di comando fornisce automaticamente la chiave o il token, quindi non è necessario passarlo in modo esplicito.
az ml online-endpoint invoke -n my-endpoint -r request.json
Riferimento: az ml online-endpoint invoke
Monitorare il traffico degli endpoint
Per abilitare la registrazione del traffico nelle impostazioni di diagnostica per l'endpoint, completare i passaggi descritti in Attivare i log.
Se l'impostazione di diagnostica è abilitata, è possibile visualizzare la tabella per visualizzare la AmlOnlineEndpointTrafficLogs modalità di autenticazione e l'identità utente.
Risolvere gli errori di autenticazione
Nella tabella seguente sono elencati gli errori di autenticazione comuni e le relative risoluzioni.
| Error | Causa possibile | Resolution |
|---|---|---|
| 401 - Non autorizzato | Token del pubblico mancante, scaduto o errato | Verificare che il gruppo di destinatari del token corrisponda al tipo di endpoint: management.azure.com per il piano di controllo, ml.azure.com per il piano dati. Aggiornare i token scaduti. |
| 403 Vietato | L'identità utente non dispone del ruolo RBAC richiesto | Assegnare AzureML Data Scientist o un ruolo personalizzato con l'autorizzazione score/action nell'ambito dell'endpoint. Vedere Assegnare autorizzazioni all'identità. |
aad_token non accettato |
Utilizzare aad_token su un endpoint Kubernetes |
Passa a key o aml_token. L'autenticazione del token Microsoft Entra è supportata solo per gli endpoint online gestiti. |
AADSTS700016 o errore di Entra simile |
Risorsa o gruppo di destinatari errato nella richiesta di token | Verificare che il parametro della risorsa corrisponda al tipo di operazione: https://management.azure.com per il piano di controllo, https://ml.azure.com per il piano dati. |
Contenuti correlati
- Autenticazione e autorizzazione per gli endpoint online
- Configurare l'autenticazione per Azure Machine Learning
- Distribuire e assegnare un punteggio a un modello di Machine Learning usando un endpoint online
- Usare REST per distribuire un modello come endpoint online
- Gestire l'accesso a un'area di lavoro di Azure Machine Learning
- Proteggere gli endpoint online gestiti usando l'isolamento di rete