Dela via

Använda REST-API:er programmatiskt

  • Artikel

Dokumentöversättning är en molnbaserad funktion i Azure AI Translator-tjänsten . Du kan använda API:et för dokumentöversättning för att asynkront översätta hela dokument på språk som stöds och olika filformat samtidigt som källdokumentets struktur och textformatering bevaras . I den här instruktionsguiden lär du dig att använda API:er för dokumentöversättning med valfritt programmeringsspråk och HTTP REST API.

Förutsättningar

Kommentar

  • När du skapar en Azure AI-resurs i Azure-portalen kan du vanligtvis skapa en nyckel för flera tjänster eller en enskild tjänstnyckel. Dokumentöversättning stöds dock för närvarande endast i Translator-resursen (enskild tjänst) och ingår inte i Azure AI-tjänsternas resurs (flera tjänster).

  • Dokumentöversättning stöds i S1 Standard Service Plan (Betala per användning) och C2, C3, C4 och D3 Volymrabattplaner. Se Prissättning för Azure AI-tjänster – Translator.

Du behöver följande för att komma igång:

  • Ett aktivt Azure-konto. Om du inte har ett konto kan du skapa ett kostnadsfritt konto

  • Ett Azure Blob Storage-konto. Du måste också skapa containrar i ditt Azure Blob Storage-konto för dina käll- och målfiler:

    • Källcontainer. I den här containern laddar du upp dina filer för översättning (krävs).
    • Målcontainer. I den här containern lagras dina översatta filer (krävs).

  • En Translator-resurs med en enda tjänst (inte en Azure AI-tjänstresurs med flera tjänster):

    Fyll i fälten Translator-projekt- och instansinformation på följande sätt:

    1. Prenumeration. Välj en av dina tillgängliga Azure-prenumerationer.

    2. Resursgrupp. Du kan skapa en ny resursgrupp eller lägga till resursen i en befintlig resursgrupp som delar samma livscykel, behörigheter och principer.

    3. Resursregion. Välj Global om inte ditt företag eller program kräver en viss region. Om du planerar att använda en systemtilldelad hanterad identitet för autentisering väljer du en geografisk region som USA, västra.

    4. Namn. Ange det namn som du valde för resursen. Namnet du väljer måste vara unikt i Azure.

      Kommentar

      Dokumentöversättning kräver en anpassad domänslutpunkt. Värdet som du anger i fältet Namn är den anpassade domännamnsparametern för slutpunkten.

    5. Prisnivå. Dokumentöversättning stöds inte på den kostnadsfria nivån. Om du vill prova tjänsten väljer du Standard S1.

    6. Välj Granska + skapa.

    7. Granska tjänstvillkoren och välj Skapa för att distribuera resursen.

    8. När resursen har distribuerats väljer du Gå till resurs för att hämta nyckeln och slutpunkten.

Hämta din nyckel och din anpassade domänslutpunkt

  • Begäranden till Translator-tjänsten kräver en skrivskyddad nyckel och en anpassad slutpunkt för att autentisera åtkomsten. Den anpassade domänslutpunkten är en URL som är formaterad med resursnamnet, värdnamnet och Translator-underkatalogerna och är tillgänglig i Azure-portalen.

  1. Om du har skapat en ny resurs väljer du Gå till resurs när den har distribuerats. Om du har en befintlig dokumentöversättningsresurs går du direkt till resurssidan.

  2. Välj Nycklar och slutpunkt under Resurshantering i det vänstra spåret.

  3. Kopiera och klistra in och key document translation endpoint på en lämplig plats, till exempel Microsoft Anteckningar. Endast en nyckel krävs för att göra ett API-anrop.

  4. Du key och document translation endpoint i kodexemplen för att autentisera din begäran till dokumentöversättningstjänsten.

    Skärmbild som visar fältet Hämta din nyckel i Azure-portalen.

Hämta din nyckel

Begäranden till Translator-tjänsten kräver en skrivskyddad nyckel för autentisering av åtkomst.

  1. Om du har skapat en ny resurs väljer du Gå till resurs när den har distribuerats. Om du har en befintlig dokumentöversättningsresurs går du direkt till resurssidan.
  2. Välj Nycklar och slutpunkt under Resurshantering i det vänstra spåret.
  3. Kopiera och klistra in din nyckel på en lämplig plats, till exempel Microsoft Anteckningar.
  4. Du klistrar in den i kodexemplet för att autentisera din begäran till dokumentöversättningstjänsten.

Bild av hämta ditt nyckelfält i Azure-portalen.

Skapa Azure Blob Storage-containrar

Du måste skapa containrar i ditt Azure Blob Storage-konto för käll- och målfiler.

  • Källcontainer. I den här containern laddar du upp dina filer för översättning (krävs).
  • Målcontainer. I den här containern lagras dina översatta filer (krävs).

Kommentar

Dokumentöversättning stöder ordlistor som blobar i målcontainrar (inte separata ordlistecontainrar). Om du vill inkludera en anpassad ordlista lägger du till den i målcontainern och inkluderar glossaryUrl med begäran. Om översättningsspråkparet inte finns i ordlistan tillämpas det inte. Se Översätta dokument med hjälp av en anpassad ordlista

Skapa SAS-åtkomsttoken för dokumentöversättning

Den sourceUrl valfria glossaryUrl , targetUrl och måste innehålla en SAS-token (Signatur för delad åtkomst), som läggs till som en frågesträng. Token kan tilldelas till din container eller specifika blobar. Se Skapa SAS-token för dokumentöversättningsprocessen.

  • Källcontainern eller bloben måste ange läs- och liståtkomst.
  • Målcontainern eller bloben måste ange skriv- och liståtkomst.
  • Ordlistebloben måste ange läs- och liståtkomst.

Dricks

  • Om du översätter flera filer (blobar) i en åtgärd delegerar du SAS-åtkomst på containernivå.
  • Om du översätter en enskild fil (blob) i en åtgärd delegerar du SAS-åtkomst på blobnivå.
  • Som ett alternativ till SAS-token kan du använda en systemtilldelad hanterad identitet för autentisering.

HTTP-begäranden

En asynkron batchöversättningsbegäran skickas till translator-tjänstslutpunkten via en POST-begäran. Om det lyckas returnerar POST-metoden en 202 Accepted svarskod och tjänsten skapar en batchbegäran. De översatta dokumenten visas i målcontainern.

Detaljerad information om begränsningar för Azure AI Translator Service-begäranden finns i Begränsningar för begäran om dokumentöversättning.

HTTP-rubriker

Följande rubriker ingår i varje BEGÄRAN om API för dokumentöversättning:

HTTP-huvud beskrivning
Ocp-Apim-Subscription-Key Obligatoriskt: Värdet är Azure-nyckeln för din Translator- eller Azure AI-tjänstresurs.
Innehållstyp Obligatoriskt: Anger innehållstypen för nyttolasten. Godkända värden är application/json eller charset=UTF-8.

Egenskaper för POST-begärandetext

  • URL:en för POST-begäran är POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • POST-begärandetexten är ett JSON-objekt med namnet inputs.
  • Objektet inputs innehåller både sourceURL och targetURL containeradresser för dina käll- och målspråkpar.
  • Och prefix suffix är skiftlägeskänsliga strängar för att filtrera dokument i källsökvägen för översättning. Fältet prefix används ofta för att definiera undermappar för översättning. Fältet suffix används oftast för filnamnstillägg.
  • Ett värde för fältet glossaries (valfritt) tillämpas när dokumentet översätts.
  • För targetUrl varje målspråk måste vara unikt.

Kommentar

Om det redan finns en fil med samma namn i målet misslyckas jobbet.

Översätta alla dokument i en container

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Översätta ett visst dokument i en container

  • Ange "storageType": "File".
  • Om du inte använder en systemtilldelad hanterad identitet för autentisering kontrollerar du att du har skapat käll-URL:en och SAS-token för den specifika bloben/dokumentet (inte för containern).
  • Se till att du har angett målfilnamnet som en del av mål-URL:en, även om SAS-token fortfarande är för containern.
  • Den här exempelbegäran returnerar ett enda dokument som översätts till två målspråk.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es"
                },
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "de"
                }
            ]
        }
    ]
}

Översätta dokument med hjälp av en anpassad ordlista

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

Använda kod för att skicka begäranden om dokumentöversättning

Konfigurera din kodningsplattform

  • Skapa ett nytt projekt.
  • Ersätt Program.cs med C#-kodexemplet.
  • Ange värdena för slutpunkt, nyckel och container-URL i Program.cs.
  • Lägg till Newtonsoft.Json-paketet med .NET CLI för bearbetning av JSON-data.
  • Kör programmet från projektkatalogen.

Viktigt!

För kodexemplen hårdkodar du din SAS-URL (Signatur för delad åtkomst) där det anges. Kom ihåg att ta bort SAS-URL:en från koden när du är klar och publicera den aldrig offentligt. För produktion använder du ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter som Azure Managed Identity. Mer information finns i Azure Storage-säkerhet.

Du kan behöva uppdatera följande fält beroende på åtgärden:

  • endpoint
  • basePath
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (jobb-ID)

Hitta värdet id

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

Starta asynkron batchöversättning


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

            }

        }

    }

Få dokumentformat som stöds

Hämta en lista över filformat som stöds. Om det lyckas returnerar den här metoden en 200 OK svarskod.


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

Hämta status för ett översättningsjobb

Hämta aktuell status för ett enskilt jobb och en sammanfattning av alla jobb i en begäran om dokumentöversättning. Om det lyckas returnerar den här metoden en 200 OK svarskod.


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

Hämta status för ett visst dokument

Kort översikt

Hämta status för ett visst dokument i en begäran om dokumentöversättning. Om det lyckas returnerar den här metoden en 200 OK svarskod.


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

Ta bort jobb

Kort översikt

Avbryt bearbetningen eller det köade jobbet. Endast dokument för vilka översättningen inte startas avbryts.


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

Vanliga HTTP-statuskoder

HTTP-statuskod beskrivning Möjlig orsak
200 OK Begäran lyckades.
400 Felaktig förfrågan En obligatorisk parameter saknas, är tom eller null. Eller så är värdet som skickas till en obligatorisk eller valfri parameter ogiltigt. Ett vanligt problem är en rubrik som är för lång.
401 Behörighet saknas Begäran är inte auktoriserad. Kontrollera att din nyckel eller token är giltig och i rätt region. När du hanterar din prenumeration på Azure-portalen kontrollerar du att du använder translator-resursen för en enda tjänst, inte Azure AI-tjänsternas multitjänstresurs.
429 För många begäranden Du har överskridit kvoten eller antalet begäranden som tillåts för din prenumeration.
502 Felaktig gateway Problem på nätverks- eller serversidan. Kan också ange ogiltiga rubriker.

Läs mer

Nästa steg

Skapa ett anpassat språksystem med Custom Translator