Tradutor v3.0

  • Artigo

Novidades?

A versão 3.0 do Translator fornece uma API Web moderna baseada em JSON. Ele melhora a usabilidade e o desempenho, consolidando os recursos existentes em menos operações, e fornece novos recursos.

  • Transliteração para converter texto em um idioma de um script para outro.
  • Tradução para vários idiomas em um único pedido.
  • Deteção, tradução e transliteração de idioma em uma solicitação.
  • Dicionário para procurar traduções alternativas de um termo, para encontrar retrotraduções e exemplos que mostram termos usados no contexto.
  • Resultados de deteção de linguagem mais informativos.

Base URLs

As solicitações ao Translator são, na maioria dos casos, tratadas pelo datacenter mais próximo de onde a solicitação se originou. Se houver uma falha no datacenter ao usar o ponto de extremidade global, a solicitação poderá ser roteada para fora da geografia.

Para forçar a solicitação a ser tratada dentro de 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.

Geografia URL de base (ponto final geográfico) Datacenters
Global (non-regional) api.cognitive.microsofttranslator.com Datacenter disponível mais próximo
Ásia-Pacífico api-apc.cognitive.microsofttranslator.com Coreia do Sul, Leste do Japão, Sudeste Asiático e Leste da Austrália
Europa api-eur.cognitive.microsofttranslator.com Europa do Norte, Europa Ocidental
Estados Unidos da América api-nam.cognitive.microsofttranslator.com Leste dos EUA, Centro-Sul dos EUA, Centro-Oeste dos EUA e Oeste dos EUA 2

1 Os clientes com um recurso localizado na Suíça Norte ou Suíça Oeste podem garantir que suas solicitações de API de texto sejam atendidas na Suíça. Para garantir que as solicitações sejam tratadas na Suíça, crie o recurso Tradutor no ou Switzerland Weste, em seguida, use o ponto de extremidade personalizado do recurso em Resource regionSwitzerland North suas solicitações de API.

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

// 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

2 O Tradutor Personalizado não está disponível atualmente na Suíça.

Autenticação

Assine o Translator ou multisserviço nos serviços de IA do Azure e use sua chave (disponível no portal do 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 Description
Ocp-Apim-Subscription-Key Use com a assinatura de serviços de IA do Azure se você estiver passando sua chave secreta.
O valor é a chave secreta do Azure para sua assinatura do Translator.
Autorização Use com a assinatura de serviços de IA do Azure se estiver passando 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 Description
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 Description
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 Description
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 , deverá especificar a região com o parâmetro Subscription-KeySubscription-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
Global 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 para o serviço Tradutor como um token ao 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 que o serviço Tradutor valide se o cliente solicitante está autorizado a usar o recurso e a concluir a solicitação.

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

Cabeçalho Valor
Autorização O valor é um token de portador de acesso gerado pelo Azure AD.
  • 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 Translator Resource → Properties.
  • Formato de ID do recurso:
    /subscriptions/subscriptionId>/resourceGroups/resourceGroupName/providers/Microsoft.CognitiveServices/accounts/resourceName/<<<>>
Página de propriedades do tradutor — portal do Azure

Screenshot:Translator properties page in the Azure portal.

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 serviço Tradutor agora está disponível com recursos de Rede Virtual (VNET) em todas as regiões da nuvem pública do Azure. Para habilitar a Rede Virtual, consulteConfigurando redes virtuais de serviços de IA do Azure.

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.

  1. Navegue até o recurso Tradutor no portal do Azure.

  2. Selecione Rede na seção Gerenciamento de Recursos.

  3. Na guia Firewalls e redes virtuais, escolha Redes selecionadas e pontos de extremidade privados.

    Screenshot of the virtual network setting in the Azure portal.

  4. Selecione Guardar para aplicar as alterações.

  5. Selecione Chaves e Ponto Final na seção Gerenciamento de Recursos.

  6. Selecione a guia Rede Virtual.

  7. Estão listados os pontos finais para Tradução de Texto e Tradução de Documentos.

    Screenshot of the virtual network endpoint.

Cabeçalhos Description
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?'}]"

Erros

Uma resposta de erro padrão é um objeto JSON com o par 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 que dá uma representação legível por humanos do erro.

Por exemplo, um cliente com uma assinatura de avaliação gratuita receberá o seguinte erro quando a cota gratuita se 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. Os códigos de erro comuns são:

Código Description
400000 Uma das entradas do pedido não é válida.
400001 O parâmetro "scope" é inválido.
400002 O parâmetro "category" é inválido.
400003 Um especificador de idioma está em falta ou é inválido.
400004 Um especificador de script de destino ("Script de destino") está em falta ou é inválido.
400005 Falta um texto de entrada ou é inválido.
400006 A combinação de idioma e script não é válida.
400018 Um especificador de script de origem ("Script de origem") está em falta ou é inválido.
400019 Uma dos idiomas especificados não é suportado.
400020 Um dos elementos na matriz do texto de entrada não é válido.
400021 O parâmetro da versão da API está em falta ou é inválido.
400023 Um dos pares de idiomas especificados não é válido.
400035 O idioma origem (campo "De") não é válido.
400036 A idioma de destino (campo "Para") está em falta ou é inválido.
400042 Uma das opções especificadas (campo "Opções") não é válida.
400043 O ID de rastreio do cliente (campo ClientTraceId ou cabeçalho X-ClientTranceId) está em falta ou é inválido.
400050 O texto de entrada é demasiado longo. Veja os limites dos pedidos.
400064 O parâmetro "translation" está em falta ou é inválido.
400070 O número de scripts de destino (parâmetro ToScript) não corresponde ao número de idiomas de destino (parâmetro To).
400071 O valor não é válido para TextType.
400072 A matriz do texto de entrada tem demasiados elementos.
400073 O parâmetro script não é válido.
400074 O corpo do pedido não é um JSON válido.
400075 O par de idiomas e a combinação de categorias não são válidos.
400077 O tamanho máximo do pedido foi excedido. Veja os limites dos pedidos.
400079 O sistema personalizado pedido para tradução do idiomas de origem e destino não existe.
400080 A transliteração não é suportada para o idioma ou o script.
401000 A solicitação não é autorizada porque as credenciais estão ausentes ou são inválidas.
401015 "As credenciais fornecidas são para a API de fala. Esta solicitação requer credenciais para a API de texto. Use uma assinatura do Translator."
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 é suportado para o recurso solicitado.
408001 O sistema de tradução pedido está a ser preparado. Tente novamente dentro de alguns minutos.
408002 O pedido excedeu o tempo limite ao aguardar no fluxo de dados de entrada. O cliente não produziu um pedido dentro do tempo em que o servidor estava preparado para aguardar. O cliente pode repetir o pedido 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 Ocorreu um erro inesperado. Se o erro persistir, informe-o com data/hora do erro, identificador de solicitação do cabeçalho de resposta X-RequestId e identificador de cliente do cabeçalho de solicitação X-ClientTraceId.
503000 O serviço está temporariamente indisponível. Tente novamente. Se o erro persistir, informe-o com data/hora do erro, identificador de solicitação do cabeçalho de resposta X-RequestId e identificador de cliente do cabeçalho de solicitação X-ClientTraceId.

Métricas

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

Translator Metrics

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

Métricas do Description
TotalCalls Número total de chamadas de API.
TotalTokenCalls Número total de chamadas de API via serviço de token usando token de autenticação.
Chamadas bem-sucedidas Número de chamadas bem-sucedidas.
TotalErrors Número de chamadas com resposta de erro.
Chamadas bloqueadas Número de chamadas que excederam o limite de tarifa ou quota.
Erros de servidor Número de chamadas com erro interno do servidor (5XX).
ClientErrors Número de chamadas com erro do lado do cliente(4XX).
Latência Duração para concluir a solicitação em milissegundos.
CaracteresTraduzido Número total de caracteres na solicitação de texto de entrada.