Autenticação e autorização

Cada pedido a uma ferramenta Foundry 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ê pode explorar maneiras de autenticar uma solicitação e os requisitos para cada uma.

Autentique-se com uma chave de recurso regional, global de serviço único ou multisserviço .
Autentique-se com um token de portador.
Autenticar com o Microsoft Entra ID é uma solução de identidade baseada em nuvem projetada para gerenciar o acesso e as permissões do usuário para serviços, recursos e aplicativos da Microsoft. O Microsoft Entra ID permite-lhe autenticar pedidos para os seus recursos Azure sem necessidade de palavras-passe ou chaves.

Cabeçalhos

Subscreva o Tradutor ou multi-serviço no Foundry Tools e use a sua chave (disponível no portal Azure) para autenticar.

Há três cabeçalhos que você pode usar para autenticar sua assinatura. Esta tabela descreve como cada um é usado:

Cabeçalhos	Descrição
Ocp-Apim-Subscription-Key	Use com subscrição do Foundry Tools se estiver a passar a sua chave secreta. O valor é a chave secreta do Azure para sua assinatura do Translator.
Autorização	Use com subscrição do Foundry Tools se estiver a passar um token de autenticação. O valor é o token ao portador: `Bearer <token>`.
OCP-Apim-Assinatura-Região	Use com recurso de tradutor regional e multisserviço. O valor é a região do recurso de tradutor regional ou multisserviço. Esse valor é opcional ao usar um recurso de tradutor global.

Chave secreta

A primeira opção é autenticar usando o Ocp-Apim-Subscription-Key cabeçalho. Adicione o Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> cabeçalho ao seu pedido.

Autenticação com um recurso global

Ao usar um recurso de tradutor global, você precisa incluir um cabeçalho para chamar o Tradutor.

Cabeçalhos	Descrição
Ocp-Apim-Subscription-Key	O valor é a chave secreta do Azure para sua assinatura do Translator.

Aqui está um exemplo de solicitação para chamar o Tradutor usando o recurso de tradutor global

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"

Autenticação com um recurso regional

Quando você usa um recurso de tradutor regional, há dois cabeçalhos que você precisa chamar de Tradutor.

Cabeçalhos	Descrição
Ocp-Apim-Subscription-Key	O valor é a chave secreta do Azure para sua assinatura do Translator.
OCP-Apim-Assinatura-Região	O valor é a região do recurso do tradutor.

Aqui está um exemplo de solicitação para chamar o Tradutor usando o recurso de tradutor regional

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Ocp-Apim-Subscription-Region:<your-region>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"

Autenticação com um recurso multisserviço

Um recurso multisserviço permite que você use uma única chave de API para autenticar solicitações para vários serviços.

Ao usar uma chave secreta multisserviço, você deve incluir dois cabeçalhos de autenticação com sua solicitação. Há dois cabeçalhos que você precisa chamar o Tradutor.

Cabeçalhos	Descrição
Ocp-Apim-Subscription-Key	O valor é a chave secreta do Azure para seu recurso multisserviço.
OCP-Apim-Assinatura-Região	O valor é a região do recurso multisserviço.

A região é necessária para a assinatura da API de texto multisserviço. A região selecionada é a única que você pode usar para tradução de texto ao usar a chave multisserviço. Deve ser a mesma região que selecionou quando se inscreveu para a sua subscrição multisserviço através do portal do Azure.

Se você passar a chave secreta na cadeia de caracteres de consulta com o parâmetro Subscription-Key, deverá especificar a região com o parâmetro Subscription-Regionquery .

Autenticação com um token de acesso

Como alternativa, você pode trocar sua chave secreta por um token de acesso. Esse token é incluído em cada solicitação como cabeçalho Authorization . Para obter um token de autorização, faça uma POST solicitação para a seguinte URL:

Tipo de recurso	URL do serviço de autenticação
A nível mundial	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Regional ou Multi-Serviço	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Aqui estão exemplos de solicitações para obter um token dado uma chave secreta para um recurso global:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

E aqui estão exemplos de solicitações para obter um token dado uma chave secreta para um recurso regional localizado no centro dos EUA:

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

Uma solicitação bem-sucedida retorna o token de acesso codificado como texto sem formatação no corpo da resposta. O token válido é passado ao Tradutor como token portador na Autorização.

Authorization: Bearer <Base64-access_token>

Um token de autenticação é válido por 10 minutos. O token deve ser reutilizado ao fazer várias chamadas para o Tradutor. No entanto, se o seu programa fizer solicitações ao Tradutor durante um longo período de tempo, o programa deverá solicitar um novo token de acesso em intervalos regulares (por exemplo, a cada 8 minutos).

Autenticação com ID do Microsoft Entra

O Translator v3.0 suporta a autenticação Microsoft Entra, a solução de gerenciamento de identidade e acesso baseada em nuvem da Microsoft. Os cabeçalhos de autorização permitem ao Tradutor validar que o cliente solicitante está autorizado a usar o recurso e a completar o pedido.

Pré-requisitos

Uma breve compreensão de como autenticar com o Microsoft Entra ID.
Uma breve compreensão de como autorizar o acesso a identidades gerenciadas.

Cabeçalhos de ID do Microsoft Entra

Cabeçalho	Valor
Autorização	O valor é um token de portador de acesso gerado pelo Microsoft Entra ID. O token ao portador fornece prova de autenticação e valida a autorização do cliente para usar o recurso. Um token de autenticação é válido por 10 minutos e deve ser reutilizado ao fazer várias chamadas para o Translator. ConsulteSolicitação de exemplo: 2. Obter um token
OCP-Apim-Assinatura-Região	O valor é a região do recurso do tradutor. Esse valor é opcional se o recurso for global.
OCP-Apim-ResourceId	O valor é o ID do recurso para sua instância de recurso do Translator. Você encontra a ID do Recurso no portal do Azure em Propriedades do → de Recursos do Tradutor. Formato de ID do recurso: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Página de propriedades do tradutor — portal do Azure

Captura de tela:Página de propriedades do tradutor no portal do Azure.

Importante

Atribua a função de Usuário dos Serviços Cognitivos à entidade de serviço. Ao atribuir essa função, você concede acesso da entidade de serviço ao recurso Tradutor.

Exemplos

Usando o endpoint global

// Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Ocp-Apim-ResourceId: <Resource ID>" \
    -H "Ocp-Apim-Subscription-Region: <your-region>" \
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

Usando seu ponto de extremidade personalizado

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

Exemplos usando identidades gerenciadas

O Translator v3.0 também suporta a autorização de acesso a identidades gerenciadas. Se uma identidade gerenciada estiver habilitada para um recurso de tradutor, você poderá passar o token de portador gerado pela identidade gerenciada no cabeçalho da solicitação.

Com o endpoint global

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Ocp-Apim-ResourceId: <Resource ID>" \
    -H "Ocp-Apim-Subscription-Region: <your-region>" \
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

Com o seu ponto de extremidade personalizado

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

Suporte de Rede Virtual

O Tradutor está agora disponível com capacidades de Rede Virtual (VNET) em todas as regiões da cloud pública Azure. Para ativar a Rede Virtual, vejaConfigurar redes virtuais das Foundry Tools.

Depois de ativar esse recurso, você deve usar o ponto de extremidade personalizado para chamar o Tradutor. Não é possível usar o ponto de extremidade do tradutor global ("api.cognitive.microsofttranslator.com") e não é possível autenticar com um token de acesso.

Você pode encontrar o ponto de extremidade personalizado depois de criar um recurso de tradutor e permitir o acesso de redes selecionadas e pontos de extremidade privados.

Navegue até o recurso Tradutor no portal do Azure.
Selecione Rede na seção Gerenciamento de Recursos.
Na guia Firewalls e redes virtuais, escolha Redes Selecionadas e Pontos de Extremidade Privados.
Selecione Guardar para aplicar as alterações.
Selecione Chaves e Ponto Final na seção Gerenciamento de Recursos .
Selecione a guia Rede Virtual .
Estão listados os pontos finais para Tradução de Texto e Tradução de Documentos.

Cabeçalhos	Descrição
Ocp-Apim-Subscription-Key	O valor é a chave secreta do Azure para sua assinatura do Translator.
OCP-Apim-Assinatura-Região	O valor é a região do recurso do tradutor. Este valor é opcional se o recurso for `global`

Aqui está um exemplo de solicitação para chamar o Translator usando o ponto de extremidade personalizado

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Ocp-Apim-Subscription-Region:<your-region>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"

Feedback

Esta página foi útil?

Last updated on 2025-11-18