Batchübersetzung starten

Artikel
06/01/2024

Referenz
Feature: Azure KI Übersetzer → Dokumentübersetzung
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 Feature „Dokumentübersetzung“ 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	Bedingung
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-US. &aufzählungszeichen.
Content-Type	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.tsv",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
  "options": {
    "experimental": true
  }
}

Eingaben

Definition für die Eingabe Batchübersetzungsanforderung.

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

inputs.source

Definition für die Quelldaten.

Schlüsselparameter	type	Erforderlich	Anforderungsparameter	Beschreibung
inputs.source	`object`	True	• sourceUrl (Zeichenfolge) • filter (Objekt) • language (Zeichenfolge) • storageSource (Zeichenfolge)	Quelldaten für Eingabedokumente.
inputs.source.sourceUrl	`string`	True	•Schnur	Containerspeicherort für die Quelldatei oder den Quellordner.
inputs.source.filter	`object`	False	• prefix (Zeichenfolge) • suffix (Zeichenfolge)	Zeichenfolgen mit Beachtung der Groß-/Kleinschreibung zum Filtern von Dokumenten im Quellpfad.
inputs.source.filter.prefix	`string`	False	•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`	False	•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“
inputs.source.language	`string`	False	•Schnur	Der Sprachcode für die Quelldokumente. Wenn nicht angegeben, wird autodetect implementiert.
inputs.source.storageSource	`string`	False	•Schnur	Speicherquelle für Eingaben. Wird standardmäßig auf `AzureBlob` festgelegt.

inputs.targets

Definition für Ziel- und Glossardaten.

Schlüsselparameter	type	Erforderlich	Anforderungsparameter	Beschreibung
inputs.targets	`array`	True	• targetUrl (Zeichenfolge) • category (Zeichenfolge) • language (Zeichenfolge) • glossaries (Array) • storageSource (Zeichenfolge)	Ziel- und Glossardaten für übersetzte Dokumente.
inputs.targets.targetUrl	`string`	True	•Schnur	Speicherort des Containerspeicherorts für übersetzte Dokumente.
inputs.targets.category	`string`	False	•Schnur	Klassifizierung oder Kategorie für die Übersetzungsanforderung. Beispiel: allgemein.
inputs.targets.language	`string`	True	•Schnur	Zielsprachencode. Beispiel: „fr“.
inputs.targets.glossaries	`array`	False	• glossarUrl (Zeichenfolge) • format (Zeichenfolge) • version (Zeichenfolge) • storageSource (Zeichenfolge)	Siehe Erstellen und Verwenden von Glossaren
inputs.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.
inputs.targets.glossaries.format	`string`	False	•Schnur	Angegebenes Dateiformat für das Glossar. Informationen zum Überprüfen, ob Ihr Dateiformat unterstützt wird, finden Sie unter "Abrufen unterstützter Glossarformate".
inputs.targets.glossaries.version	`string`	False	•Schnur	Versionsindikator. Beispiel: „2.0“.
inputs.targets.glossaries.storageSource	`string`	False	•Schnur	Speicherquelle für Glossare. Wird standardmäßig auf `_AzureBlob_` festgelegt.
inputs.targets.storageSource	`string`	False	•Schnur	Speicherquelle für "targets.defaults" auf `_AzureBlob_`.

inputs.storageType

Definition der Speicherentität für Eingabedokumente.

Schlüsselparameter	type	Erforderlich	Anforderungsparameter	Beschreibung
inputs.storageType	`string`	False	•`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`	False	Quellinformationen für Eingabedokumente.
options.experimental	`boolean`	False	•`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 wurde eingeschränkter Zugriff auf den Inhalt eines Azure Storage-Containers mithilfe eines SAS-Tokens (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 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=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
Operation-Location	{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	Typ	BESCHREIBUNG
code	`string`	Enumerationen, die High-Level-Fehlercodes enthalten. Mögliche Werte:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Nicht autorisiert
message	`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

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

Erste Schritte bei der Dokumentübersetzung

Teilen über