Compartilhar via

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

A tradução de documentos tem suporte para o Plano de Serviço Standard S1 (pagamento conforme o uso) e com os Planos de Desconto por Volume C2, C3, C4 e D3. Consulte 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 do Translator:

    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. É possível criar um grupo de recursos ou adicionar seu recurso a um grupo de recursos existente que compartilha o mesmo ciclo de vida, 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.

    Captura de tela mostrando o campo obter sua chave no portal do Azure.

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.

Imagem do campo para obter sua chave no portal do Azure.

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. Consulte Traduzir 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. Consulte Criar tokens de 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, confira Limites 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"
                        }
                    ]
                }
            ]
        }
    ]
}

🆕 Traduzir texto inserido em imagens em documentos

Observação

  • Esse recurso é opcional e deve ser habilitado para cada solicitação de tradução.
  • Habilitar esse recurso incorrerá em custos adicionais com base no uso. Para obter mais informações, confira preços da Visão de IA do Azure
  • No momento, esse recurso está disponível apenas com a API de Tradução de Documento em Lote.
  • O formato de arquivo com suporte é apenas .docx.
  • Um recurso dos Serviços de IA do Azure (não o recurso Translator autônomo) é necessário para usar esse recurso.

Configuração de solicitação

  • Usar o parâmetro translateTextWithinImage opcional no campo options

    • Tipo de dados: booliano (true ou false)
    • A configuração booliana padrão é false. Defina a opção como true para habilitar a tradução de texto de imagem.

  • Detalhes da resposta. Quando o recurso está habilitado, as informações de processamento de imagem adicionadas são incluídas com a resposta:

    • totalImageScansSucceeded. O número de verificações de imagem traduzidas com êxito.

    • totalImageScansFailed. O número de verificações de imagem que falharam no processamento.

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
  • basePath
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (job ID)

Localizando o valor id

  • Você pode encontrar o trabalho id no valor da URL Operation-Location do cabeçalho de resposta start-batch-translation do método POST. A cadeia de caracteres alfanumérica seguindo o parâmetro /document/ é o trabalho da operaçãoid:
Cabeçalho de resposta URL da Resposta
Operation-Location {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date}
  • Você também pode usar uma solicitação get-translations-status para recuperar uma lista de trabalhos de tradução e seus ids.

Iniciar a tradução assíncrona em lote


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


    class Program
    {

        static readonly string route = "?api-version={date}";

        private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";

        private static readonly string key = "{your-api-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(basePath + 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 documento compatíveis

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 basePath = "{your-document-translation-endpoint}/translator/document/formats";

    static readonly string route = "?api-version={date}&type=document";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(basePath + 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 o status de um trabalho de tradução

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 basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(basePath + 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 o status de um documento específico

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 basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(basePath + 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 basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Delete;
                request.RequestUri = new Uri(basePath + 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.
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