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

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:

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.

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.

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.

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:

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

Tradutor página de propriedades — portal do Azure

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.

   

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.

   

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:

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.

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.