Translator verze 3.0

Co je nového

Verze 3 Translator poskytuje moderní webové rozhraní API založené na formátu 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 na jiný skript
  • 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í back-překladů a příkladů znázorňující termíny použité v kontextu
  • Více informativní výsledky rozpoznávání jazyka.

Základní adresy URL

Žádosti o Translator se ve většině případů zpracovávají datacentrem, které je nejblíže místu, 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í zeměpisné oblasti, použijte požadovaný geografický koncový bod. Všechny požadavky se zpracovávají mezi datovými centry v rámci zeměpisné oblasti.

Geografie Základní adresa URL (geografický koncový bod) Datová centra
Globální (neregionální) api.cognitive.microsofttranslator.com Nejbližší dostupné datové centrum
Asie a Tichomoří api-apc.cognitive.microsofttranslator.com Korea – jih, Japonsko – východ, Jihovýchodní Asie a Austrálie – východ
Evropa api-eur.cognitive.microsofttranslator.com Severní Evropa, Západní Evropa
USA api-nam.cognitive.microsofttranslator.com USA – východ, USA – středojiž, USA – středozápad a USA – západ 2

1 Zákazníci s prostředkem umístěným ve Švýcarsku – sever nebo Švýcarsko – západ můžou zajistit, aby jejich požadavky na textové rozhraní API byly obsluhovány ve Švýcarsku. Pokud chcete zajistit, aby se požadavky zpracovávaly ve Švýcarsku, vytvořte prostředek Translator v oblasti prostředků Švýcarsko – sever nebo Švýcarsko – západ a pak v požadavcích rozhraní API použijte vlastní koncový bod prostředku. Například: Pokud vytvoříte Translator prostředek v Azure Portal s oblastí prostředků jako "Švýcarsko – sever" a název vašeho prostředku je my-ch-n, pak váš vlastní koncový bod jehttps://my-ch-n.cognitiveservices.azure.com" ";". Ukázkový požadavek na překlad je:

// Pass secret key and region using headers to a custom endpoint
curl -X POST " my-ch-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

2 Vlastní Translator momentálně není ve Švýcarsku k dispozici.

Authentication

Přihlaste se k odběru Translator nebo více služeb Cognitive Services ve službách Azure Cognitive Services a k ověření použijte svůj klíč (dostupný v 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 Description
Ocp-Apim-Subscription-Key Používá se s předplatným služeb Cognitive Services, pokud předáváte tajný klíč.
Hodnota je tajný klíč Azure pro vaše předplatné Translator.
Autorizace Používá se s předplatným služeb Cognitive Services, 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 Cognitive Services a regionálním překladatelským prostředkem.
Hodnota je oblast prostředku s více službami nebo regionálním překladatelem. Tato hodnota je volitelná při použití globálního prostředku translatoru.

Tajný klíč

První možností je ověření pomocí hlavičky Ocp-Apim-Subscription-Key . Přidejte do žádosti 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 zahrnout jedno záhlaví pro volání Translator.

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

Tady je příklad požadavku na volání Translator pomocí globálního prostředku translatoru.

// 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 zdroj místního překladatele. Existují dvě záhlaví, která potřebujete volat Translator.

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

Tady je příklad požadavku na volání Translator pomocí zdroje místního překladatele.

// 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 služby Cognitive Service pro více služeb 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 Description
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. Vybraná oblast je jediná oblast, kterou můžete použít pro překlad textu při použití klíče více služeb, a musí být stejná oblast, kterou jste vybrali při registraci předplatného více služeb prostřednictvím Azure Portal.

Pokud předáte tajný klíč v řetězci dotazu s parametrem Subscription-Key, musíte 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, vytvořte 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 ukázkové požadavky na získání tokenu poskytnutého tajným klíčem 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 pro tajný klíč 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á 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í Translator. Pokud ale váš program v průběhu delšího časového období odešle požadavky na Translator, 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í Azure Active Directory (Azure AD)

Translator v3.0 podporuje ověřování Azure AD, cloudové řešení pro správu identit a přístupu Microsoftu. Autorizační hlavičky umožňují službě Translator ověřit, že žadatel má autorizaci k používání prostředku a k dokončení požadavku.

Požadavky

Hlavičky

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í Translator.
  • VizOvěřování pomocí přístupového tokenu výše.
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 vaší instance prostředku Translator.
  • ID prostředku najdete v Azure Portal ve vlastnostech Translator prostředku →.
  • Formát ID prostředku:
    /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/
Translator stránka vlastností – Azure Portal

Screenshot:Translator properties page in the Azure portal.

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 verze 3.0 také podporuje autorizaci přístupu ke spravovaným identitám. Pokud je pro prostředek 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.'}]"

Pomocí vlastního koncového bodu

//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 Virtual Network (VNET) ve všech oblastech veřejného cloudu Azure. Pokud chcete povolit Virtual Network, vizKonfigurace virtuálních sítí Azure Cognitive Services.

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

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

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

Tady je příklad požadavku na volání 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 name/value pair error. 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 pro další kategorizaci chyby. Běžné kódy chyb:

Kód Description
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 ("Ze skriptu") 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 párů jazyků není platný.
400035 Pole Zdrojový jazyk (Pole Od) není platné.
400036 Cílového jazyka (pole Komu) chybí nebo je neplatné.
400042 Jedna ze zadaných možností (pole Možnosti) není platná.
400043 ID trasování klienta (pole ClientTraceId nebo hlavička X-ClientTranceId) chybí nebo je neplatné.
400050 Vstupní text je příliš dlouhý. Umožňuje zobrazit limity 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 není platný json.
400075 Kombinace párů jazyků a kategorií není platná.
400077 Byla překročena maximální velikost požadavku. Umožňuje zobrazit limity požadavků.
400079 Vlastní systém požadovaný pro překlad mezi jazykem a z jazyka neexistuje.
400080 Transliterace 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žijte předplatné k 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 je připravený. Zkuste to znovu za několik minut.
408002 Vypršel časový limit požadavku čekající na příchozí stream. Klient nevytvářel požadavek v době, kdy byl server připravený čekat. Klient může požadavek opakovat bez jakýchkoli úprav později.
415000 Hlavička 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á, nahlašte ji s datem a časem chyby, identifikátorem požadavku z hlavičky X-RequestId odpovědi a identifikátorem klienta z hlavičky požadavku X-ClientTraceId.
503000 Služba je dočasně nedostupná. Opakovat. Pokud chyba přetrvává, nahlašte ji s datem a časem chyby, identifikátorem požadavku z hlavičky X-RequestId odpovědi a identifikátorem klienta z hlavičky požadavku X-ClientTraceId.

Metriky

Metriky umožňují zobrazit informace o využití a dostupnosti překladatele v 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 Description
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čet volání, která překročila sazbu nebo limit kvóty
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