Freigeben über


Batchübersetzung starten

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.

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.