Delen via

REST API's programmatisch gebruiken

  • Artikel

Documentomzetting is een cloudfunctie van de Azure AI Translator-service . U kunt de Documentomzettings-API gebruiken om hele documenten asynchroon te vertalen in ondersteunde talen en verschillende bestandsindelingen , terwijl de brondocumentstructuur en tekstopmaak behouden blijven. In deze handleiding leert u hoe u API's voor documentomzetting gebruikt met een programmeertaal van uw keuze en de HTTP REST API.

Vereisten

Notitie

  • Wanneer u een Azure AI-resource maakt in Azure Portal, hebt u doorgaans de mogelijkheid om een sleutel met meerdere services of één servicesleutel te maken. Documentomzetting wordt momenteel echter alleen ondersteund in de Translator-resource (één service) en is niet opgenomen in de Azure AI-servicesresource (multiservice).

  • Documentomzetting wordt ondersteund in het S1 Standard-serviceplan (betalen per gebruik) en C2, C3, C4 en D3 Volumekortingsplannen. Zie prijzen voor Azure AI-services: Translator.

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

  • Een actief Azure-account. Als u nog geen account hebt, kunt u een gratis account maken

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

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

  • Een Translator-resource met één service (niet een Azure AI-servicesresource met meerdere services):

    Voltooi de velden translator-project- en exemplaardetails als volgt:

    1. Abonnement. Selecteer een van uw beschikbare Azure-abonnementen.

    2. Resourcegroep. U kunt een nieuwe resourcegroep maken of uw resource toevoegen aan een bestaande resourcegroep die dezelfde levenscyclus, machtigingen en beleidsregels deelt.

    3. Resourceregio. Kies Globaal , tenzij uw bedrijf of toepassing een specifieke regio vereist. Als u van plan bent om een door het systeem toegewezen beheerde identiteit te gebruiken voor verificatie, kiest u een geografische regio, zoals VS - west.

    4. Name. Voer de naam in die u voor uw resource hebt gekozen. De naam die u kiest, moet uniek zijn binnen Azure.

      Notitie

      Documentomzetting vereist een aangepast domeineindpunt. De waarde die u invoert in het veld Naam, is de parameter voor de aangepaste domeinnaam voor uw eindpunt.

    5. Prijscategorie. Documentomzetting wordt niet ondersteund in de gratis laag. Als u de service wilt proberen, selecteert u Standard S1.

    6. Selecteer Controleren + maken.

    7. Controleer de servicevoorwaarden en selecteer Maken om uw resource te implementeren.

    8. Nadat uw resource is geïmplementeerd, selecteert u Ga naar de resource om uw sleutel en eindpunt op te halen.

Uw sleutel en aangepast domeineindpunt ophalen

  • Aanvragen voor de Translator-service vereisen een alleen-lezen sleutel en een aangepast eindpunt om toegang te verifiëren. Het eindpunt van het aangepaste domein is een URL die is opgemaakt met uw resourcenaam, hostnaam en Translator-submappen en is beschikbaar in Azure Portal.

  1. Als u een nieuwe resource hebt gemaakt nadat deze is geïmplementeerd, selecteert u Ga naar de resource. Als u een bestaande documentomzettingsresource hebt, gaat u rechtstreeks naar de resourcepagina.

  2. Selecteer sleutels en eindpunt in de linkerrail onder Resourcebeheer.

  3. Kopieer en plak uw key en document translation endpoint op een handige locatie, zoals Microsoft Kladblok. Er is slechts één sleutel nodig om een API-aanroep te maken.

  4. U key en document translation endpoint in de codevoorbeelden om uw aanvraag te verifiëren bij de service Documentvertaling.

    Schermopname van het sleutelveld ophalen in Azure Portal.

Uw sleutel ophalen

Aanvragen voor de Translator-service vereisen een alleen-lezen sleutel voor het verifiëren van toegang.

  1. Als u een nieuwe resource hebt gemaakt nadat deze is geïmplementeerd, selecteert u Ga naar de resource. Als u een bestaande documentomzettingsresource hebt, gaat u rechtstreeks naar de resourcepagina.
  2. Selecteer sleutels en eindpunt in de linkerrail onder Resourcebeheer.
  3. Kopieer en plak uw sleutel op een handige locatie, zoals Microsoft Kladblok.
  4. U plakt deze in het codevoorbeeld om uw aanvraag te verifiëren bij de documentomzettingsservice.

Afbeelding van het sleutelveld ophalen 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

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

SAS-toegangstokens maken voor documentomzetting

Het sourceUrl , targetUrl en optioneel glossaryUrl moet een SAS-token (Shared Access Signature) bevatten, toegevoegd als een querytekenreeks. Het token kan worden toegewezen aan uw container of specifieke blobs. Zie SAS-tokens maken voor documentomzettingsproces.

  • Uw broncontainer of -blob moet lees- en lijsttoegang aanwijzen.
  • Uw doelcontainer of blob moet schrijf- en lijsttoegang aanwijzen.
  • De woordenlijst-blob moet lees- en lijsttoegang aanwijzen.

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.
  • Als alternatief voor SAS-tokens kunt u een door het systeem toegewezen beheerde identiteit gebruiken voor verificatie.

HTTP-aanvragen

Een asynchrone batchomzettingsaanvraag wordt via een POST-aanvraag verzonden naar uw Translator-service-eindpunt. Als dit lukt, retourneert de POST-methode een 202 Accepted antwoordcode en maakt de service een batchaanvraag. De vertaalde documenten worden weergegeven in uw doelcontainer.

Zie Aanvraaglimieten voor documentomzetting voor gedetailleerde informatie over aanvraaglimieten voor Azure AI Translator Service.

HTTP-kopteksten

De volgende headers zijn opgenomen in elke api-aanvraag voor documentomzetting:

HTTP-header Beschrijving
Ocp-Apim-Subscription-Key Vereist: De waarde is de Azure-sleutel voor uw Translator- of Azure AI-servicesresource.
Inhoudstype Vereist: Hiermee geeft u het inhoudstype van de nettolading op. Geaccepteerde waarden zijn application/json of charset=UTF-8.

Eigenschappen van post-aanvraagbody

  • De URL van de POST-aanvraag is POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • De hoofdtekst van de POST-aanvraag is een JSON-object met de naam inputs.
  • Het inputs object bevat zowel containeradressen sourceURL voor de bron- als targetURL doeltaalparen.
  • De prefix en suffix zijn hoofdlettergevoelige tekenreeksen voor het filteren van documenten in het bronpad voor vertaling. Het prefix veld wordt vaak gebruikt om submappen voor vertaling af te bakenen. Het suffix veld wordt meestal gebruikt voor bestandsextensies.
  • Er wordt een waarde voor het glossaries 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": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Een specifiek document vertalen in een container

  • Geef "storageType": "File" op.
  • Als u geen door het systeem toegewezen beheerde identiteit gebruikt voor verificatie, moet u ervoor zorgen dat u bron-URL en SAS-tokens hebt gemaakt voor de specifieke blob/het document (niet voor de container).
  • Zorg ervoor dat u de bestandsnaam van het doel hebt opgegeven als onderdeel van de doel-URL, hoewel het SAS-token nog steeds voor de container is.
  • Met deze voorbeeldaanvraag wordt één document geretourneerd dat in twee doeltalen is vertaald.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es"
                },
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "de"
                }
            ]
        }
    ]
}

Documenten vertalen met behulp van een aangepaste woordenlijst

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
             },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "{glossaryUrl/en-es.xlf}",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Code gebruiken om aanvragen voor documentomzetting in te dienen

Uw coderingsplatform instellen

  • Een nieuw project maken.
  • Vervang Program.cs door het C#-codevoorbeeld.
  • Stel uw eindpunt-, sleutel- en container-URL-waarden in Program.cs in.
  • Voeg het Newtonsoft.Json-pakket toe met behulp van .NET CLI voor het verwerken van JSON-gegevens.
  • Voer het programma uit vanuit de projectmap.

Belangrijk

Voor de codevoorbeelden code codet u de SAS-URL (Shared Access Signature) waar aangegeven. Vergeet niet om de SAS-URL uit uw code te verwijderen wanneer u klaar bent en deze nooit openbaar te plaatsen. Gebruik voor productie een veilige manier om uw referenties op te slaan en te openen, zoals Azure Managed Identity. Zie Azure Storage-beveiliging voor meer informatie.

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

  • endpoint
  • basePath
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (taak-id)

id De waarde zoeken

  • 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={date}

Asynchrone batchomzetting starten


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


    class Program
    {

        static readonly string route = "?api-version={date}";

        private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";

        private static readonly string key = "{your-api-key}";

        static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"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(basePath + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);
                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");

            }

        }

    }

De ondersteunde documentindelingen ophalen

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 basePath = "{your-document-translation-endpoint}/translator/document/formats";

    static readonly string route = "?api-version={date}&type=document";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

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


                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);
            }
}

Status ophalen voor een vertaaltaak

De huidige status voor één taak en een overzicht van alle taken in een aanvraag voor documentomzetting 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 basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

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


                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);
            }
    }
}

Status ophalen voor een specifiek document

Kort overzicht

Haal de status voor een specifiek document op in een aanvraag voor documentomzetting. 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 basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

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


                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 momenteel de verwerking of wachtrijtaak. 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 basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

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


                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);
            }
}

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 is doorgegeven aan een vereiste of optionele parameter, is ongeldig. Een veelvoorkomend probleem is een header die te lang is.
401 Niet geautoriseerd De aanvraag is niet geautoriseerd. Controleer of uw sleutel of token geldig is en zich in de juiste regio bevindt. Wanneer u uw abonnement beheert in Azure Portal, moet u ervoor zorgen dat u de Translator-resource met één service gebruikt, niet de Resource voor meerdere services van Azure AI-services.
429 Te veel aanvragen U hebt het quotum of de frequentie van aanvragen overschreden die zijn toegestaan voor uw abonnement.
502 Ongeldige gateway Probleem aan de netwerk- of serverzijde. Kan ook ongeldige headers aangeven.

Meer informatie

Volgende stappen

Een aangepast taalsysteem maken met Custom Translator