Sdílet prostřednictvím

Programové použití rozhraní REST API

  • Článek

Překlad dokumentů je cloudová funkce služby Azure AI Translator . Rozhraní API pro překlad dokumentů můžete použít k asynchronnímu překladu celých dokumentů v podporovaných jazycích a různých formátech souborů při zachování struktury zdrojového dokumentu a formátování textu. V tomto návodu se naučíte používat rozhraní API pro překlad dokumentů s programovacím jazykem podle vašeho výběru a rozhraním HTTP REST API.

Požadavky

Poznámka:

Překlad dokumentů je podporován v plánech služeb S1 Standard (průběžné platby) a C2, C3, C4 a D3 Volume Discount Plans. Podívejte se na ceny služeb Azure AI – Translator.

Na začátek budete potřebovat:

  • Aktivní účet Azure Pokud ho nemáte, můžete si vytvořit bezplatný účet.

  • Účet služby Azure Blob Storage. Potřebujete také vytvořit kontejnery v účtu služby Azure Blob Storage pro zdrojové a cílové soubory:

    • Zdrojový kontejner. V tomto kontejneru nahrajete soubory pro překlad (povinné).
    • Cílový kontejner. V tomto kontejneru jsou uložené přeložené soubory (povinné).

  • Prostředek Translatoru:

    Vyplňte pole podrobností projektu a instance služby Translator následujícím způsobem:

    1. Předplatné Vyberte jedno z dostupných předplatných Azure.

    2. Skupina prostředků: Můžete vytvořit novou skupinu prostředků nebo přidat prostředek do existující skupiny prostředků, která sdílí stejný životní cyklus, oprávnění a zásady.

    3. Oblast zdroje. Zvolte Globální, pokud vaše firma nebo aplikace nevyžaduje konkrétní oblast. Pokud pro ověřování plánujete použít spravovanou identitu přiřazenou systémem, zvolte geografickou oblast, jako je USA – západ.

    4. Název. Zadejte název, který jste zvolili pro prostředek. Název, který zvolíte, musí být v rámci Azure jedinečný.

      Poznámka:

      Překlad dokumentů vyžaduje vlastní koncový bod domény. Hodnota, kterou zadáte do pole Název, bude parametrem vlastního názvu domény pro váš koncový bod.

    5. Cenová úroveň: Překlad dokumentů není podporován na úrovni Free. Pokud chcete službu vyzkoušet, vyberte Standard S1.

    6. Vyberte Zkontrolovat a vytvořit.

    7. Projděte si podmínky služby a vyberte Vytvořit a nasaďte prostředek.

    8. Po úspěšném nasazení prostředku vyberte Přejít k prostředku a načtěte svůj klíč a koncový bod.

Načtení klíče a vlastního koncového bodu domény

  • Požadavky na službu Translator vyžadují pro ověření přístupu klíč jen pro čtení a vlastní koncový bod. Koncový bod vlastní domény je adresa URL naformátovaná názvem vašeho prostředku, názvem hostitele a podadresáři Translator a je k dispozici na webu Azure Portal.

  1. Pokud jste vytvořili nový prostředek, po 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. Na levém řádku v části Správa prostředků vyberte Klíče a koncový bod.

  3. Zkopírujte a vložte své key a document translation endpoint do vhodného umístění, jako je Například Microsoft Notepad. K volání rozhraní API je nutný jenom jeden klíč.

  4. Vy key a document translation endpoint do ukázek kódu ověřte svou žádost ve službě Překlad dokumentů.

    Snímek obrazovky znázorňující pole získat klíč na webu Azure Portal

Získání klíče

Požadavky na službu Translator vyžadují klíč jen pro čtení pro ověřování přístupu.

  1. Pokud jste vytvořili nový prostředek, po 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. Na levém řádku v části Správa prostředků vyberte Klíče a koncový bod.
  3. Zkopírujte a vložte svůj klíč do vhodného umístění, jako je Microsoft Notepad.
  4. Vložíte ho do ukázky kódu pro ověření požadavku ve službě Překlad dokumentů.

Obrázek pole získat klíč na webu Azure Portal

Vytvoření kontejnerů Azure Blob Storage

Ke zdrojovým a cílovým souborům potřebujete vytvořit kontejnery ve svém účtu služby Azure Blob Storage.

  • Zdrojový kontejner. V tomto kontejneru nahrajete soubory pro překlad (povinné).
  • Cílový kontejner. V tomto kontejneru jsou uložené přeložené soubory (povinné).

Poznámka:

Překlad dokumentů podporuje glosáře jako objekty blob v cílových kontejnerech (nikoli jako samostatné kontejnery glosáře). Pokud chcete zahrnout vlastní glosář, přidejte ho do cílového kontejneru a přidejte ho glossaryUrl do požadavku. Pokud pár jazyka překladu není v glosáři, nepoužije se. Zobrazení překladu dokumentů pomocí vlastního glosáře

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

Znak sourceUrl , targetUrl a volitelné glossaryUrl musí obsahovat token sdíleného přístupového podpisu (SAS) připojený jako řetězec dotazu. Token se dá 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í určit přístup pro čtení a seznam.
  • Cílový kontejner nebo objekt blob musí určit přístup k zápisu a seznamu.
  • Objekt blob glosáře musí určit přístup pro čtení a seznam .

Tip

  • Pokud v operaci překládáte více souborů (objektů blob), delegujte přístup SAS na úrovni kontejneru.
  • Pokud v operaci překládáte jeden soubor (objekt blob), delegujte přístup SAS na úrovni objektu blob.
  • Jako alternativu k tokenům SAS můžete k ověřování použít spravovanou identitu přiřazenou systémem.

Požadavky HTTP

Požadavek na asynchronní dávkové překlad se odešle do koncového bodu služby Translator prostřednictvím požadavku POST. V případě úspěchu metoda POST vrátí 202 Accepted kód odpovědi a služba vytvoří dávkový požadavek. Přeložené dokumenty jsou uvedené v cílovém kontejneru.

Podrobné informace o omezeních požadavků služby Azure AI Translator najdete v tématu Omezení požadavků na překlad dokumentů.

Záhlaví HTTP

Každá žádost rozhraní DOCUMENT Translation API obsahuje následující hlavičky:

Hlavička HTTP Popis
Ocp-Apim-Subscription-Key Povinné: Hodnota je klíč Azure pro váš prostředek služby Translator nebo Azure AI.
Typ obsahu Povinné: Určuje typ obsahu datové části. Akceptované hodnoty jsou application/json nebo charset=UTF-8.

Vlastnosti textu požadavku POST

  • Adresa URL požadavku POST je POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • Text požadavku POST je objekt JSON s názvem inputs.
  • Objekt inputs obsahuje adresy kontejneru targetURL sourceURL pro páry zdrojového a cílového jazyka.
  • Řetězce prefix rozlišující malá a suffix velká písmena pro filtrování dokumentů ve zdrojové cestě pro překlad. Pole prefix se často používá k vymezení podsložek pro překlad. Pole suffix se nejčastěji používá pro přípony souborů.
  • Při překladu glossaries dokumentu se použije hodnota pole (volitelné).
  • Pro targetUrl každý cílový jazyk musí být jedinečný.

Poznámka:

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

Překlad všech dokumentů v kontejneru

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

Překlad konkrétního dokumentu v kontejneru

  • Zadejte "storageType": "File".
  • Pokud pro ověřování nepoužíváte spravovanou identitu přiřazenou systémem, ujistěte se, že jste pro konkrétní objekt blob nebo dokument (ne pro kontejner) vytvořili zdrojovou adresu URL a tokeny SAS.
  • Ujistěte se, že jste jako součást cílové adresy URL zadali cílový název souboru , i když je token SAS stále pro kontejner.
  • Tento ukázkový požadavek vrátí jeden dokument přeložený do dvou cílových jazyků.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es"
                },
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "de"
                }
            ]
        }
    ]
}

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

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

🆕 Překlad textu vložených do obrázků v dokumentech

Poznámka:

  • Tato funkce je volitelná a musí být povolená pro každou žádost o překlad.
  • Povolením této funkce se na základě využití účtují další náklady. Další informace najdete v tématu o cenách služby Azure AI Vision.
  • Tato funkce je aktuálně dostupná jenom s rozhraním API pro dávkové překlady dokumentů.
  • Podporovaný formát souboru je .docx pouze.
  • K použití této funkce se vyžaduje prostředek azure AI Services (nikoli samostatný prostředek Služby Translator).

Konfigurace požadavku

  • Použití volitelného translateTextWithinImage parametru options v poli

    • Datový typ: Logická hodnota (true nebo false)
    • Výchozí logické nastavení je false. Nastavte možnost pro true povolení překladu textu obrázku.

  • Podrobnosti odpovědi. Když je tato funkce povolená, do odpovědi se zahrnou přidané informace o zpracování obrázků:

    • totalImageScansSucceeded. Počet úspěšně přeložených kontrol obrázků.

    • totalImageScansFailed. Počet kontrol obrázků, které selhaly při zpracování.

Odeslání žádostí o překlad dokumentů pomocí kódu

Nastavení programovací platformy

Důležité

V případě ukázek kódu pevně zakódujete adresu URL sdíleného přístupového podpisu (SAS), kde je uvedeno. Nezapomeňte odebrat adresu URL SAS z kódu, až budete hotovi, a nikdy ji veřejně neposílejte. V produkčním prostředí použijte zabezpečený způsob ukládání přihlašovacích údajů a přístupu k vašim přihlašovacím údajům, jako je spravovaná identita Azure. Další informace najdete v tématu Zabezpečení služby Azure Storage.

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

  • endpoint
  • basePath
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (ID úlohy)

Vyhledání id hodnoty

  • Úlohu id najdete v hodnotě adresy URL hlavičky Operation-Location odpovědi metody POSTstart-batch-translation. Alfanumerický řetězec za /document/ parametrem je úloha idoperace:
Hlavička odpovědi Adresa URL odpovědi
Umístění operace {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date}

Spuštění asynchronního dávkového překladu


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

            }

        }

    }

Získání podporovaných formátů dokumentů

Načtěte seznam podporovaných formátů souborů. Pokud je tato metoda úspěšná 200 OK , vrátí kód odpovědi.


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

Získání stavu úlohy překladu

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


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

Získání stavu pro konkrétní dokument

Stručný přehled

Načtěte stav určitého dokumentu v žádosti o překlad dokumentu. Pokud je tato metoda úspěšná 200 OK , vrátí kód odpovědi.


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

Odstranění úlohy

Stručný přehled

Zrušit aktuálně zpracovávanou úlohu nebo úlohu zařazenou do fronty Zruší se jenom dokumenty, pro které není překlad spuštěný.


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

Běžné stavové kódy HTTP

Stavový kód HTTP Popis Možný důvod
200 OK Požadavek byl úspěšný.
400 Nesprávná žádost Požadovaný parametr chybí, je prázdný nebo null. Nebo hodnota předaná požadovanému nebo volitelnému parametru je neplatná. Běžným problémem je příliš dlouhá hlavička.
401 Neautorizováno Požadavek není autorizovaný. Zkontrolujte, jestli je klíč nebo token platný a ve správné oblasti.
429 Příliš mnoho požadavků Překročili jste kvótu nebo míru požadavků povolených pro vaše předplatné.
502 Chybná brána Problém na straně sítě nebo serveru Může také znamenat neplatné hlavičky.

Další informace

Další kroky

Vytvoření přizpůsobeného jazykového systému pomocí služby Custom Translator