Freigeben über

Programmgesteuertes Verwenden von REST-APIs

  • Artikel

Die Dokumentübersetzung ist ein cloudbasiertes Feature des Azure KI Übersetzer Service. Mit der Dokumentübersetzungs-API können Sie asynchron ganze Dokumente in unterstützte Sprachen und verschiedene Dateiformate übersetzen, wobei die Struktur und Textformatierung des Quelldokuments erhalten bleibt. In dieser Schrittanleitung erfahren Sie, wie Sie Dokumentübersetzungs-APIs mit einer Programmiersprache Ihrer Wahl und der HTTP-REST-API verwenden.

Voraussetzungen

Hinweis

Dokumentenübersetzung wird im S1 Standard Service Plan (nutzungsbasierte Zahlung) sowie in den C2-, C3-, C4- und D3-Volumenrabattplänen unterstützt. Siehe Preise für Azure KI Services – 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. Für Ihre Quell- und Zieldateien müssen Sie in Ihrem Azure Blob Storage-Konto auch Container 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).

  • Ressource für die Textübersetzung:

    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 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 geografische Region wie USA, Westen 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. Wählen Sie nach erfolgter Bereitstellung Ihrer Ressource Zu Ressource wechseln aus, um Ihren Schlüssel und den Endpunkt abzurufen.

Abrufen ihres Schlüssels und des Endpunkts für benutzerdefinierte Domänen

  • Für Anforderungen an den Übersetzungsdienst benötigen Sie einen schreibgeschützten Schlüssel und einen benutzerdefinierten Endpunkt zur Authentifizierung des Zugriffs. Der Endpunkt einer benutzerdefinierten Domäne ist eine URL, die mit Ihrem Ressourcennamen, Hostnamen und den Unterverzeichnissen für die Textübersetzung formatiert ist. Die URL ist im Azure-Portal verfügbar.

  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 key und document translation endpoint, und fügen Sie sie an einem geeigneten Ort ein, z. B. in den Editor von Microsoft. Für einen API-Aufruf ist nur ein Schlüssel erforderlich.

  4. Sie fügen key und document translation endpoint in die Codebeispiele ein, um Ihre Anforderung an den Dokumentübersetzungsdienst zu authentifizieren.

    Screenshot: Feld zum Abrufen Ihres Schlüssels im Azure-Portal

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 sie später in das Codebeispiel ein, um Ihre Anforderung an den Dokumentübersetzungsdienst zu authentifizieren.

Abbildung: Feld „Ihren Schlüssel abrufen“ im Azure-Portal

Erstellen von Azure Blob Storage-Containern

Für Quell- und Zieldateien müssen Sie in Ihrem Azure Blob Storage-KontoContainer 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 dazu Übersetzen von Dokumenten 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. Informationen hierzu finden Sie unter Erstellen 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 Glossarblob 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 asynchrone Batchübersetzungsanforderung wird als POST-Anforderung an Ihren Übersetzer-Endpunkt gesendet. Wenn der Vorgang erfolgreich ist, gibt die POST-Methode den Antwortcode 202 Accepted zurück, und der Dienst erstellt eine Batchanforderung. Die übersetzten Dokumente werden in Ihrem Zielcontainer aufgeführt.

Detaillierte Informationen zu den Anforderungsgrenzwerten von Azure KI Übersetzer finden Sie unter Anforderungsgrenzwerte für die Dokumentübersetzung.

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 Übersetzer- oder Azure KI 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.1/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": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "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 oder Dokument (nicht für den Container) erstellt haben.
  • Stellen Sie sicher, dass Sie den Zieldateinamen als Teil der Ziel-URL angegeben haben. Das SAS-Token ist für den Container jedoch noch immer vorhanden.
  • Diese Beispielanforderung zeigt, wie ein einzelnes Dokument in zwei Zielsprachen übersetzt wird.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es"
                },
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "de"
                }
            ]
        }
    ]
}

Übersetzen von Dokumente mithilfe von benutzerdefinierten Glossaren

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
             },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "{glossaryUrl/en-es.xlf}",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

🆕 Übersetzen von Text, der in Bildern in Dokumenten eingebettet ist

Hinweis

  • Dieses Feature ist optional und muss für jede Übersetzungsanforderung aktiviert werden.
  • Das Aktivieren dieses Features verursacht zusätzliche Kosten basierend auf der Nutzung. Für weitere Informationen siehe Preise für Azure KI Vision
  • Dieses Feature ist derzeit nur mit der Batchdokumentübersetzungs-API verfügbar.
  • Das unterstützte Dateiformat ist nur .docx.
  • Für die Verwendung dieses Features ist eine Azure KI Services-Ressource (nicht die eigenständige Übersetzerressource) erforderlich.

Anforderungskonfiguration

  • Verwenden des optionalen translateTextWithinImage Parameters im options Feld

    • Datentyp: Boolesch (true oder false)
    • Die boolesche Standardeinstellung ist false. Legen Sie die Option auf true fest, um die Bildtextübersetzung zu aktivieren.

  • Antwortdetails. Wenn das Feature aktiviert ist, werden hinzugefügte Bildverarbeitungsinformationen in der Antwort enthalten:

    • totalImageScansSucceeded. Die Anzahl der erfolgreich übersetzten Bildscans.

    • totalImageScansFailed. Die Anzahl der Bildscans, bei denen die Verarbeitung fehlgeschlagen ist.

Senden von Dokumentübersetzungsanforderungen mithilfe von Code

Einrichten der Codierungsplattform

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

Wichtig

In den Codebeispielen verwenden Sie eine hartcodierte SAS-URL (Shared Access Signature), wo dies angegeben ist. Denken Sie daran, die SAS-URL aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. Verwenden Sie für die Produktion eine sichere Methode zum Speichern von und Zugreifen auf Anmeldeinformationen wie eine verwaltete Azure-Identität. Weitere Informationen finden Sie unter Azure Storage-Sicherheit.

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

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

Ermitteln des Werts für id

  • Sie finden die Auftrags-id im URL-Wert Operation-Location des Antwortheaders der POST-Methode start-batch-translation. Die alphanumerische Zeichenfolge nach dem /document/ Parameter ist die Auftrags-id des Vorgangs:
Antwortheader Antwort-URL
Operation-Location {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date}
  • Sie können auch eine get-translation-status-Anforderung verwenden, um eine Liste der Übersetzungsaufträge und deren ids abzurufen.

Starten der asynchronen Batchübersetzung


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

            }

        }

    }

Abrufen unterstützter Dokumentformate

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

Abrufen des Status eines Übersetzungsauftrags

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

Abrufen des Status eines bestimmten Dokuments

Kurze Übersicht

Rufen Sie den Status eines bestimmten Dokuments mit einer Dokumentübersetzungsanforderung 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 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);
            }
}

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

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.
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. Das kann auch auf ungültige Header hindeuten.

Weitere Informationen

Nächste Schritte

Erstellen eines angepassten Sprachsystems mit Benutzerdefinierter Translator