Translator v3.0

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é 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í:

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.

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.

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.

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:

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í

Stránka vlastností translatoru – 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 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ů.

1. Na webu Azure Portal přejděte k prostředku služby Translator.

2. V části Správa prostředků vyberte Sítě.

3. Na kartě Brány firewall a virtuální sítě zvolte Vybrané sítě a privátní koncové body.

   

4. Výběrem možnosti Uložit se vaše změny uplatní.

5. V části Správa prostředků vyberte klíče a koncový bod.

6. Vyberte kartu Virtuální síť.

7. V seznamu jsou koncové body pro překlad textu a překlad dokumentu.

   

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:

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.

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