Usar APIs REST programaticamente

  • Artigo

A Tradução de Documentos é um recurso baseado em nuvem do serviço Tradutor de IA do Azure. Você pode usar a API de Tradução de Documentos para traduzir documentos inteiros de forma assíncrona nos idiomas com suporte e em vários formatos de arquivo, preservando a estrutura do documento de origem e a formatação de texto. Neste guia de instruções, você aprenderá a usar APIs de tradução de documentos com uma linguagem de programação de sua escolha e a API HTTP REST.

Pré-requisitos

Observação

  • Normalmente, ao criar um recurso de IA do Azure no portal do Azure, você tem a opção de criar uma chave de vários serviços ou uma chave de serviço único. No entanto, a Tradução de Documentos tem suporte atualmente apenas no recurso Tradutor (serviço único) e não está incluído no recurso Serviços de IA do Azure (vários serviços).

  • A Tradução de Documentos só com suporte no plano de serviço Standard S1 (pago conforme o uso) ou no plano de desconto por volume D3. Confira Preços dos serviços de IA do Azure – Tradutor.

Para começar, você precisa do seguinte:

  • Uma conta do Azure ativa. Se você não tiver uma, poderá criar uma conta gratuita

  • Uma conta de Armazenamento de Blobs do Azure. Você precisará criar contêineres na sua conta de armazenamento de blobs do Azure para os arquivos de origem e destino:

    • Contêiner de origem. Esse contêiner é onde você carrega os arquivos para tradução (obrigatório).
    • Contêiner de destino. Esse contêiner é o local em que os arquivos traduzidos são armazenados (obrigatório).

  • Um recurso de Tradução de serviço único (não um recurso de vários serviços dos serviços de IA do Azure):

    Preencha os campos Tradutor detalhes do projeto e da instância da seguinte forma:

    1. Assinatura. Selecione uma das suas assinaturas do Azure disponíveis.

    2. Grupo de Recursos. Você pode criar um grupo de recursos ou adicionar o recurso a um grupo de recursos existente que compartilhe o mesmo ciclo de vida e as mesmas permissões e políticas.

    3. Região do recurso. Escolha Global, a menos que seu negócio ou aplicativo exija uma região específica. Se você estiver planejando usar uma identidade gerenciada atribuída pelo sistema para autenticação, escolha uma região geográfica como Oeste dos EUA.

    4. Nome.. Insira o nome escolhido para o recurso. O nome escolhido deve ser exclusivo dentro do Azure.

      Observação

      A Tradução de Documentos requer um ponto de extremidade de domínio personalizado. O valor que você inserir no campo Nome será o parâmetro de nome de domínio personalizado para o ponto de extremidade.

    5. Tipo de preço. Não há suporte para a Tradução de Documentos na camada gratuita. Para experimentar o serviço, selecione Standard S1.

    6. Selecione Examinar + criar.

    7. Examine os termos de serviço e selecione Criar para implantar o seu recurso.

    8. Depois que o recurso for implantado com êxito, selecione Ir para o recurso para recuperar a chave e ponto de extremidade.

Recuperar sua chave e o ponto de extremidade de domínio personalizado

  • As solicitações para o serviço de Tradução exigem uma chave somente leitura e um ponto de extremidade personalizado para autenticar o acesso. O ponto de extremidade do domínio personalizado é uma URL formatada com o nome do recurso, nome do host e os subdiretórios de Tradução e está disponível no portal do Azure.

  1. Se você tiver criado um novo recurso, depois que ele for implantado, selecione Ir para o recurso. Se você tiver um recurso de Tradução de Documento existente, navegue diretamente para a página de recursos.

  2. No trilho à esquerda, em Gerenciamento de Recursos, selecione Chaves e Ponto de Extremidade.

  3. Copie e cole key e document translation endpoint em um local conveniente, como o Bloco de Notas da Microsoft. Apenas uma chave é necessária para fazer uma chamada à API.

  4. Você cola key e document translation endpoint no exemplo de código para autenticar sua solicitação para o serviço de Tradução de Documento.

    Screenshot showing the get your key field in Azure portal.

Obter sua chave

As solicitações para o serviço do Tradutor exigem uma chave somente leitura para autenticar o acesso.

  1. Se você tiver criado um novo recurso, depois que ele for implantado, selecione Ir para o recurso. Se você tiver um recurso de Tradução de Documento existente, navegue diretamente para a página de recursos.
  2. No trilho à esquerda, em Gerenciamento de Recursos, selecione Chaves e Ponto de Extremidade.
  3. Copie e cole a chave em um local conveniente, como o Bloco de Notas da Microsoft.
  4. Cole-o no exemplo de código para autenticar sua solicitação ao serviço de Tradução de Documentos.

Image of the get your key field in Azure portal.

Criar contêineres de armazenamento de blobs do Azure

Você precisa criar contêineres na sua conta de armazenamento de blobs do Azure para os arquivos de origem e destino.

  • Contêiner de origem. Esse contêiner é onde você carrega os arquivos para tradução (obrigatório).
  • Contêiner de destino. Esse contêiner é o local em que os arquivos traduzidos são armazenados (obrigatório).

Observação

A tradução de documento é compatível com glossários em blobs nos contêineres de destino (não contêineres de glossário separados). Se quiser incluir um glossário personalizado, adicione-o ao contêiner de destino e inclua o glossaryUrl com a solicitação. Se o par de idiomas de tradução não estiver presente no glossário, ele não será aplicado. ConsulteTraduzir documentos usando um glossário personalizado

Criar tokens de acesso SAS para Tradução de Documento

O contêineres sourceUrl, targetUrl e glossaryUrl opcional devem incluir um token de SAS (Assinatura de Acesso Compartilhado), anexado como uma cadeia de caracteres de consulta. O token pode ser atribuído ao contêiner ou a blobs específicos. ConfiraCriar tokens SAS para o processo de Tradução de Documento.

  • O contêiner ou o blob de origem deve ter acesso de leitura e lista designado.
  • O contêiner ou blob de destino deve ter acesso de gravação e lista designados.
  • O blob do glossário deve designar o acesso de leitura e lista.

Dica

  • Se você estiver traduzindo vários arquivos (blobs) em uma operação, delegue acesso SAS no nível do contêiner.
  • Se você estiver traduzindo um único arquivo (blob) em uma operação, delegue acesso SAS no nível do blob.
  • Como alternativa aos tokens SAS, você pode usar uma identidade gerenciada atribuída pelo sistema para autenticação.

Solicitações HTTP

Uma solicitação de tradução em lote assíncrona é enviada para o ponto de extremidade de serviço de Tradução de Texto por meio de uma solicitação POST. Se for bem-sucedido, o método POST retornará um código de resposta 202 Accepted e a solicitação em lote será criada pelo serviço. Os documentos traduzidos estão listados no contêiner de destino.

Para obter informações detalhadas sobre os limites da solicitação do Serviço Tradutor de IA do Azure, consulteLimites de solicitação de tradução de documentos.

Cabeçalhos HTTP

Os seguintes cabeçalhos estão incluídos em cada solicitação de API de Tradução de Documento:

Cabeçalho HTTP Descrição
Ocp-Apim-Subscription-Key Obrigatório: o valor é a chave do Azure para seu recurso de Tradução ou de serviços de IA do Azure.
Tipo de conteúdo Obrigatório: especifica o tipo de conteúdo da payload. Os valores aceitos são application/json ou CharSet=UTF-8.

Propriedades do corpo da solicitação POST

  • A URL da solicitação POST é POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • O corpo da solicitação POST é um objeto JSON chamado inputs.
  • O objeto inputs contém os ambos os endereços de contêiner sourceURL e o targetURL para os pares de idiomas de origem e de destino.
  • prefix e suffix são cadeias de caracteres que diferenciam maiúsculas de minúsculas para filtrar documentos no caminho de origem para tradução. O campo prefix geralmente é usado para delinear subpastas para tradução. O campo suffix é usado com mais frequência para extensões de arquivo.
  • Um valor para o campo glossaries (opcional) é aplicado quando o documento está sendo traduzido.
  • O targetUrl para cada idioma de destino deve ser exclusivo.

Observação

Se um arquivo com o mesmo nome já existir no destino, o trabalho falhará.

Traduzir todos os documentos em um contêiner

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traduzir um documento específico em um contêiner

  • Especifique "storageType": "File".
  • Se você não estiver usando uma identidade gerenciada atribuída pelo sistema para autenticação, verifique se criou o token SAS e a URL de origem para o blob/documento específico (não para o contêiner).
  • Verifique se você especificou o nome de arquivo de destino como parte da URL de destino, embora o token SAS ainda seja para o contêiner.
  • Esse exemplo de solicitação retorna um único documento traduzido em dois idiomas de destino.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es"
                },
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "de"
                }
            ]
        }
    ]
}

Traduzir documentos usando um glossário personalizado

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
             },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "{glossaryUrl/en-es.xlf}",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Usar código para enviar solicitações de tradução de documento

Configurar a plataforma de codificação

  • Criar um novo projeto.
  • Substitua Program.cs pelo código de exemplo C#.
  • Defina seus valores de ponto de extremidade, chave e URL de contêiner em Program.cs.
  • Adicione o pacote Newtonsoft.Json usando a CLI do .NET para processar dados JSON.
  • Execute o programa usando o diretório do projeto.

Importante

Para os exemplos de código, você embutirá a URL de SAS (Assinatura de acesso compartilhado) onde indicado. Lembre-se de remover a URL de SAS do código quando terminar e de nunca postá-la publicamente. Para produção, use um modo seguro de armazenar e acessar suas credenciais, como a Identidade Gerenciada do Azure. Para saber mais, confira Segurança do Armazenamento do Azure.

Talvez seja necessário atualizar os seguintes campos, dependendo da operação:

  • endpoint
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (job ID)

Localizando o valor id

  • Você encontra o trabalho id no valor da URL do Cabeçalho Operation-Location de resposta do método POST. O último parâmetro da URL é o trabalho da operação id :
Cabeçalho de resposta URL do Resultado
Operation-Location https://<NOME-DO-SEU-RECURSO>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec
  • Você também pode usar uma solicitação GET Jobs para recuperar um trabalho de Tradução de Documentos id.

Traduzir documentos


    using System;
    using System.Net.Http;
    using System.Threading.Tasks;
    using System.Text;


    class Program
    {

        static readonly string route = "/batches";

        private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";

        private static readonly string key = "<YOUR-KEY>";

        static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");

        static async Task Main(string[] args)
        {
            using HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {

                StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

                request.Method = HttpMethod.Post;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);
                request.Content = content;

                HttpResponseMessage  response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;
                if (response.IsSuccessStatusCode)
                {
                    Console.WriteLine($"Status code: {response.StatusCode}");
                    Console.WriteLine();
                    Console.WriteLine($"Response Headers:");
                    Console.WriteLine(response.Headers);
                }
                else
                    Console.Write("Error");

            }

        }

    }

Obter formatos de arquivo

Recupera uma lista de formatos de arquivo com suporte. Se for bem-sucedido, esse método retornará um código de resposta 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";

    static readonly string route = "/documents/formats";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Obter status do trabalho

Obtenha o status atual de um único trabalho e um resumo de todos os trabalhos em uma solicitação de Tradução de Documento. Se for bem-sucedido, esse método retornará um código de resposta 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";

    static readonly string route = "/batches/{id}";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
    }
}

Obter status do documento

Visão geral resumida

Recupera o status de um documento específico em uma solicitação de Tradução de Documento. Se for bem-sucedido, esse método retornará um código de resposta 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";

    static readonly string route = "/{id}/document/{documentId}";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Excluir o trabalho

Visão geral resumida

Cancela o trabalho em processamento ou em fila no momento. Somente os documentos para os quais a tradução não foi iniciada são cancelados.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";

    static readonly string route = "/batches/{id}";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Delete;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Códigos de status HTTP comuns

Código de status HTTP Descrição Possível motivo
200 OK A solicitação foi bem-sucedida.
400 Solicitação incorreta Um parâmetro obrigatório está ausente, vazio ou nulo. Ou então, o valor passado como um parâmetro obrigatório ou opcional é inválido. Um problema comum é um cabeçalho que é muito longo.
401 Não Autorizado A solicitação não está autorizada. Verifique se a chave ou o token são válidos e se estão na região correta. Ao gerenciar sua assinatura no portal do Azure, verifique se você está usando o recurso de serviço único Tradutor e não o recurso de vários serviços dos Serviços de IA do Azure.
429 Número Excessivo de Solicitações Você excedeu a cota ou a taxa de solicitações permitidas para a sua assinatura.
502 Gateway incorreto Problema de rede ou do servidor. Também pode indicar cabeçalhos inválidos.

Saiba mais

Próximas etapas

Criar um sistema de idioma personalizado usando o Tradutor Personalizado