Tradutor v3.0

Artigo
09/02/2024

Novidades

A versão 3.0 do Tradutor fornece uma API Web moderna baseada em JSON. Ela melhora o uso e o desempenho por meio da consolidação dos recursos existentes em menos operações, além de fornecer novos recursos.

Transliteração para converter texto em um idioma de um script para outro script.
Tradução para vários idiomas em uma solicitação.
Detecção de idioma, tradução e transliteração em uma solicitação.
Dicionário para pesquisar traduções alternativas de um termo, encontrar traduções reversas e exemplos que mostram os termos usados no contexto.
Resultados de detecção de idioma mais informativos.

URLs base

Na maioria dos casos, as solicitações para o Tradutor são tratadas pelo datacenter mais próximo do qual a solicitação foi originada. Se houver uma falha no datacenter ao usar o ponto de extremidade global, a solicitação poderá ser roteada para fora da área geográfica.

Para forçar a solicitação a ser tratada em uma geografia específica, use o ponto de extremidade geográfico desejado. Todas as solicitações são processadas entre os datacenters dentro da geografia.

✔️ Recurso: Tradução de Texto

Ponto de extremidade de serviço	Data center de processamento de solicitações
Global (recomendado): `api.cognitive.microsofttranslator.com`	Data center disponível mais próximo.
Américas: `api-nam.cognitive.microsofttranslator.com`	Leste dos EUA 2 • Oeste dos EUA 2
Pacífico Asiático: `api-apc.cognitive.microsofttranslator.com`	Leste do Japão • Sudeste da Ásia
Europa (exceto Suíça): `api-eur.cognitive.microsofttranslator.com`	França Central • Oeste da Europa
Suíça: Para mais informações, consulte os pontos de extremidade de serviço na Suíça.	Norte da Suíça • Oeste da Suíça

Pontos de extremidade de serviço da Suíça

Os clientes com um recurso localizado no Norte da Suíça ou no Oeste da Suíça podem garantir que as solicitações da API de Texto sejam atendidas na Suíça. Para garantir que as solicitações sejam processadas na Suíça, crie o recurso do Tradutor no Resource region Switzerland North ou Switzerland West, e use o ponto de extremidade personalizado do recurso em suas solicitações de API.

Por exemplo: se você criar um recurso do Tradutor no portal do Azure com Resource region como Switzerland North e o nome do recurso for my-swiss-n, o ponto de extremidade personalizado será https://my-swiss-n.cognitiveservices.azure.com. E uma solicitação de exemplo para tradução será:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

Atualmente, o Tradutor Personalizado não está disponível na Suíça.

Autenticação

Inscreva-se no Tradutor ou no recurso de vários serviços nos serviços de IA do Azure e use sua chave (disponível no portal do Azure) para autenticação.

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 a assinatura dos serviços de IA do Azure se estiver passando a chave secreta. O valor é a chave secreta do Azure da sua assinatura do Tradutor.
Autorização	Use com a assinatura dos serviços de IA do Azure se estiver passando um token de autenticação. O valor é o token de portador: `Bearer <token>`.
Ocp-Apim-Subscription-Region	Use com o recurso de vários serviços e de tradutor regional. O valor é a região do recurso de vários serviços e de tradutor regional. Esse valor é opcional quando um recurso de tradutor global é usado.

Chave secreta

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

Autenticação com um recurso global

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

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

Veja um exemplo de solicitação usada 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 necessários para você chamar o Tradutor.

Cabeçalhos	Descrição
Ocp-Apim-Subscription-Key	O valor é a chave secreta do Azure da sua assinatura do Tradutor.
Ocp-Apim-Subscription-Region	O valor é a região do recurso de tradutor.

Veja um exemplo de solicitação usada 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 de vários serviços

Um recurso de vários serviços permite que você use uma só chave de API para autenticar solicitações para vários serviços.

Ao usar uma chave secreta de vários serviços, você precisará incluir dois cabeçalhos de autenticação com a solicitação. Há dois cabeçalhos necessários para chamar o Tradutor.

Cabeçalhos	Descrição
Ocp-Apim-Subscription-Key	O valor é a chave secreta do Azure do recurso de vários serviços.
Ocp-Apim-Subscription-Region	O valor é a região do recurso de vários serviços.

A região é necessária para a assinatura da API de Texto de vários serviços. A região selecionada é a única região que você pode usar para tradução de texto ao usar a chave multisserviço. Deverá ser a mesma região que você selecionou quando se inscreveu para a assinatura de vários serviços por meio do portal do Azure.

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

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 o cabeçalho Authorization. Para obter um token de autorização, faça uma solicitação POST à URL a seguir:

Tipo de recurso	URL do serviço de autenticação
Global	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Regional ou de vários serviços	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Estes são exemplos de solicitações para obter um token, considerando 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>'

Estes são exemplos de solicitações para obter um token, considerando uma chave secreta para um recurso regional localizado na região EUA Central:

// 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 para o serviço de Tradução como um token de portador na Autorização.

Authorization: Bearer <Base64-access_token>

Um token de autenticação é válido por 10 minutos. O token deve ser reutilizado quando várias chamadas são feitas ao Tradutor. No entanto, se o programa faz solicitações ao Tradutor por um período prolongado, o programa precisa solicitar um novo token de acesso em intervalos regulares (por exemplo, a cada oito minutos).

Autenticação com o Microsoft Entra ID

O Tradutor v3.0 dá suporte à autenticação do Microsoft Entra, à solução de gerenciamento de acesso e à identidade baseada em nuvem da Microsoft. Os cabeçalhos de autorização permitem que o serviço de Tradutor valide se o cliente solicitante está autorizado a usar o recurso e para concluir a solicitação.

Pré-requisitos

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

Cabeçalhos

Cabeçalho	Valor
Autorização	O valor é um token de portador de acesso gerado pelo Azure AD. O token de portador fornece uma 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 Tradutor. Consulte Exemplo de solicitação: 2. Obter um token
Ocp-Apim-Subscription-Region	O valor é a região do recurso de tradutor. Esse valor será opcional se o recurso for global.
Ocp-Apim-ResourceId	O valor é a ID de recurso para sua instância de recurso de Tradução. Você encontra a ID do recurso no portal do Azure em Propriedades → Recurso do Tradutor. Formato da ID do recurso: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Tradutor página de propriedades — portal do Azure

Captura de tela: página de propriedades de 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ê está concedendo acesso à entidade de serviço ao recurso Tradutor.

Exemplos

Usando o ponto de extremidade 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 de usar identidades gerenciadas

O Tradutor v3.0 também dá suporte à 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 ponto de extremidade 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 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 para Rede Virtual

O serviço de Tradutor já está disponível com funcionalidades de VNET (Rede Virtual) em todas as regiões da nuvem pública do Azure. Para habilitar a Rede Virtual, consulte Configurando redes virtuais dos serviços de IA do Azure.

Depois de ativar essa funcionalidade, você precisará usar o ponto de extremidade personalizado para chamar o Tradutor. Você não poderá usar o ponto de extremidade de tradução global ("api.cognitive.microsofttranslator.com") nem se autenticar com um token de acesso.

Encontre o ponto de extremidade personalizado depois de criar um recurso de tradutor e permitir o acesso em redes selecionadas e pontos de extremidade privados.

Navegue até a página do seu recurso de Tradução no portal do Azure.
Selecione Rede na seção Gerenciamento de Recursos .
Na guia Firewalls e redes virtuais, selecione Redes Selecionadas e Pontos de Extremidade Privados.
Selecione Salvar para salvar suas alterações.
Selecione Chaves e Ponto de Extremidade na seção Gerenciamento de Recursos.
Selecione a guia Rede Virtual.
Os pontos de extremidade estão listados 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 da sua assinatura do Tradutor.
Ocp-Apim-Subscription-Region	O valor é a região do recurso de tradutor. Esse valor será opcional se o recurso for `global`

Veja um exemplo de solicitação usada para chamar o Tradutor 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?'}]"

Errors

Uma resposta de erro padrão é um objeto JSON com o par de nome/valor chamado error. O valor também é um objeto JSON com propriedades:

code: um código de erro definido pelo servidor.
message: uma cadeia de caracteres fornecendo uma representação legível do erro.

Por exemplo, um cliente com uma assinatura de avaliação gratuita receberia o seguinte erro após a cota livre esgotar:

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

O código de erro é um número de 6 dígitos que combina o código de status HTTP de 3 dígitos seguido por um número de 3 dígitos para categorizar ainda mais o erro. Códigos de erro comuns são:

Código	Descrição
400000	Uma das entradas de solicitação não é válida.
400001	O parâmetro "scope" é inválido.
400002	O parâmetro "category" é inválido.
400003	Um especificador de linguagem está ausente ou inválido.
400004	Um especificador de script de destino ("To script") está ausente ou é inválido.
400005	Um texto de entrada está faltando ou é inválido.
400006	A combinação de idioma e script não é válida.
400018	Um especificador de script de origem ("From script") está ausente ou é inválido.
400019	Não há suporte para um dos idiomas especificados.
400020	Um dos elementos na matriz de texto de entrada não é válido.
400021	O parâmetro da versão da API está ausente ou é inválido.
400023	Um dos pares de idiomas especificados não é válido.
400035	O idioma de origem (campo "De") não é válido.
400036	O idioma de destino (campo "Para") está ausente ou é inválido.
400042	Uma das opções especificadas (campo "Opções") não é válida.
400043	A ID de rastreamento do cliente (campo ClientTraceId ou cabeçalho X-ClientTraceId) está ausente ou é inválida.
400050	O texto de entrada é muito longo. Veja Limites de solicitação.
400064	O parâmetro "translation" está ausente ou é inválido.
400070	O número de scripts de destino (parâmetro ToScript) não corresponde ao número de linguagens de destino (parâmetro To).
400071	O valor não é válido para o TextType.
400072	A matriz de texto de entrada possui muitos elementos.
400073	O parâmetro de script não é válido.
400074	O corpo da solicitação não é válido como JSON.
400075	A combinação de pares de idiomas e categorias não é válida.
400077	O tamanho máximo da solicitação foi excedido. Veja Limites de solicitação.
400079	O sistema personalizado solicitado para tradução entre "de" e "para" o idioma não existe.
400080	Não há suporte para a transliteração no idioma ou no script.
401000	A solicitação não está autorizada porque as credenciais estão ausentes ou são inválidas.
401015	"As credenciais fornecidas são para a Speech API. Esta solicitação requer credenciais para a API de texto. Use uma assinatura do Tradutor".
403000	A operação não é permitida.
403001	A operação não é permitida porque a assinatura excedeu sua cota gratuita.
405000	O método de solicitação não é compatível com o recurso solicitado.
408001	O sistema de tradução solicitado está sendo preparado. Tente novamente em alguns minutos.
408002	A solicitação atingiu o tempo limite aguardando o fluxo de entrada. O cliente não produziu uma solicitação no momento em que o servidor estava preparado para aguardar. O cliente poderá repetir a solicitação sem modificações em qualquer momento posterior.
415000	O cabeçalho Content-Type está ausente ou é inválido.
429000, 429001, 429002	O servidor rejeitou a solicitação porque o cliente excedeu os limites de solicitação.
500000	Erro inesperado. Se o erro persistir, informe-o com data / hora do erro, solicite o identificador do cabeçalho de resposta X-RequestId e o identificador de cliente do cabeçalho de solicitação X-ClientTraceId.
503000	O serviço está temporariamente indisponível. Repetir. Se o erro persistir, informe-o com data / hora do erro, solicite o identificador do cabeçalho de resposta X-RequestId e o identificador de cliente do cabeçalho de solicitação X-ClientTraceId.

Métricas

As métricas permitem que você veja as informações de uso e disponibilidade do tradutor no portal do Azure, na seção Métricas, conforme mostrado na captura de tela abaixo. Para obter mais informações, confira Métricas de dados e plataforma.

Métricas do Tradutor

Esta tabela lista as métricas disponíveis com a descrição de como são utilizadas para monitorar as chamadas à API de tradução.

Métricas	Descrição
TotalCalls	Número total de chamadas de API.
TotalTokenCalls	Número total de chamadas à API por meio do serviço de token usando o token de autenticação.
SuccessfulCalls	Número de chamadas com êxito.
TotalErrors	Número de chamadas com uma resposta com erro.
BlockedCalls	Número de chamadas que excederam a taxa ou o limite de cota.
ServerErrors	Número de chamadas com um erro interno do servidor (5XX).
ClientErrors	Número de chamadas com um erro do cliente (4XX).
Latency	Duração necessária para concluir a solicitação em milissegundos.
CharactersTranslated	Número total de caracteres na solicitação de texto de entrada.

Compartilhar via