Začínáme s překladem dokumentů

  • Článek
  • 16 min ke čtení

V tomto článku se dozvíte, jak pomocí metod překladu dokumentů REST API HTTP. Překlad dokumentů je cloudová funkce služby Azure Translator Service. Rozhraní API pro překlad dokumentů umožňuje překlad celých dokumentů při zachování struktury zdrojového dokumentu a formátování textu.

Požadavky

Poznámka

  1. Obecně platí, že při vytváření prostředku služby Cognitive Service v Azure Portal máte možnost vytvořit klíč předplatného s více službami nebo klíč předplatného s jednou službou. Překlad dokumentů se ale aktuálně podporuje pouze v prostředku Translator (s jednou službou) a není součástí prostředku Cognitive Services (více služeb).
  2. Překlad dokumentů je k dispozici pouze v plánu služby S1 Standard (s platbou podle tarifu s platbou) nebo v plánu D3 Volume Discount Plan. Viz Cognitive Services ceny – Translator.

Abyste začali, budete potřebovat:

Název vlastní domény a klíč předplatného

Důležité

  • Všechny požadavky rozhraní API na službu překladu dokumentů vyžadují vlastní koncový bod domény.
  • K požadavkům HTTP na překlad dokumentů nebudete používat koncový bod, který najdete na stránce klíčů Azure Portal a koncového bodu, ani globálního koncového bodu překladače. api.cognitive.microsofttranslator.com

Co je koncový bod vlastní domény?

Koncový bod vlastní domény je adresa URL formátovaná pomocí názvu prostředku, názvu hostitele a Translator podadresářů:

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

Vyhledání vlastního názvu domény

Parametr NAME-OF-YOUR-RESOURCE (také nazývaný vlastní název domény) je hodnota, kterou jste zadali do pole Název při vytváření prostředku Translator domény.

Obrázek názvu Azure Portal, vytvoření prostředku, okamžité podrobnosti, pole názvu.

Získání klíče předplatného

Žádosti od Translator vyžadují pro ověřování přístupu klíč jen pro čtení.

  1. Pokud jste vytvořili nový prostředek, po jeho nasazení vyberte Přejít k prostředku. Pokud máte existující prostředek překladu dokumentů, přejděte přímo na stránku prostředku.
  2. V levé kolejnici v části Správa prostředků vyberte Klíče a koncový bod.
  3. Klíč předplatného zkopírujte a vložte do vhodného umístění, například Microsoft Poznámkový blok.
  4. Vložíte ho do následujícího kódu pro ověření vaší žádosti ve službě překladu dokumentů.

Obrázek pole Get your subscription key (Získat klíč předplatného) v Azure Portal.

Vytvoření kontejnerů úložiště objektů blob v Azure

V účtu úložiště objektů blob v Azure budete muset vytvořit kontejnery pro zdrojové a cílové soubory.

  • Zdrojový kontejner. Do tohoto kontejneru nahrajete soubory k překladu (povinné).
  • Cílový kontejner. Do tohoto kontejneru se budou ukládat přeložené soubory (povinné).

Poznámka

Překlad dokumentů podporuje glosáře jako objekty blob v cílových kontejnerech (nikoli samostatné kontejnery glosáře). Pokud chcete zahrnout vlastní glosář, přidejte ho do cílového kontejneru a zahrnovat s glossaryUrl požadavkem . Pokud v glosáře není pár jazyka překladu, nebude použit. Viz Překlad dokumentů pomocí vlastního glosáře.

Vytvoření přístupových tokenů SAS pro překlad dokumentů

, sourceUrl targetUrl a nepovinné glossaryUrl musí obsahovat token sdíleného přístupového podpisu (SAS) připojený jako řetězec dotazu. Token je možné přiřadit ke kontejneru nebo konkrétním objektům blob. Viz Vytvoření tokenů SAS pro proces překladu dokumentů.

  • Zdrojový kontejner nebo objekt blob musí mít určený přístup ke čtení a zobrazení seznamu.
  • Cílový kontejner nebo objekt blob musí mít určený přístup k zápisu a seznamu.
  • Objekt blob glosáře musí mít určený přístup pro čtení a seznam.

Tip

  • Pokud v operaci překládáte více souborů (objektů blob), delegování přístupu SAS na úrovni kontejneru.
  • Pokud v operaci překládáte jeden soubor (objekt blob), delegování přístupu SAS na úrovni objektu blob.

Překlad dokumentů: Požadavky HTTP

Dávkový požadavek na překlad dokumentů se do koncového Translator služby prostřednictvím požadavku POST. V případě úspěchu vrátí metoda POST kód odpovědi a služba 202 Accepted vytvoří požadavek batche.

Hlavičky PROTOKOLU HTTP

V každé žádosti rozhraní Document Translator API jsou následující hlavičky:

Hlavička PROTOKOLU HTTP Description
Ocp-Apim-Subscription-Key Povinné: Hodnota je klíč předplatného Azure pro váš Translator nebo Cognitive Services prostředků.
Typ obsahu Povinné: Určuje typ obsahu datové části. Akceptované hodnoty jsou application/json nebo charset=UTF-8.
Délka obsahu Povinné: Délka textu požadavku.

Vlastnosti textu požadavku POST

  • Adresa URL požadavku POST je POST. https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches
  • Text požadavku POST je objekt JSON s názvem inputs .
  • Objekt inputs obsahuje adresy sourceURL kontejnerů i pro páry targetURL zdrojového a cílového jazyka.
  • Pole prefix suffix a (volitelné) slouží k filtrování dokumentů v kontejneru včetně složek.
  • Hodnota pole glossaries (volitelné) se použije při překladu dokumentu.
  • Pro targetUrl každý cílový jazyk musí být jedinečný.

Poznámka

Pokud v cíli již existuje soubor se stejným názvem, úloha selže.

Překlad všech dokumentů v kontejneru

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

Překlad konkrétního dokumentu v kontejneru

  • Ujistěte se, že jste zadali storageType: File.
  • Ujistěte se, že jste vytvořili zdrojovou adresu URL & TOKEN SAS pro konkrétní objekt blob nebo dokument (ne pro kontejner).
  • Ujistěte se, že jste jako součást cílové adresy URL zadali cílový název souboru , přestože token SAS je stále pro kontejner.
  • Ukázkový požadavek níže ukazuje jeden dokument, který se překládá do dvou cílových jazyků.
{
    "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"
                }
            ]
        }
    ]
}

Překlad dokumentů pomocí vlastního glosáře

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

Použití kódu k odesílání žádostí o překlad dokumentů

Nastavení platformy pro kódování

Důležité

V případě níže uvedených ukázek kódu na místě, kde je to vyznačené, kód na pevném kódu zadáte. Nezapomeňte odebrat klíč z kódu, až budete hotovi, a nikdy ho veřejně ne zveřejníte. Způsoby Azure Cognitive Services a přístupu k přihlašovacím údajům najdete v tématu zabezpečení sítě.

V závislosti na operaci možná budete muset aktualizovat následující pole:

  • endpoint
  • subscriptionKey
  • sourceURL
  • targetURL
  • glossaryURL
  • id (ID úlohy)

Vyhledání id hodnoty

  • Úlohu najdete v hodnotě adresy URL hlavičky odpovědi metody id Operation-Location POST. Posledním parametrem adresy URL je úloha operace id :
Hlavička odpovědi Adresa URL výsledku
Operation-Location https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec
  • K načtení úlohy překladu dokumentů můžete použít také požadavek GET Jobs id (Úlohy GET).

Překlad 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");

            }

        }

    }
}

Získání formátů souborů

Načtení seznamu podporovaných formátů souborů V případě úspěchu vrátí tato metoda 200 OK kód odpovědi.


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

Získání stavu úlohy

Získejte aktuální stav pro jednu úlohu a souhrn všech úloh v žádosti o překlad dokumentu. V případě úspěchu vrátí tato metoda 200 OK kód odpovědi.


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

Získání stavu dokumentu

Stručný přehled

Načtěte stav konkrétního dokumentu v požadavku na překlad dokumentu. V případě úspěchu vrátí tato metoda 200 OK kód odpovědi.


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

Odstranění úlohy

Stručný přehled

Zruší aktuálně zpracování nebo úlohu zařazenou do fronty. Zruší se pouze dokumenty, pro které se překlad nezačal.


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

Omezení obsahu

Následující tabulka uvádí omezení pro data odesílaná do překladu dokumentů.

Atribut Omezení
Velikost dokumentu ≤ 40 MB
Celkový počet souborů ≤ 1000
Celková velikost obsahu v dávce ≤ 250 MB
Počet cílových jazyků v dávce ≤ 10
Velikost souboru paměti překladu ≤ 10 MB

Překlad dokumentů nelze použít k překladu zabezpečených dokumentů, jako jsou dokumenty se šifrovaným heslem nebo s omezeným přístupem ke kopírování obsahu.

Řešení potíží

Běžné stavové kódy HTTP

Stavový kód HTTP Popis Možný důvod
200 OK Požadavek byl úspěšný.
400 Chybný požadavek Požadovaný parametr chybí, je prázdný nebo null. Nebo je hodnota předaná požadovaném nebo volitelném parametru neplatná. Běžným problémem je hlavička, která je příliš dlouhá.
401 Neautorizováno Požadavek není autorizovaný. Zkontrolujte, jestli je klíč nebo token předplatného platný a ve správné oblasti. Při správě předplatného na Azure Portal se ujistěte, že používáte prostředek s jednou službou Translator ne prostředek s více Cognitive Services více služeb.
429 Příliš mnoho požadavků Překročili jste kvótu nebo rychlost požadavků povolených pro vaše předplatné.
502 Chybná brána Problém se sítí nebo serverem. Může také značit neplatné hlavičky.

Další informace

Další kroky

Vytvoření přizpůsobeného jazykového systému pomocí vlastních Translator