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

2025-05-20

Cada solicitação aos serviços de IA do Azure deve incluir um cabeçalho de autenticação. Este cabeçalho transmite uma chave de recurso ou token de autenticação, que é usado para validar sua assinatura para um serviço ou grupo de serviços. Neste artigo, você aprenderá 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 de multisserviço da Fábrica de IA.
Autenticar com um token.
Autenticar com Microsoft Entra ID.

Pré-requisitos

Antes de fazer uma solicitação, você precisa de uma assinatura do Azure e de um recurso do AI Foundry. Se você precisar de um recurso do AI Foundry, consulte o guia criar um recurso do AI Foundry .

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.

parâmetro	Descrição
Ocp-Apim-Subscription-Key	Use esse cabeçalho para autenticar com uma chave de recurso para um serviço específico ou uma chave de recurso do AI Foundry.
Ocp-Apim-Subscription-Region	Esse cabeçalho só é necessário ao usar uma chave de recurso do AI Foundry com o serviço tradutor de IA do Azure. Use esse cabeçalho para especificar a região do recurso.
Autorização	Use esse cabeçalho se você está usando um token de acesso. As etapas para executar uma troca de tokens estã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 Tradutor de IA do Azure. As chaves estão disponíveis no portal do Azure para cada recurso que você criou. Acesse o seu recurso no portal do Azure. A seção Chaves e Ponto de Extremidade pode ser encontrada na seção Gerenciamento de Recursos. Copie o ponto de extremidade e as chave de acesso, pois você precisará de ambos para autenticar suas chamadas à API. Você pode usar KEY1 ou KEY2. Ter sempre duas chaves permite girar e regenerar chaves com segurança, sem causar interrupção de serviço.

Para usar uma chave de recurso para autenticar uma solicitação, ela deve ser transmitida como cabeçalho Ocp-Apim-Subscription-Key. Essa é uma chamada de exemplo para o serviço do Tradutor de IA do Azure:

Essa é uma chamada de exemplo para o serviço do 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

Autenticar com uma chave de recurso do AI Foundry

Você pode usar uma chave de recurso do AI Foundry para autenticar solicitações para vários serviços de IA do Azure. As credenciais de autenticação não estão vinculadas a um serviço específico. Confira os preços dos serviços de IA do Azure para obter informações sobre disponibilidade regional, recursos com suporte e preços.

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

Regiões com suporte

Ao usar a chave de recurso do AI Foundry para fazer uma solicitação 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 do AI Foundry com o Tradutor de IA do Azure, você deve especificar a região do recurso com o Ocp-Apim-Subscription-Region cabeçalho.

Há suporte para autenticação de recurso do AI Foundry nessas regiões:

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

Solicitações de exemplo

Essa é uma chamada de exemplo para o serviço do Tradutor de IA do Azure:

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, estes serviços dão suporte a tokens de acesso:

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

Aviso

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

As chaves de recurso de AI Foundry e dos serviços de IA 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 JWT (Token Web JSON) e podem ser consultados programaticamente usando as bibliotecas JWT.

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

Solicitações de exemplo

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"

Essas regiões dão suporte à troca de tokens para recursos da AI Foundry:

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

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

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

Autenticação com o Microsoft Entra ID

Importante

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

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

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 paralisado, 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 sua organização estiver autenticando pela ID do Microsoft Entra, você deverá desabilitar a autenticação local (autenticação com chaves) para que os usuários da organização sempre usem a ID do Microsoft Entra.

Crie um recurso com um subdomínio personalizado

A primeira etapa é criar um subdomínio personalizado. Se você quiser usar um recurso existente do AI Foundry que não tenha o nome do subdomínio personalizado, siga as instruções nos subdomínios personalizados dos serviços de IA do Azure para habilitar o subdomínio personalizado para seu recurso.

Comece abrindo o Azure Cloud Shell. Em seguida, selecione uma assinatura:
```
Set-AzContext -SubscriptionName <SubscriptionName>
```

Em seguida, crie um recurso de AI Foundry com um subdomínio personalizado. O nome do subdomínio deve 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>

Se for bem-sucedido, o Ponto de extremidade deverá mostrar o nome do subdomínio exclusivo para 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.

Observação

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

Primeiro, vamos registrar um aplicativo do 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.

Em seguida, você precisa criar uma entidade de serviço para o aplicativo Microsoft Entra.
```
New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
```
Observação

Se você registrar um aplicativo no portal do Azure, esta etapa será concluída para você.
A última etapa é atribuir a função "Usuário de Serviços Cognitivos do Azure" à entidade de serviço (com escopo definido para o recurso). Ao atribuir uma função, você está concedendo acesso principal de serviço a este recurso. Você pode conceder ao mesmo acesso de emtodade de serviço a vários recursos em sua assinatura.

Observação

O ObjectId da entidade de serviço é usada, não o ObjectId do aplicativo. O ACCOUNT_ID será a ID de recurso do Azure do recurso AI Foundry que você criou. Você pode encontrar o ID de recurso nas "propriedades" do recurso no portal do Azure.
```
New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
```

Solicitação de exemplo

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

Obtenha sua TenantId:

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

Obter 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

Observação

Sempre que utilizar palavras-passe num script, a opção mais segura é utilizar o módulo PowerShell Secrets Management e integrar-se com uma solução como o Azure Key Vault.

Chame a API de Visão de IA do Azure:

$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 segurança do usuário também tem suporte por ter permissões delegadas por outro aplicativo do Microsoft Entra. Nesse caso, em vez de senhas ou certificados, os usuários devem solicitar a autenticação de dois fatores ao adquirir o token.

Autorizar o acesso a identidades gerenciadas

Os serviços de IA do Azure dão suporte à autenticação do Microsoft Entra com identidades gerenciadas para recursos do Azure. As identidades gerenciadas para recursos do Azure podem autorizar o acesso aos recursos do AI Foundry usando as credenciais do Microsoft Entra 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. 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 (Máquina Virtual)

Antes de usar identidades gerenciadas para recursos do Azure para autorizar o acesso aos recursos do AI Foundry de sua VM, você deve habilitar identidades gerenciadas para recursos do Azure na VM. Para saber como habilitar identidades gerenciadas para recursos do Azure, confira:

Para saber mais sobre identidades gerenciadas, confira 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 do Azure AI Foundry. O Key Vault permite armazenar suas credenciais de autenticação na nuvem e reduz a probabilidade de vazamento acidental dos segredos, pois as informações de segurança não são armazenadas no aplicativo.

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

Compartilhar via

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

Pré-requisitos

Cabeçalhos de autenticação

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

Autenticar com uma chave de recurso do AI Foundry

Regiões com suporte

Solicitações de exemplo

Autenticar com um token de acesso

Solicitações de exemplo

Autenticação com o Microsoft Entra ID

Crie um recurso com um subdomínio personalizado

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

Solicitação de exemplo

Autorizar o acesso a identidades gerenciadas

Habilitar identidades gerenciadas em uma VM (Máquina Virtual)

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

Conteúdo relacionado

Comentários

Recursos adicionais