Translator v3.0

Článek
09/01/2024

Co je nového?

Translator verze 3.0 poskytuje moderní webové rozhraní API založené na JSON. Zlepšuje použitelnost a výkon sloučením stávajících funkcí do menšího počtu operací a poskytuje nové funkce.

Transkliterace pro převod textu v jednom jazyce z jednoho skriptu do jiného skriptu
Překlad do více jazyků v jednom požadavku
Rozpoznávání jazyka, překlad a transklitace v jednom požadavku.
Slovník pro vyhledání alternativních překladů termínu, vyhledání zpětných překladů a příkladů zobrazující termíny použité v kontextu.
Podrobnější výsledky rozpoznávání jazyka

Základní adresy URL

Žádosti o translator jsou ve většině případů zpracovávány datacentrem, které je nejblíže místě, kde žádost pochází. Pokud při použití globálního koncového bodu dojde k selhání datacentra, může být požadavek směrován mimo zeměpisnou oblast.

Pokud chcete vynutit zpracování požadavku v rámci konkrétní geografické oblasti, použijte požadovaný geografický koncový bod. Všechny požadavky se zpracovávají mezi datacentry v rámci zeměpisné oblasti.

✔️ Funkce: Translator Text

Koncový bod služby	Žádost o zpracování datacentra
Globální (doporučeno): `api.cognitive.microsofttranslator.com`	Nejbližší dostupné datové centrum
Amerika: `api-nam.cognitive.microsofttranslator.com`	USA – východ 2 • USA – západ 2
Asie a Tichomoří: `api-apc.cognitive.microsofttranslator.com`	Japonsko – východ • Jihovýchodní Asie
Evropa (s výjimkou Švýcarska): `api-eur.cognitive.microsofttranslator.com`	Francie – střed • Západní Evropa
Švýcarsko: Další informace najdete v tématu Koncové body služby Švýcarsko.	Švýcarsko – sever • Švýcarsko – západ

Koncové body služby Švýcarsko

Zákazníci s prostředkem umístěným ve Švýcarsku – sever nebo Švýcarsko – západ můžou zajistit, aby se jejich požadavky na textové rozhraní API obsluhovaly ve Švýcarsku. Pokud chcete zajistit, aby se požadavky zpracovávaly ve Švýcarsku, vytvořte prostředek Translatoru v Resource region Switzerland North nebo Switzerland Westa pak ve vašich požadavcích rozhraní API použijte vlastní koncový bod prostředku.

Příklad: Pokud na webu Azure Portal vytvoříte prostředek translatoru jako Resource region Switzerland North a název prostředku je my-swiss-n, pak je https://my-swiss-n.cognitiveservices.azure.comváš vlastní koncový bod . A ukázkový požadavek na překlad:

// 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

Custom Translator není v současné době k dispozici ve Švýcarsku.

Ověřování

Přihlaste se k odběru služby Translator nebo multi-service ve službách Azure AI a k ověření použijte svůj klíč (dostupný na webu Azure Portal).

K ověření předplatného můžete použít tři hlavičky. Tato tabulka popisuje, jak se jednotlivé používají:

Hlavičky	Popis
Ocp-Apim-Subscription-Key	Pokud předáváte tajný klíč, použijte s předplatným služeb Azure AI. Hodnota je tajný klíč Azure pro vaše předplatné služby Translator.
Autorizace	Používá se s předplatným služeb Azure AI, pokud předáváte ověřovací token. Hodnota je nosný token: `Bearer <token>`.
Ocp-Apim-Subscription-Region	Používá se s více službami a regionálními prostředky translatoru. Hodnota je oblast víceslužného nebo regionálního překladatelského prostředku. Tato hodnota je volitelná při použití globálního prostředku překladatele.

Tajný klíč

První možností je ověření pomocí hlavičky Ocp-Apim-Subscription-Key . Přidejte do požadavku hlavičku Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> .

Ověřování pomocí globálního prostředku

Pokud používáte prostředek globálního překladače, musíte k volání služby Translator zahrnout jednu hlavičku.

Hlavičky	Popis
Ocp-Apim-Subscription-Key	Hodnota je tajný klíč Azure pro vaše předplatné služby Translator.

Tady je příklad požadavku na volání služby Translator pomocí prostředku globálního překladače.

// 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?'}]"

Ověřování pomocí místního prostředku

Pokud používáte prostředek místního překladače, musíte volat službu Translator dvěma záhlavími.

Hlavičky	Popis
Ocp-Apim-Subscription-Key	Hodnota je tajný klíč Azure pro vaše předplatné služby Translator.
Ocp-Apim-Subscription-Region	Hodnota je oblast prostředku translatoru.

Tady je příklad požadavku na volání služby Translator pomocí zdroje místního překladače.

// 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?'}]"

Ověřování pomocí prostředku s více službami

Prostředek s více službami umožňuje použít jeden klíč rozhraní API k ověřování požadavků pro více služeb.

Pokud používáte tajný klíč s více službami, musíte do požadavku zahrnout dvě hlavičky ověřování. Existují dvě záhlaví, která potřebujete volat Translator.

Hlavičky	Popis
Ocp-Apim-Subscription-Key	Hodnota je tajný klíč Azure pro váš prostředek s více službami.
Ocp-Apim-Subscription-Region	Hodnota je oblast prostředku s více službami.

Oblast se vyžaduje pro předplatné rozhraní TEXT API s více službami. Oblast, kterou vyberete, je jediná oblast, kterou můžete použít k překladu textu při použití klíče s více službami. Musí to být stejná oblast, kterou jste vybrali při registraci předplatného s více službami prostřednictvím webu Azure Portal.

Pokud předáte tajný klíč v řetězci dotazu s parametrem Subscription-Key, je nutné zadat oblast s parametrem Subscription-Regiondotazu .

Ověřování pomocí přístupového tokenu

Případně můžete tajný klíč vyměnit za přístupový token. Tento token je součástí každého požadavku jako hlavičky Authorization . Pokud chcete získat autorizační token, nastavte POST požadavek na následující adresu URL:

Typ prostředku	Adresa URL ověřovací služby
Globální	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Místní nebo více služeb	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Tady jsou příklady požadavků na získání tokenu uděleného tajnému klíči pro globální prostředek:

// 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>'

Tady jsou příklady požadavků na získání tokenu uděleného tajnému klíči pro místní prostředek umístěný v oblasti USA – střed:

// 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>"

Úspěšný požadavek vrátí kódovaný přístupový token jako prostý text v textu odpovědi. Platný token se předává službě Translator jako nosný token v autorizaci.

Authorization: Bearer <Base64-access_token>

Ověřovací token je platný po dobu 10 minut. Token by se měl znovu použít při provádění více volání služby Translator. Pokud ale váš program odešle žádosti do služby Translator po delší dobu, musí váš program v pravidelných intervalech požádat o nový přístupový token (například každých 8 minut).

Ověřování pomocí Microsoft Entra ID

Translator v3.0 podporuje ověřování Microsoft Entra, cloudové řešení pro správu identit a přístupu od Microsoftu. Autorizační hlavičky umožňují službě Translator ověřit, že žádající klient má oprávnění k používání prostředku a k dokončení požadavku.

Požadavky

Stručný přehled o tom, jak se ověřit pomocí ID Microsoft Entra.
Stručný přehled toho, jak autorizovat přístup ke spravovaným identitám.

Záhlaví

Hlavička	Hodnota
Autorizace	Hodnota je přístupový nosný token vygenerovaný službou Azure AD. Nosný token poskytuje doklad o ověření a ověřuje autorizaci klienta pro použití prostředku. Ověřovací token je platný po dobu 10 minut a měl by se znovu použít při provádění více volání služby Translator. Viz Ukázkový požadavek: 2. Získání tokenu
Ocp-Apim-Subscription-Region	Hodnota je oblast prostředku translatoru. Tato hodnota je volitelná, pokud je prostředek globální.
Ocp-Apim-ResourceId	Hodnota je ID prostředku pro instanci prostředku Služby Translator. ID prostředku najdete na webu Azure Portal ve vlastnostech služby Translator Resource →. Formát ID prostředku: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Stránka vlastností translatoru – Azure Portal

Snímek obrazovky: Stránka vlastností služby Translator na webu Azure Portal

Důležité

Přiřaďte instančnímu objektu roli uživatele služeb Cognitive Services. Přiřazením této role udělujete instančnímu objektu přístup k prostředku Služby Translator.

Příklady

Použití globálního koncového bodu

 // 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.'}]"

Použití vlastního koncového bodu

// 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říklady použití spravovaných identit

Translator v3.0 také podporuje autorizaci přístupu ke spravovaným identitám. Pokud je pro prostředek služby Translator povolená spravovaná identita, můžete předat nosný token vygenerovaný spravovanou identitou v hlavičce požadavku.

S globálním koncovým bodem

// 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.'}]"

S vlastním koncovým bodem

//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.'}]"

Podpora virtuální sítě

Služba Translator je teď dostupná s možnostmi virtuální sítě ve všech oblastech veřejného cloudu Azure. Pokud chcete povolit virtuální síť, přečtěte si téma Konfigurace virtuálních sítí služeb Azure AI.

Jakmile tuto funkci zapnete, musíte k volání služby Translator použít vlastní koncový bod. Nemůžete použít koncový bod globálního překladače ("api.cognitive.microsofttranslator.com") a nemůžete se ověřit pomocí přístupového tokenu.

Vlastní koncový bod najdete po vytvoření prostředku služby Translator a povolení přístupu z vybraných sítí a privátních koncových bodů.

Na webu Azure Portal přejděte k prostředku služby Translator.
V části Správa prostředků vyberte Sítě.
Na kartě Brány firewall a virtuální sítě zvolte Vybrané sítě a privátní koncové body.
Výběrem možnosti Uložit se vaše změny uplatní.
V části Správa prostředků vyberte klíče a koncový bod.
Vyberte kartu Virtuální síť.
V seznamu jsou koncové body pro překlad textu a překlad dokumentu.

Hlavičky	Popis
Ocp-Apim-Subscription-Key	Hodnota je tajný klíč Azure pro vaše předplatné služby Translator.
Ocp-Apim-Subscription-Region	Hodnota je oblast prostředku translatoru. Tato hodnota je nepovinná, pokud je prostředek `global`

Tady je příklad požadavku na volání služby Translator pomocí vlastního koncového bodu.

// 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?'}]"

Chyby

Standardní chybová odpověď je objekt JSON s názvem errorname/value pair . Hodnota je také objekt JSON s vlastnostmi:

code: Kód chyby definovaný serverem.
message: Řetězec, který poskytuje čitelné znázornění chyby člověkem.

Například zákazník s bezplatným zkušebním předplatným by se po vyčerpání bezplatné kvóty zobrazila následující chyba:

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

Kód chyby je 6místné číslo, které kombinuje 3místný stavový kód HTTP následovaný 3místným číslem, aby se chyba dále kategorizovala. Běžné kódy chyb:

Kód	Popis
400000	Jeden ze vstupů požadavku není platný.
400001	Parametr scope je neplatný.
400002	Parametr category je neplatný.
400003	Specifikátor jazyka chybí nebo je neplatný.
400004	Specifikátor cílového skriptu (To script) chybí nebo je neplatný.
400005	Vstupní text chybí nebo je neplatný.
400006	Kombinace jazyka a skriptu není platná.
400018	Specifikátor zdrojového skriptu (From script) chybí nebo je neplatný.
400019	Jeden ze zadaných jazyků se nepodporuje.
400020	Jeden z prvků v poli vstupního textu není platný.
400021	Parametr verze rozhraní API chybí nebo je neplatný.
400023	Jeden ze zadaných jazykových párů není platný.
400035	Zdrojový jazyk (pole From) není platný.
400036	Cílový jazyk (pole To) chybí nebo je neplatný.
400042	Jedna ze zadaných možností (pole Options) není platná.
400043	ID trasování klienta (pole ClientTraceId nebo hlavička X-ClientTraceId) chybí nebo je neplatné.
400050	Vstupní text je příliš dlouhý. Projděte si omezení počtu požadavků.
400064	Parametr translation chybí nebo je neplatný.
400070	Počet cílových skriptů (parametr ToScript) neodpovídá počtu cílových jazyků (parametr To).
400071	Hodnota není platná pro TextType.
400072	Pole vstupního textu má příliš mnoho prvků.
400073	Parametr skriptu není platný.
400074	Text požadavku nemá platný formát JSON.
400075	Kombinace jazykového páru a kategorie není platná.
400077	Byla překročena maximální velikost požadavku. Projděte si omezení počtu požadavků.
400079	Vlastní systém požadovaný pro překlad mezi zdrojovým a cílovým jazykem neexistuje.
400080	Transkripce není podporována pro jazyk nebo skript.
401000	Požadavek není autorizovaný, protože chybí nebo jsou neplatné přihlašovací údaje.
401015	Zadané přihlašovací údaje jsou určené pro rozhraní Speech API. Tento požadavek vyžaduje přihlašovací údaje pro textové rozhraní API. Použití předplatného služby Translator."
403000	Operace není povolená.
403001	Operace není povolená, protože předplatné překročilo svou bezplatnou kvótu.
405000	Metoda požadavku není pro požadovaný prostředek podporovaná.
408001	Požadovaný systém překladu se připravuje. Zkuste to znovu za několik minut.
408002	Vypršel časový limit požadavku čekajícího na příchozí datový proud. Klient nevytvářel požadavek v době, kdy byl server připraven čekat. Klient může požadavek zopakovat bez úprav později.
415000	Záhlaví Content-Type chybí nebo je neplatné.
429000, 429001, 429002	Server odmítl požadavek, protože klient překročil limity požadavků.
500000	Došlo k neočekávané chybě. Pokud chyba přetrvává, nahlaste ji s datem a časem chyby, identifikátorem požadavku z hlavičky odpovědi X-RequestId a identifikátorem klienta z hlavičky požadavku X-ClientTraceId.
503000	Služba je dočasně nedostupná. Zkuste to znovu. Pokud chyba přetrvává, nahlaste ji s datem a časem chyby, identifikátorem požadavku z hlavičky odpovědi X-RequestId a identifikátorem klienta z hlavičky požadavku X-ClientTraceId.

Metriky

Metriky umožňují zobrazit informace o využití a dostupnosti služby Translator na webu Azure Portal v části metriky, jak je znázorněno na následujícím snímku obrazovky. Další informace najdete v tématu Data a metriky platformy.

Translator Metrics

Tato tabulka uvádí dostupné metriky s popisem toho, jak se používají k monitorování volání rozhraní API pro překlad.

Metriky	Popis
TotalCalls	Celkový počet volání rozhraní API
TotalTokenCalls	Celkový počet volání rozhraní API prostřednictvím služby tokenů pomocí ověřovacího tokenu
SuccessfulCalls	Počet úspěšných volání
TotalErrors	Počet volání s chybovou odpovědí
BlockedCalls	Početvoláních
Chyby serveru	Počet volání s interní chybou serveru (5XX).
Chyby klienta	Počet volání s chybou na straně klienta (4XX).
Latence	Doba trvání dokončení požadavku v milisekundách
ZnakyTranslated	Celkový počet znaků v příchozím textovém požadavku

Sdílet prostřednictvím