Translator v3.0

Cikk
09/01/2024

Újdonságok

A Translator 3.0-s verziója egy modern JSON-alapú webes API-t biztosít. A meglévő funkciók kevesebb műveletre való összevonásával javítja a használhatóságot és a teljesítményt, és új funkciókat biztosít.

Átírás az egyik nyelv szövegének konvertálásához egy szkriptből egy másik szkriptbe.
Fordítás több nyelvre egyetlen kérelemben.
Nyelvfelismerés, fordítás és átírás egyetlen kérelemben.
Szótár a kifejezés alternatív fordításainak kereséséhez, a háttérfordítások és a kontextusban használt kifejezéseket bemutató példák kereséséhez.
Informatívabb nyelvfelismerési eredmények.

Alap URL-címek

A Translatornek küldött kérelmeket a legtöbb esetben az adatközpont kezeli, amely a legközelebb van a kérés kiindulási helyéhez. Ha a globális végpont használatakor adatközpont-hiba történik, előfordulhat, hogy a kérést a földrajzi helyen kívülre irányítják.

Ha a kérelmet egy adott földrajzi helyen szeretné kezelni, használja a kívánt földrajzi végpontot. A rendszer az összes kérést a földrajzi helyen lévő adatközpontok között dolgozza fel.

✔️ Funkció: Translator Text

Szolgáltatásvégpont	Adatfeldolgozási adatközpont kérése
Globális (ajánlott): `api.cognitive.microsofttranslator.com`	Legközelebbi elérhető adatközpont.
Amerika: `api-nam.cognitive.microsofttranslator.com`	USA 2. keleti régiója • USA 2. nyugati régiója
Ázsia és a Csendes-óceáni térség `api-apc.cognitive.microsofttranslator.com`:	Kelet-Japán • Délkelet-Ázsia
Európa (Svájc kivételével): `api-eur.cognitive.microsofttranslator.com`	Közép-Franciaország • Nyugat-Európa
Svájc: További információ: Svájc szolgáltatásvégpontjai.	Észak-Svájc • Nyugat-Svájc

Svájc szolgáltatásvégpontjai

Az észak- vagy svájc nyugati svájcban található erőforrással rendelkező ügyfelek gondoskodhatnak arról, hogy a Text API-kéréseik Svájcban legyenek kiszolgálva. Annak érdekében, hogy a kérések Svájcban legyenek kezelve, hozza létre a Translator-erőforrást a Resource region Switzerland North vagy Switzerland West, majd használja az erőforrás egyéni végpontját az API-kérésekben.

Például: Ha egy Translator-erőforrást hoz létre az Azure Portalon Resource region az as és Switzerland North az erőforrás neve alapjánmy-swiss-n, akkor az egyéni végpontja.https://my-swiss-n.cognitiveservices.azure.com A fordítási mintakérés pedig a következő:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

A Custom Translator jelenleg nem érhető el Svájcban.

Hitelesítés

Iratkozzon fel a Translatorre vagy a többszolgáltatásos Azure AI-szolgáltatásokra, és használja a kulcsát (amely az Azure Portalon érhető el) a hitelesítéshez.

Az előfizetés hitelesítéséhez három fejléc használható. Ez a táblázat az egyes eszközök használatát ismerteti:

Fejlécek	Leírás
Ocp-Apim-Subscription-Key	Használja az Azure AI-szolgáltatások előfizetését, ha titkos kulcsot ad át. Az érték a Translator-előfizetés azure-titkos kulcsa.
Engedélyezés	Ha hitelesítési jogkivonatot ad át, használja az Azure AI-szolgáltatások előfizetésével. Az érték a Tulajdonos jogkivonata: `Bearer <token>`.
Ocp-Apim-Subscription-Region	Többszolgáltatásos és regionális fordítói erőforrással használható. Az érték a többszolgáltatásos vagy regionális fordítói erőforrás régiója. Ez az érték nem kötelező globális fordítói erőforrás használatakor.

Titkos kulcs

Az első lehetőség a fejléc használatával történő Ocp-Apim-Subscription-Key hitelesítés. Adja hozzá a Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> fejlécet a kéréshez.

Hitelesítés globális erőforrással

Globális fordítói erőforrás használata esetén egy fejlécet kell tartalmaznia a Translator meghívásához.

Fejlécek	Leírás
Ocp-Apim-Subscription-Key	Az érték a Translator-előfizetés azure-titkos kulcsa.

Íme egy példakérés a Translator meghívására a globális fordítói erőforrás használatával

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Hitelesítés regionális erőforrással

Regionális fordítói erőforrás használata esetén két fejlécet kell meghívnia a Translatornek.

Fejlécek	Leírás
Ocp-Apim-Subscription-Key	Az érték a Translator-előfizetés azure-titkos kulcsa.
Ocp-Apim-Subscription-Region	Az érték a fordítóerőforrás régiója.

Íme egy példakérés a Translator meghívására a regionális fordítói erőforrás használatával

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Hitelesítés többszolgáltatásos erőforrással

A többszolgáltatásos erőforrás lehetővé teszi egyetlen API-kulcs használatát több szolgáltatás kéréseinek hitelesítéséhez.

Többszolgáltatásos titkos kulcs használatakor két hitelesítési fejlécet kell tartalmaznia a kéréshez. Két fejlécet kell meghívnia a Translatornek.

Fejlécek	Leírás
Ocp-Apim-Subscription-Key	Az érték a többszolgáltatásos erőforrás Azure titkos kulcsa.
Ocp-Apim-Subscription-Region	Az érték a többszolgáltatásos erőforrás régiója.

A többszolgáltatásos Text API-előfizetéshez régióra van szükség. A kijelölt régió az egyetlen régió, amelyet szövegfordításhoz használhat a többszolgáltatásos kulcs használatakor. A többszolgáltatásos előfizetésre az Azure Portalon való regisztrációkor kiválasztott régiónak kell lennie.

Ha a lekérdezési sztring titkos kulcsát a paraméterrel Subscription-Keyegyütt adja meg, akkor meg kell adnia a lekérdezési paraméterrel Subscription-Regionrendelkező régiót.

Hitelesítés hozzáférési jogkivonattal

Másik lehetőségként kicserélheti a titkos kulcsot egy hozzáférési jogkivonatra. Ez a jogkivonat az egyes kérések fejléceként szerepel.Authorization Engedélyezési jogkivonat beszerzéséhez küldjön egy kérést POST a következő URL-címre:

Erőforrás típusa	Hitelesítési szolgáltatás URL-címe
Globális	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Regionális vagy többszolgáltatásos	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Íme néhány példakérés egy globális erőforrás titkos kulcsához kapott jogkivonat beszerzésére:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

Az alábbiakban példakéréseket talál az USA középső régiójában található regionális erőforrás titkos kulcsához kapott jogkivonat beszerzésére:

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

A sikeres kérés a kódolt hozzáférési jogkivonatot egyszerű szövegként adja vissza a válasz törzsében. Az érvényes jogkivonat a Translator szolgáltatásnak lesz átadva tulajdonosi jogkivonatként az Engedélyezésben.

Authorization: Bearer <Base64-access_token>

A hitelesítési jogkivonat 10 percig érvényes. A jogkivonatot újra fel kell használni, amikor több hívást kezdeményez a Translator felé. Ha azonban a program hosszabb időn keresztül kér kéréseket a Translatornek, akkor a programnak rendszeres időközönként (például 8 percenként) új hozzáférési jogkivonatot kell kérnie.

Hitelesítés Microsoft Entra-azonosítóval

A Translator 3.0-s verzió támogatja a Microsoft Entra-hitelesítést, a Microsoft felhőalapú identitás- és hozzáférés-kezelési megoldását. Az engedélyezési fejlécek lehetővé teszik a Translator szolgáltatás számára annak ellenőrzését, hogy a kérelmező ügyfél jogosult-e az erőforrás használatára és a kérés teljesítésére.

Előfeltételek

Rövid útmutató a Microsoft Entra-azonosítóval történő hitelesítéshez.
A felügyelt identitásokhoz való hozzáférés engedélyezésének rövid ismertetése.

Fejlécek

Fejléc	Érték
Engedélyezés	Az érték az Azure AD által létrehozott hozzáférési jogkivonat . A tulajdonosi jogkivonat igazolja a hitelesítést, és ellenőrzi, hogy az ügyfél engedélyezte-e az erőforrás használatát. A hitelesítési jogkivonat 10 percig érvényes, és a Translator felé irányuló több hívás esetén újra fel kell használni. Lásd a mintakérést: 2. Jogkivonat lekérése
Ocp-Apim-Subscription-Region	Az érték a fordítóerőforrás régiója. Ez az érték nem kötelező, ha az erőforrás globális.
Ocp-Apim-ResourceId	Az érték a Translator-erőforráspéldány erőforrás-azonosítója. Az erőforrás-azonosítót az Azure Portalon találja a Translator Resource → Properties webhelyen. Erőforrás-azonosító formátuma: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName/>

Translator tulajdonságlap – Azure Portal

Képernyőkép:Translator properties page in the Azure Portal.

Fontos

Cognitive Services felhasználói szerepkör hozzárendelése a szolgáltatásnévhez. A szerepkör hozzárendelésével szolgáltatásnév-hozzáférést biztosít a Translator-erőforráshoz.

Példák

A globális végpont használata

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Az egyéni végpont használata

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Példák felügyelt identitások használatára

A Translator 3.0-s verzió is támogatja a felügyelt identitásokhoz való hozzáférés engedélyezését. Ha egy felügyelt identitás engedélyezve van egy fordítóerőforráshoz, a kérelem fejlécében átadhatja a felügyelt identitás által létrehozott tulajdonosi jogkivonatot.

A globális végponttal

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Az egyéni végponttal

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Virtuális hálózatok támogatása

A Translator szolgáltatás mostantól virtuális hálózat (VNET) funkciókkal érhető el az Azure nyilvános felhő minden régiójában. A virtuális hálózat engedélyezéséhez tekintse meg az Azure AI-szolgáltatások virtuális hálózatának konfigurálását.

Miután bekapcsolta ezt a funkciót, az egyéni végpontot kell használnia a Translator meghívásához. A globális fordítóvégpont ("api.cognitive.microsofttranslator.com") nem használható, és nem hitelesíthető hozzáférési jogkivonattal.

Miután létrehozott egy fordítóerőforrást, és engedélyezte a hozzáférést a kiválasztott hálózatokról és privát végpontokról, megtalálhatja az egyéni végpontot.

Lépjen a Translator-erőforráshoz az Azure Portalon.
Válassza a Hálózatkezelés lehetőséget az Erőforrás-kezelés szakaszban.
A Tűzfalak és a virtuális hálózatok lapon válassza a Kijelölt hálózatok és privát végpontok lehetőséget.
Válassza a Mentés lehetőséget a módosítások alkalmazásához.
Válassza a Kulcsok és végpont lehetőséget az Erőforrás-kezelés szakaszban.
Válassza a Virtuális hálózat lapot.
A listában a szövegfordítás és a dokumentumfordítás végpontjai találhatók.

Fejlécek	Leírás
Ocp-Apim-Subscription-Key	Az érték a Translator-előfizetés azure-titkos kulcsa.
Ocp-Apim-Subscription-Region	Az érték a fordítóerőforrás régiója. Ez az érték nem kötelező, ha az erőforrás `global`

Íme egy példakérés a Translator egyéni végponttal való meghívására

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Errors

A standard hibaválasz egy név/érték pár nevű errorJSON-objektum. Az érték egy JSON-objektum is, amely a következő tulajdonságokkal rendelkezik:

code: Kiszolgáló által definiált hibakód.
message: Egy sztring, amely a hiba emberi olvasásra alkalmas ábrázolását adja meg.

Az ingyenes próbaverziós előfizetéssel rendelkező ügyfelek például a következő hibaüzenetet kapják az ingyenes kvóta kimerítése után:

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

A hibakód egy 6 jegyű szám, amely egyesíti a 3 jegyű HTTP-állapotkódot, majd egy háromjegyű számot a hiba további kategorizálásához. Gyakori hibakódok:

Kód	Leírás
400000	Az egyik kérelembemenet nem érvényes.
400001	A „scope” paraméter érvénytelen.
400002	A „category” paraméter érvénytelen.
400003	Hiányzó vagy érvénytelen nyelvdefiniáló.
400004	Hiányzó vagy érvénytelen célszkript-definiáló („To script”).
400005	Hiányzó vagy érvénytelen bemeneti szöveg.
400006	A nyelv és szkript kombinációja nem érvényes.
400018	Hiányzó vagy érvénytelen forrásszkript-definiáló („From script”).
400019	A megadott nyelvek egyike nem támogatott.
400020	A bemeneti szöveg tömbjének egyik eleme nem érvényes.
400021	Az API-verzió paraméter hiányzik vagy érvénytelen.
400023	A megadott nyelvpárok egyike nem érvényes.
400035	A forrásnyelv („From” mező) nem érvényes.
400036	A célnyelv („To” mező) hiányzik vagy érvénytelen.
400042	Az egyik megadott lehetőség („Options” mező) nem érvényes.
400043	Az ügyfél nyomkövetési azonosítója (ClientTraceId mező vagy X-ClientTraceId fejléc) hiányzik vagy érvénytelen.
400050	A bemeneti szöveg túl hosszú. Tekintse meg a kérelmekre vonatkozó korlátokat.
400064	A „translation” paraméter hiányzik vagy érvénytelen.
400070	A célszkriptek száma (ToScript paraméter) nem egyezik a célnyelvek számával (To paraméter).
400071	A TextType nem támogatja az értéket.
400072	A bemeneti szöveg tömbje túl sok elemet tartalmaz.
400073	A szkriptparaméter nem érvényes.
400074	A kérelem törzse nem érvényes JSON.
400075	A nyelvpár és kategória kombinációja nem érvényes.
400077	Túllépte a maximális kérelemméretet. Tekintse meg a kérelmekre vonatkozó korlátokat.
400079	A forrás- és célnyelv közötti fordításhoz kért egyéni rendszer nem létezik.
400080	A nyelv vagy szkript esetében az átírás nem támogatott.
401000	A kérés nincs engedélyezve, mert a hitelesítő adatok hiányoznak vagy érvénytelenek.
401015	"A megadott hitelesítő adatok a Speech API-hoz tartoznak. Ehhez a kéréshez hitelesítő adatokra van szükség a Text API-hoz. A Translator előfizetésének használata."
403000	A művelet nem engedélyezett.
403001	A művelet nem engedélyezett, mert az előfizetés túllépte az ingyenes kvótáját.
405000	A kérelemmetódus nem támogatott a kért erőforrás esetében.
408001	A kért fordítási rendszer előkészítése folyamatban van. Próbálkozzon újra néhány perc múlva.
408002	A kérelem túllépte az időkorlátot a bejövő streamre várakozva. Az ügyfél nem küldött kérelmet a kiszolgáló várakozásra szánt idején belül. Az ügyfél később módosítás nélkül megismételheti a kérelmet.
415000	A Tartalomtípus fejléc hiányzik vagy érvénytelen.
429000, 429001, 429002	A kiszolgáló elutasította a kérést, mert az ügyfél túllépte a kérelmek korlátait.
500 000	Egy váratlan hiba történt. Ha a hiba továbbra is fennáll, jelentse a hiba dátumát/időpontját, az X-RequestId válaszfejlécből származó kérésazonosítót és az X-ClientTraceId kérelemfejléc ügyfélazonosítóját.
503000	A szolgáltatás átmenetileg nem elérhető. Próbálkozzon újra. Ha a hiba továbbra is fennáll, jelentse a hiba dátumát/időpontját, az X-RequestId válaszfejlécből származó kérésazonosítót és az X-ClientTraceId kérelemfejléc ügyfélazonosítóját.

Mérőszámok

A metrikák segítségével megtekintheti a fordító használati és rendelkezésre állási adatait az Azure Portalon, a metrikák szakaszban, az alábbi képernyőképen látható módon. További információ: Adatok és platformmetrikák.

Translator-metrikák

Ez a táblázat felsorolja az elérhető metrikákat, és leírja, hogyan használják őket a fordítási API-hívások figyelésére.

Mérőszámok	Leírás
TotalCalls	API-hívások teljes száma.
TotalTokenCalls	A tokenszolgáltatáson keresztüli API-hívások teljes száma hitelesítési jogkivonat használatával.
Sikeres hívás	Sikeres hívások száma.
TotalErrors	A hibaválaszt tartalmazó hívások száma.
BlockedCalls	A sebesség- vagy kvótakorlátot túllépő hívások száma.
ServerErrors	A kiszolgáló belső hibájával (5XX) rendelkező hívások száma.
ClientErrors	Ügyféloldali hibával (4XX) rendelkező hívások száma.
Késés	A kérés teljesítésének időtartama ezredmásodpercben.
CharactersTranslated	A bejövő szöveges kérelemben szereplő karakterek teljes száma.

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