Starta batchöversättning

Artikel
06/22/2024

Referensfunktion
: Azure AI Translator → API-version för dokumentöversättning
: HTTP-metod 2024-05-01
: POST

Start Translation Använd metoden för att köra en asynkron batchöversättningsbegäran.
Metoden kräver ett Azure Blob Storage-konto med lagringscontainrar för källan och översatta dokument.

Begärans-URL

Viktigt!

Alla API-begäranden till funktionen Dokumentöversättning kräver en anpassad domänslutpunkt som finns på resursöversiktssidan i Azure-portalen.

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

Begärandehuvuden

Begärandehuvuden är:

Sidhuvuden	beskrivning	Villkor
Ocp-Apim-Subscription-Key	Din TRANSLATOR-tjänst-API-nyckel från Azure-portalen.	Obligatoriskt
Ocp-Apim-Subscription-Region	Den region där resursen skapades.	• Krävs när du använder en regional (geografisk) resurs som USA, västra. &punkt.
Innehållstyp	Nyttolastens innehållstyp. Det godkända värdet är application/json eller charset=UTF-8.	• Krävs

BatchRequest (brödtext)

Varje begäran kan innehålla flera dokument och måste innehålla en käll- och målcontainer för varje dokument. Källmedietyper: application/json, text/json, application/*+json.
Prefixet och suffixfiltret (om det tillhandahålls) används för att filtrera mappar. Prefixet tillämpas på undersökvägen efter containernamnet.
Ordlistor kan ingå i begäran. Om ordlistan är ogiltig eller inte kan nås under översättningen visas ett fel i dokumentstatusen.
Om det redan finns en fil med samma namn i målmålet misslyckas jobbet.
TargetUrl för varje målspråk måste vara unikt.


{
  "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
  }
}

Indata

Definition för begäran om indatabatchöversättning.

Nyckelparameter	Typ	Obligatoriskt	Parametrar för begäran	beskrivning
Ingångar	`array`	Sant	• källa (objekt) • mål (matris) • storageType (sträng)	Indata för källdata.

inputs.source

Definition för källdata.

Nyckelparameter	Typ	Obligatoriskt	Parametrar för begäran	beskrivning
inputs.source	`object`	Sant	• sourceUrl (sträng) • filter (objekt) • språk (sträng) • storageSource (sträng)	Källdata för indatadokument.
inputs.source.sourceUrl	`string`	Sant	•sträng	Containerplats för källfilen eller mappen.
inputs.source.filter	`object`	Falsk	• prefix (sträng) • suffix (sträng)	Skiftlägeskänsliga strängar för att filtrera dokument i källsökvägen.
inputs.source.filter.prefix	`string`	Falsk	•sträng	Skiftlägeskänslig prefixsträng för att filtrera dokument i källsökvägen för översättning. Används ofta för att utse undermappar för översättning. Exempel: "FolderA".
inputs.source.filter.suffix	`string`	Falsk	•sträng	Skiftlägeskänslig suffixsträng för att filtrera dokument i källsökvägen för översättning. Används oftast för filnamnstillägg. Exempel: ".txt"
inputs.source.language	`string`	Falsk	•sträng	Språkkoden för källdokumenten. Om det inte anges implementeras autodetect.
inputs.source.storageSource	`string`	Falsk	•sträng	Lagringskälla för indata. Standardvärdet är `AzureBlob`.

inputs.targets

Definition för mål- och ordlistedata.

Nyckelparameter	Typ	Obligatoriskt	Parametrar för begäran	beskrivning
inputs.targets	`array`	Sant	• targetUrl (sträng) • kategori (sträng) • språk (sträng) • ordlistor (matris) • storageSource (sträng)	Mål och ordlistor för översatta dokument.
inputs.targets.targetUrl	`string`	Sant	•sträng	Plats för containerplatsen för översatta dokument.
inputs.targets.category	`string`	Falsk	•sträng	Klassificering eller kategori för översättningsbegäran. Exempel: allmänt.
inputs.targets.language	`string`	Sant	•sträng	Målspråkkod. Exempel: "fr".
inputs.targets.glossaries	`array`	Falsk	• ordlistaUrl (sträng) • format (sträng) • version (sträng) • storageSource (sträng)	Se Skapa och använda ordlistor
inputs.targets.glossaries.glossaryUrl	`string`	Sant (om du använder ordlistor)	•sträng	Ordlistans plats. Filtillägget används för att extrahera formateringen om formatparametern inte har angetts. Om översättningsspråkparet inte finns i ordlistan tillämpas det inte.
inputs.targets.glossaries.format	`string`	Falsk	•sträng	Angivet filformat för ordlistan. Information om hur du kontrollerar om filformatet stöds finns i Hämta ordlisteformat som stöds.
inputs.targets.glossaries.version	`string`	Falsk	•sträng	Versionsindikator. Exempel: "2.0".
inputs.targets.glossaries.storageSource	`string`	Falsk	•sträng	Lagringskälla för ordlistor. Standardvärdet är `_AzureBlob_`.
inputs.targets.storageSource	`string`	Falsk	•sträng	Lagringskälla för targets.defaults till `_AzureBlob_`.

inputs.storageType

Definition av lagringsentiteten för indatadokument.

Nyckelparameter	Typ	Obligatoriskt	Parametrar för begäran	beskrivning
inputs.storageType	`string`	Falsk	•`Folder` • `File`	Lagringstyp för källsträngen för indatadokument. Endast "Mapp" eller "Fil" är giltiga värden.

Alternativ

Definition för begäran om indatabatchöversättning.

Nyckelparameter	Typ	Obligatoriskt	Parametrar för begäran	beskrivning
Alternativ	`object`	Falsk	Källinformation för indatadokument.
options.experimental	`boolean`	Falsk	•`true` • `false`	Anger om begäran innehåller en experimentell funktion (om tillämpligt). Endast booleska `true` värden eller `false` är giltiga värden.

Exempelbegäranden

Följande är exempel på batchbegäranden.

Kommentar

I följande exempel har begränsad åtkomst beviljats till innehållet i en Azure Storage-container med hjälp av en SAS-token (signatur för delad åtkomst).

Översätta alla dokument i en 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"
                }
            ]
        }
    ]
}

Översätta alla dokument i en container med ordlistor

{
    "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"
                        }
                    ]

                }
            ]
        }
    ]
}

Översätta en specifik mapp i en container

Kontrollera att du anger mappnamnet (skiftlägeskänsligt) som prefix i filtret.

{
    "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"
                }
            ]
        }
    ]
}

Översätta ett specifikt dokument i en container

Ange "storageType": File.
Skapa käll-URL och SAS-token för den specifika bloben/dokumentet.
Ange målfilnamnet som en del av mål-URL:en , även om SAS-token fortfarande är för containern.

Den här exempelbegäran visar ett enda dokument som översätts till två målspråk.

{
    "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"
                }
            ]
        }
    ]
}

Dricks

Den här metoden returnerar jobbparametern id för frågesträngarna get-translation-status, get-documents-status, get-document-status och cancel-translation request.

Du hittar jobbet id i POST-metodens start-batch-translation svarshuvud-URL-värde Operation-Location . Den alfanumeriska strängen som följer parametern /document/ är åtgärdens jobb id:

Svarsrubrik Svars-URL

Åtgärdsplats {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01
Du kan också använda en begäran om get-translations-status för att hämta en lista över översättningsjobb och deras id.

Svarsrubrik	Svars-URL
Åtgärdsplats	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`?api-version=2024-05-01

Svarsstatuskoder

Följande är de möjliga HTTP-statuskoder som en begäran returnerar.

Statuskod	beskrivning
202	Accepterad. Lyckad begäran och batchbegäran har skapats. Rubriken Operation-Location anger en status-URL med åtgärds-ID.HeadersOperation-Location: sträng
400	Felaktig begäran. Ogiltig begäran. Kontrollera indataparametrar.
401	Behörighet saknas. Kontrollera dina autentiseringsuppgifter.
429	Begärandefrekvensen är för hög.
500	Internt serverfel.
503	Tjänsten är för närvarande inte tillgänglig. Försök igen senare.
Andra statuskoder	• För många förfrågningar. Servern är tillfälligt otillgänglig

Felsvar

Nyckelparameter	Typ	Beskrivning
kod	`string`	Uppräkningar som innehåller felkoder på hög nivå. Möjliga värden:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Obehörig
meddelande	`string`	Hämtar felmeddelande på hög nivå.
innerError	InnerTranslationError	Nytt format för inre fel som överensstämmer med API-riktlinjerna för Azure AI-tjänster. Det här felmeddelandet innehåller nödvändiga egenskaper: ErrorCode, meddelande och valfria egenskaper, information (nyckelvärdepar) och inre fel (det kan kapslas).
inre. Felkod	`string`	Hämtar kodfelsträngen.
innerError.message	`string`	Hämtar felmeddelande på hög nivå.
innerError.target	`string`	Hämtar källan till felet. Det skulle till exempel vara `documents` eller `document id` om dokumentet är ogiltigt.

Exempel på felsvar

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

Nästa steg

Följ vår snabbstart om du vill veta mer om hur du använder dokumentöversättning och klientbiblioteket.

Kom igång med dokumentöversättning

Dela via