Autenticar solicitações para os Serviços Cognitivos do AzureAuthenticate requests to Azure Cognitive Services

Cada solicitação para um Serviço Cognitivo do Azure deve incluir um cabeçalho de autenticação.Each request to an Azure Cognitive Service must include an authentication header. Esse cabeçalho passa uma chave de assinatura ou token de acesso, que é usado para validar sua assinatura em um serviço ou grupo de serviços.This header passes along a subscription key or access token, which is used to validate your subscription for a service or group of services. Neste artigo, você aprenderá três maneiras de autenticar uma solicitação e os requisitos para cada uma.In this article, you'll learn about three ways to authenticate a request and the requirements for each.

Pré-requisitosPrerequisites

Antes de fazer uma solicitação, você precisará de uma conta do Azure e uma assinatura dos Serviços Cognitivos do Azure.Before you make a request, you need an Azure account and an Azure Cognitive Services subscription. Se você já tiver uma conta, pule para a próxima seção.If you already have an account, go ahead and skip to the next section. Se você não tiver uma conta, temos um guia para configurá-lo em minutos: criar uma conta de serviços cognitivas para o 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.

Você pode obter sua chave de assinatura do portal do Azure depois de criar sua conta.You can get your subscription key from the Azure portal after creating your account.

Cabeçalhos de autenticaçãoAuthentication headers

Vamos analisar rapidamente os cabeçalhos de autenticação disponíveis para uso com os Serviços Cognitivos do Azure.Let's quickly review the authentication headers available for use with Azure Cognitive Services.

CabeçalhoHeader DescriçãoDescription
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key Use esse cabeçalho para autenticar com uma chave de assinatura para um serviço específico ou uma chave de assinatura para vários serviços.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 Esse cabeçalho só é necessário ao usar uma chave de assinatura de vários serviços com o serviço do tradutor.This header is only required when using a multi-service subscription key with the Translator service. Use esse cabeçalho para especificar a região da assinatura.Use this header to specify the subscription region.
AutorizaçãoAuthorization Use esse cabeçalho se você está usando um token de autenticação.Use this header if you are using an authentication token. As etapas para executar uma troca de tokens estão detalhadas nas seções a seguir.The steps to perform a token exchange are detailed in the following sections. O valor fornecido segue este formato: Bearer <TOKEN>.The value provided follows this format: Bearer <TOKEN>.

Autenticar com uma chave de assinatura para um único serviçoAuthenticate with a single-service subscription key

A primeira opção é autenticar uma solicitação com uma chave de assinatura para um serviço específico, como o tradutor.The first option is to authenticate a request with a subscription key for a specific service, like Translator. As chaves estão disponíveis no portal do Azure para cada recurso que você criou.The keys are available in the Azure portal for each resource that you've created. Para usar uma chave de assinatura e autenticar uma solicitação, ela deve ser transmitida como o cabeçalho 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.

Essas solicitações de exemplo demonstram como usar o cabeçalho Ocp-Apim-Subscription-Key.These sample requests demonstrates how to use the Ocp-Apim-Subscription-Key header. Tenha em mente, ao usar este exemplo, que você precisará incluir uma chave de assinatura válida.Keep in mind, when using this sample you'll need to include a valid subscription key.

Isso é um exemplo de chamada à API de Pesquisa na Web do 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

Esta é uma chamada de exemplo para o serviço do Tradutor:This is a sample call to the Translator service:

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

O vídeo a seguir demonstra como usar uma chave dos Serviços Cognitivos.The following video demonstrates using a Cognitive Services key.

Autenticar com uma chave de assinatura para vários serviçosAuthenticate with a multi-service subscription key

Aviso

Neste momento, esses serviços não dão suporte a chaves de vários serviços: QnA Maker, serviços de fala, visão personalizada e detector de anomalias.At this time, these services don't support multi-service keys: QnA Maker, Speech Services, Custom Vision, and Anomaly Detector.

Essa opção também usa uma chave de assinatura para autenticar solicitações.This option also uses a subscription key to authenticate requests. A principal diferença é que uma chave de assinatura não está vinculada a um serviço específico; na verdade, uma mesma chave pode ser usada para autenticar solicitações para vários Serviços Cognitivos.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. Confira Preço dos Serviços Cognitivos para obter informações sobre disponibilidade regional, recursos com suporte e preços.See Cognitive Services pricing for information about regional availability, supported features, and pricing.

A chave de assinatura é fornecida em cada solicitação como o cabeçalho Ocp-Apim-Subscription-Key.The subscription key is provided in each request as the Ocp-Apim-Subscription-Key header.

Demonstração da chave de assinatura de vários serviços para serviços cognitivasMulti-service subscription key demonstration for Cognitive Services

Regiões com suporteSupported regions

Quando usar a chave de assinatura de vários serviços a fim de fazer uma solicitação para api.cognitive.microsoft.com, você deve incluir a região na 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. Por exemplo: westus.api.cognitive.microsoft.com.For example: westus.api.cognitive.microsoft.com.

Ao usar a chave de assinatura de vários serviços com o serviço do tradutor, você deve especificar a região da assinatura com o Ocp-Apim-Subscription-Region cabeçalho.When using multi-service subscription key with the Translator service, you must specify the subscription region with the Ocp-Apim-Subscription-Region header.

A autenticação de vários serviços tem suporte nestas regiões:Multi-service authentication is supported in these regions:

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

Solicitações de exemploSample requests

Isso é um exemplo de chamada à API de Pesquisa na Web do 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

Esta é uma chamada de exemplo para o serviço do Tradutor:This is a sample call to the Translator service:

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

Autenticar com um token de autenticaçãoAuthenticate with an authentication token

Alguns Serviços Cognitivos do Azure aceitam (e, em alguns casos, exigem) um token de autenticação.Some Azure Cognitive Services accept, and in some cases require, an authentication token. Atualmente, estes serviços dão suporte a tokens de autenticação:Currently, these services support authentication tokens:

  • API de Tradução de TextoText Translation API
  • Serviços de fala: API REST de fala em textoSpeech Services: Speech-to-text REST API
  • Serviços de fala: API REST de conversão de texto em falaSpeech Services: Text-to-speech REST API

Observação

O QnA Maker também usa o cabeçalho Authorization, mas requer uma chave de ponto de extremidade.QnA Maker also uses the Authorization header, but requires an endpoint key. Para obter mais informações, consulte QnA Maker: obter resposta da base de dados de conhecimento.For more information, see QnA Maker: Get answer from knowledge base.

Aviso

Os serviços que dão suporte a tokens de autenticação podem mudar ao longo do tempo; confira a referência de API do serviço antes de usar esse método de autenticação.The services that support authentication tokens may change over time, please check the API reference for a service before using this authentication method.

Tanto as chaves de assinatura para um único serviço quanto a para vários serviços podem ser trocadas por tokens de autenticação.Both single service and multi-service subscription keys can be exchanged for authentication tokens. Os tokens de autenticação são válidos por 10 minutos.Authentication tokens are valid for 10 minutes.

Os tokens de autenticação são incluídos em uma solicitação como o cabeçalho Authorization.Authentication tokens are included in a request as the Authorization header. O valor do token fornecido deve ser precedido por Bearer, por exemplo, Bearer YOUR_AUTH_TOKEN.The token value provided must be preceded by Bearer, for example: Bearer YOUR_AUTH_TOKEN.

Solicitações de exemploSample requests

Use esta URL para trocar uma chave de assinatura por um token de autenticação: 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"

Estas regiões de vários serviços dão suporte à troca de tokens:These multi-service regions support token exchange:

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

Depois de obter um token de autenticação, você precisará transmiti-lo em cada solicitação como o cabeçalho Authorization.After you get an authentication token, you'll need to pass it in each request as the Authorization header. Esta é uma chamada de exemplo para o serviço do Tradutor:This is a sample call to the Translator service:

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

Autenticar com o Azure Active DirectoryAuthenticate with Azure Active Directory

Importante

  1. Atualmente, somente o API da Pesquisa Visual Computacional, API de Detecção Facial, API de análise de texto, leitor de imersão, reconhecedor de formulário, detector de anomalias e todos os serviços do Bing, exceto pesquisa personalizada do Bing dar suporte à autenticação usando o Azure Active Directory (AAD).Currently, only the Computer Vision API, Face API, Text Analytics API, Immersive Reader, Form Recognizer, Anomaly Detector, and all Bing services except Bing Custom Search support authentication using Azure Active Directory (AAD).
  2. A autenticação do AAD precisa ser sempre usada junto com o nome de subdomínio personalizado do recurso do Azure.AAD authentication needs to be always used together with custom subdomain name of your Azure resource. Os pontos de extremidade regionais não dão suporte à autenticação do AAD.Regional endpoints does not support AAD authentication.

Nas seções anteriores, mostramos como se autenticar nos serviços cognitivas do Azure usando uma chave de assinatura de serviço único ou de vários serviços.In the previous sections, we showed you how to authenticate against Azure Cognitive Services using either a single-service or multi-service subscription key. Embora essas chaves forneçam um caminho rápido e fácil para iniciar o desenvolvimento, elas ficam curtas em cenários mais complexos que exigem o controle de acesso baseado em função do Azure (RBAC do Azure).While these keys provide a quick and easy path to start development, they fall short in more complex scenarios that require Azure role-based access control (Azure RBAC). Vamos dar uma olhada no que é necessário para autenticar usando o Azure Active Directory (AAD).Let's take a look at what's required to authenticate using Azure Active Directory (AAD).

Nas seções a seguir, você usará o ambiente de Azure Cloud Shell ou o CLI do Azure para criar um subdomínio, atribuir funções e obter um token de portador para chamar os serviços cognitivas do 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 você ficar preso, os links serão fornecidos em cada seção com todas as opções disponíveis para cada comando no Azure Cloud Shell/CLI do Azure.If you get stuck, links are provided in each section with all available options for each command in Azure Cloud Shell/Azure CLI.

Criar um recurso com um subdomínio personalizadoCreate a resource with a custom subdomain

A primeira etapa é criar um subdomínio personalizado.The first step is to create a custom subdomain. Se você quiser usar um recurso de serviços cognitivas existente que não tem um nome de subdomínio personalizado, siga as instruções em subdomínios personalizados de serviços cognitivas para habilitar o subdomínio personalizado para seu recurso.If you want to use an existing Cognitive Services resource which does not have custom subdomain name, follow the instructions in Cognitive Services Custom Subdomains to enable custom subdomain for your resource.

  1. Comece abrindo a Azure Cloud Shell.Start by opening the Azure Cloud Shell. Em seguida, Selecione uma assinatura:Then select a subscription:

    Set-AzContext -SubscriptionName <SubscriptionName>
    
  2. Em seguida, crie um recurso de serviços cognitivas com um subdomínio personalizado.Next, create a Cognitive Services resource with a custom subdomain. O nome do subdomínio precisa ser globalmente exclusivo e não pode incluir caracteres especiais, como: ".", "!", ",".The subdomain name needs to be globally unique and cannot include special characters, such as: ".", "!", ",".

    $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
    
  3. Se for bem-sucedido, o ponto de extremidade deverá mostrar o nome do subdomínio exclusivo para seu recurso.If successful, the Endpoint should show the subdomain name unique to your resource.

Atribuir uma função a uma entidade de serviçoAssign a role to a service principal

Agora que você tem um subdomínio personalizado associado ao recurso, será necessário atribuir uma função a uma entidade de serviço.Now that you have a custom subdomain associated with your resource, you're going to need to assign a role to a service principal.

Observação

Tenha em mente que as atribuições de função do Azure podem levar até cinco minutos para serem propagadas.Keep in mind that Azure role assignments may take up to five minutes to propagate.

  1. Primeiro, vamos registrar um aplicativo do AAD.First, let's register an AAD application.

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

    Você precisará do ApplicationId na próxima etapa.You're going to need the ApplicationId in the next step.

  2. Em seguida, você precisa criar uma entidade de serviço para o aplicativo do AAD.Next, you need to create a service principal for the AAD application.

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
    

    Observação

    Se você registrar um aplicativo no portal do Azure, essa etapa será concluída para você.If you register an application in the Azure portal, this step is completed for you.

  3. A última etapa é atribuir a função "usuário de serviços cognitivas" à entidade de serviço (com escopo para o recurso).The last step is to assign the "Cognitive Services User" role to the service principal (scoped to the resource). Ao atribuir uma função, você está concedendo acesso de entidade de serviço a esse recurso.By assigning a role, you're granting service principal access to this resource. Você pode conceder o mesmo acesso de entidade de serviço a vários recursos em sua assinatura.You can grant the same service principal access to multiple resources in your subscription.

    Observação

    O ObjectId da entidade de serviço é usado, não o ObjectId do aplicativo.The ObjectId of the service principal is used, not the ObjectId for the application. O ACCOUNT_ID será a ID de recurso do Azure da conta de serviços cognitivas que você criou.The ACCOUNT_ID will be the Azure resource Id of the Cognitive Services account you created. Você pode encontrar a ID de recurso do Azure de "Propriedades" do recurso em portal do 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"
    

Solicitação de exemploSample request

Neste exemplo, uma senha é usada para autenticar a entidade de serviço.In this sample, a password is used to authenticate the service principal. O token fornecido é usado para chamar o API da Pesquisa Visual Computacional.The token provided is then used to call the Computer Vision API.

  1. Obtenha sua tenantid:Get your TenantId:

    $context=Get-AzContext
    $context.Tenant.Id
    
  2. Obter um token:Get a token:

    Observação

    Se você estiver usando Azure Cloud Shell, a SecureClientSecret classe não estará disponível.If you're using Azure Cloud Shell, the SecureClientSecret class isn't available.

    $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
    

  1. Chame o API da Pesquisa Visual Computacional: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
    

Como alternativa, a entidade de serviço pode ser autenticada com um certificado.Alternatively, the service principal can be authenticated with a certificate. Além da entidade de serviço, a entidade de usuário também tem suporte ao ter permissões delegadas por meio de outro aplicativo do AAD.Besides service principal, user principal is also supported by having permissions delegated through another AAD application. Nesse caso, em vez de senhas ou certificados, os usuários devem solicitar a autenticação de dois fatores ao adquirir o token.In this case, instead of passwords or certificates, users would be prompted for two-factor authentication when acquiring token.

Autorizar o acesso a identidades gerenciadasAuthorize access to managed identities

Os serviços cognitivas dão suporte à autenticação Azure Active Directory (Azure AD) com identidades gerenciadas para recursos do Azure.Cognitive Services support Azure Active Directory (Azure AD) authentication with managed identities for Azure resources. Identidades gerenciadas para recursos do Azure podem autorizar o acesso a recursos de serviços cognitivas usando as credenciais do Azure AD de aplicativos em execução em VMs (máquinas virtuais) do Azure, aplicativos de funções, conjuntos de dimensionamento de máquinas virtuais e outros serviços.Managed identities for Azure resources can authorize access to Cognitive Services resources using Azure AD credentials from applications running in Azure virtual machines (VMs), function apps, virtual machine scale sets, and other services. Usando identidades gerenciadas para recursos do Azure junto com a autenticação do Azure AD, você pode evitar o armazenamento de credenciais com seus aplicativos que são executados na nuvem.By using managed identities for Azure resources together with Azure AD authentication, you can avoid storing credentials with your applications that run in the cloud.

Habilitar identidades gerenciadas em uma VMEnable managed identities on a VM

Antes de poder usar identidades gerenciadas para recursos do Azure para autorizar o acesso a recursos de serviços cognitivas de sua VM, você deve habilitar identidades gerenciadas para recursos do Azure na VM.Before you can use managed identities for Azure resources to authorize access to Cognitive Services resources from your VM, you must enable managed identities for Azure resources on the VM. Para saber como habilitar identidades gerenciadas para recursos do Azure, consulte:To learn how to enable managed identities for Azure Resources, see:

Para obter mais informações sobre identidades gerenciadas, consulte identidades gerenciadas para recursos do Azure.For more information about managed identities, see Managed identities for Azure resources.

Confira tambémSee also