Batchübersetzung starten

2025-05-20

Referenzfeature
: Azure AI Translator → Dokumentübersetzungs-API
Version: 2024-05-01 HTTP-Methode: POST

Verwenden Sie die Start Translation Methode, um eine asynchrone Batchübersetzungsanforderung auszuführen.
Die Methode erfordert ein Azure Blob Storage-Konto mit Speichercontainern für Ihre Quell- und übersetzten Dokumente.

Anforderungs-URL

Wichtig

Für alle API-Anforderungen an das Dokumentübersetzungsfeature ist ein benutzerdefinierter Domänenendpunkt erforderlich, der sich auf der Seite "Ressourcenübersicht" im Azure-Portal befindet.

  curl -i -X POST "{document-translation-endpoint}/translator/document/batches?api-version={date}"

Anforderungsheader

Anforderungsheader:

Header	Beschreibung	Erkrankung
Ocp-Apim-Subscription-Key	Ihr Übersetzerdienst-API-Schlüssel aus dem Azure-Portal.	Erforderlich
Ocp-Apim-Subscription-Region	Die Region, in der Ihre Ressource erstellt wurde.	Erforderlich bei Verwendung einer regionalen (geografischen) Ressource wie West-USA. &aufzählungszeichen.
Inhaltstyp	Der Inhaltstyp der Nutzdaten. Die akzeptierten Werte sind application/json oder charset=UTF-8.	Erforderlich

BatchRequest (Text)

Jede Anforderung kann mehrere Dokumente enthalten und muss einen Quell- und einen Zielcontainer für jedes Dokument enthalten. Quellmedientypen: application/json, text/json, application/*+json.
Der Präfix- und Suffixfilter (falls angegeben) wird zum Filtern von Ordnern verwendet. Das Präfix wird auf den Unterpfad nach dem Containernamen angewendet.
Glossare können in die Anforderung aufgenommen werden. Wenn das Glossar während der Übersetzung ungültig ist oder nicht erreichbar ist, wird im Dokumentstatus ein Fehler ausgegeben.
Wenn eine Datei mit demselben Namen bereits im Zielziel vorhanden ist, schlägt der Auftrag fehl.
Die Ziel-URL für die einzelnen Zielsprachen muss jeweils eindeutig sein.


{
  "inputs": [
    {
      "source": {
        "sourceUrl": "https://myblob.blob.core.windows.net/Container/",
        "filter": {
          "prefix": "FolderA",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

Eingaben

Definition für die Eingabe Batchübersetzungsanforderung.

Schlüsselparameter	type	Erforderlich	Anforderungsparameter	Beschreibung
Eingänge	`array`	Richtig	• source (Objekt) • targets (Array) • storageType (Zeichenfolge)	Eingaben von Quelldaten.

input.source

Definition für die Quelldaten.

Schlüsselparameter	type	Erforderlich	Anforderungsparameter	Beschreibung
input.source	`object`	Richtig	• sourceUrl (Zeichenfolge) • filter (Objekt) • language (Zeichenfolge) • storageSource (Zeichenfolge)	Quelldaten für Eingabedokumente.
input.source.sourceUrl	`string`	Richtig	•Schnur	Containerspeicherort für die Quelldatei oder den Quellordner.
input.source.filter	`object`	Falsch	• prefix (Zeichenfolge) • suffix (Zeichenfolge)	Zeichenfolgen mit Beachtung der Groß-/Kleinschreibung zum Filtern von Dokumenten im Quellpfad.
input.source.filter.prefix	`string`	Falsch	•Schnur	Eine Präfixzeichenfolge mit Beachtung der Groß-/Kleinschreibung zum Filtern von Dokumenten im Quellpfad für die Übersetzung. Wird häufig zum Festlegen von Unterordnern für die Übersetzung verwendet. Beispiel: „FolderA“.
inputs.source.filter.suffix	`string`	Falsch	•Schnur	Eine Präfixzeichenfolge mit Beachtung der Groß-/Kleinschreibung zum Filtern von Dokumenten im Quellpfad für die Übersetzung. Wird am häufigsten für Dateierweiterungen verwendet. Beispiel: „.txt“
input.source.language	`string`	Falsch	•Schnur	Der Sprachcode für die Quelldokumente. Wenn nicht angegeben, wird autodetect implementiert.
input.source.storageSource	`string`	Falsch	•Schnur	Speicherquelle für Eingaben. Wird standardmäßig auf `AzureBlob` festgelegt.

input.targets

Definition für Ziel- und Glossardaten.

Schlüsselparameter	type	Erforderlich	Anforderungsparameter	Beschreibung
input.targets	`array`	Richtig	• targetUrl (Zeichenfolge) • category (Zeichenfolge) • language (Zeichenfolge) • glossaries (Array) • storageSource (Zeichenfolge)	Ziel- und Glossardaten für übersetzte Dokumente.
input.targets.targetUrl	`string`	Richtig	•Schnur	Speicherort des Containerspeicherorts für übersetzte Dokumente.
input.targets.category	`string`	Falsch	•Schnur	Klassifizierung oder Kategorie für die Übersetzungsanforderung. Beispiel: allgemein.
input.targets.language	`string`	Richtig	•Schnur	Zielsprachencode. Beispiel: „fr“.
input.targets.glossaries	`array`	Falsch	• glossarUrl (Zeichenfolge) • format (Zeichenfolge) • version (Zeichenfolge) • storageSource (Zeichenfolge)	SieheErstellen und Verwenden von Glossaren
input.targets.glossaries.glossaryUrl	`string`	True (bei Verwendung von Glossaren)	•Schnur	Speicherort des Glossars. Die Dateierweiterung wird zum Extrahieren der Formatierung verwendet, wenn der Formatparameter nicht bereitgestellt wird. Wenn das Übersetzungssprachpaar nicht im Glossar vorhanden ist, wird es nicht angewendet.
input.targets.glossaries.format	`string`	Falsch	•Schnur	Angegebenes Dateiformat für das Glossar. Weitere Informationen zum Überprüfen, ob Ihr Dateiformat unterstützt wird, finden Sie unterAbrufen unterstützter Glossarformate.
input.targets.glossaries.version	`string`	Falsch	•Schnur	Versionsindikator. Beispiel: „2.0“.
input.targets.glossaries.storageSource	`string`	Falsch	•Schnur	Speicherquelle für Glossare. Wird standardmäßig auf `_AzureBlob_` festgelegt.
input.targets.storageSource	`string`	Falsch	•Schnur	Speicherquelle für "targets.defaults" auf `_AzureBlob_`.

input.storageType

Definition der Speicherentität für Eingabedokumente.

Schlüsselparameter	type	Erforderlich	Anforderungsparameter	Beschreibung
input.storageType	`string`	Falsch	•`Folder` • `File`	Der Speichertyp der Quellzeichenfolge der Eingabedokumente. Nur „Folder“ oder „File“ sind gültige Werte.

Optionen

Definition für die Eingabe Batchübersetzungsanforderung.

Schlüsselparameter	type	Erforderlich	Anforderungsparameter	Beschreibung
Optionen	`object`	Falsch	Quellinformationen für Eingabedokumente.
options.experimental	`boolean`	Falsch	•`true` • `false`	Gibt an, ob die Anforderung ein experimentelles Feature enthält (falls zutreffend). Nur die booleschen Werte `true` oder `false` sind gültige Werte.

Beispielanforderung

Im Folgenden werden Beispiele für Batchanforderungen aufgeführt:

Hinweis

In den folgenden Beispielen wird eingeschränkter Zugriff auf den Inhalt eines Azure Storage-Containers mit einem SAS-Token (Shared Access Signature) gewährt.

Übersetzen aller Dokumente in einem Container

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Übersetzen aller Dokumente in einem Container, unter Verwendung von Glossaren

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?{SAS-token-query-string}",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

Übersetzen eines bestimmten Ordners in einen Container

Stellen Sie sicher, dass Sie den Ordnernamen (Groß-/Kleinschreibung) als Präfix im Filter angeben.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Übersetzen eines bestimmten Dokuments in einen Container

Geben Sie "storageType" an: File.
Erstellen Sie Quell-URL- und SAS-Token für das bestimmte Blob/Dokument.
Geben Sie den Zieldateinamen als Teil der Ziel-URL an – auch wenn das SAS-Token für den Container noch immer vorhanden ist.

Diese Beispielanforderung zeigt ein einzelnes Dokument, das in zwei Zielsprachen übersetzt wurde.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?{SAS-token-query-string}",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?{SAS-token-query-string}",
                    "language": "de"
                }
            ]
        }
    ]
}

Tipp

Diese Methode gibt den Auftragsparameter id für die Abfragezeichenfolgen "get-translation-status", "get-documents-status", "get-document-status" und "Cancel-translation request" zurück.

Sie finden die Auftrags-id im URL-Wert start-batch-translation des Antwortheaders der POST-Methode Operation-Location. Die alphanumerische Zeichenfolge nach dem /document/ Parameter ist die Auftrags-id des Vorgangs:

Antwortheader Antwort-URL

Operationsstandort {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01
Sie können auch eine Anforderung für get-translation-status verwenden, um eine Liste der Übersetzungsaufträge und deren idAufträge abzurufen.

Antwortheader	Antwort-URL
Operationsstandort	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`?api-version=2024-05-01

Antwortstatuscodes

Im Folgenden finden Sie die möglichen HTTP-Statuscodes, die eine Anforderung zurückgeben kann.

Statuscode	Beschreibung
202	Akzeptiert: Die Anforderung wurde erfolgreich ausgeführt, und die Batchanforderung wird erstellt. Der Header „Operation-Location“ gibt eine Status-URL mit dem Vorgang „ID.HeadersOperation-Location: string“ an.
400	Ungültige Anforderung; Ungültige Anforderung. Eingabeparameter prüfen.
401	Nicht autorisiert. Anmeldeinformationen prüfen.
429	Die Anforderungsrate ist zu hoch.
500	Interner Serverfehler.
503	Dienst ist derzeit nicht verfügbar. Versuchen Sie es später noch einmal.
Andere Statuscodes	• Zu viele Anforderungen. Der Server ist vorübergehend nicht verfügbar.

Fehlerantwort

Schlüsselparameter	type	Beschreibung
Code	`string`	Enumerationen, die High-Level-Fehlercodes enthalten. Akzeptierte Werte:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Nicht autorisiert
Nachricht	`string`	Ruft High-Level-Fehlermeldung ab.
innerError	InnerTranslationError	Neues Format für innere Fehler, das den Richtlinien der Azure KI Services-API entspricht. Diese Fehlermeldung enthält erforderliche Eigenschaften: ErrorCode, Message und optionale Eigenschaftenziel, Details(Schlüsselwertpaar) und inneren Fehler (er kann geschachtelt werden).
inner. Errorcode	`string`	Ruft Code der Fehlerzeichenfolge ab.
innerError.message	`string`	Ruft High-Level-Fehlermeldung ab.
innerError.target	`string`	Ruft die Ursache des Fehlers ab. Wenn das Dokument gültig ist, würde sie `documents` oder `document id` lauten.

Beispiel für Fehlerantwort

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

Nächste Schritte

Folgen Sie unserer Schnellstartanleitung, um mehr über die Verwendung der Dokumentübersetzung und der Clientbibliothek zu erfahren.

Erste Schritte mit der Dokumentübersetzung