Kom igång med dokumentöversättning

  • Artikel
  • 15 minuter för att läsa

I den här artikeln får du lära dig att använda dokumentöversättning med HTTP REST API metoder. Dokumentöversättning är en molnbaserad funktion i Azure Translator tjänsten. API:et för dokumentöversättning möjliggör översättning av hela dokument samtidigt som källdokumentstrukturen och textformateringen bevaras.

Förutsättningar

Anteckning

  1. När du skapar en Cognitive Service-resurs i Azure Portal har du i allmänhet möjlighet att skapa en prenumerationsnyckel för flera tjänster eller en prenumerationsnyckel för en tjänst. Dokumentöversättning stöds dock för närvarande endast i Translator-resursen (en tjänst) och ingår inte i Cognitive Services resursen (flera tjänster).
  2. Dokumentöversättning är endast tillgängligt i S1-standardtjänstplanen (betala per du- go) eller i D3-volymrabattplanen. Se Cognitive Services priser – Translator.

För att komma igång behöver du:

Anpassat domännamn och prenumerationsnyckel

Viktigt

  • Alla API-begäranden till tjänsten för dokumentöversättning kräver en anpassad domänslutpunkt.
  • Du använder inte slutpunkten som finns på sidan Azure Portal nycklar och slutpunkter eller slutpunkten för global översättning– – för att api.cognitive.microsofttranslator.com göra HTTP-begäranden till dokumentöversättning.

Vad är slutpunkten för den anpassade domänen?

Slutpunkten för den anpassade domänen är en URL formaterad med ditt resursnamn, värdnamn och Translator underkataloger:

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

Hitta ditt anpassade domännamn

Parametern NAME-OF-YOUR-RESOURCE (kallas även anpassat domännamn) är det värde som du angav i fältet Namn när du skapade Translator resurs.

Bild av Azure Portal, skapa resurs, omedelbar information, namnfält.

Hämta din prenumerationsnyckel

Begäranden till Translator tjänsten kräver en skrivskyddade 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 resurs för dokumentöversättning 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 prenumerationsnyckel på en lämplig plats, till exempel Microsoft Anteckningar.
  4. Du klistrar in den i koden nedan för att autentisera din begäran till tjänsten för dokumentöversättning.

Bild av fältet Hämta din prenumerationsnyckel i Azure Portal.

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).

Anteckning

Dokumentöversättning stöder ordlista 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 med i ordlistan tillämpas det inte. Se Översätta dokument med en anpassad ordlista

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

Valfria sourceUrl , och måste innehålla en targetUrl glossaryUrl 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 ha angiven läs- och liståtkomst.
  • Målcontainern eller bloben måste ha angiven skriv- och liståtkomst.
  • Din ordlista måste ha angiven läs- och liståtkomst.

Tips

  • 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å.

Dokumentöversättning: HTTP-begäranden

En batchbegäran om dokumentöversättning skickas till Translator tjänstslutpunkt via en POST-begäran. Om det lyckas returnerar POST-metoden 202 Accepted en svarskod och batchbegäran skapas av tjänsten.

HTTP-huvuden

Följande huvuden ingår i varje Document Translator API-begäran:

HTTP-huvud Beskrivning
Ocp-Apim-Subscription-Key Obligatoriskt: Värdet är Azure-prenumerationsnyckeln för din Translator eller Cognitive Services resurs.
Content-Type Obligatoriskt: Anger nyttolastens innehållstyp. Godkända värden är application/json eller charset=UTF-8.
Innehållslängd Obligatoriskt: längden på begärandetexten.

Egenskaper för begärandetexten i POST

  • URL:en för POST-begäran är POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches
  • POST-begärandetexten är ett JSON-objekt med namnet inputs .
  • -objektet inputs innehåller både - och sourceURL targetURL -containeradresser för dina käll- och målspråkpar
  • Fälten prefix och suffix (valfritt) används för att filtrera dokument i containern, inklusive mappar.
  • Ett värde för glossaries fältet (valfritt) tillämpas när dokumentet översätts.
  • för targetUrl varje målspråk måste vara unikt.

Anteckning

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

Översätta alla dokument i en 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"
                }
            ]
        }
    ]
}

Översätta ett specifikt dokument i en container

  • Kontrollera att du har angett "storageType": "File"
  • Kontrollera att du har skapat käll-URL& 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.
  • Exempelbegäran nedan visar ett enskilt dokument som översätts till två målspråk
{
    "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"
                }
            ]
        }
    ]
}

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

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

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

Konfigurera din kodplattform

  • Skapa ett nytt projekt.
  • Ersätt Program.cs med C#-koden som visas nedan.
  • Ange värden för slutpunkt, prenumerationsnyckel och container-URL i Program.cs.
  • Om du vill bearbeta JSON-data lägger du till Newtonsoft.Json-paketet med hjälp av .NET CLI.
  • Kör programmet från projektkatalogen.

Viktigt

För kodexe exemplen nedan hårdkodar du nyckeln och slutpunkten där det anges. kom ihåg att ta bort nyckeln från koden när du är klar och aldrig publicera den offentligt. Se Azure Cognitive Services för olika sätt att lagra och komma åt dina autentiseringsuppgifter på ett säkert sätt.

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

  • endpoint
  • subscriptionKey
  • sourceURL
  • targetURL
  • glossaryURL
  • id (jobb-ID)

Hitta id värdet

  • Jobbet finns i värdet för id POST-metodens svarshuvud-URL. Operation-Location Den sista parametern i URL:en är åtgärdens jobb id :
Svarshuvud Resultat-URL
Operation-Location https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec
  • Du kan också använda en GET-jobbbegäran för att hämta ett dokumentöversättningsjobb. id

Översätta dokument


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

            }

        }

    }
}

Hämta filformat

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

Hämta jobbstatus

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

Hämta dokumentstatus

Kort översikt

Hämta status för ett specifikt 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 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);
            }
}

Ta bort jobb

Kort översikt

Avbryt pågående bearbetning eller jobb i kö. Endast dokument som översättningen inte har startats för avbryts.


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

Innehållsbegränsningar

Tabellen nedan visar gränserna för data som du skickar till dokumentöversättning.

Attribut Gräns
Dokumentstorlek ≤ 40 MB
Totalt antal filer. ≤ 1000
Total innehållsstorlek i en batch ≤ 250 MB
Antal målspråk i en batch ≤ 10
Storleken på översättningsminnesfilen ≤ 10 MB

Dokumentöversättning kan inte användas för att översätta skyddade dokument, till exempel dokument med ett krypterat lösenord eller med begränsad åtkomst till att kopiera innehåll.

Felsökning

Vanliga HTTP-statuskoder

HTTP-statuskod Beskrivning Möjlig orsak
200 OK Begäran lyckades.
400 Felaktig begäran En obligatorisk parameter saknas, är tom eller null. Eller så är värdet som skickas till antingen en obligatorisk eller valfri parameter ogiltig. Ett vanligt problem är en rubrik som är för lång.
401 Behörighet saknas Begäran har inte auktoriserats. Kontrollera att din prenumerationsnyckel eller token är giltig och i rätt region. När du hanterar prenumerationen på Azure Portal bör du se till att du använder Translator resurs för en enskild tjänst, inte Cognitive Services resurs för flera tjänster.
429 För många begäranden Du har överskridit kvoten eller frekvensen för begäranden som tillåts för din prenumeration.
502 Felaktig gateway Problem på nätverks- eller serversidan. Kan också tyda på ogiltiga huvuden.

Läs mer

Nästa steg

Skapa ett anpassat språksystem med custom Translator