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:
Abonnement: Wählen Sie eines Ihrer verfügbaren Azure-Abonnements aus.
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.
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.
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.
Tarif: Die Dokumentübersetzung wird im Free-Tarif nicht unterstützt. Wählen Sie den Tarif Standard S1 aus, um den Dienst auszuprobieren.
Klicken Sie auf Überprüfen + erstellen.
Lesen Sie die Nutzungsbedingungen, und klicken Sie auf Erstellen, um Ihre Ressource bereitzustellen.
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.
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.
- 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.
- Klicken Sie in der linken Schiene unter Ressourcenverwaltung auf Schlüssel und Endpunkt.
- Kopieren Sie Ihren Schlüssel, und fügen Sie ihn an einem geeigneten Ort ein, z. B. in den Editor von Microsoft.
- Sie fügen ihn dann in den folgenden Code ein, um Ihre Anforderung für den Dokumentübersetzungsdienst zu authentifizieren.
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
inputsenthält die Adressen beider ContainersourceURLundtargetURLfür Ihre Quell- und Zielsprachpaare. prefixundsuffixsind Zeichenfolgen mit Beachtung der Groß-/Kleinschreibung zum Filtern von Dokumenten im Quellpfad für die Übersetzung. Das Feldprefixwird häufig verwendet, um Unterordner für die Übersetzung anzugeben. Das Feldsuffixwird am häufigsten für Dateierweiterungen verwendet.- Ein Wert für das Feld
glossaries(optional) wird angewendet, wenn das Dokument übersetzt wird. - Die
targetUrlfü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:
endpointkeysourceURLtargetURLglossaryURLid(Auftrags-ID)
Ermitteln des Werts für id
- Sie finden die
iddes Auftrags im URL-WertOperation-Locationdes 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. |