Vertaling starten

Gebruik deze API om een vertaalaanvraag te starten met de documentvertalingsservice. Elke aanvraag kan meerdere documenten bevatten en moet een bron- en doelcontainer voor elk document bevatten.

Het voorvoegsel en het achtervoegselfilter (indien opgegeven) worden gebruikt om mappen te filteren. Het voorvoegsel wordt toegepast op het subpad na de containernaam.

Woordenlijsten/vertaalgeheugen kunnen worden opgenomen in de aanvraag en worden toegepast door de service wanneer het document wordt vertaald.

Als de woordenlijst ongeldig of onbereikbaar is tijdens de vertaling, wordt een fout aangegeven in de documentstatus. Als er al een bestand met dezelfde naam in het doel bestaat, mislukt de taak. De targetUrl voor elke doeltaal moet uniek zijn.

Aanvraag-URL

Verzend een POST aanvraag naar:

POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches

Meer informatie over het vinden van uw aangepaste domeinnaam.

Belangrijk

  • Voor alle API-aanvragen voor de documentvertalingsservice is een aangepast domein-eindpunt vereist.
  • U kunt het eindpunt op de pagina sleutels en eindpunt van uw Azure Portal resource, noch het globale translator-eindpunt, , gebruiken om HTTP-aanvragen voor documentvertaling api.cognitive.microsofttranslator.com te maken.

Aanvraagheaders

Aanvraagheaders zijn:

Kopteksten Beschrijving
Ocp-Apim-Subscription-Key Vereiste aanvraagheader

Aanvraag body: batch indienen aanvraag

Naam Type Description
Ingangen BatchRequest[] BatchRequest wordt hieronder vermeld. De invoerlijst met documenten of mappen met documenten. Mediatypen: "application/json", "text/json", "application/*+json".

Invoerwaarden

Definitie voor de aanvraag voor batchvertaling van invoer.

Naam Type Vereist Beschrijving
source SourceInput[] Waar inputs.source die hieronder wordt vermeld. Bron van de invoerdocumenten.
storageType StorageInputType[] Niet waar inputs.storageType wordt hieronder vermeld. Storage type van de bronreeks voor invoerdocumenten. Alleen vereist voor enkelvoudige documentvertaling.
Doelstellingen TargetInput[] Waar inputs.target die hieronder wordt vermeld. Locatie van de bestemming voor de uitvoer.

inputs.source

Bron van de invoerdocumenten.

Naam Type Vereist Beschrijving
filter DocumentFilter[] Niet waar DocumentFilter[] hieronder vermeld.
filter.prefix tekenreeks Niet waar Een tekenreeks met een casegevoelig voorvoegsel om documenten in het bronpad te filteren voor vertaling. Als u bijvoorbeeld een Azure Storage Blob-URI gebruikt, gebruikt u het voorvoegsel om submappen voor vertaling te beperken.
filter.achtervoegsel tekenreeks Niet waar Een tekenreeks met een casegevoelig achtervoegsel om documenten in het bronpad te filteren voor vertaling. Dit wordt meestal gebruikt voor bestandsextensies.
language tekenreeks Niet waar Taalcode Als er geen is opgegeven, voeren we automatische detectie uit op het document.
sourceUrl tekenreeks True Locatie van de map/container of één bestand met uw documenten.
storageSource StorageSource Niet waar StorageSource die hieronder wordt vermeld.
storageSource.AzureBlob tekenreeks Niet waar

inputs.storageType

Storage type van de bronreeks voor invoerdocumenten.

Naam Type
file tekenreeks
map tekenreeks

inputs.target

Doel voor de voltooide vertaalde documenten.

Naam Type Vereist Beschrijving
category tekenreeks Niet waar Categorie/aangepast systeem voor vertaalaanvraag.
Glossaria Verklarende woordenlijst[] Niet waar Verklarende woordenlijst die hieronder wordt vermeld. Lijst met woordenlijst.
glossaries.format tekenreeks Niet waar Formaat.
glossaries.glossaryUrl tekenreeks Waar (als u woordenlijsten gebruikt) Locatie van de woordenlijst. We gebruiken de bestandsextensie om de opmaak te extraheren als de indelingsparameter niet is opgegeven. Als het vertaaltaalpaar niet aanwezig is in de woordenlijst, wordt het niet toegepast.
glossaries.storageSource StorageSource Niet waar StorageSource die hierboven wordt vermeld.
glossaries.version tekenreeks Niet waar Optionele versie. Als dit niet is opgegeven, wordt de standaardinstelling gebruikt.
targetUrl tekenreeks True Locatie van de map/container met uw documenten.
language tekenreeks True Doeltaalcode van twee letters. Zie de lijst met taalcodes.
storageSource StorageSource [] Niet waar StorageSource [] hierboven vermeld.

Voorbeeldaanvraag

Hier volgen enkele voorbeelden van batchaanvragen.

Alle documenten in een container vertalen

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Alle documenten in een container vertalen die woordenlijsten toepassen

Zorg ervoor dat u een verklarende URL hebt & SAS-token voor de specifieke blob/het specifieke document (niet voor de container)

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=BsciG3NWoOoRjOYesTaUmxlXzyjsX4AgVkt2AsxJ9to%3D",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

Een specifieke map in een container vertalen

Zorg ervoor dat u de mapnaam (casegevoelig) als voorvoegsel in het filter hebt opgegeven, hoewel het SAS-token nog steeds voor de container is.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Een specifiek document in een container vertalen

  • Zorg ervoor dat u 'storageType': 'File' hebt opgegeven
  • Zorg ervoor dat u een bron-URL hebt & SAS-token voor de specifieke blob/het specifieke document (niet voor de container)
  • Zorg ervoor dat u de doelbestandsnaam hebt opgegeven als onderdeel van de doel-URL, hoewel het SAS-token nog steeds voor de container is.
  • Voorbeeldaanvraag hieronder toont één document dat wordt vertaald in twee doeltalen
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

Antwoordstatuscodes

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

Statuscode Description
202 Aanvaard. Een geslaagde aanvraag en de batchaanvraag worden gemaakt door de service. De header Operation-Location geeft een status-URL aan met de bewerking ID.HeadersOperation-Location: string
400 Slechte aanvraag. Ongeldige aanvraag. Controleer de invoerparameters.
401 Onbevoegde. Controleer uw referenties.
429 De aanvraagsnelheid is te hoog.
500 Interne serverfout.
503 De service is momenteel niet beschikbaar. Probeert u het later nog eens.
Andere statuscodes
  • Te veel aanvragen
  • Server tijdelijk niet beschikbaar

Foutbericht

Naam Type Description
code tekenreeks Enums met foutcodes op hoog niveau. Mogelijke waarden:
  • InternalServerError
  • InvalidArgument
  • InvalidRequest
  • RequestRateTooHigh
  • ResourceNotFound
  • ServiceUnavailable
  • Niet geautoriseerd
message tekenreeks Haalt een foutbericht op hoog niveau op.
innerError InnerTranslationError Nieuwe interne foutindeling die voldoet aan Cognitive Services API-richtlijnen. Dit bevat de vereiste eigenschappen ErrorCode, bericht en optionele eigenschappen target, details(sleutel-waardepaar), interne fout (dit kan worden genest).
Innerlijke. Foutcode tekenreeks Haalt de codefoutreeks op.
innerError.message tekenreeks Haalt een foutbericht op hoog niveau op.
innerError.target tekenreeks Haalt de bron van de fout op. Dit zijn bijvoorbeeld 'documenten' of 'document-id' in het geval van een ongeldig document.

Voorbeelden

Voorbeeld van een geslaagd antwoord

De volgende informatie wordt geretourneerd als een geslaagd antwoord.

U vindt de taak-id in de antwoordheader van de POST-methode Operation-Location URL-waarde. De laatste parameter van de URL is de taak-id van de bewerking (de tekenreeks na "/operation/").

Operation-Location: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55

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 Documentvertaling en de clientbibliotheek.