REST API-k programozott használata
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 azAzure 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:
Előfizetés. Válasszon egyet az elérhető Azure-előfizetései közül.
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.
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.
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.
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.
Válassza a Felülvizsgálat és létrehozás lehetőséget.
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.
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.
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.
A bal oldali korlát Erőforrás-kezelés területén válassza a Kulcsok és végpont lehetőséget.
Másolja és illessze be a
keydocument translation endpointmegfelelő helyre, például a Microsoft Jegyzettömbbe. API-hívás létrehozásához csak egy kulcs szükséges.Ön
keyésdocument translation endpointa kódminták segítségével hitelesítheti a kérést a Dokumentumfordítási szolgáltatásban.
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.
- 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.
- A bal oldali korlát Erőforrás-kezelés területén válassza a Kulcsok és végpont lehetőséget.
- Másolja és illessze be a kulcsot egy kényelmes helyre, például a Microsoft Jegyzettömbbe.
- Illessze be a kódmintába, hogy hitelesítse a kérést a Dokumentumfordítási szolgáltatásban.
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álré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
inputsobjektum a forrás- éstargetURLcélnyelvi párok mindkétsourceURLés tárolócímét tartalmazza. - A
prefixfordítás forrásútvonalában található dokumentumok szűréséhez használt kis- éssuffixnagybetűk megkülönböztetése. Aprefixmezőt gyakran használják almappák fordításához. Asuffixmezőt leggyakrabban fájlkiterjesztésekhez használják. - A dokumentum lefordításakor a
glossariesprogram a mező értékét alkalmazza (nem kötelező). - Az
targetUrlegyes 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:
endpointkeysourceURLtargetURLglossaryURLid(feladatazonosító)
Az id érték keresése
- A feladatot
ida POSTstart-batch-translationmetódus válaszfejlécÉNEKOperation-LocationURL-címében találja. A paramétert követő/document/alfanumerikus sztring a művelet feladataid:
| Válaszfejléc | Válasz URL-címe |
|---|---|
| Művelet helye | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01 |
- A fordítási feladatok és azok
idlistájának lekéréséhez a get-translations állapotkérelmet is használhatja.
Dokumentumok fordítása
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.1";
private static readonly string key = "<YOUR-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(endpoint + 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");
}
}
}
Fájlformá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 endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";
static readonly string route = "/documents/formats";
private static readonly string key = "<YOUR-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", 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 á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 endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";
static readonly string route = "/batches/{id}";
private static readonly string key = "<YOUR-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", 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);
}
}
}
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 endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";
static readonly string route = "/{id}/document/{documentId}";
private static readonly string key = "<YOUR-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", 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 endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";
static readonly string route = "/batches/{id}";
private static readonly string key = "<YOUR-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", 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
Visszajelzés
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ: https://aka.ms/ContentUserFeedback.
Visszajelzés küldése és megtekintése a következőhöz: