Erste Schritte bei der Dokumentübersetzung

In diesem Artikel wird beschrieben, wie Sie die Dokumentübersetzung mit HTTP-REST-API-Methoden verwenden. Die Dokumentübersetzung ist ein cloudbasiertes Feature des Azure-Textübersetzungsdiensts. Die API für die Dokumentübersetzung ermöglicht die Übersetzung gesamter Dokumente unter Beibehaltung der Struktur und Textformatierung des Quelldokuments.

Voraussetzungen

Hinweis

  • Beim Erstellen einer Cognitive Services-Ressource im Azure-Portal haben Sie normalerweise die Möglichkeit, einen Schlüssel für mehrere Dienste oder nur für einen Dienst zu erstellen. Dokumentübersetzung wird derzeit aber nur für die Textübersetzungsressource (einzelner Dienst) unterstützt und ist nicht in der Cognitive Services-Ressource (mehrere Dienste) enthalten.

  • Die Dokumentübersetzung wird nur im Diensttarif „S1 Standard“ (nutzungsbasierte Bezahlung) oder im Tarif „D3 Volume Discount“ (Volumenrabatt) unterstützt. Weitere Informationen finden Sie unterCognitive Services-Preise – Translator.

Zunächst benötigen Sie Folgendes:

  • Ein aktives Azure-Konto. Falls Sie noch kein Konto haben, können Sie ein kostenloses Konto erstellen.

  • Ein Azure Blob Storage-Konto. Sie erstellen Container zum Speichern und Organisieren Ihrer Blobdaten unter Ihrem Speicherkonto.

  • Eine Textübersetzungsressource in Form eines einzelnen Diensts (keine Cognitive Services-Ressource mit mehreren Diensten):

    Füllen Sie die Felder zu Projekt- und Instanzdetails für die Textübersetzung wie folgt aus:

    1. Abonnement: Wählen Sie eines Ihrer verfügbaren Azure-Abonnements aus.

    2. Ressourcengruppe: Sie können eine neue Ressourcengruppe erstellen oder Ihre Ressource zu einer bereits vorhandenen Ressourcengruppe hinzufügen, die denselben Lebenszyklus, dieselben Berechtigungen und dieselben Richtlinien aufweist.

    3. Ressourcenregion: Wählen Sie die Option Global aus, es sei denn, Ihr Unternehmen oder Ihre Anwendung erfordert eine spezifische Region. Wenn Sie planen, eine systemseitig zugewiesene verwaltete Identität für die Authentifizierung zu verwenden, wählen Sie eine nicht globale Region aus.

    4. Name. Geben Sie den Namen ein, den Sie für Ihre Ressource ausgewählt haben. Der ausgewählte Name muss innerhalb von Azure eindeutig sein.

      Hinweis

      Die Dokumentübersetzung erfordert einen benutzerdefinierten Domänenendpunkt. Der Wert, den Sie in das Feld „Name“ eingeben, ist der benutzerdefinierte Domänennamenparameter für Ihren Endpunkt.

    5. Tarif: Die Dokumentübersetzung wird im Free-Tarif nicht unterstützt. Wählen Sie den Tarif Standard S1 aus, um den Dienst auszuprobieren.

    6. Klicken Sie auf Überprüfen + erstellen.

    7. Lesen Sie die Nutzungsbedingungen, und klicken Sie auf Erstellen, um Ihre Ressource bereitzustellen.

    8. Nachdem Ihre Ressource erfolgreich bereitgestellt wurde, klicken Sie auf Zu Ressource wechseln.

Ihr benutzerdefinierter Domänenname und Schlüssel

Wichtig

  • Für alle API-Anforderungen an den Dienst für die Dokumentübersetzung muss ein Endpunkt einer benutzerdefinierten Domäne verwendet werden.
  • Zum Senden von HTTP-Anforderungen für die Dokumentübersetzung verwenden Sie nicht den Endpunkt, der im Azure-Portal auf der Ressourcenseite Schlüssel und Endpunkt angegeben ist, und auch nicht den globalen Übersetzungsendpunkt api.cognitive.microsofttranslator.com.

Was ist der Endpunkt einer benutzerdefinierten Domäne?

Der Endpunkt einer benutzerdefinierten Domäne ist eine URL, die mit Ihrem Ressourcennamen, Hostnamen und den Unterverzeichnissen für die Textübersetzung formatiert ist:

https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0

Ermitteln des Namens Ihrer benutzerdefinierten Domäne

Der Parameter NAME-OF-YOUR-RESOURCE (auch als Name der benutzerdefinierten Domäne bezeichnet) steht hier für den Wert, den Sie beim Erstellen Ihrer Textübersetzungsressource im Feld Name eingegeben haben.

Image of the Azure portal, create resource, instant details, name field.

Ihren Schlüssel abrufen

Für Anforderungen, die an den Textübersetzungsdienst gesendet werden, wird ein schreibgeschützter Schlüssel für die Authentifizierung des Zugriffs benötigt.

  1. Wählen Sie Zu Ressource wechseln aus, nachdem eine von Ihnen erstellte neue Ressource bereitgestellt wurde. Navigieren Sie direkt zu Ihrer Ressourcenseite, falls Sie über eine vorhandene Ressource für die Dokumentübersetzung verfügen.
  2. Klicken Sie in der linken Schiene unter Ressourcenverwaltung auf Schlüssel und Endpunkt.
  3. Kopieren Sie Ihren Schlüssel, und fügen Sie ihn an einem geeigneten Ort ein, z. B. in den Editor von Microsoft.
  4. Sie fügen ihn dann in den folgenden Code ein, um Ihre Anforderung für den Dokumentübersetzungsdienst zu authentifizieren.

Image of the get your key field in Azure portal.

Erstellen des Azure Blob Storage-Containers

Für Quell- und Zieldateien müssen Sie in Ihrem Azure-BlobspeicherkontoContainer erstellen.

  • Quellcontainer: In diesen Container laden Sie Ihre Dateien für die Übersetzung hoch (erforderlich).
  • Zielcontainer: In diesem Container werden Ihre übersetzten Dateien gespeichert (erforderlich).

Hinweis

Die Dokumentübersetzung unterstützt Glossare als Blobs in Zielcontainern (keine separaten Glossarcontainer). Wenn Sie ein benutzerdefiniertes Glossar hinzufügen möchten, fügen Sie es dem Zielcontainer hinzu, und fügen Sie das glossaryUrl in die Anforderung ein. Wenn das Übersetzungssprachpaar nicht im Glossar vorhanden ist, wird es nicht angewendet. SieheÜbersetzen von Dokumente mithilfe von benutzerdefinierten Glossaren

Erstellen von SAS-Zugriffstoken für die Dokumentübersetzung

Die URLs sourceUrl, targetUrl und glossaryUrl (optional) müssen ein SAS-Token (Shared Access Signature) enthalten, das als Abfragezeichenfolge angefügt ist. Das Token kann Ihrem Container oder bestimmten Blobs zugewiesen sein. SieheErstellen von SAS-Token für die Verarbeitung der Dokumentübersetzung.

  • Ihr Quellcontainer oder Blob muss über Zugriff vom Typ Lesen und Auflisten verfügen.
  • Ihr Zielcontainer oder Blob muss über Zugriff vom Typ Schreiben und Auflisten verfügen.
  • Ihr Glossar-Blob muss über Zugriff vom Typ Lesen und Auflisten verfügen.

Tipp

  • Falls Sie mehrere Dateien (Blobs) während eines Vorgangs übersetzen, sollten Sie den SAS-Zugriff auf Containerebene delegieren.
  • Falls Sie nur eine Datei (Blob) während eines Vorgangs übersetzen, sollten Sie den SAS-Zugriff auf Blobebene delegieren.
  • Als Alternative zu SAS-Token können Sie eine systemseitig zugewiesene verwaltete Identität Identität für die Authentifizierung verwenden.

HTTP-Anforderungen

Eine Batchanforderung für die Dokumentübersetzung wird als POST-Anforderung an Ihren Endpunkt mit dem Textübersetzungsdienst gesendet. Wenn der Vorgang erfolgreich ist, gibt die POST-Methode den Antwortcode 202 Accepted zurück, und die Batchanforderung wird vom Dienst erstellt. Die übersetzten Dokumente werden in Ihrem Zielcontainer aufgeführt.

HTTP-Header

Jede Anforderung der API für die Dokumentübersetzung enthält die folgenden Header:

HTTP-Header BESCHREIBUNG
Ocp-Apim-Subscription-Key Erforderlich: Dieser Wert ist der Azure-Schlüssel für Ihre Textübersetzungs- oder Cognitive Services-Ressource.
Content-Type Erforderlich: Gibt den Inhaltstyp der Nutzdaten an. „application/json“ oder „charset=UTF-8“ werden als Werte akzeptiert.

Eigenschaften des POST-Anforderungstexts

  • Die URL für die POST-Anforderung lautet: POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches.
  • Der POST-Anforderungstext ist ein JSON-Objekt mit dem Namen inputs.
  • Das Objekt inputs enthält die Adressen beider Container sourceURL und targetURL für Ihre Quell- und Zielsprachpaare.
  • prefix und suffix sind Zeichenfolgen mit Beachtung der Groß-/Kleinschreibung zum Filtern von Dokumenten im Quellpfad für die Übersetzung. Das Feld prefix wird häufig verwendet, um Unterordner für die Übersetzung anzugeben. Das Feld suffix wird am häufigsten für Dateierweiterungen verwendet.
  • Ein Wert für das Feld glossaries (optional) wird angewendet, wenn das Dokument übersetzt wird.
  • Die targetUrl für die einzelnen Zielsprachen muss jeweils eindeutig sein.

Hinweis

Wenn am Ziel bereits eine Datei mit dem gleichen Namen vorhanden ist, tritt beim Auftrag ein Fehler auf.

Übersetzen aller Dokumente in einem Container

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Übersetzen eines bestimmten Dokuments in einen Container

  • Geben Sie "storageType": "File" an.
  • Wenn Sie keine systemseitig zugewiesene verwaltete Identität für die Authentifizierung verwenden, stellen Sie sicher, dass Sie das URL- und SAS-Quelltoken für das spezifische Blob/Dokument (nicht für den Container) erstellt haben.
  • Stellen Sie sicher, dass Sie den Zieldateinamen als Teil der Ziel-URL angegeben haben – obwohl das SAS-Token für den Container noch immer vorhanden ist.
  • Die Beispielanforderung unten zeigt, wie ein einzelnes Dokument in zwei Zielsprachen übersetzt wird.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

Übersetzen von Dokumente mithilfe von benutzerdefinierten Glossaren

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://myblob.blob.core.windows.net/source",
             },
            "targets": [
                {
                    "targetUrl": "https://myblob.blob.core.windows.net/target",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https:// myblob.blob.core.windows.net/glossary/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Senden von Dokumentübersetzungsanforderungen mithilfe von Code

Einrichten der Codierungsplattform

  • Erstellen Sie ein neues Projekt.
  • Ersetzen Sie den Code in „Program.cs“ durch den unten abgebildeten C#-Code.
  • Legen Sie Ihre URL-Werte für den Endpunkt, Schlüssel und Container in Program.cs fest.
  • Fügen Sie für die Verarbeitung der JSON-Daten das Newtonsoft.Json-Paket mit der .NET CLI hinzu.
  • Führen Sie das Programm aus dem Projektverzeichnis aus.

Wichtig

Für die unten angegebenen Codebeispiele führen Sie für Ihren Schlüssel und Endpunkt das Hartcodieren durch, wo dies angegeben ist. Achten Sie darauf, den Schlüssel nach Abschluss des Vorgangs aus Ihrem Code zu entfernen und ihn nicht öffentlich zugänglich zu machen. Informationen zum sicheren Speichern und Zugreifen auf Ihre Anmeldeinformationen finden Sie unter Sicherheit von Azure Cognitive Services.

Je nach Vorgang müssen Sie ggf. die folgenden Felder aktualisieren:

  • endpoint
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (Auftrags-ID)

Ermitteln des Werts für id

  • Sie finden die id des Auftrags im URL-Wert Operation-Location des Antwortheaders der POST-Methode. Der letzte Parameter der URL ist die Auftrags-ID ( id ) des Vorgangs:
Antwortheader Ergebnis-URL
Operation-Location https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec
  • Sie können auch eine Anforderung zum Abrufen von Aufträgen (GET Jobs) verwenden, um die Auftrags-ID (id) für die Dokumentübersetzung zu ermitteln.

Übersetzen von Dokumenten


    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.0";

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

            }

        }

    }

Abrufen von Dateiformaten

Rufen Sie eine Liste mit den unterstützten Dateiformaten ab. Wenn der Vorgang erfolgreich ist, wird mit dieser Methode der Antwortcode 200 OK zurückgegeben.


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.0";

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

Abrufen des Auftragsstatus

Rufen Sie den aktuellen Status für einen bestimmten Auftrag und eine Zusammenfassung aller Aufträge in einer Anforderung der Dokumentübersetzung ab. Wenn der Vorgang erfolgreich ist, wird mit dieser Methode der Antwortcode 200 OK zurückgegeben.


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.0";

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

Abrufen des Dokumentstatus

Kurze Übersicht

Rufen Sie den Status eines bestimmten Dokuments in einer Anforderung der Dokumentübersetzung ab. Wenn der Vorgang erfolgreich ist, wird mit dieser Methode der Antwortcode 200 OK zurückgegeben.


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.0";

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

Auftrag löschen

Kurze Übersicht

Brechen Sie den derzeit ausgeführten oder einen in die Warteschlange eingereihten Auftrag ab. Nur Dokumente, für die die Übersetzung noch nicht gestartet wurde, werden abgebrochen.


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.0";

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

Grenzwerte für den Inhalt

In der folgenden Tabelle sind die Grenzwerte für Daten aufgelistet, die Sie an die Dokumentübersetzung senden können.

attribute Begrenzung
Dokumentgröße ≤ 40 MB
Gesamtzahl an Dateien ≤ 1.000
Gesamtgröße des Inhalts in einem Batch ≤ 250 MB
Anzahl von Zielsprachen in einem Batch ≤ 10
Größe der Übersetzungsspeicherdatei ≤ 10 MB

Die Dokumentübersetzung kann nicht verwendet werden, um geschützte Dokumente zu übersetzen, z. B. Dokumente mit einem verschlüsselten Kennwort oder eingeschränktem Zugriff zum Kopieren von Inhalten.

Problembehandlung

Allgemeine HTTP-Statuscodes

HTTP-Statuscode BESCHREIBUNG Mögliche Ursache
200 OK Die Anforderung wurde erfolgreich gesendet.
400 Ungültige Anforderung Ein erforderlicher Parameter fehlt, ist leer oder Null. Oder der an einen erforderlichen oder optionalen Parameter übergebene Wert ist ungültig. Ein häufiges Problem sind zu lange Kopfzeilen.
401 Nicht autorisiert Die Anforderung ist nicht autorisiert. Stellen Sie sicher, dass Ihr Schlüssel oder Token gültig ist und sich in der richtigen Region befindet. Achten Sie bei der Verwaltung Ihres Abonnements im Azure-Portal darauf, dass Sie die Textübersetzungsressource (einzelner Dienst) nutzen und nicht die Cognitive Services-Ressource (mehrere Dienste).
429 Zu viele Anforderungen Sie haben das Kontingent oder die zulässige Anforderungsrate für das Abonnement überschritten.
502 Ungültiges Gateway Netzwerk- oder serverseitiges Problem. Kann auch auf ungültige Header hinweisen.

Erfahren Sie mehr

Nächste Schritte