Azure Cognitive Services-Dokumentübersetzungsclientbibliothek für .NET– Version 1.0.0

Artikel
04/27/2023

Die Azure Cognitive Services-Dokumentübersetzung ist ein Clouddienst, der Dokumente in und aus 90 Sprachen und Dialekten übersetzt und dabei die Dokumentstruktur und das Datenformat beibehalten. Verwenden Sie die Clientbibliothek für die Dokumentübersetzung für Folgendes:

Übersetzen Sie zahlreiche große Dateien aus einem Azure Blob Storage Container in einen Zielcontainer in der Sprache Ihrer Wahl.
Überprüfen Sie die übersetzungs-status und den Fortschritt jedes Dokuments im Übersetzungsvorgang.
Wenden Sie ein benutzerdefiniertes Übersetzungsmodell oder Glossare an, um die Übersetzung an Ihren spezifischen Fall anzupassen.

Quellcode | Paket (NuGet) | API-Referenzdokumentation | Produktdokumentation | Proben

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Document Translation-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.AI.Translation.Document

Hinweis: Diese Version der Clientbibliothek verwendet standardmäßig die v1.0 Version des Diensts.

Voraussetzungen

Ein Azure-Abonnement.
Eine vorhandene Translator-Ressource.

Erstellen einer Translator-Ressource

Die Dokumentübersetzung unterstützt nur den Einzeldienstzugriff . Um auf den Dienst zuzugreifen, erstellen Sie eine Translator-Ressource.

Sie können eine Der folgenden Ressourcen erstellen:

Option 1:Azure-Portal.

Option 2:Azure CLI.

Im Folgenden finden Sie ein Beispiel dafür, wie Sie eine Translator-Ressource mithilfe der CLI erstellen können:

# 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

Weitere Informationen zum Erstellen der Ressource oder zum Abrufen der Standortinformationen finden Sie hier.

Authentifizieren des Clients

Um mit dem Dokumentübersetzungsdienst zu interagieren, müssen Sie eine instance der DocumentTranslationClient-Klasse erstellen. Sie benötigen einen Endpunkt und entweder einen API-Schlüssel oder TokenCredential zum Instanziieren eines Clientobjekts. Weitere Informationen zur Authentifizierung mit Cognitive Services finden Sie unter Authentifizieren von Anforderungen an Azure Cognitive Services.

Nachschlagen des Endpunkts

Für die Dokumentübersetzung müssen Sie einen Custom Domain Endpunkt verwenden, der den Namen Ihrer Translator-Ressource verwendet.

Api-Schlüssel abrufen

Sie können informationen API key aus der Translator-Ressource im Azure-Portal abrufen.

Alternativ können Sie den folgenden Azure CLI-Codeausschnitt verwenden, um den API-Schlüssel aus der Translator-Ressource abzurufen.

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

Erstellen von DocumentTranslationClient mit API-Schlüsselanmeldeinformationen

Sobald Sie über den Wert für den API-Schlüssel verfügen, erstellen Sie eine AzureKeyCredential. Dadurch können Sie den API-Schlüssel aktualisieren, ohne einen neuen Client zu erstellen.

Mit dem Wert des Endpunkts und einer AzureKeyCredentialkönnen Sie documentTranslationClient erstellen:

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

Erstellen von DocumentTranslationClient mit Azure Active Directory-Anmeldeinformationen

Die Client-API-Schlüsselauthentifizierung wird in den meisten Beispielen in diesem Leitfaden zu den ersten Schritten verwendet, aber Sie können sich auch mit Azure Active Directory mithilfe der Azure Identity-Bibliothek authentifizieren. Beachten Sie, dass regionale Endpunkte die AAD-Authentifizierung nicht unterstützen.

Erstellen Sie eine benutzerdefinierte Unterdomäne für Ihre Ressource, um diesen Authentifizierungstyp zu verwenden.

Installieren Sie das Azure.Identity-Paket, um den unten gezeigten DefaultAzureCredential-Anbieter oder andere Anmeldeinformationsanbieter zu verwenden, die mit dem Azure SDK bereitgestellt werden:

dotnet add package Azure.Identity

Sie müssen auch eine neue AAD-Anwendung registrieren und Zugriff auf Ihre Translator-Ressource gewähren, indem Sie die "Cognitive Services User" Rolle Ihrem Dienstprinzipal zuweisen.

Legen Sie die Werte von client ID, tenant IDund client secret der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

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

Wichtige Begriffe

Der Dokumentübersetzungsdienst erfordert, dass Sie Ihre Dateien in einen Azure Blob Storage Quellcontainer hochladen und einen Zielcontainer bereitstellen, in dem die übersetzten Dokumente geschrieben werden können. SAS-Token für die Container (oder Dateien) werden verwendet, um auf die Dokumente zuzugreifen und die übersetzten Dokumente im Zielcontainer zu erstellen. Weitere Informationen zum Einrichten finden Sie in der Dienstdokumentation:

Richten Sie Azure Blob Storage Container mit Ihren Dokumenten ein.
Wenden Sie optional Glossare oder ein benutzerdefiniertes Modell für die Übersetzung an.
Generieren Sie SAS-Token für Ihre Container (oder Dateien) mit den entsprechenden Berechtigungen.

DocumentTranslationClient

Eine DocumentTranslationClient ist die primäre Schnittstelle für Entwickler, die die Dokumentübersetzungs-Clientbibliothek verwenden. Es stellt sowohl synchrone als auch asynchrone Methoden bereit, um die folgenden Vorgänge auszuführen:

Erstellen eines Übersetzungsvorgangs, um Dokumente in Ihren Quellcontainern zu übersetzen und Ergebnisse in Ihre Zielcontainer zu schreiben.
Aufzählen aller vergangenen und aktuellen Übersetzungsvorgänge.
Identifizieren unterstützter Glossar- und Dokumentformate.

Übersetzungseingabe

Um einen Übersetzungsvorgang zu starten, müssen Sie eine instance oder eine Liste von DocumentTranslationInputerstellen.

Eine einzelne Quell-URL für Dokumente kann in viele verschiedene Sprachen übersetzt werden:

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

Oder mehrere verschiedene Quellen können jeweils mit eigenen Zielen bereitgestellt werden.

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

Beachten Sie, dass dokumente, die in einen Zielcontainer geschrieben werden, eindeutige Namen aufweisen müssen. Daher können Sie einen Quellcontainer nicht zweimal in einen Zielcontainer übersetzen oder Quellen mit denselben Dokumenten in denselben Zielcontainer übersetzen lassen.

Long-Running Vorgänge

Die Dokumentübersetzung wird als lang andauernder Vorgang implementiert. Vorgänge mit langer Ausführungsdauer bestehen aus einer anfänglichen Anforderung, die an den Dienst gesendet wird, um einen Vorgang zu starten, gefolgt von der Abfrage des Diensts in Intervallen, um festzustellen, ob der Vorgang erfolgreich abgeschlossen oder fehlgeschlagen ist.

Für Vorgänge mit langer Ausführungsdauer im Azure SDK macht der Client eine Start<operation-name> -Methode verfügbar, die eine PageableOperation<T>zurückgibt. Sie können die Erweiterungsmethode WaitForCompletionAsync() verwenden, um auf den Abschluss des Vorgangs zu warten und das Ergebnis zu erhalten. Ein Beispielcodeausschnitt wird bereitgestellt, um die Verwendung von Vorgängen mit langer Ausführungszeit unten zu veranschaulichen.

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und voneinander unabhängig sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Beispiele

Der folgende Abschnitt enthält mehrere Codeausschnitte, die das clientoben erstellte verwenden, und behandelt die Standard Funktionen der Dokumentübersetzung. Hinweis: unsere DocumentTranslationClient bietet sowohl synchrone als auch asynchrone Methoden.

Synchronisierungsbeispiele

Hinweis: unsere DocumentTranslationClient bietet sowohl synchrone als auch asynchrone Methoden.

Übersetzung starten

Asynchrones Starten der Übersetzung

Starten Sie einen Übersetzungsvorgang, um Dokumente im Quellcontainer zu übersetzen und die übersetzten Dateien in den Zielcontainer zu schreiben. DocumentTranslationOperationmit können Sie die status des Übersetzungsvorgangs abfragen und die status der einzelnen Dokumente abrufen.

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

Asynchrones Abrufen des Vorgangsverlaufs

Abrufen des Verlaufs der übermittelten Übersetzungsvorgänge der letzten 7 Tage. Der Optionsparameter kann nicht mehr angegeben werden, wenn der Benutzer alle übermittelten Vorgänge zurückgeben möchte.

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

Asynchrones Starten der Übersetzung mit mehreren Eingaben

Starten Sie einen Übersetzungsvorgang, um Dokumente in mehreren Quellcontainern in mehrere Zielcontainer in verschiedenen Sprachen zu übersetzen. DocumentTranslationOperationmit können Sie die status des Übersetzungsvorgangs abfragen und die status der einzelnen Dokumente abrufen.

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

Übersetzung starten

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

Problembehandlung

Allgemein

Wenn Sie mit der Clientbibliothek für die Cognitive Services-Dokumentübersetzung mithilfe des .NET SDK interagieren, entsprechen vom Dienst zurückgegebene Fehler denselben HTTP-status Codes, die für REST-API-Anforderungen zurückgegeben werden.

Wenn Sie beispielsweise eine Anforderung mit einer leeren Zielliste übermitteln, wird ein 400 Fehler zurückgegeben, der auf "Ungültige Anforderung" hinweist.

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

Sie werden feststellen, dass zusätzliche Informationen protokolliert werden, z. B. die Clientanforderungs-ID des Vorgangs.

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

Einrichten der Konsolenprotokollierung

Die einfachste Möglichkeit, die Protokolle anzuzeigen, besteht darin, die Konsolenprotokollierung zu aktivieren. Verwenden Sie die AzureEventSourceListener.CreateConsoleLogger-Methode, um einen Azure SDK-Protokolllistener zu erstellen, der Nachrichten an die Konsole ausgibt.

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

Weitere Informationen zu anderen Protokollierungsmechanismen finden Sie hier.

Nächste Schritte

Beispiele zur Verwendung der Cognitive Services-Dokumentübersetzungsbibliothek sind in diesem GitHub-Repository verfügbar.

Erweiterte Beispiele

Mitwirken

Ausführliche Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie im CONTRIBUTING.md .

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe

Freigeben über