Megosztás a következőn keresztül:

REST API-k programozott használata

  • Cikk

A dokumentumfordítás az Azure AI Translator szolgáltatás felhőalapú funkciója. A Document Translation API-val a teljes dokumentumokat aszinkron módon fordíthatja le támogatott nyelveken és különböző fájlformátumokban , miközben megőrzi a forrásdokumentum szerkezetét és a szövegformázást. Ebben az útmutatóban megtanulhatja, hogyan használhatja a dokumentumfordítási API-kat egy tetszőleges programozási nyelvvel és a HTTP REST API-val.

Előfeltételek

Feljegyzés

  • Amikor Azure AI-erőforrást hoz létre az Azure Portalon, általában lehetősége van többszolgáltatásos vagy egyszolgáltatásos kulcs létrehozására. A dokumentumfordítás jelenleg csak a Translator (egyszolgáltatásos) erőforrásban támogatott, és nem szerepel az Azure AI-szolgáltatások (többszolgáltatásos) erőforrásában.

  • A dokumentumfordítás támogatott az S1 Standard szolgáltatáscsomagban (használatalapú fizetés) és a C2, C3, C4 és D3 mennyiségi kedvezménycsomagokban. Tekintse meg az Azure AI-szolgáltatások díjszabását – Translator.

A kezdéshez a következők szükségesek:

  • Aktív Azure-fiók. Ha nem rendelkezik ilyen fiókkal, létrehozhat egy ingyenes fiókot

  • Egy Azure Blob Storage-fiók. Tárolókat is létre kell hoznia az Azure Blob Storage-fiókban a forrás- és célfájlokhoz:

    • Forrástároló. Ebben a tárolóban töltheti fel a fájlokat fordításra (kötelező).
    • Céltároló. Ez a tároló tárolja a lefordított fájlokat (kötelező).

  • Egyszolgáltatásos Translator-erőforrás (nem többszolgáltatásos Azure AI-szolgáltatási erőforrás):

    Töltse ki a Translator projekt és a példány részleteit tartalmazó mezőket az alábbiak szerint:

    1. Előfizetés. Válasszon egyet az elérhető Azure-előfizetései közül.

    2. Erőforráscsoport. Létrehozhat egy új erőforráscsoportot, vagy hozzáadhatja az erőforrást egy már meglévő erőforráscsoporthoz, amely ugyanazokkal az életciklussal, engedélyekkel és szabályzatokkal rendelkezik.

    3. Erőforrásrégió. Válassza a Globális lehetőséget, kivéve, ha a vállalat vagy az alkalmazás egy adott régiót igényel. Ha rendszer által hozzárendelt felügyelt identitást szeretne használni a hitelesítéshez, válasszon egy olyan földrajzi régiót, mint az USA nyugati régiója.

    4. Név. Adja meg az erőforráshoz választott nevet. A választott névnek egyedinek kell lennie az Azure-ban.

      Feljegyzés

      A dokumentumfordításhoz egyéni tartományvégpont szükséges. A Név mezőben megadott érték lesz a végpont egyéni tartománynév paramétere.

    5. Tarifacsomag. A dokumentumfordítás nem támogatott az ingyenes szinten. A szolgáltatás kipróbálásához válassza a Standard S1 lehetőséget.

    6. Válassza a Felülvizsgálat és létrehozás lehetőséget.

    7. Tekintse át a szolgáltatási feltételeket, és válassza a Létrehozás lehetőséget az erőforrás üzembe helyezéséhez.

    8. Az erőforrás sikeres üzembe helyezése után válassza az Ugrás az erőforrásra lehetőséget a kulcs és a végpont lekéréséhez.

A kulcs és az egyéni tartományvégpont lekérése

  • A Translator szolgáltatáshoz érkező kérésekhez írásvédett kulcsra és egyéni végpontra van szükség a hozzáférés hitelesítéséhez. Az egyéni tartományvégpont az erőforrásnévvel, a gazdagépnévvel és a Translator alkönyvtárakkal formázott URL-cím, amely az Azure Portalon érhető el.

  1. Ha létrehozott egy új erőforrást, az üzembe helyezés után válassza az Ugrás az erőforrásra lehetőséget. Ha már rendelkezik dokumentumfordítási erőforrással, lépjen közvetlenül az erőforráslapra.

  2. A bal oldali korlát Erőforrás-kezelés területén válassza a Kulcsok és végpont lehetőséget.

  3. Másolja és illessze be a key document translation endpoint megfelelő helyre, például a Microsoft Jegyzettömbbe. API-hívás létrehozásához csak egy kulcs szükséges.

  4. Ön key és document translation endpoint a kódminták segítségével hitelesítheti a kérést a Dokumentumfordítási szolgáltatásban.

    Képernyőkép a kulcsmező lekérése az Azure Portalon.

A kulcs lekérése

A Translator szolgáltatáshoz érkező kérelmekhez írásvédett kulcs szükséges a hozzáférés hitelesítéséhez.

  1. Ha létrehozott egy új erőforrást, az üzembe helyezés után válassza az Ugrás az erőforrásra lehetőséget. Ha már rendelkezik dokumentumfordítási erőforrással, lépjen közvetlenül az erőforráslapra.
  2. A bal oldali korlát Erőforrás-kezelés területén válassza a Kulcsok és végpont lehetőséget.
  3. Másolja és illessze be a kulcsot egy kényelmes helyre, például a Microsoft Jegyzettömbbe.
  4. Illessze be a kódmintába, hogy hitelesítse a kérést a Dokumentumfordítási szolgáltatásban.

A kulcsmező lekérése az Azure Portalon.

Azure Blob Storage-tárolók létrehozása

Tárolókat kell létrehoznia az Azure Blob Storage-fiókban a forrás- és célfájlokhoz.

  • Forrástároló. Ebben a tárolóban töltheti fel a fájlokat fordításra (kötelező).
  • Céltároló. Ez a tároló tárolja a lefordított fájlokat (kötelező).

Feljegyzés

A dokumentumfordítás a céltárolókban blobként (nem különálló szószedettárolókban) támogatja a szószedeteket. Ha egyéni szószedetet szeretne felvenni, vegye fel a céltárolóba, és adja hozzá a glossaryUrl kéréshez. Ha a fordítási nyelvpár nem szerepel a szószedetben, az nem lesz alkalmazva. Lásd: Dokumentumok fordítása egyéni szószedet használatával

SAS-hozzáférési jogkivonatok létrehozása a dokumentumfordításhoz

A sourceUrl , targetUrl és nem kötelező glossaryUrl , tartalmaznia kell egy közös hozzáférésű jogosultságkód (SAS) jogkivonatot, amely lekérdezési sztringként van hozzáfűzve. A jogkivonat hozzárendelhető a tárolóhoz vagy adott blobokhoz. Lásd: SAS-jogkivonatok létrehozása a dokumentumfordítási folyamathoz.

  • A forrástárolónak vagy blobnak olvasási és listahozzáférést kell kijelölnie.
  • A céltárolónak vagy blobnak írási és listahozzáférést kell kijelölnie.
  • A szószedet-blobnak olvasási és listahozzáférést kell kijelölnie.

Tipp.

  • Ha egy műveletben több fájlt (blobot) fordít át, delegálja az SAS-hozzáférést a tároló szintjén.
  • Ha egyetlen fájlt (blobot) fordít egy műveletben, delegálja az SAS-hozzáférést a blob szintjén.
  • Az SAS-jogkivonatok alternatívaként használhatja a rendszer által hozzárendelt felügyelt identitást a hitelesítéshez.

HTTP-kérések

Egy aszinkron kötegfordítási kérelmet küld a Translator szolgáltatás végpontjához egy POST-kérésen keresztül. Ha sikeres, a POST metódus válaszkódot 202 Accepted ad vissza, és a szolgáltatás létrehoz egy kötegkérelmet. A lefordított dokumentumok a céltárolóban vannak felsorolva.

Az Azure AI Translator Service kéréskorlátairól a Dokumentumfordítási kérelmek korlátai című témakörben talál részletes információt.

HTTP-fejlécek

A dokumentumfordítási API-kérések a következő fejléceket tartalmazzák:

HTTP-fejléc Leírás
Ocp-Apim-Subscription-Key Kötelező: Az érték a Translator vagy az Azure AI-szolgáltatások erőforrásának Azure-kulcsa.
Content-Type Kötelező: Megadja a hasznos adat tartalomtípusát. Az elfogadott értékek az application/json vagy charset=UTF-8.

POST kérelem törzstulajdonságai

  • A POST kérelem URL-címe POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • A POST kérelem törzse egy JSON-objektum neve inputs.
  • Az inputs objektum a forrás- és targetURL célnyelvi párok mindkét sourceURL és tárolócímét tartalmazza.
  • A prefix fordítás forrásútvonalában található dokumentumok szűréséhez használt kis- és suffix nagybetűk megkülönböztetése. A prefix mezőt gyakran használják almappák fordításához. A suffix mezőt leggyakrabban fájlkiterjesztésekhez használják.
  • A dokumentum lefordításakor a glossaries program a mező értékét alkalmazza (nem kötelező).
  • Az targetUrl egyes célnyelvek esetében egyedinek kell lennie.

Feljegyzés

Ha egy azonos nevű fájl már létezik a célhelyen, a feladat sikertelen lesz.

Egy tároló összes dokumentumának fordítása

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

Adott dokumentum fordítása egy tárolóban

  • Adja meg a következőt: "storageType": "File".
  • Ha nem használ rendszer által hozzárendelt felügyelt identitást a hitelesítéshez, győződjön meg arról, hogy forrás URL- és SAS-jogkivonatokat hozott létre az adott blobhoz/dokumentumhoz (nem a tárolóhoz).
  • Győződjön meg arról, hogy a célfájlnevet a cél URL-cím részeként adta meg – bár az SAS-jogkivonat továbbra is a tárolóhoz tartozik.
  • Ez a mintakérelem egyetlen, két célnyelvre lefordított dokumentumot ad vissza.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es"
                },
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "de"
                }
            ]
        }
    ]
}

Dokumentumok fordítása egyéni szószedet használatával

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

Dokumentumfordítási kérelmek elküldése kód használatával

A kódolási platform beállítása

  • Új projekt létrehozása.
  • Cserélje le Program.cs a C# kódmintára.
  • Állítsa be a végpont, a kulcs és a tároló URL-értékeit a Program.cs.
  • Adja hozzá a Newtonsoft.Json-csomagot a .NET CLI használatával a JSON-adatok feldolgozásához.
  • Futtassa a programot a projektkönyvtárból.

Fontos

A kódminták esetében a megosztott hozzáférésű jogosultságkód (SAS) URL-címét a megadott módon fogja kódba írni. Ne felejtse el eltávolítani az SAS URL-címet a kódból, amikor elkészült, és soha ne tegye közzé nyilvánosan. Éles környezetben biztonságos módon tárolhatja és érheti el a hitelesítő adatait, például az Azure Managed Identity-et. További információ: Azure Storage security.

A művelettől függően előfordulhat, hogy frissítenie kell a következő mezőket:

  • endpoint
  • basePath
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (feladatazonosító)

Az id érték keresése

  • A feladatot id a POST start-batch-translation metódus válaszfejlécÉNEK Operation-Location URL-címében találja. A paramétert követő /document/ alfanumerikus sztring a művelet feladata id:
Válaszfejléc Válasz URL-címe
Művelet helye {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date}
  • A fordítási feladatok és azok idlistájának lekéréséhez a get-translations állapotkérelmet is használhatja.

Aszinkron kötegelt fordítás indítása


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

            }

        }

    }

Támogatott dokumentumformátumok lekérése

Kérje le a támogatott fájlformátumok listáját. Ha sikeres, ez a metódus válaszkódot 200 OK ad vissza.


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

Fordítási feladat állapotának lekérése

Egyetlen feladat aktuális állapotának és a dokumentumfordítási kérelemben szereplő összes feladat összegzésének lekérése. Ha sikeres, ez a metódus válaszkódot 200 OK ad vissza.


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

Adott dokumentum állapotának lekérése

Rövid áttekintés

Egy adott dokumentum állapotának lekérése egy dokumentumfordítási kérelemben. Ha sikeres, ez a metódus válaszkódot 200 OK ad vissza.


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

Feladat törlése

Rövid áttekintés

Az aktuális feldolgozási vagy várólistás feladat megszakítása. A rendszer csak azokat a dokumentumokat törli, amelyek fordítása nem kezdődött el.


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

Gyakori HTTP-állapotkódok

HTTP-állapotkód Leírás Lehetséges ok
200 OK A kérés sikeres volt.
400 Hibás kérés Hiányzik egy kötelező paraméter, üres vagy null. Vagy a kötelező vagy nem kötelező paraméternek átadott érték érvénytelen. Gyakori probléma a túl hosszú fejléc.
401 Nem engedélyezett A kérés nincs engedélyezve. Ellenőrizze, hogy a kulcs vagy a jogkivonat érvényes-e, és hogy a megfelelő régióban van-e. Az előfizetés Azure Portalon történő kezelésekor győződjön meg arról, hogy a Translator egyszolgáltatásos erőforrást használja, nem pedig az Azure AI-szolgáltatások többszolgáltatásos erőforrását.
429 Túl sok kérés Túllépte az előfizetéshez engedélyezett kérelmek kvótáját vagy arányát.
502 Hibás átjáró Hálózati vagy kiszolgálóoldali probléma. Érvénytelen fejléceket is jelezhet.

További információ

Következő lépések

Testreszabott nyelvi rendszer létrehozása a Custom Translator használatával