Batchvertaling starten

Artikel
09/26/2024

Referentiefunctie: Azure AI Translator → API-versie van documentomzetting
: 2024-05-01
HTTP-methode: POST

Gebruik de Start Translation methode om een asynchrone batchomzettingsaanvraag uit te voeren.
Voor de methode is een Azure Blob Storage-account met opslagcontainers vereist voor uw bron en vertaalde documenten.

Aanvraag-URL

Belangrijk

Voor alle API-aanvragen voor de functie Documentvertaling is een aangepast domeineindpunt vereist dat zich op de overzichtspagina van uw resource in Azure Portal bevindt.

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

Aanvraagheaders

Aanvraagheaders zijn:

Kopteksten	Beschrijving	Voorwaarde
Ocp-Apim-Subscription-Key	De API-sleutel van uw Translator-service vanuit Azure Portal.	Vereist
Ocp-Apim-Subscription-Region	De regio waar uw resource is gemaakt.	Vereist bij het gebruik van een regionale (geografische) resource, zoals VS - west. & opsommingsteken.
Content-Type	Het inhoudstype van de nettolading. De geaccepteerde waarde is application/json of charset=UTF-8.	Vereist

BatchRequest (hoofdtekst)

Elke aanvraag kan meerdere documenten bevatten en moet een bron- en doelcontainer voor elk document bevatten. Bronmediatypen: application/json, text/json, application/*+json.
Het voorvoegsel- en achtervoegselfilter (indien opgegeven) worden gebruikt om mappen te filteren. Het voorvoegsel wordt toegepast op het subpad na de containernaam.
Woordenlijsten kunnen worden opgenomen in de aanvraag. Als de woordenlijst tijdens de vertaling ongeldig of onbereikbaar is, wordt een fout aangegeven in de documentstatus.
Als er al een bestand met dezelfde naam bestaat in de doelbestemming, mislukt de taak.
De targetUrl voor elke doeltaal moet uniek zijn.


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

Invoerwaarden

Definitie voor de aanvraag voor het omzetten van invoerbatches.

Sleutelparameter	Type	Vereist	Aanvraagparameters	Beschrijving
Ingangen	`array`	Waar	• bron (object) • doelen (matrix) • storageType (tekenreeks)	Invoerbrongegevens.

inputs.source

Definitie voor de brongegevens.

Sleutelparameter	Type	Vereist	Aanvraagparameters	Beschrijving
inputs.source	`object`	Waar	• sourceUrl (tekenreeks) • filter (object) • taal (tekenreeks) • storageSource (tekenreeks)	Brongegevens voor invoerdocumenten.
inputs.source.sourceUrl	`string`	Waar	•snaar	Containerlocatie voor het bronbestand of de bronmap.
inputs.source.filter	`object`	Onwaar	• voorvoegsel (tekenreeks) • achtervoegsel (tekenreeks)	Hoofdlettergevoelige tekenreeksen om documenten in het bronpad te filteren.
inputs.source.filter.prefix	`string`	Onwaar	•snaar	Hoofdlettergevoelige voorvoegseltekenreeks voor het filteren van documenten in het bronpad voor vertaling. Vaak gebruikt om submappen voor vertaling aan te wijzen. Voorbeeld: 'FolderA'.
inputs.source.filter.suffix	`string`	Onwaar	•snaar	Hoofdlettergevoelige achtervoegseltekenreeks voor het filteren van documenten in het bronpad voor vertaling. Meestal gebruikt voor bestandsextensies. Voorbeeld: '.txt'
inputs.source.language	`string`	Onwaar	•snaar	De taalcode voor de brondocumenten. Als dit niet is opgegeven, wordt autodetectie geïmplementeerd.
inputs.source.storageSource	`string`	Onwaar	•snaar	Opslagbron voor invoer. Standaard ingesteld op `AzureBlob`.

inputs.targets

Definitie voor doel- en woordenlijstgegevens.

Sleutelparameter	Type	Vereist	Aanvraagparameters	Beschrijving
inputs.targets	`array`	Waar	• targetUrl (tekenreeks) • categorie (tekenreeks) • taal (tekenreeks) • woordenlijsten (matrix) • storageSource (tekenreeks)	Doelen en woordenlijstgegevens voor vertaalde documenten.
inputs.targets.targetUrl	`string`	Waar	•snaar	Locatie van de containerlocatie voor vertaalde documenten.
inputs.targets.category	`string`	Onwaar	•snaar	Classificatie of categorie voor de vertaalaanvraag. Voorbeeld: algemeen.
inputs.targets.language	`string`	Waar	•snaar	Doeltaalcode. Voorbeeld: 'fr'.
inputs.targets.glossaries	`array`	Onwaar	• woordenlijstUrl (tekenreeks) • indeling (tekenreeks) • versie (tekenreeks) • storageSource (tekenreeks)	Zie Woordenlijsten maken en gebruiken
inputs.targets.glossaries.glossaryUrl	`string`	Waar (als woordenlijsten worden gebruikt)	•snaar	Locatie van de woordenlijst. De bestandsextensie wordt gebruikt om de opmaak op te halen als de indelingsparameter niet wordt opgegeven. Als het vertaaltaalpaar niet aanwezig is in de woordenlijst, wordt deze niet toegepast.
inputs.targets.glossaries.format	`string`	Onwaar	•snaar	Opgegeven bestandsindeling voor woordenlijst. Zie Ondersteunde woordenlijstindelingen ophalen om te controleren of uw bestandsindeling wordt ondersteund.
inputs.targets.glossaries.version	`string`	Onwaar	•snaar	Versie-indicator. Voorbeeld: '2.0'.
inputs.targets.glossaries.storageSource	`string`	Onwaar	•snaar	Opslagbron voor woordenlijsten. Standaard ingesteld op `_AzureBlob_`.
inputs.targets.storageSource	`string`	Onwaar	•snaar	Opslagbron voor targets.defaults to `_AzureBlob_`.

inputs.storageType

Definitie van de opslagentiteit voor invoerdocumenten.

Sleutelparameter	Type	Vereist	Aanvraagparameters	Beschrijving
inputs.storageType	`string`	Onwaar	•`Folder` • `File`	Opslagtype van de brontekenreeks voor invoerdocumenten. Alleen Map of Bestand zijn geldige waarden.

Opties

Definitie voor de aanvraag voor het omzetten van invoerbatches.

Sleutelparameter	Type	Vereist	Aanvraagparameters	Beschrijving
Opties	`object`	Onwaar	Broninformatie voor invoerdocumenten.
options.experimenteel	`boolean`	Onwaar	•`true` • `false`	Geeft aan of de aanvraag een experimentele functie bevat (indien van toepassing). Alleen de Booleaanse `true` waarden of `false` geldige waarden zijn.

Voorbeeld van aanvraag

Hier volgen voorbeelden van batchaanvragen.

Notitie

In de volgende voorbeelden is beperkte toegang verleend aan de inhoud van een Azure Storage-container met behulp van een SAS-token (Shared Access Signature).

Alle documenten in een container vertalen

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

Alle documenten in een container vertalen die woordenlijsten toepassen

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

                }
            ]
        }
    ]
}

Specifieke map vertalen in een container

Zorg ervoor dat u de mapnaam (hoofdlettergevoelig) opgeeft als voorvoegsel in het filter.

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

Een specifiek document vertalen in een container

Geef 'storageType' op: File.
Maak bron-URL en SAS-token voor de specifieke blob/het specifieke document.
Geef de doelbestandsnaam op als onderdeel van de doel-URL, hoewel het SAS-token nog steeds voor de container is.

In deze voorbeeldaanvraag ziet u één document dat in twee doeltalen is vertaald.

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

Tip

Deze methode retourneert de taakparameter id voor de queryreeksen get-translation-status, get-documents-status, get-document-status en aanvraagtekenreeksen voor annuleren-vertaling .

U vindt de taak id in de URL-waarde van de POST-methode-antwoordheader start-batch-translation Operation-Location . De alfanumerieke tekenreeks na de /document/ parameter is de taak idvan de bewerking:

Antwoordheader Antwoord-URL

Operation-Location {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01
U kunt ook een get-translation-statusaanvraag gebruiken om een lijst met vertaaltaken en hun idtaken op te halen.

Antwoordheader	Antwoord-URL
Operation-Location	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`?api-version=2024-05-01

Antwoordstatuscodes

Hier volgen de mogelijke HTTP-statuscodes die een aanvraag retourneert.

Statuscode	Beschrijving
202	Geaccepteerd. Geslaagde aanvraag en de gemaakte batchaanvraag. De header Operation-Location geeft een status-URL aan met de bewerkings-ID.HeadersOperation-Location: tekenreeks
400	Ongeldig verzoek. Ongeldige aanvraag. Controleer de invoerparameters.
401	Onbevoegd. Controleer uw referenties.
429	Aanvraagsnelheid is te hoog.
500	Interne serverfout.
503	De service is momenteel niet beschikbaar. Probeer het later opnieuw.
Overige statuscodes	• Te veel aanvragen. De server is tijdelijk niet beschikbaar

Foutrespons

Sleutelparameter	Type	Description
code	`string`	Opsommingen met foutcodes op hoog niveau. Mogelijke waarden:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Niet geautoriseerd
bericht	`string`	Hiermee wordt een foutbericht op hoog niveau weergegeven.
innerError	InnerTranslationError	Nieuwe interne foutindeling die voldoet aan api-richtlijnen voor Azure AI-services. Dit foutbericht bevat de vereiste eigenschappen: Foutcode, bericht en optionele eigenschappendoel, details (sleutelwaardepaar) en interne fout (deze kunnen worden genest).
binnenste. Foutcode	`string`	Hiermee haalt u de codefoutreeks op.
innerError.message	`string`	Hiermee wordt een foutbericht op hoog niveau weergegeven.
innerError.target	`string`	Hiermee haalt u de bron van de fout op. Dit kan bijvoorbeeld zijn `documents` of `document id` als het document ongeldig is.

Voorbeeld van een foutbericht

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

Volgende stappen

Volg onze quickstart voor meer informatie over het gebruik van documentomzetting en de clientbibliotheek.

Aan de slag met de documentvertaling

Delen via