Autenticación de solicitudes en Azure Cognitive ServicesAuthenticate requests to Azure Cognitive Services

Cada solicitud a una instancia de Azure Cognitive Services debe incluir un encabezado de autenticación.Each request to an Azure Cognitive Service must include an authentication header. Este encabezado pasa una clave de suscripción o token de acceso, que se utiliza para validar su suscripción a un servicio o grupo de servicios.This header passes along a subscription key or access token, which is used to validate your subscription for a service or group of services. En este artículo, aprenderá sobre tres maneras de autenticar una solicitud y los requisitos para cada una.In this article, you'll learn about three ways to authenticate a request and the requirements for each.

Requisitos previosPrerequisites

Antes de hacer una solicitud, necesita una cuenta de Azure y una suscripción a Azure Cognitive Services.Before you make a request, you need an Azure account and an Azure Cognitive Services subscription. Si ya tiene una cuenta, siga adelante y vaya a la sección siguiente.If you already have an account, go ahead and skip to the next section. Si no tiene una cuenta, tenemos una guía para que la configure en unos minutos: Creación de una cuenta de Cognitive Services para 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.

Puede obtener la clave de suscripción en Azure Portal después de crear la cuenta.You can get your subscription key from the Azure portal after creating your account.

Encabezados de autenticaciónAuthentication headers

Revisemos rápidamente los encabezados de autenticación disponibles para su uso con Azure Cognitive Services.Let's quickly review the authentication headers available for use with Azure Cognitive Services.

EncabezadoHeader DescripciónDescription
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key Utilice este encabezado para autenticarse con una clave de suscripción para un servicio específico o una clave de suscripción a varios servicios.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 Este encabezado solo es necesario cuando se utiliza una clave de suscripción multiservicio con el servicio de Traductor.This header is only required when using a multi-service subscription key with the Translator service. Utilice este encabezado para especificar la región de la suscripción.Use this header to specify the subscription region.
AuthorizationAuthorization Utilice este encabezado si está usando un token de autenticación.Use this header if you are using an authentication token. En las secciones siguientes se describen los pasos necesarios para realizar un intercambio de tokens.The steps to perform a token exchange are detailed in the following sections. El valor proporcionado sigue este formato: Bearer <TOKEN>.The value provided follows this format: Bearer <TOKEN>.

Autenticación con una clave de suscripción a un servicio únicoAuthenticate with a single-service subscription key

La primera opción es autenticar una solicitud con una clave de suscripción para un servicio específico, como Traductor.The first option is to authenticate a request with a subscription key for a specific service, like Translator. Las claves están disponibles en Azure Portal para cada recurso que se ha creado.The keys are available in the Azure portal for each resource that you've created. Para utilizar una clave de suscripción para autenticar una solicitud, esta se debe pasar como encabezado 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.

En estas solicitudes de ejemplo se muestra cómo utilizar el encabezado Ocp-Apim-Subscription-Key.These sample requests demonstrates how to use the Ocp-Apim-Subscription-Key header. Tenga en cuenta que, cuando utilice este ejemplo, deberá incluir una clave de suscripción válida.Keep in mind, when using this sample you'll need to include a valid subscription key.

Esta es una llamada de ejemplo a Bing Web Search API: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 es una llamada de ejemplo al servicio Traductor: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

En el siguiente vídeo se explica cómo se usa una clave de Cognitive Services.The following video demonstrates using a Cognitive Services key.

Autenticación con una clave de suscripción a varios serviciosAuthenticate with a multi-service subscription key

Advertencia

En este momento, estos servicios no admiten las claves de varios servicios: QnA Maker, servicios de Voz, Custom Vision y Anomaly Detector.At this time, these services don't support multi-service keys: QnA Maker, Speech Services, Custom Vision, and Anomaly Detector.

Esta opción también utiliza una clave de suscripción para autenticar las solicitudes.This option also uses a subscription key to authenticate requests. La principal diferencia es que una clave de suscripción no está asociada a un servicio específico, sino que se puede utilizar una única clave para autenticar solicitudes de varios servicios de Cognitive Services.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. Consulte los precios de Cognitive Services para más información sobre la disponibilidad regional, características admitidas y precios.See Cognitive Services pricing for information about regional availability, supported features, and pricing.

La clave de suscripción se proporciona en cada solicitud como encabezado Ocp-Apim-Subscription-Key.The subscription key is provided in each request as the Ocp-Apim-Subscription-Key header.

Clave de suscripción a varios servicios para Cognitive ServicesMulti-service subscription key demonstration for Cognitive Services

Regiones admitidasSupported regions

Cuando utilice la clave de suscripción a varios servicios para realizar una solicitud a api.cognitive.microsoft.com, debe incluir la región en la dirección 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 ejemplo: westus.api.cognitive.microsoft.com.For example: westus.api.cognitive.microsoft.com.

Cuando utilice la clave de suscripción a varios servicios con Traductor, debe especificar la región de suscripción con el encabezado Ocp-Apim-Subscription-Region.When using multi-service subscription key with the Translator service, you must specify the subscription region with the Ocp-Apim-Subscription-Region header.

Se admite la autenticación de varios servicios en estas regiones:Multi-service authentication is supported in these regions:

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

Solicitudes de ejemploSample requests

Esta es una llamada de ejemplo a Bing Web Search API: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 es una llamada de ejemplo al servicio Traductor: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

Autenticación con un token de autenticaciónAuthenticate with an authentication token

Algunos servicios de Azure Cognitive Services aceptan, y en algunos casos requieren, un token de autenticación.Some Azure Cognitive Services accept, and in some cases require, an authentication token. Actualmente, estos servicios admiten tokens de autenticación:Currently, these services support authentication tokens:

  • Text Translation APIText Translation API
  • Servicios Voz: Speech-to-text REST APISpeech Services: Speech-to-text REST API
  • Servicios Voz: Text-to-speech REST APISpeech Services: Text-to-speech REST API

Nota

QnA Maker también utiliza el encabezado de autorización, pero requiere una clave de punto de conexión.QnA Maker also uses the Authorization header, but requires an endpoint key. Para más información, consulte QnA Maker: Get answer from knowledge base (QnA Maker: Obtención de respuesta de Knowledge Base).For more information, see QnA Maker: Get answer from knowledge base.

Advertencia

Los servicios que admiten los tokens de autenticación pueden cambiar con el tiempo. Consulte la referencia de la API de un servicio antes de utilizar este método de autenticación.The services that support authentication tokens may change over time, please check the API reference for a service before using this authentication method.

Tanto las claves de suscripción de servicio único como las de varios servicios se pueden intercambiar por tokens de autenticación.Both single service and multi-service subscription keys can be exchanged for authentication tokens. Los token de autenticación tienen una validez de 10 minutos.Authentication tokens are valid for 10 minutes.

Los tokens de autenticación se incluyen en una solicitud como encabezado Authorization.Authentication tokens are included in a request as the Authorization header. El valor del token proporcionado debe ir precedido de Bearer, por ejemplo: Bearer YOUR_AUTH_TOKEN.The token value provided must be preceded by Bearer, for example: Bearer YOUR_AUTH_TOKEN.

Solicitudes de ejemploSample requests

Use esta dirección URL para intercambiar una clave de suscripción para un token de autenticación: 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 regiones de varios servicios admiten el intercambio de tokens:These multi-service regions support token exchange:

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

Después de obtener un token de autenticación, deberá pasarlo en cada solicitud como encabezado Authorization.After you get an authentication token, you'll need to pass it in each request as the Authorization header. Esta es una llamada de ejemplo al servicio Traductor: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

Autenticación mediante Azure Active DirectoryAuthenticate with Azure Active Directory

Importante

  1. Actualmente, solo Computer Vision API, Face API, Text Analytics API, Lector inmersivo, Form Recognizer, Anomaly Detector, QnA Maker y todos los servicios de Bing, excepto Bing Custom Search, admiten la autenticación mediante Azure Active Directory (AAD).Currently, only the Computer Vision API, Face API, Text Analytics API, Immersive Reader, Form Recognizer, Anomaly Detector, QnA Maker, and all Bing services except Bing Custom Search support authentication using Azure Active Directory (AAD).
  2. La autenticación con AAD siempre debe usarse junto con el nombre de subdominio personalizado de su recurso de Azure.AAD authentication needs to be always used together with custom subdomain name of your Azure resource. Los puntos de conexión regionales no admiten la autenticación con AAD.Regional endpoints does not support AAD authentication.

En las secciones anteriores, le mostramos cómo realizar la autenticación en Azure Cognitive Services mediante una clave de suscripción de un solo servicio o de varios servicios.In the previous sections, we showed you how to authenticate against Azure Cognitive Services using either a single-service or multi-service subscription key. Aunque estas claves proporcionan un camino rápido y fácil para iniciar el desarrollo, se quedan cortas en escenarios más complejos que requieren control de acceso basados en roles de Azure (RBAC de 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). Echemos un vistazo a lo que se necesita para autenticarse con Azure Active Directory (AAD).Let's take a look at what's required to authenticate using Azure Active Directory (AAD).

En las secciones siguientes, usará el entorno de Azure Cloud Shell o la CLI de Azure para crear un subdominio, asignar roles y obtener un token de portador para llamar a Cognitive Services de 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. Si se bloquea, se proporcionan vínculos en cada sección con todas las opciones disponibles para cada comando de Azure Cloud Shell o la CLI de Azure.If you get stuck, links are provided in each section with all available options for each command in Azure Cloud Shell/Azure CLI.

Creación de un recurso con un subdominio personalizadoCreate a resource with a custom subdomain

El primer paso es crear un subdominio personalizado.The first step is to create a custom subdomain. Si desea usar un recurso de Cognitive Services existente que no tenga un nombre de subdominio personalizado, siga las instrucciones de Subdominios personalizados para Cognitive Services para habilitar el subdominio personalizado para el 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. Para empezar, abra Azure Cloud Shell,Start by opening the Azure Cloud Shell. Después seleccione una suscripción:Then select a subscription:

    Set-AzContext -SubscriptionName <SubscriptionName>
    
  2. A continuación, cree un recurso de Cognitive Services con un subdominio personalizado.Next, create a Cognitive Services resource with a custom subdomain. El nombre del subdominio debe ser único globalmente y no puede incluir caracteres especiales, 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. Si se realiza correctamente, el punto de conexión debe mostrar el nombre de subdominio único del recurso.If successful, the Endpoint should show the subdomain name unique to your resource.

Asignación de un rol a una entidad de servicioAssign a role to a service principal

Ahora que tiene un subdominio personalizado asociado al recurso, deberá asignar un rol a una entidad de servicio.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

Tenga en cuenta que las asignaciones de roles de Azure pueden tardar hasta cinco minutos en propagarse.Keep in mind that Azure role assignments may take up to five minutes to propagate.

  1. En primer lugar, vamos a registrar una aplicación de 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
    

    Va a necesitar el valor de ApplicationID en el paso siguiente.You're going to need the ApplicationId in the next step.

  2. Después, tiene que crear una entidad de servicio para la aplicación de AAD.Next, you need to create a service principal for the AAD application.

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
    

    Nota

    Si registra una aplicación en Azure Portal, este paso se completa automáticamente.If you register an application in the Azure portal, this step is completed for you.

  3. El último paso es asignar el rol "Usuario de Cognitive Services" a la entidad de servicio (en el ámbito del recurso).The last step is to assign the "Cognitive Services User" role to the service principal (scoped to the resource). Mediante la asignación de un rol, concede acceso a la entidad de servicio a este recurso.By assigning a role, you're granting service principal access to this resource. Puede conceder a la misma entidad de servicio acceso a varios recursos de la suscripción.You can grant the same service principal access to multiple resources in your subscription.

    Nota

    Se utiliza el valor de ObjectId de la entidad de servicio, no el valor de ObjectId de la aplicación.The ObjectId of the service principal is used, not the ObjectId for the application. ACCOUNT_ID será el identificador de recurso de Azure de la cuenta de Cognitive Services que ha creado.The ACCOUNT_ID will be the Azure resource Id of the Cognitive Services account you created. Puede encontrar el identificador de recurso de Azure en las "propiedades" del recurso en Azure Portal.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"
    

Solicitud de ejemploSample request

En este ejemplo, se usa una contraseña para autenticar la entidad de servicio.In this sample, a password is used to authenticate the service principal. El token proporcionado se usa para llamar a la API Computer Vision.The token provided is then used to call the Computer Vision API.

  1. Obtenga el TenantId:Get your TenantId:

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

    Nota

    Si está usando Azure Cloud Shell, la clase SecureClientSecret no está disponible.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. Llame a la API Computer Vision: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, la entidad de servicio se puede autenticar con un certificado.Alternatively, the service principal can be authenticated with a certificate. Además de la entidad de servicio, la entidad de seguridad de usuario también se admite si tiene permisos delegados a través de otra aplicación de AAD.Besides service principal, user principal is also supported by having permissions delegated through another AAD application. En este caso, en lugar de contraseñas o certificados, se les pedirá a los usuarios la autenticación en dos fases al adquirir el token.In this case, instead of passwords or certificates, users would be prompted for two-factor authentication when acquiring token.

Autorización para obtener acceso a identidades administradasAuthorize access to managed identities

Cognitive Services admite la autenticación de Azure Active Directory (Azure AD) con identidades administradas para los recursos de Azure.Cognitive Services support Azure Active Directory (Azure AD) authentication with managed identities for Azure resources. Las identidades administradas para recursos de Azure pueden autorizar el acceso a los recursos de Cognitive Services con credenciales de Azure AD desde aplicaciones que se ejecutan en máquinas virtuales (VM) de Azure, aplicaciones de función, conjuntos de escalado de máquinas virtuales y otros servicios.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. Si usa identidades administradas para recursos de Azure junto con autenticación de Azure AD, puede evitar el almacenamiento de credenciales con las aplicaciones que se ejecutan en la nube.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.

Habilitación de identidades administradas en una máquina virtualEnable managed identities on a VM

Para poder usar identidades administradas para recursos de Azure a fin de autorizar el acceso los recursos de Cognitive Services desde la VM, primero debe habilitar las identidades administradas para los recursos de Azure en la 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 aprender a habilitar las identidades administradas para los recursos de Azure, consulte:To learn how to enable managed identities for Azure Resources, see:

Para más información sobre las identidades administradas, consulte Identidades administradas para recursos de Azure.For more information about managed identities, see Managed identities for Azure resources.

Consulte tambiénSee also