Sdílet prostřednictvím

Programové použití rozhraní API pro překlad dokumentů

Překlad dokumentů je cloudová funkce služby Azure 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 a C2, C3, C4 a D3 Volume Discount Plans. Podívejte se naceny za Foundry Tools – 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é).

  • Překladatelský prostředek:

    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. Region zdrojů. 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, je parametr vlastního názvu domény pro váš koncový bod.

    5. Cenová úroveň: Překlad dokumentů se nepodporuje 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ředkua načtěte svůj klíč a koncový bod.

Získejte svůj klíč a vlastní koncový bod domény

  • Požadavky na 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í, například Microsoft Notepad. K volání rozhraní API je nutný jenom jeden klíč.

  4. Autentizujte svou žádost ve službě překladu dokumentů pomocí key a document translation endpoint ve vzorových kódech.

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

Získání klíče

Požadavky na 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í, například Microsoft Notepad.
  4. Vložíte ho do ukázky kódu, abyste ověřili vaši žádost ve službě překladu dokumentů.

Obrázek pole Získat klíč v Azure portálu

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 se jazykový pár pro překlad nenachází v glosáři, glosář se nepoužije. Podívejte sena překlad 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 ke specifickým blobům. VizVytvoření tokenů SAS pro proces překladu dokumentů.

  • Zdrojový kontejner nebo objekt blob musí povolit přístup pro čtení a přístup pro seznam.
  • Cílový kontejner nebo objekt BLOB musí určit přístup k zápisu a přístup k seznamu.
  • Objekt blob glosáře musí stanovit přístup ke čtení a přístup k seznamu.

Návod

  • 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 Translator najdete v tématuOmezení žádostí o překlad dokumentů.

Záhlaví HTTP

Každá žádost rozhraní API pro překlad dokumentů obsahuje následující hlavičky:

Hlavička HTTP Popis
Ocp-Apim–Subscription-Key Povinné: Hodnota je klíč Azure pro váš prostředek Translator nebo Microsoft Foundry.
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 sourceURLtargetURL pro páry zdrojového a cílového jazyka.
  • Řetězce rozlišující malá a velká písmena prefix a suffix 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 každý cílový jazyk musí být targetUrl 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": "{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 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í této funkce povede k dalším nákladům na základě využití. Další informace najdete v tématuAzure Vision in Foundry Tools – ceny
  • 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 je vyžadován prostředek Foundry (a nikoli samostatný prostředek Translatoru).

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 na true pro umožnění překladu textu v obrázcích.

  • Tady je ukázkový požadavek JSON:

    {
  "inputs": [
    {
      "source": {
        "sourceUrl": "<SAS-URL>",
        "language": "en"
      },
      "targets": [
        {
          "targetUrl": "<SAS-URL>",
          "language": "ta"
        }
      ]
    }
  ],
  "options": {
    "experimental": false,
    "translateTextWithinImage": true
  }
}

  • 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 skenů obrázků.

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

  • Tady je ukázková odpověď JSON:

      {
      "id": "1a2b0c23-45d6-789-a123-a456fdaf7890",
      "createdDateTimeUtc": "2024-11-13T22:06:58.2789197Z",
      "lastActionDateTimeUtc": "2024-11-13T22:07:14.1608283Z",
      "status": "Running",
      "summary": {
          "total": 1,
          "failed": 0,
          "success": 0,
          "inProgress": 1,
          "notYetStarted": 0,
          "cancelled": 0,
          "totalCharacterCharged": 1355,
          "totalImageScansSucceeded": 2,
          "totalImageScansFailed": 0
      }
  }

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

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ódujte 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ě URL v záhlaví odpovědi metody POST start-batch-translationOperation-Location. 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);
            }
}

Odstranit úlohu

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ě zpracová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á záhlaví.

Další informace

Další kroky

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

  • Last updated on