Biblioteca de clientes de Tradução de Documentos dos Serviços Cognitivos do Azure para .NET – versão 1.0.0

Artigo
04/27/2023

A Tradução de Documentos dos Serviços Cognitivos do Azure é um serviço de nuvem que converte documentos de e para 90 idiomas e dialetos, preservando a estrutura do documento e o formato de dados. Use a biblioteca de clientes para Tradução de Documentos para:

Traduza vários arquivos grandes de um contêiner de Armazenamento de Blobs do Azure para um contêiner de destino em seu idioma de escolha.
Verifique o status de tradução e o progresso de cada documento na operação de tradução.
Aplique um modelo de tradução personalizado ou glossários para personalizar a tradução para seu caso específico.

Código-fonte | Pacote (NuGet) | Documentação | de referência da API Documentação do produto | Amostras

Introdução

Instalar o pacote

Instale a biblioteca de clientes da Tradução de Documentos do Azure para .NET com o NuGet:

dotnet add package Azure.AI.Translation.Document

Observação: essa versão da biblioteca de clientes usa como padrão a v1.0 versão do serviço.

Pré-requisitos

Uma assinatura do Azure.
Um recurso do Tradutor existente.

Criar um recurso Tradutor

A Tradução de Documentos dá suporte apenas ao acesso de serviço único . Para acessar o serviço, crie um recurso de Tradutor.

Você pode criar qualquer recurso usando:

Opção 1:Portal do Azure.

Opção 2:CLI do Azure.

Veja abaixo um exemplo de como você pode criar um recurso de Tradutor usando a CLI:

# Create a new resource group to hold the Translator resource -
# if using an existing resource group, skip this step
az group create --name <your-resource-name> --location <location>

# Create Translator
az cognitiveservices account create \
    --name <your-resource-name> \
    --custom-domain <your-resource-name> \
    --resource-group <your-resource-group-name> \
    --kind TextTranslation \
    --sku S1 \
    --location <location> \
    --yes

Para obter mais informações sobre como criar o recurso ou como obter as informações de localização, consulte aqui.

Autenticar o cliente

Para interagir com o serviço de Tradução de Documentos, você precisará criar uma instância da classe DocumentTranslationClient . Você precisará de um ponto de extremidade e uma chave de API ou TokenCredential para instanciar um objeto cliente. Para obter mais informações sobre como autenticar com serviços cognitivos, consulte Autenticar solicitações nos Serviços Cognitivos do Azure.

Pesquisando o ponto de extremidade

Para Tradução de Documentos, você precisará usar um ponto de extremidade Custom Domain usando o nome do recurso tradutor.

Obter chave de API

Você pode obter as API key informações do recurso Tradutor no Portal do Azure.

Como alternativa, use o snippet da CLI do Azure abaixo para obter a chave de API do recurso Tradutor.

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Criar DocumentTranslationClient com credencial de chave de API

Depois de ter o valor da chave de API, crie um AzureKeyCredential. Isso permitirá que você atualize a chave de API sem criar um novo cliente.

Com o valor do ponto de extremidade e um AzureKeyCredential, você pode criar o DocumentTranslationClient:

string endpoint = "<Document Translator Resource Endpoint>";
string apiKey = "<Document Translator Resource API Key>";
var client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

Criar DocumentTranslationClient com a Credencial do Azure Active Directory

A autenticação de chave de API do cliente é usada na maioria dos exemplos neste guia de introdução, mas você também pode autenticar com o Azure Active Directory usando a biblioteca de Identidade do Azure. Observe que os pontos de extremidade regionais não dão suporte à autenticação do AAD.

Crie um subdomínio personalizado para o recurso para usar esse tipo de autenticação.

Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, instale o pacote Azure.Identity:

dotnet add package Azure.Identity

Você também precisará registrar um novo aplicativo do AAD e conceder acesso ao recurso tradutor atribuindo a "Cognitive Services User" função à entidade de serviço.

Defina os valores do client ID, tenant IDe client secret do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, . AZURE_CLIENT_SECRET

string endpoint = "<Document Translator Resource Endpoint>";
var client = new DocumentTranslationClient(new Uri(endpoint), new DefaultAzureCredential());

Principais conceitos

O serviço de Tradução de Documentos exige que você carregue seus arquivos em um contêiner de origem Armazenamento de Blobs do Azure e forneça um contêiner de destino em que os documentos traduzidos possam ser gravados. Os tokens SAS para os contêineres (ou arquivos) são usados para acessar os documentos e criar os documentos traduzidos no contêiner de destino. Informações adicionais sobre como configurar isso podem ser encontradas na documentação do serviço:

Configure Armazenamento de Blobs do Azure contêineres com seus documentos.
Opcionalmente, aplique glossários ou um modelo personalizado para tradução.
Gere tokens SAS para seus contêineres (ou arquivos) com as permissões apropriadas.

DocumentTranslationClient

Um DocumentTranslationClient é a interface principal para desenvolvedores que usam a biblioteca de clientes de Tradução de Documentos. Ele fornece métodos síncronos e assíncronos para executar as seguintes operações:

Criando uma operação de tradução para traduzir documentos em seus contêineres de origem e gravar resultados para os contêineres de destino.
Enumerando todas as operações de tradução passadas e atuais.
Identificando os formatos de glossário e documento com suporte.

Entrada de tradução

Para iniciar uma operação de tradução, você precisa criar uma instância ou uma lista de DocumentTranslationInput.

Uma ÚNICA URL de origem para documentos pode ser convertida em vários idiomas diferentes:

Uri sourceSasUri = new Uri("<source SAS URI>");
Uri frenchTargetSasUri = new Uri("<french target SAS URI>");
var input = new DocumentTranslationInput(sourceSasUri, frenchTargetSasUri, "fr");

Ou várias fontes diferentes podem ser fornecidas cada uma com seus próprios destinos.

Uri arabicTargetSasUri = new Uri("<arabic target SAS URI>");
Uri spanishTargetSasUri = new Uri("<spanish target SAS URI>");
Uri source1SasUri = new Uri("<source1 SAS URI>");
Uri source2SasUri = new Uri("<source2 SAS URI>");

var inputs = new List<DocumentTranslationInput>
{
    new DocumentTranslationInput(source1SasUri, spanishTargetSasUri, "es"),
    new DocumentTranslationInput(
        source: new TranslationSource(source2SasUri),
        targets: new List<TranslationTarget>
        {
            new TranslationTarget(frenchTargetSasUri, "fr"),
            new TranslationTarget(arabicTargetSasUri, "ar")
        }),
};

Observe que os documentos gravados em um contêiner de destino devem ter nomes exclusivos. Portanto, você não pode converter um contêiner de origem em um contêiner de destino duas vezes ou ter fontes com os mesmos documentos convertidos no mesmo contêiner de destino.

Operações de Long-Running

A Tradução de Documentos é implementada como uma operação de execução prolongada. As operações de execução prolongada consistem em uma solicitação inicial enviada ao serviço para iniciar uma operação, seguida por sondar o serviço em intervalos para determinar se a operação foi concluída com êxito ou falhou.

Para operações de execução prolongada no SDK do Azure, o cliente expõe um Start<operation-name> método que retorna um PageableOperation<T>. Você pode usar o método WaitForCompletionAsync() de extensão para aguardar a conclusão da operação e obter seu resultado. Um snippet de código de exemplo é fornecido para ilustrar o uso de operações de execução prolongada abaixo.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Exemplos

A seção a seguir fornece vários snippets de código usando o clientcriado acima e aborda as funções main da Tradução de Documentos. Observação: nosso DocumentTranslationClient fornece métodos síncronos e assíncronos.

Exemplos assíncronos

Iniciar a tradução de forma assíncrona
Histórico de operações de forma assíncrona
Várias entradas de forma assíncrona

Exemplos de sincronização

Observação: nosso DocumentTranslationClient fornece métodos síncronos e assíncronos.

Iniciar Tradução

Iniciar a tradução de forma assíncrona

Inicie uma operação de tradução para traduzir documentos no contêiner de origem e gravar os arquivos traduzidos no contêiner de destino. DocumentTranslationOperationpermite sondar o status da operação de tradução e obter o status dos documentos individuais.

Uri sourceUri = new Uri("<source SAS URI>");
Uri targetUri = new Uri("<target SAS URI>");
var input = new DocumentTranslationInput(sourceUri, targetUri, "es");

DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

await operation.WaitForCompletionAsync();

Console.WriteLine($"  Status: {operation.Status}");
Console.WriteLine($"  Created on: {operation.CreatedOn}");
Console.WriteLine($"  Last modified: {operation.LastModified}");
Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

await foreach (DocumentStatusResult document in operation.Value)
{
    Console.WriteLine($"Document with Id: {document.Id}");
    Console.WriteLine($"  Status:{document.Status}");
    if (document.Status == DocumentTranslationStatus.Succeeded)
    {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language code: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
    }
    else
    {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
    }
}

Obter histórico de operações de forma assíncrona

Obter Histórico de operações de tradução enviadas dos últimos 7 dias. O parâmetro de opções poderá ser omitido se o usuário quiser retornar todas as operações enviadas.

int operationsCount = 0;
int totalDocs = 0;
int docsCanceled = 0;
int docsSucceeded = 0;
int docsFailed = 0;

DateTimeOffset lastWeekTimestamp = DateTimeOffset.Now.AddDays(-7);

var options = new GetTranslationStatusesOptions
{
    CreatedAfter = lastWeekTimestamp
};

await foreach (TranslationStatusResult translationStatus in client.GetTranslationStatusesAsync(options))
{
    if (translationStatus.Status == DocumentTranslationStatus.NotStarted ||
        translationStatus.Status == DocumentTranslationStatus.Running)
    {
        DocumentTranslationOperation operation = new DocumentTranslationOperation(translationStatus.Id, client);
        await operation.WaitForCompletionAsync();
    }

    operationsCount++;
    totalDocs += translationStatus.DocumentsTotal;
    docsCanceled += translationStatus.DocumentsCanceled;
    docsSucceeded += translationStatus.DocumentsSucceeded;
    docsFailed += translationStatus.DocumentsFailed;
}

Console.WriteLine($"# of operations: {operationsCount}");
Console.WriteLine($"Total Documents: {totalDocs}");
Console.WriteLine($"Succeeded Document: {docsSucceeded}");
Console.WriteLine($"Failed Document: {docsFailed}");
Console.WriteLine($"Canceled Documents: {docsCanceled}");

Iniciar a tradução com várias entradas de forma assíncrona

Inicie uma operação de tradução para traduzir documentos em vários contêineres de origem para vários contêineres de destino em idiomas diferentes. DocumentTranslationOperationpermite sondar o status da operação de tradução e obter o status dos documentos individuais.

Uri source1SasUri = new Uri("<source1 SAS URI>");
Uri source2SasUri = new Uri("<source2 SAS URI>");
Uri frenchTargetSasUri = new Uri("<french target SAS URI>");
Uri arabicTargetSasUri = new Uri("<arabic target SAS URI>");
Uri spanishTargetSasUri = new Uri("<spanish target SAS URI>");
Uri frenchGlossarySasUri = new Uri("<french glossary SAS URI>");

var glossaryFormat = "TSV";

var input1 = new DocumentTranslationInput(source1SasUri, frenchTargetSasUri, "fr", new TranslationGlossary(frenchGlossarySasUri, glossaryFormat));
input1.AddTarget(spanishTargetSasUri, "es");

var input2 = new DocumentTranslationInput(source2SasUri, arabicTargetSasUri, "ar");
input2.AddTarget(frenchTargetSasUri, "fr", new TranslationGlossary(frenchGlossarySasUri, glossaryFormat));

var inputs = new List<DocumentTranslationInput>()
    {
        input1,
        input2
    };

DocumentTranslationOperation operation = await client.StartTranslationAsync(inputs);

await operation.WaitForCompletionAsync();

await foreach (DocumentStatusResult document in operation.GetValuesAsync())
{
    Console.WriteLine($"Document with Id: {document.Id}");
    Console.WriteLine($"  Status:{document.Status}");
    if (document.Status == DocumentTranslationStatus.Succeeded)
    {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language code: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
    }
    else
    {
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
    }
}

Iniciar Tradução

Uri sourceUri = new Uri("<source SAS URI>");
Uri targetUri = new Uri("<target SAS URI>");
var input = new DocumentTranslationInput(sourceUri, targetUri, "es");

DocumentTranslationOperation operation = client.StartTranslation(input);

TimeSpan pollingInterval = new(1000);

while (true)
{
    operation.UpdateStatus();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    if (operation.HasCompleted)
    {
        break;
    }
    else
    {
        if (operation.GetRawResponse().Headers.TryGetValue("Retry-After", out string value))
        {
            pollingInterval = TimeSpan.FromSeconds(Convert.ToInt32(value));
        }
        Thread.Sleep(pollingInterval);
    }
}

foreach (DocumentStatusResult document in operation.GetValues())
{
    Console.WriteLine($"Document with Id: {document.Id}");
    Console.WriteLine($"  Status:{document.Status}");
    if (document.Status == DocumentTranslationStatus.Succeeded)
    {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language code: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
    }
    else
    {
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
    }
}

Solução de problemas

Geral

Quando você interage com a biblioteca de clientes de Tradução de Documentos dos Serviços Cognitivos usando o SDK do .NET, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações de API REST.

Por exemplo, se você enviar uma solicitação com uma lista de destinos vazia, um 400 erro será retornado, indicando "Solicitação Incorreta".

var invalidInput = new DocumentTranslationInput(new TranslationSource(new Uri(endpoint)), new List<TranslationTarget>());

try
{
    DocumentTranslationOperation operation = client.StartTranslation(invalidInput);
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Você observará que informações adicionais são registradas, como a ID de solicitação do cliente da operação.

Message:
    Azure.RequestFailedException: Service request failed.
    Status: 400 (Bad Request)

Content:
    {"error":{"code":"InvalidRequest","message":"No translation target found.","target":"TargetInput","innerError":{"code":"NoTranslationTargetFound","message":"No translation target found."}}}

Headers:
    Transfer-Encoding: chunked
    X-RequestId: REDACTED
    Content-Type: application/json; charset=utf-8
    Set-Cookie: REDACTED
    X-Powered-By: REDACTED
    apim-request-id: REDACTED
    Strict-Transport-Security: REDACTED
    x-content-type-options: REDACTED
    Date: Mon, 22 Mar 2021 11:54:58 GMT

Configuração do registro em log do console

A maneira mais simples de ver os logs é habilitar o log do console. Para criar um ouvinte de log do SDK do Azure que gera mensagens para o console, use o método AzureEventSourceListener.CreateConsoleLogger.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Para saber mais sobre outros mecanismos de registro em log, confira aqui.

Próximas etapas

Exemplos mostrando como usar a biblioteca de Tradução de Documentos dos Serviços Cognitivos estão disponíveis neste repositório GitHub.

Exemplos avançados

Participante

Consulte a CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões

Compartilhar via