Autenticare le richieste a Servizi cognitivi di AzureAuthenticate requests to Azure Cognitive Services

Ogni richiesta a un servizio di Servizi cognitivi di Azure deve includere un'intestazione di autenticazione.Each request to an Azure Cognitive Service must include an authentication header. Questa intestazione viene passata insieme a una chiave di sottoscrizione o un token di connessione, che viene usato per convalidare la sottoscrizione a un servizio o un gruppo di servizi.This header passes along a subscription key or access token, which is used to validate your subscription for a service or group of services. Questo articolo descrive i tre modi di autenticare una richiesta e i requisiti per ciascun modo.In this article, you'll learn about three ways to authenticate a request and the requirements for each.

PrerequisitiPrerequisites

Per poter effettuare una richiesta, è necessario disporre di un account Azure e di una sottoscrizione di Servizi cognitivi di Azure.Before you make a request, you need an Azure account and an Azure Cognitive Services subscription. Se si dispone già di un account, passare direttamente alla sezione successiva.If you already have an account, go ahead and skip to the next section. Se non si dispone dell'account, seguire le indicazioni per crearne uno in pochi minuti: Creare un account Servizi cognitivi di Azure.If you don't have an account, we have a guide to get you set up in minutes: Create a Cognitive Services account for Azure.

È possibile ottenere la chiave di sottoscrizione dalla portale di Azure dopo la creazione dell'account o l'attivazione di una versione di valutazione gratuita.You can get your subscription key from the Azure portal after creating your account, or activating a free trial.

Intestazioni di autenticazioneAuthentication headers

È opportuno esaminare rapidamente le intestazioni di autenticazione disponibili per l'uso con Servizi cognitivi di Azure.Let's quickly review the authentication headers available for use with Azure Cognitive Services.

IntestazioneHeader DESCRIZIONEDescription
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key Usare questa intestazione per eseguire l'autenticazione con una chiave di sottoscrizione per un servizio specifico o una chiave di sottoscrizione multiservizio.Use this header to authenticate with a subscription key for a specific service or a multi-service subscription key.
Ocp-Apim-Subscription-RegionOcp-Apim-Subscription-Region Questa intestazione è richiesta solo quando si usa una chiave di sottoscrizione multiservizio con l'API Traduzione testuale.This header is only required when using a multi-service subscription key with the Translator Text API. Usare questa intestazione per specificare l'area di sottoscrizione.Use this header to specify the subscription region.
AuthorizationAuthorization Usare questa intestazione se si usa un token di autenticazione.Use this header if you are using an authentication token. Le sezioni seguenti descrivono in dettaglio i passaggi per eseguire uno scambio di token.The steps to perform a token exchange are detailed in the following sections. Il valore specificato segue questo formato: Bearer <TOKEN>.The value provided follows this format: Bearer <TOKEN>.

Eseguire l'autenticazione con una chiave di sottoscrizione a servizio singoloAuthenticate with a single-service subscription key

La prima opzione consiste nell'autenticare una richiesta con una chiave di sottoscrizione per un servizio specifico, ad esempio Traduzione testuale.The first option is to authenticate a request with a subscription key for a specific service, like Translator Text. Le chiavi sono disponibili nel portale di Azure per ogni risorsa creata.The keys are available in the Azure portal for each resource that you've created. Per usare una chiave di sottoscrizione per autenticare una richiesta, la chiave deve essere passata insieme all'intestazione Ocp-Apim-Subscription-Key.To use a subscription key to authenticate a request, it must be passed along as the Ocp-Apim-Subscription-Key header.

Queste richieste di esempio mostrano come usare l'intestazione Ocp-Apim-Subscription-Key.These sample requests demonstrates how to use the Ocp-Apim-Subscription-Key header. Tenere presente che quando si usa questo esempio è necessario includere una chiave di sottoscrizione valida.Keep in mind, when using this sample you'll need to include a valid subscription key.

Questa è una chiamata di esempio per l'API Ricerca Web Bing:This is a sample call to the Bing Web Search API:

curl -X GET 'https://api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

Questa è una chiamata di esempio per l'API Traduzione testuale:This is a sample call to the Translator Text API:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Il video seguente illustra l'uso di una chiave di Servizi cognitivi.The following video demonstrates using a Cognitive Services key.

Eseguire l'autenticazione con una chiave di sottoscrizione multiservizioAuthenticate with a multi-service subscription key

Avviso

Attualmente questi servizi non supportano le chiavi multiservizio: QnA Maker, servizi vocali, Visione personalizzata e rilevamento anomalie.At this time, these services don't support multi-service keys: QnA Maker, Speech Services, Custom Vision, and Anomaly Detector.

Questa opzione usa anche una chiave di sottoscrizione per autenticare le richieste.This option also uses a subscription key to authenticate requests. La differenza principale è che una chiave di sottoscrizione non è associata a un servizio specifico. Una singola chiave può infatti essere usata per autenticare le richieste per più servizi cognitivi.The main difference is that a subscription key is not tied to a specific service, rather, a single key can be used to authenticate requests for multiple Cognitive Services. Per informazioni sulla disponibilità regionale, le funzionalità supportate e i prezzi, vedere Prezzi di Servizi cognitivi.See Cognitive Services pricing for information about regional availability, supported features, and pricing.

La chiave di sottoscrizione viene specificata in ogni richiesta come intestazione Ocp-Apim-Subscription-Key.The subscription key is provided in each request as the Ocp-Apim-Subscription-Key header.

Dimostrazione d'uso della chiave di sottoscrizione multiservizio per Servizi cognitiviMulti-service subscription key demonstration for Cognitive Services

Aree supportateSupported regions

Quando si usa la chiave di sottoscrizione multiservizio per effettuare una richiesta a api.cognitive.microsoft.com, è necessario includere l'area nell'URL.When using the multi-service subscription key to make a request to api.cognitive.microsoft.com, you must include the region in the URL. Ad esempio: westus.api.cognitive.microsoft.com.For example: westus.api.cognitive.microsoft.com.

Quando si usa la chiave di sottoscrizione multiservizio con l'API Traduzione testuale, è necessario specificare l'area di sottoscrizione con l'intestazione Ocp-Apim-Subscription-Region.When using multi-service subscription key with the Translator Text API, you must specify the subscription region with the Ocp-Apim-Subscription-Region header.

L'autenticazione multiservizio è supportata nelle aree seguenti:Multi-service authentication is supported in these regions:

australiaeast brazilsouth canadacentral
centralindia eastasia eastus
japaneast northeurope southcentralus
southeastasia uksouth westcentralus
westeurope westus westus2

Richieste di esempioSample requests

Questa è una chiamata di esempio per l'API Ricerca Web Bing:This is a sample call to the Bing Web Search API:

curl -X GET 'https://YOUR-REGION.api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

Questa è una chiamata di esempio per l'API Traduzione testuale:This is a sample call to the Translator Text API:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Ocp-Apim-Subscription-Region: YOUR_SUBSCRIPTION_REGION' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Eseguire l'autenticazione con un token di autenticazioneAuthenticate with an authentication token

Alcuni Servizi cognitivi di Azure accettano e in alcuni casi richiedono un token di autenticazione.Some Azure Cognitive Services accept, and in some cases require, an authentication token. Questi servizi attualmente supportano i token di autenticazione:Currently, these services support authentication tokens:

  • API Traduzione testualeText Translation API
  • Servizi Voce: API REST di riconoscimento vocaleSpeech Services: Speech-to-text REST API
  • Servizi Voce: API REST di sintesi vocaleSpeech Services: Text-to-speech REST API

Nota

Anche QnA Maker usa l'intestazione di autorizzazione, ma richiede una chiave di endpoint.QnA Maker also uses the Authorization header, but requires an endpoint key. Per altre informazioni, vedere QnA Maker: Ottenere risposte da una knowledge base.For more information, see QnA Maker: Get answer from knowledge base.

Avviso

I servizi che supportano i token di autenticazione possono cambiare nel tempo. Controllare l'API di riferimento per un servizio prima di usare questo metodo di autenticazione.The services that support authentication tokens may change over time, please check the API reference for a service before using this authentication method.

Entrambe le chiavi di sottoscrizione per servizio singolo e multiservizio possono essere scambiate come token di autenticazione.Both single service and multi-service subscription keys can be exchanged for authentication tokens. La validità di un token di autenticazione è di 10 minuti.Authentication tokens are valid for 10 minutes.

I token di autenticazione vengono inclusi in una richiesta come intestazione Authorization.Authentication tokens are included in a request as the Authorization header. Il valore del token specificato deve essere preceduto da Bearer, ad esempio: Bearer YOUR_AUTH_TOKEN.The token value provided must be preceded by Bearer, for example: Bearer YOUR_AUTH_TOKEN.

Richieste di esempioSample requests

Usare questo URL per scambiare una chiave di sottoscrizione con un token di autenticazione: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken.Use this URL to exchange a subscription key for an authentication token: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken.

curl -v -X POST \
"https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Queste aree multiservizio supportano lo scambio del token:These multi-service regions support token exchange:

australiaeast brazilsouth canadacentral
centralindia eastasia eastus
japaneast northeurope southcentralus
southeastasia uksouth westcentralus
westeurope westus westus2

Dopo avere ottenuto un token di autenticazione, è necessario passarlo in ogni richiesta come intestazione Authorization.After you get an authentication token, you'll need to pass it in each request as the Authorization header. Questa è una chiamata di esempio per l'API Traduzione testuale:This is a sample call to the Translator Text API:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Eseguire l'autenticazione con Azure Active DirectoryAuthenticate with Azure Active Directory

Importante

Attualmente, solo le API Visione artificiale, API Viso, API analisi del testo e il lettore immersivo supportano l'autenticazione tramite Azure Active Directory (AAD).Currently, only the Computer Vision API, Face API, Text Analytics API, and Immersive Reader support authentication using Azure Active Directory (AAD).

Nelle sezioni precedenti è stato illustrato come eseguire l'autenticazione in Servizi cognitivi di Azure usando una chiave di sottoscrizione a servizio singolo o multiservizio.In the previous sections, we showed you how to authenticate against Azure Cognitive Services using either a single-service or multi-service subscription key. Sebbene queste chiavi forniscano un percorso rapido e semplice per iniziare lo sviluppo, si riferiscono a scenari più complessi che richiedono controlli degli accessi in base al ruolo.While these keys provide a quick and easy path to start development, they fall short in more complex scenarios that require role-based access controls. Verranno ora esaminati gli elementi necessari per l'autenticazione con Azure Active Directory (AAD).Let's take a look at what's required to authenticate using Azure Active Directory (AAD).

Nelle sezioni seguenti verrà usato l'ambiente Azure Cloud Shell o l'interfaccia della riga di comando di Azure per creare un sottodominio, assegnare i ruoli e ottenere un bearer token per chiamare i servizi cognitivi di Azure.In the following sections, you'll use either the Azure Cloud Shell environment or the Azure CLI to create a subdomain, assign roles, and obtain a bearer token to call the Azure Cognitive Services. Se ci si blocca, i collegamenti vengono forniti in ogni sezione con tutte le opzioni disponibili per ogni comando nell'interfaccia della riga di comando Azure Cloud Shell/Azure.If you get stuck, links are provided in each section with all available options for each command in Azure Cloud Shell/Azure CLI.

Creare una risorsa con un sottodominio personalizzatoCreate a resource with a custom subdomain

Il primo passaggio consiste nel creare un sottodominio personalizzato.The first step is to create a custom subdomain.

  1. Per iniziare, aprire il Azure Cloud Shell.Start by opening the Azure Cloud Shell. selezionare quindi una sottoscrizione:then select a subscription:

    Select-AzureSubscription -SubscriptionName <YOUR_SUBCRIPTION>
    
  2. Successivamente, creare una risorsa Servizi cognitivi con un sottodominio personalizzato.Next, create a Cognitive Services resource with a custom subdomain. Il nome del sottodominio deve essere globalmente univoco e non può includere caratteri speciali, ad esempio: ".", "!", ",".The subdomain name needs to be globally unique and cannot include special characters, such as: ".", "!", ",".

    New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
    
  3. In caso di esito positivo, l' endpoint dovrebbe mostrare il nome del sottodominio univoco per la risorsa.If successful, the Endpoint should show the subdomain name unique to your resource.

Assegnare un ruolo a un'entità servizioAssign a role to a service principal

Ora che è stato associato un sottodominio personalizzato alla risorsa, sarà necessario assegnare un ruolo a un'entità servizio.Now that you have a custom subdomain associated with your resource, you're going to need to assign a role to a service principal.

Nota

Tenere presente che le assegnazioni di ruolo AAD possono richiedere fino a cinque minuti per la propagazione.Keep in mind that AAD role assignments may take up to five minutes to propagate.

  1. Prima di tutto, registrare un' applicazione AAD.First, let's register an AAD application.

    $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force
    
    New-AzADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -Password $SecureStringPassword
    

    Il ApplicationID sarà necessario nel passaggio successivo.You're going to need the ApplicationId in the next step.

  2. Successivamente, è necessario creare un'entità servizio per l'applicazione AAD.Next, you need to create a service principal for the AAD application.

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
    

    Nota

    Se si registra un'applicazione nel portale di Azure, questo passaggio viene completato.If you register an application in the Azure portal, this step is completed for you.

  3. L'ultimo passaggio consiste nell' assegnare il ruolo "utente servizi cognitivi" all'entità servizio (ambito della risorsa).The last step is to assign the "Cognitive Services User" role to the service principal (scoped to the resource). Assegnando un ruolo, si concede all'entità servizio l'accesso a questa risorsa.By assigning a role, you're granting service principal access to this resource. È possibile concedere all'entità servizio l'accesso a più risorse nella sottoscrizione.You can grant the same service principal access to multiple resources in your subscription.

    Nota

    Viene usato il valore ObjectId dell'entità servizio, non il valore ObjectId per l'applicazione.The ObjectId of the service principal is used, not the ObjectId for the application. ACCOUNT_ID sarà l'ID risorsa di Azure dell'account di servizi cognitivi creato.The ACCOUNT_ID will be the Azure resource Id of the Cognitive Services account you created. È possibile trovare l'ID risorsa di Azure da "Properties" della risorsa in portale di Azure.You can find Azure resource Id from "properties" of the resource in Azure portal.

    New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
    

Richiesta di esempioSample request

In questo esempio viene usata una password per autenticare l'entità servizio.In this sample, a password is used to authenticate the service principal. Il token fornito viene quindi utilizzato per chiamare il API Visione artificiale.The token provided is then used to call the Computer Vision API.

  1. Ottenere il TenantId:Get your TenantId:

    $context=Get-AzContext
    $context.Tenant.Id
    
  2. Ottenere un token:Get a token:

    $authContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList "https://login.windows.net/<TENANT_ID>"
    $secureSecretObject = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.SecureClientSecret" -ArgumentList $SecureStringPassword   
    $clientCredential = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential" -ArgumentList $app.ApplicationId, $secureSecretObject
    $token=$authContext.AcquireTokenAsync("https://cognitiveservices.azure.com/", $clientCredential).Result
    $token
    
  3. Chiamare la API Visione artificiale:Call the Computer Vision API:

    $url = $account.Endpoint+"vision/v1.0/models"
    $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"=$token.CreateAuthorizationHeader()} -Verbose
    $result | ConvertTo-Json
    

In alternativa, l'entità servizio può essere autenticata con un certificato.Alternatively, the service principal can be authenticated with a certificate. Oltre all'entità servizio, l'entità utente è supportata anche con le autorizzazioni delegate tramite un'altra applicazione di AAD.Besides service principal, user principal is also supported by having permissions delegated through another AAD application. In questo caso, anziché le password o i certificati, agli utenti viene richiesto di eseguire l'autenticazione a due fattori durante l'acquisizione del token.In this case, instead of passwords or certificates, users would be prompted for two-factor authentication when acquiring token.

Vedere ancheSee also