Translator v3.0

Co je nového

Verze 3 Translator poskytuje moderní webové rozhraní API založené na JSON. Zlepšuje použitelnost a výkon tím, že konsoliduje stávající funkce do menšího počtu operací a poskytuje nové funkce.

• Transkliterace pro převod textu v jednom jazyce z jednoho skriptu do jiného.
• Překlad do více jazyků v jednom požadavku.
• Rozpoznávání, překlad a transkliterace jazyka v jednom požadavku.
• Slovník pro vyhledání alternativních překladů termínů, aby bylo možné najít zpětná překlady a příklady znázorňující termíny používané v kontextu.
• Informativnější výsledky rozpoznávání jazyka

Základní adresy URL

Žádosti o Translator jsou ve většině případů zpracovávány datovým centrem, které je nejblíže místa, odkud žádost pochází. Pokud při použití globálního koncového bodu dojde k selhání datacentra, požadavek může být 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 žádosti se zpracovávají v datových centrech v rámci zeměpisné oblasti.

^{1 Zákazníci} s prostředky nacházejícími se ve Švýcarskou – sever nebo Švýcarsko – západ mohou zajistit, aby se jejich požadavky rozhraní TEXT API dosloužily ve Švýcarskou. Pokud chcete zajistit zpracování požadavků ve Švýcarskou, vytvořte prostředek Translator v oblasti prostředků Severní Švýcarsko nebo Švýcarsko – západ a pak v požadavcích rozhraní API použijte vlastní koncový bod prostředku. Příklad: Pokud vytvoříte prostředek Translator v nástroji Azure Portal s oblastí prostředků jako "Švýcarsko – sever" a názvem vašeho prostředku je my-ch-n, pak je váš vlastní koncový bod https://my-ch-n.cognitiveservices.azure.com " " . A 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

² Vlastní Translator nejsou aktuálně k dispozici ve Švýcarskou.

Authentication

Přihlaste se Translator nebo Cognitive Services více služeb v Azure Cognitive Services a k ověření použijte svůj klíč předplatného (k dispozici v Azure Portal).

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

Tajný klíč

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

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

Když použijete prostředek globálního překladače, je potřeba zahrnout jednu hlavičku pro volání Translator.

Tady je příklad požadavku na volání Translator pomocí globálního prostředku 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í regionálního prostředku

Při použití zdroje regionálního překladače. Existují dvě hlavičky, které je třeba volat Translator.

Tady je příklad požadavku na volání Translator s využitím zdroje regionální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

Když používáte prostředek služby Cognitive Service s více službami. To vám umožní použít jeden tajný klíč k ověřování požadavků na více služeb.

Pokud použijete tajný klíč více služeb, musíte do požadavku zahrnout dvě hlavičky ověřování. Existují dvě hlavičky, které je třeba volat Translator.

Pro předplatné rozhraní Text API pro více služeb se vyžaduje oblast. Oblast, kterou vyberete, je jediná oblast, kterou můžete použít k překladu textu při použití klíče předplatného s více službami, a musí to být stejná oblast, kterou jste vybrali při přihlášení k předplatnému pro více služeb prostřednictvím Azure Portal.

Pokud předáte tajný klíč v řetězci dotazu s parametrem , musíte zadat Subscription-Key oblast pomocí parametru dotazu Subscription-Region .

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 Authorization hlavičky. Pokud chcete získat autorizační token, vytvořte POST požadavek na následující adresu URL:

Tady jsou příklady požadavků na získání tokenu s tajným klíčem:

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

Ú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 bearer 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 více voláních do Translator. Pokud ale váš program po určitou dobu Translator požadavky na Translator, musí si program v pravidelných intervalech vyžádat nový přístupový token (například každých 8 minut).

Ověřování pomocí Azure Active Directory (Azure AD)

Translator verze 3.0 podporuje ověřování Azure AD, cloudové řešení Microsoftu pro správu identit a přístupu. 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é porozumění ověřování pomocí Azure Active Directory.

• Stručné porozumění tomu, jak autorizovat přístup ke spravovaným identitám.

Hlavičky

Translator stránky vlastností – 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/translator/text/v3.0/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 ověřování přístupu ke spravovaným identitám. Pokud je pro prostředek překladače povolená spravovaná identita, můžete v hlavičce požadavku předat nosný token vygenerovaný spravovanou identitou.

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/translator/text/v3.0/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 funkcemi Virtual Network (VNET) ve všech oblastech veřejného cloudu Azure. Pokud chcete Virtual Network, podívejte se na téma Azure Cognitive Services virtuálních sítí.

Po zapnutí této funkce musíte vlastní koncový bod použít k volání Translator. Nemůžete použít globální koncový bod 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 překladače a povolení přístupu z vybraných sítí a privátních koncových bodů.

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 párem název/hodnota s názvem error . Hodnota je také objekt JSON s vlastnostmi:

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

Zákazníkovi s bezplatnou zkušební verzí předplatného se například po vyčerpání bezplatné kvóty zobrazí následující chyba:

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

Kód chyby je 6ciferné číslo kombinující 3místný stavový kód HTTP následovaný 3ciferným číslem pro další kategorizaci chyby. Běžné kódy chyb:

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 metriky dat a platforem.

Tato tabulka uvádí dostupné metriky s popisem způsobu jejich použití pro monitorování volání rozhraní API pro překlad.