Compartilhar via


Tradutor v3.0

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

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.

  1. Navegue até a página do seu recurso de Tradução no portal do Azure.

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

  3. Na guia Firewalls e redes virtuais, selecione Redes Selecionadas e Pontos de Extremidade Privados.

    Captura de tela da configuração da rede virtual no portal do Azure.

  4. Selecione Salvar para salvar suas alterações.

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

  6. Selecione a guia Rede Virtual.

  7. Os pontos de extremidade estão listados para Tradução de Texto e Tradução de Documentos.

    Captura de tela do ponto de extremidade da rede virtual.

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.