Bibliothèque cliente de traduction de documents Azure Cognitive Services pour .NET - version 1.0.0

Article
04/26/2023

La traduction de documents Azure Cognitive Services est un service cloud qui traduit des documents vers et à partir de 90 langues et dialectes tout en préservant la structure et le format des données du document. Utilisez la bibliothèque cliente pour la traduction de documents pour :

Traduire de nombreux fichiers volumineux d’un conteneur Stockage Blob Azure vers un conteneur cible dans la langue de votre choix.
Vérifiez la status de traduction et la progression de chaque document dans l’opération de traduction.
Appliquez un modèle de traduction personnalisé ou des glossaires pour adapter la traduction à votre cas spécifique.

| Code source Package (NuGet) | Documentation de référence sur les | API | Documentation produit Échantillons

Prise en main

Installer le package

Installez la bibliothèque cliente De traduction de documents Azure pour .NET avec NuGet :

dotnet add package Azure.AI.Translation.Document

Remarque : cette version de la bibliothèque cliente utilise par défaut la v1.0 version du service.

Prérequis

Un abonnement Azure.
Une ressource Translator existante.

Créer une ressource pour Translator

La traduction de documents prend uniquement en charge l’accès à un seul service . Pour accéder au service, créez une ressource Translator.

Vous pouvez créer l’une ou l’autre des ressources à l’aide de :

Option 1 :Portail Azure.

Option 2 :Azure CLI.

Voici un exemple de création d’une ressource Translator à l’aide de l’interface 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

Pour plus d’informations sur la création de la ressource ou sur la façon d’obtenir les informations d’emplacement , consultez ici.

Authentifier le client

Pour interagir avec le service De traduction de documents, vous devez créer une instance de la classe DocumentTranslationClient. Vous aurez besoin d’un point de terminaison et d’une clé API ou TokenCredential pour instancier un objet client. Pour plus d’informations sur l’authentification auprès de Cognitive Services, consultez Authentifier les demandes auprès d’Azure Cognitive Services.

Recherche du point de terminaison

Pour la traduction de documents, vous devez utiliser un point de terminaison Custom Domain en utilisant le nom de votre ressource Translator.

Obtenir la clé API

Vous pouvez obtenir le API key à partir des informations de ressource Translator dans le portail Azure.

Vous pouvez également utiliser l’extrait de code Azure CLI ci-dessous pour obtenir la clé API à partir de la ressource Translator.

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

Créer DocumentTranslationClient avec les informations d’identification de clé API

Une fois que vous avez la valeur de la clé API, créez un AzureKeyCredential. Cela vous permettra de mettre à jour la clé API sans créer de client.

Avec la valeur du point de terminaison et d’un AzureKeyCredential, vous pouvez créer le DocumentTranslationClient :

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

Créer DocumentTranslationClient avec les informations d’identification Azure Active Directory

L’authentification par clé API cliente est utilisée dans la plupart des exemples de ce guide de prise en main, mais vous pouvez également vous authentifier auprès d’Azure Active Directory à l’aide de la bibliothèque Azure Identity. Notez que les points de terminaison régionaux ne prennent pas en charge l’authentification AAD.

Créez un sous-domaine personnalisé pour votre ressource afin d’utiliser ce type d’authentification.

Pour utiliser le fournisseur DefaultAzureCredential indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le package Azure.Identity :

dotnet add package Azure.Identity

Vous devez également inscrire une nouvelle application AAD et accorder l’accès à votre ressource Translator en attribuant le "Cognitive Services User" rôle à votre principal de service.

Définissez les valeurs de , client IDtenant IDet client secret de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, . AZURE_CLIENT_SECRET

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

Concepts clés

Le service De traduction de documents vous demande de charger vos fichiers dans un conteneur source Stockage Blob Azure et de fournir un conteneur cible dans lequel les documents traduits peuvent être écrits. Les jetons SAP des conteneurs (ou fichiers) sont utilisés pour accéder aux documents et créer les documents traduits dans le conteneur cible. Pour plus d’informations sur cette configuration, consultez la documentation du service :

Configurez Stockage Blob Azure conteneurs avec vos documents.
Appliquez éventuellement des glossaires ou un modèle personnalisé pour la traduction.
Générez des jetons SAP pour vos conteneurs (ou fichiers) avec les autorisations appropriées.

DocumentTranslationClient

A DocumentTranslationClient est l’interface principale pour les développeurs qui utilisent la bibliothèque cliente De traduction de documents. Il fournit des méthodes synchrones et asynchrones pour effectuer les opérations suivantes :

Création d’une opération de traduction pour traduire des documents dans vos conteneurs sources et écrire les résultats dans les conteneurs cibles.
Énumération de toutes les opérations de traduction passées et actuelles.
Identification des formats de glossaire et de document pris en charge.

Entrée de traduction

Pour démarrer une opération de traduction, vous devez créer un instance ou une liste de DocumentTranslationInput.

Une URL source unique vers des documents peut être traduite dans de nombreuses langues différentes :

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

Ou plusieurs sources différentes peuvent être fournies chacune avec leurs propres cibles.

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")
        }),
};

Notez que les documents écrits dans un conteneur cible doivent avoir des noms uniques. Vous ne pouvez donc pas traduire deux fois un conteneur source en conteneur cible ou faire traduire des sources avec les mêmes documents dans le même conteneur cible.

opérations Long-Running

La traduction de documents est implémentée en tant qu’opération de longue durée. Les opérations de longue durée se composent d’une demande initiale envoyée au service pour démarrer une opération, suivie d’un interrogation du service à intervalles réguliers pour déterminer si l’opération s’est terminée avec succès ou a échoué.

Pour les opérations de longue durée dans le Kit de développement logiciel (SDK) Azure, le client expose une Start<operation-name> méthode qui retourne un PageableOperation<T>. Vous pouvez utiliser la méthode WaitForCompletionAsync() d’extension pour attendre que l’opération se termine et obtenir son résultat. Un exemple d’extrait de code est fourni pour illustrer l’utilisation d’opérations de longue durée ci-dessous.

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Exemples

La section suivante fournit plusieurs extraits de code à l’aide de ce client qui a été créé ci-dessus et couvre les fonctions main de la traduction de documents. Remarque : notre DocumentTranslationClient offre des méthodes synchrones et asynchrones.

Exemples asynchrones

Démarrer la traduction de manière asynchrone
Historique des opérations de manière asynchrone
Entrées multiples de manière asynchrone

Exemples de synchronisation

Remarque : notre DocumentTranslationClient offre des méthodes synchrones et asynchrones.

Démarrer la traduction

Démarrer la traduction de manière asynchrone

Démarrez une opération de traduction pour traduire des documents dans le conteneur source et écrivez les fichiers traduits dans le conteneur cible. DocumentTranslationOperationvous permet d’interroger les status de l’opération de traduction et d’obtenir les status des documents individuels.

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}");
    }
}

Obtenir l’historique des opérations de manière asynchrone

Obtenir l’historique des opérations de traduction envoyées des 7 derniers jours. Le paramètre options peut être omis si l’utilisateur souhaite retourner toutes les opérations soumises.

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}");

Démarrer la traduction avec plusieurs entrées de manière asynchrone

Démarrez une opération de traduction pour traduire des documents dans plusieurs conteneurs sources en plusieurs conteneurs cibles dans différentes langues. DocumentTranslationOperationvous permet d’interroger les status de l’opération de traduction et d’obtenir les status des documents individuels.

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}");
    }
}

Démarrer la traduction

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}");
    }
}

Dépannage

Général

Lorsque vous interagissez avec la bibliothèque cliente De traduction de documents Cognitive Services à l’aide du KIT de développement logiciel (SDK) .NET, les erreurs retournées par le service correspondent aux mêmes codes status HTTP retournés pour les demandes d’API REST.

Par exemple, si vous envoyez une requête avec une liste de cibles vide, une 400 erreur est retournée, indiquant « Demande incorrecte ».

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());
}

Vous remarquerez que des informations supplémentaires sont enregistrées, telles que l’ID de demande client de l’opération.

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

Configuration de la journalisation de la console

Le moyen le plus simple de voir les journaux consiste à activer la journalisation de la console. Pour créer un écouteur de journal du Kit de développement logiciel (SDK) Azure qui génère des messages dans la console, utilisez la méthode AzureEventSourceListener.CreateConsoleLogger.

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

Pour en savoir plus sur les autres mécanismes de journalisation , consultez ici.

Étapes suivantes

Des exemples montrant comment utiliser la bibliothèque de traduction de documents Cognitive Services sont disponibles dans ce dépôt GitHub.

Exemples avancés

Contribution

Consultez la CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions

Partager via