Aan de slag met documentvertaling

  • Artikel
  • 16 minuten om te lezen

In dit artikel leert u hoe u Document translation gebruikt met HTTP-REST API methoden. Documentvertaling is een cloudfunctie van de Azure Vertalen service. Met de documentvertalings-API kunnen hele documenten worden vertaald met behoud van de structuur en tekstopmaak van brondocumenten.

Vereisten

Notitie

  1. Wanneer u in het Azure Portal een Cognitive Service-resource maakt, hebt u over het algemeen de mogelijkheid om een abonnementssleutel voor meerdere service of een abonnementssleutel voor één service te maken. Documentvertaling wordt momenteel echter alleen ondersteund in de Vertalen-resource (één service) en is niet opgenomen in de resource Cognitive Services (meerdere service).
  2. Documentvertaling is alleen beschikbaar in het S1 Standard-serviceplan (betalen per gebruik) of in het D3-volumekortingsplan. Zie Cognitive Services prijzen: Vertalen.

Om aan de slag te gaan, hebt u het volgende nodig:

Aangepaste domeinnaam en abonnementssleutel

Belangrijk

  • Voor alle API-aanvragen voor de documentvertalingsservice is een aangepast domein-eindpunt vereist.
  • U gebruikt het eindpunt dat u op uw Azure Portal resourcesleutels en eindpuntpagina hebt gevonden, noch het globale translator-eindpunt, — om HTTP-aanvragen te maken voor api.cognitive.microsofttranslator.com documentvertaling.

Wat is het eindpunt van het aangepaste domein?

Het eindpunt van het aangepaste domein is een URL die is geformatteerd met uw resourcenaam, hostnaam en Vertalen subdirectorieën:

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

Uw aangepaste domeinnaam zoeken

De parameter NAME-OF-YOUR-RESOURCE (ook wel aangepaste domeinnaam genoemd) is de waarde die u hebt ingevoerd in het veld Naam tijdens het maken van de Vertalen resource.

Afbeelding van de Azure Portal, resource maken, directe details, naamveld.

Uw abonnementssleutel op halen

Aanvragen voor de Vertalen service vereisen een alleen-lezensleutel voor het authenticeren van toegang.

  1. Als u een nieuwe resource hebt gemaakt, selecteert u Na de implementatie de optie Ga naar resource. Als u een bestaande documentvertalingsresource hebt, gaat u rechtstreeks naar de resourcepagina.
  2. Selecteer in de linkerrail onder Resourcebeheer sleutels en eindpunt.
  3. Kopieer en plak uw abonnementssleutel op een handige locatie, zoals Microsoft Kladblok.
  4. U plakt deze in de onderstaande code om uw aanvraag te verifiëren bij de documentvertalingsservice.

Afbeelding van het veld Uw abonnementssleutel in Azure Portal.

Azure Blob Storage-containers maken

U moet containers maken in uw Azure Blob Storage-account voor bron- en doelbestanden.

  • Broncontainer. In deze container uploadt u uw bestanden voor vertaling (vereist).
  • Doelcontainer. In deze container worden uw vertaalde bestanden opgeslagen (vereist).

Notitie

Document translation ondersteunt woordenlijsten als blobs in doelcontainers (geen afzonderlijke woordenlijstcontainers). Als u een aangepaste woordenlijst wilt opnemen, voegt u deze toe aan de doelcontainer en voegt u de glossaryUrl met de aanvraag toe. Als het vertaaltaalpaar niet aanwezig is in de woordenlijst, wordt het niet toegepast. Zie Documenten vertalen met behulp van een aangepaste woordenlijst

SAS-toegangstokens maken voor documentvertaling

De sourceUrl , targetUrl en optioneel moeten een glossaryUrl sas-token (Shared Access Signature) bevatten, toegevoegd als een queryreeks. Het token kan worden toegewezen aan uw container of specifieke blobs. Zie SAS-tokens maken voor het documentvertalingsproces.

  • Uw broncontainer of blob moet lees- en lijsttoegang hebben.
  • Uw doelcontainer of blob moet schrijf- en lijsttoegang hebben.
  • Uw woordenlijstblob moet lees- en lijsttoegang hebben.

Tip

  • Als u meerdere bestanden (blobs) in een bewerking vertaalt, delegeert u SAS-toegang op containerniveau.
  • Als u één bestand (blob) in een bewerking vertaalt, delegeert u SAS-toegang op blobniveau.

Documentvertaling: HTTP-aanvragen

Een aanvraag voor batchdocumentvertaling wordt via een POST-aanvraag Vertalen service-eindpunt verzonden. Als dit lukt, retourneert de POST-methode een 202 Accepted antwoordcode en wordt de batchaanvraag gemaakt door de service.

HTTP-headers

De volgende headers zijn opgenomen in elke Document Vertalen API-aanvraag:

HTTP-header Beschrijving
Ocp-Apim-Subscription-Key Vereist: de waarde is de Azure-abonnementssleutel voor uw Vertalen of Cognitive Services resource.
Content-Type Vereist: hiermee geeft u het inhoudstype van de nettolading op. Geaccepteerde waarden zijn application/json of charset=UTF-8.
Content-Length Vereist: de lengte van de aanvraag body.

Eigenschappen van post-aanvraag body

  • De POST-aanvraag-URL is POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches
  • De POST-aanvraag body is een JSON-object met de naam inputs .
  • Het inputs object bevat zowel als sourceURL targetURL containeradressen voor uw bron- en doeltaalparen
  • De prefix velden suffix en (optioneel) worden gebruikt om documenten in de container te filteren, inclusief mappen.
  • Er wordt een waarde glossaries voor het veld (optioneel) toegepast wanneer het document wordt vertaald.
  • De targetUrl voor elke doeltaal moet uniek zijn.

Notitie

Als er al een bestand met dezelfde naam in de bestemming bestaat, mislukt de taak.

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

Een specifiek document in een container vertalen

  • Zorg ervoor dat u 'storageType': 'File' hebt opgegeven
  • Zorg ervoor dat u de 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"
                }
            ]
        }
    ]
}

Documenten vertalen met behulp van een aangepaste woordenlijst

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://myblob.blob.core.windows.net/source",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://myblob.blob.core.windows.net/target",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https:// myblob.blob.core.windows.net/glossary/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Code gebruiken om aanvragen voor documentvertaling in te dienen

Uw coderingsplatform instellen

  • Een nieuw project maken.
  • Vervang Program.cs door de hieronder weergegeven C#-code.
  • Stel de waarden voor eindpunt, abonnementssleutel en container-URL in Program.cs in.
  • Als u JSON-gegevens wilt verwerken, voegt u het pakket Newtonsoft.Json toe met behulp van .NET CLI.
  • Voer het programma uit vanuit de projectmap.

Belangrijk

In de onderstaande codevoorbeelden codeert u uw sleutel en eindpunt waar aangegeven; Vergeet niet om de sleutel uit uw code te verwijderen wanneer u klaar bent en plaats deze nooit openbaar. Zie Azure Cognitive Services voor manieren om uw referenties veilig op te slaan en te openen.

Mogelijk moet u de volgende velden bijwerken, afhankelijk van de bewerking:

  • endpoint
  • subscriptionKey
  • sourceURL
  • targetURL
  • glossaryURL
  • id (taak-id)

De waarde id zoeken

  • U vindt de taak in de waarde id header-URL van de POST-methodereactie. Operation-Location De laatste parameter van de URL is de taak van de bewerking id :
Antwoordheader Resultaat-URL
Operation-Location https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec
  • U kunt ook een GET-taakaanvraag gebruiken om een documentvertalingstaken op te id halen.

Documenten vertalen


    using System;
    using System.Net.Http;
    using System.Threading.Tasks;
    using System.Text;


    class Program
    {

        static readonly string route = "/batches";

        private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

        private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

        static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\",\"filter\":{\"prefix\": \"Demo_1/\"} }, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");

        static async Task Main(string[] args)
        {
            using HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {

                StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

                request.Method = HttpMethod.Post;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
                request.Content = content;

                HttpResponseMessage  response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;
                if (response.IsSuccessStatusCode)
                {
                    Console.WriteLine($"Status code: {response.StatusCode}");
                    Console.WriteLine();
                    Console.WriteLine($"Response Headers:");
                    Console.WriteLine(response.Headers);
                }
                else
                    Console.Write("Error");

            }

        }

    }
}

Bestandsindelingen downloaden

Een lijst met ondersteunde bestandsindelingen ophalen. Als dit lukt, retourneert deze methode een 200 OK antwoordcode.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/documents/formats";

    private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Taakstatus op halen

De huidige status voor één taak en een samenvatting van alle taken in een documentomtalingsaanvraag op te halen. Als dit lukt, retourneert deze methode een 200 OK antwoordcode.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/batches/{id}";

    private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Documentstatus op halen

Kort overzicht

Haal de status van een specifiek document op in een documentvertalingsaanvraag. Als dit lukt, retourneert deze methode een 200 OK antwoordcode.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/{id}/document/{documentId}";

    private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Taak verwijderen

Kort overzicht

Annuleer de momenteel verwerkte of in de wachtrij geplaatste taak. Alleen documenten waarvoor de vertaling niet is gestart, worden geannuleerd.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/batches/{id}";

    private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Delete;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Inhoudslimieten

De onderstaande tabel bevat de limieten voor gegevens die u naar Documentvertaling verzendt.

Kenmerk Limiet
Documentgrootte ≤ 40 MB
Totaal aantal bestanden. ≤ 1000
Totale inhoudsgrootte in een batch ≤ 250 MB
Aantal doeltalen in een batch ≤ 10
Grootte van het vertaalgeheugenbestand ≤ 10 MB

Documentvertaling kan niet worden gebruikt om beveiligde documenten te vertalen, zoals documenten met een versleuteld wachtwoord of beperkte toegang tot het kopiëren van inhoud.

Problemen oplossen

Algemene HTTP-statuscodes

HTTP-statuscode Beschrijving Mogelijke reden
200 OK De aanvraag is geslaagd.
400 Onjuiste aanvraag Een vereiste parameter ontbreekt, leeg of null. Of de waarde die wordt doorgegeven aan een vereiste of optionele parameter is ongeldig. Een veelvoorkomende probleem is een header die te lang is.
401 Niet geautoriseerd De aanvraag is niet geautoriseerd. Controleer of uw abonnementssleutel of token geldig is en in de juiste regio. Wanneer u uw abonnement op de Azure Portal beheert, moet u ervoor zorgen dat u de Vertalen-resource voor één service gebruikt, niet de Cognitive Services resource voor meerdere service.
429 Te veel aanvragen U hebt het quotum of het aantal toegestane aanvragen voor uw abonnement overschreden.
502 Slechte gateway Netwerk- of serverprobleem. Kan ook duiden op ongeldige headers.

Lees meer

Volgende stappen

Een aangepast taalsysteem maken met aangepaste Vertalen