Autenticar solicitações para serviços de IA do Azure

Cada solicitação para um serviço de IA do Azure deve incluir um cabeçalho de autenticação. Esse cabeçalho passa uma chave de recurso ou token de autenticação, que é usado para validar sua assinatura de um serviço ou grupo de serviços. Neste artigo, você aprenderá sobre três maneiras de autenticar uma solicitação e os requisitos para cada uma.

• Autenticar com uma chave de recurso de serviço único ou multisserviço
• Autenticar com um token
• Autenticar com o Microsoft Entra ID

Pré-requisitos

Antes de fazer uma solicitação, você precisa de uma conta do Azure e uma assinatura de serviços de IA do Azure. Se você já tiver uma conta, vá em frente e pule para a próxima seção. Se você não tiver uma conta, temos um guia para configurá-lo em minutos: Criar um recurso multisserviço.

Você pode obter sua chave de recurso do portal do Azure depois de criar sua conta.

Cabeçalhos de autenticação

Vamos analisar rapidamente os cabeçalhos de autenticação disponíveis para uso com os serviços de IA do Azure.

Cabeçalho	Description
Ocp-Apim-Subscription-Key	Use este cabeçalho para autenticar com uma chave de recurso para um serviço específico ou uma chave de recurso multisserviço.
OCP-Apim-Assinatura-Região	Esse cabeçalho só é necessário ao usar uma chave de recurso multisserviço com o serviço Translator. Use este cabeçalho para especificar a região de recurso.
Autorização	Use este cabeçalho se estiver usando um token de acesso. As etapas para executar uma troca de token são detalhadas nas seções a seguir. O valor fornecido segue este formato: Bearer <TOKEN>.

Autenticar com uma chave de recurso de serviço único

A primeira opção é autenticar uma solicitação com uma chave de recurso para um serviço específico, como o Translator. As chaves estão disponíveis no portal do Azure para cada recurso que você criou. Para usar uma chave de recurso para autenticar uma solicitação, ela deve ser passada como o Ocp-Apim-Subscription-Key cabeçalho.

Essas solicitações de exemplo demonstram como usar o Ocp-Apim-Subscription-Key cabeçalho. Tenha em mente que, ao usar este exemplo, você precisará incluir uma chave de recurso válida.

Esta é uma chamada de exemplo para o serviço Tradutor:

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 o uso de uma chave de serviços de IA do Azure.

Autenticar com uma chave de recurso multisserviço

Você pode usar uma chave de recurso multisserviço para autenticar solicitações. A principal diferença é que a chave de recurso multisserviço não está vinculada a um serviço específico, em vez disso, uma única chave pode ser usada para autenticar solicitações para vários serviços de IA do Azure. Consulte Preços dos serviços de IA do Azure para obter informações sobre disponibilidade regional, recursos suportados e preços.

A chave de recurso é fornecida em cada solicitação como o Ocp-Apim-Subscription-Key cabeçalho.

Regiões suportadas

Ao usar a chave de recurso multisserviço para fazer uma solicitação ao api.cognitive.microsoft.com, você deve incluir a região na URL. Por exemplo: westus.api.cognitive.microsoft.com.

Ao usar uma chave de recurso multisserviço com o Azure AI Translator, você deve especificar a região de recurso com o Ocp-Apim-Subscription-Region cabeçalho.

A autenticação multisserviço é suportada nestas regiões:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2
• francecentral
• koreacentral
• northcentralus
• southafricanorth
• uaenorth
• switzerlandnorth

Pedidos de amostra

Esta é uma chamada de exemplo para o serviço Tradutor:

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 acesso

Alguns serviços de IA do Azure aceitam, e em alguns casos exigem, um token de acesso. Atualmente, esses serviços oferecem suporte a tokens de acesso:

• API de Tradução de Texto
• Serviços de fala: API de fala para texto
• Serviços de fala: API de conversão de texto em fala

Nota

O QnA Maker também usa o cabeçalho Autorização, mas requer uma chave de ponto de extremidade. Para obter mais informações, consulte QnA Maker: Obter resposta da base de dados de conhecimento.

Aviso

Os serviços que suportam tokens de acesso podem mudar ao longo do tempo, verifique a referência da API para um serviço antes de usar esse método de autenticação.

As chaves de recurso de serviço único e multisserviço podem ser trocadas por tokens de autenticação. Os tokens de autenticação são válidos por 10 minutos. Eles são armazenados no formato JSON Web Token (JWT) e podem ser consultados programaticamente usando as bibliotecas JWT.

Os tokens de acesso são incluídos em uma solicitação como cabeçalho Authorization . O valor do token fornecido deve ser precedido por , por Bearerexemplo: Bearer YOUR_AUTH_TOKEN.

Pedidos de amostra

Use este URL para trocar uma chave de recurso por um token de acesso: 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 multisserviço suportam troca de tokens:

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

Depois de obter um token de acesso, você precisará passá-lo em cada solicitação como cabeçalho Authorization . Esta é uma chamada de exemplo para o serviço Tradutor:

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 Microsoft Entra ID

Importante

A autenticação do Microsoft Entra sempre precisa ser usada junto com o nome de subdomínio personalizado do seu recurso do Azure. Os pontos de extremidade regionais não oferecem suporte à autenticação do Microsoft Entra.

Nas seções anteriores, mostramos como autenticar em serviços de IA do Azure usando uma chave de assinatura de serviço único ou multisserviço. Embora essas chaves forneçam um caminho rápido e fácil para iniciar o desenvolvimento, elas ficam aquém em cenários mais complexos que exigem o controle de acesso baseado em função do Azure (Azure RBAC). Vamos dar uma olhada no que é necessário para autenticar usando o Microsoft Entra ID.

Nas seções a seguir, você usará o ambiente do Azure Cloud Shell ou a CLI do Azure para criar um subdomínio, atribuir funções e obter um token de portador para chamar os serviços de IA do Azure. Se você ficar preso, os links são fornecidos em cada seção com todas as opções disponíveis para cada comando no Azure Cloud Shell/CLI do Azure.

Importante

Se a sua organização estiver a fazer autenticação através do Microsoft Entra ID, deve desativar a autenticação local (autenticação com chaves) para que os utilizadores na organização utilizem sempre o Microsoft Entra ID.

Criar um recurso com um subdomínio personalizado

O primeiro passo é criar um subdomínio personalizado. Se você quiser usar um recurso de serviços de IA do Azure existente que não tenha nome de subdomínio personalizado, siga as instruções em Subdomínios personalizados de serviços de IA do Azure para habilitar o subdomínio personalizado para seu recurso.

1. Comece abrindo o Azure Cloud Shell. Em seguida, selecione uma assinatura:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Em seguida, crie um recurso de serviços de IA do Azure com um subdomínio personalizado. O nome do subdomínio precisa ser globalmente exclusivo e não pode incluir caracteres especiais, como: ".", "!", ",".

   $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 Endpoint deverá mostrar o nome de subdomínio exclusivo do seu recurso.

Atribuir uma função a uma entidade de serviço

Agora que você tem um subdomínio personalizado associado ao seu recurso, precisará atribuir uma função a uma entidade de serviço.

Nota

Lembre-se de que as atribuições de função do Azure podem levar até cinco minutos para se propagar.

1. Primeiro, vamos registrar um aplicativo Microsoft Entra.

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

   Você precisará do ApplicationId na próxima etapa.

2. Em seguida, você precisa criar uma entidade de serviço para o aplicativo Microsoft Entra.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Nota

   Se você registrar um aplicativo no portal do Azure, esta etapa será concluída para você.

3. A última etapa é atribuir a função "Usuário de Serviços Cognitivos" à entidade de serviço (com escopo para o recurso). Ao atribuir uma função, você está concedendo acesso da entidade de serviço a esse recurso. Você pode conceder à mesma entidade de serviço acesso a vários recursos em sua assinatura.

   Nota

   O ObjectId da entidade de serviço é usado, não o ObjectId para o aplicativo. O ACCOUNT_ID será a ID de recurso do Azure da conta de serviços de IA do Azure que você criou. Você pode encontrar a ID do recurso do Azure em "propriedades" do recurso no portal do Azure.

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

Pedido de amostra

Neste exemplo, uma senha é usada para autenticar a entidade de serviço. O token fornecido é então usado para chamar a API de Visão Computacional.

1. Obtenha o seu TenantId:

   $context=Get-AzContext
   $context.Tenant.Id
   

2. Obtenha um token:

   $tenantId = $context.Tenant.Id
   $clientId = $app.ApplicationId
   $clientSecret = "<YOUR_PASSWORD>"
   $resourceUrl = "https://cognitiveservices.azure.com/"
   
   $tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
   $body = @{
       grant_type    = "client_credentials"
       client_id     = $clientId
       client_secret = $clientSecret
       resource      = $resourceUrl
   }
   
   $responseToken = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body
   $accessToken = $responseToken.access_token
   

   Nota

   Sempre que você usar senhas em um script, a opção mais segura é usar o módulo de Gerenciamento de Segredos do PowerShell e integrar com uma solução como o Azure KeyVault.

3. Chame a API de Visão por Computador:

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

Como alternativa, a entidade de serviço pode ser autenticada com um certificado. Além da entidade de serviço, a entidade de usuário também é suportada por ter permissões delegadas por meio de outro aplicativo Microsoft Entra. Nesse caso, em vez de senhas ou certificados, os usuários seriam solicitados para autenticação de dois fatores ao adquirir token.

Autorizar o acesso a identidades gerenciadas

Os serviços de IA do Azure suportam a autenticação Microsoft Entra com identidades geridas para recursos do Azure. As identidades gerenciadas para recursos do Azure podem autorizar o acesso aos recursos dos serviços de IA do Azure usando credenciais do Microsoft Entra de aplicativos em execução em máquinas virtuais (VMs) do Azure, aplicativos de função, conjuntos de dimensionamento de máquinas virtuais e outros serviços. Usando identidades gerenciadas para recursos do Azure junto com a autenticação do Microsoft Entra, você pode evitar armazenar credenciais com seus aplicativos executados na nuvem.

Habilitar identidades gerenciadas em uma VM

Antes de poder usar identidades gerenciadas para recursos do Azure para autorizar o acesso aos recursos de serviços de IA do Azure a partir de sua VM, você deve habilitar identidades gerenciadas para recursos do Azure na VM. Para saber como habilitar identidades gerenciadas para Recursos do Azure, consulte:

• Portal do Azure
• Azure PowerShell
• CLI do Azure
• Modelo Azure Resource Manager
• Bibliotecas de cliente do Azure Resource Manager

Para obter mais informações sobre identidades gerenciadas, consulte Identidades gerenciadas para recursos do Azure.

Usar o cofre de chaves do Azure para acessar credenciais com segurança

Você pode usar o Azure Key Vault para desenvolver com segurança aplicativos de serviços de IA do Azure. O Cofre de Chaves permite que você armazene suas credenciais de autenticação na nuvem e reduz as chances de que segredos possam ser vazados acidentalmente, porque você não armazenará informações de segurança em seu aplicativo.

A autenticação é feita através do Microsoft Entra ID. A autorização pode ser feita por meio do controle de acesso baseado em função do Azure (Azure RBAC) ou da política de acesso do Cofre da Chave. O RBAC do Azure pode ser usado para o gerenciamento dos cofres e acessar dados armazenados em um cofre, enquanto a política de acesso ao cofre de chaves só pode ser usada ao tentar acessar dados armazenados em um cofre.

Consulte também

• O que são serviços de IA do Azure?
• Preços dos serviços de IA do Azure
• Subdomínios personalizados