翻譯工具 3.0 版

發行項
05/04/2024

新功能

翻譯工具 3.0 版提供新式 JSON 型 Web API。它藉由將現有的功能合併成較少的作業，以提供新功能，藉此改善可用性和效能。

音譯，以一種語言將文字從一個腳本轉換成另一個腳本。
在一個要求中翻譯至多種語言。
一個要求中的語言偵測、翻譯和音譯。
查詢字詞替代翻譯的字典，以尋找反向翻譯和範例，其中顯示內容中使用的詞彙。
更具資訊性的語言偵測結果。

基底 URL

大部分情況下，翻譯工具的要求是由最接近要求來源的數據中心處理。如果使用全域端點時發生數據中心失敗，要求可能會路由傳送到地理位置之外。

若要強制在特定地理位置內處理要求，請使用所需的地理端點。所有要求都會在地理位置內的數據中心之間處理。

✔️ 功能：翻譯工具文字

服務端點	要求處理資料中心
全域 (建議)： `api.cognitive.microsofttranslator.com`	最接近的可用資料中心。
美洲： `api-nam.cognitive.microsofttranslator.com`	美國東部 2 • 美國西部 2
亞太地區： `api-apc.cognitive.microsofttranslator.com`	日本東部 • 東南亞
歐洲（瑞士除外）： `api-eur.cognitive.microsofttranslator.com`	法國中部 • 西歐
瑞士：如需詳細資訊，請參閱瑞士服務端點。	瑞士北部 • 瑞士西部

瑞士服務端點

位於瑞士北部或瑞士西部的資源客戶可以確保其文字 API 要求可在瑞士內提供服務。為了確保要求是在瑞士處理，請在或 Switzerland West中Resource regionSwitzerland North建立翻譯工具資源，然後在 API 要求中使用資源的自定義端點。

例如：如果您在 Azure 入口網站 Resource regionSwitzerland North 中建立翻譯工具資源，且您的資源名稱為 my-swiss-n，則您的自定義端點為 https://my-swiss-n.cognitiveservices.azure.com。要翻譯的範例要求如下：

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

瑞士目前不提供自定義翻譯工具。

驗證

訂閱 Azure AI 服務中的翻譯工具或多重服務，並使用您的密鑰（Azure 入口網站中提供）進行驗證。

有三個標頭可用來驗證訂用帳戶。下表描述如何使用每個專案：

標頭	描述
Ocp-Apim-Subscription-Key	如果您要傳遞秘密密鑰，請與 Azure AI 服務訂用帳戶搭配使用。此值是訂用帳戶翻譯工具的 Azure 秘密密鑰。
授權	如果您要傳遞驗證令牌，請與 Azure AI 服務訂用帳戶搭配使用。值為持有人令牌： `Bearer <token>`。
Ocp-Apim-Subscription-Region	搭配多服務和區域翻譯工具資源使用。此值是多服務或區域翻譯工具資源的區域。使用全域翻譯工具資源時，這個值是選擇性的。

祕密金鑰

第一個選項是使用 Ocp-Apim-Subscription-Key 標頭進行驗證。將 Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> 標頭新增至您的要求。

使用全域資源進行驗證

當您使用全域翻譯工具資源時，必須包含一個標頭來呼叫翻譯工具。

標頭	描述
Ocp-Apim-Subscription-Key	此值是訂用帳戶要翻譯工具的 Azure 秘密密鑰。

以下是使用全域翻譯工具資源呼叫翻譯工具的範例要求

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

使用區域資源進行驗證

當您使用區域翻譯工具資源時，您需要呼叫翻譯工具兩個標頭。

標頭	描述
Ocp-Apim-Subscription-Key	此值是訂用帳戶要翻譯工具的 Azure 秘密密鑰。
Ocp-Apim-Subscription-Region	此值是翻譯工具資源的區域。

以下是使用區域翻譯工具資源呼叫翻譯工具的範例要求

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

使用多服務資源進行驗證

多服務資源可讓您使用單一 API 金鑰來驗證多個服務的要求。

當您使用多服務秘密金鑰時，您必須在要求中包含兩個驗證標頭。您需要呼叫翻譯工具兩個標頭。

標頭	描述
Ocp-Apim-Subscription-Key	此值是多服務資源的 Azure 秘密金鑰。
Ocp-Apim-Subscription-Region	此值是多服務資源的區域。

多服務文字 API 訂用帳戶需要區域。您選取的區域是唯一可在使用多重服務金鑰時用於文字翻譯的區域。當您透過 Azure 入口網站註冊多服務訂用帳戶時，它必須是您選取的相同區域。

如果您使用參數 Subscription-Key在查詢字串中傳遞秘密金鑰，則必須使用查詢參數 Subscription-Region來指定區域。

使用存取權杖進行驗證

或者，您可以交換秘密金鑰以取得存取令牌。此令牌隨附於每個要求作為 Authorization 標頭。若要取得授權令牌，請向下列URL提出 POST 要求：

資源類型	驗證服務 URL
全球	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
區域或多服務	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

以下是針對全域資源取得指定秘密密鑰之令牌的範例要求：

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

以下是針對位於美國中部的區域資源取得令牌的範例要求：

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

成功的要求會將編碼存取令牌當做回應本文中的純文本傳回。有效的令牌會以授權中的持有人令牌的形式傳遞至翻譯工具服務。

Authorization: Bearer <Base64-access_token>

驗證令牌的有效期限為10分鐘。對翻譯工具進行多個呼叫時，應該重複使用令牌。不過，如果您的程式在長時間內對翻譯工具提出要求，則您的程式必須定期要求新的存取令牌（例如每 8 分鐘）。

使用 Microsoft Entra 識別碼進行驗證

翻譯工具 v3.0 支援 Microsoft Entra 驗證、Microsoft 的雲端式身分識別和存取管理解決方案。授權標頭可讓翻譯工具服務驗證要求用戶端是否有權使用資源並完成要求。

先決條件

簡短瞭解如何使用 Microsoft Entra ID 進行驗證。
簡要瞭解如何 授權存取受控識別。

標題

標頭	數值
授權	此值是 Azure AD 所產生的存取持有人令牌。持有人令牌提供驗證證明，並驗證用戶端使用資源的授權。驗證令牌的有效期限為10分鐘，而且在對翻譯工具進行多個呼叫時應該重複使用。請參閱範例要求：2。取得令牌
Ocp-Apim-Subscription-Region	此值是翻譯工具資源的區域。如果資源是全域的，這個值是選擇性的。
Ocp-Apim-ResourceId	此值是翻譯工具資源實例的資源標識符。您可以在翻譯工具資源→屬性的 Azure 入口網站中找到資源識別碼。資源標識符格式： /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName/>

翻譯工具屬性頁 — Azure 入口網站

螢幕快照：翻譯工具 Azure 入口網站中的 [屬性] 頁面。

範例

使用全域端點

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

使用您的自定義端點

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

使用受控識別的範例

翻譯工具 v3.0 也支援授權存取受控識別。如果已啟用翻譯工具資源的受控識別，您可以在要求標頭中傳遞受控識別所產生的持有人令牌。

使用全域端點

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

使用您的自定義端點

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

虛擬網路支援

翻譯工具服務現在可在 Azure 公用雲端的所有區域中使用虛擬網絡（VNET）功能。若要啟用虛擬網絡，請參閱設定 Azure AI 服務虛擬網路。

開啟這項功能之後，您必須使用自定義端點來呼叫翻譯工具。您無法使用全域翻譯工具端點（“api.cognitive.microsofttranslator.com”），且無法使用存取令牌進行驗證。

您可以在建立翻譯工具資源並允許從選取的網路和私人端點存取之後，找到自定義端點。

在 Azure 入口網站中瀏覽至 [翻譯工具] 資源。
從 [資源管理] 區段中選取 [網路]。
在 [防火牆與虛擬網路] 索引標籤下，選擇 [選取的網路與私人端點]。
選取儲存套用變更。
從 [資源管理] 區段選取 [金鑰和端點]。
選取 [虛擬網絡] 索引標籤。
列出文字翻譯和文件翻譯的端點。

標頭	描述
Ocp-Apim-Subscription-Key	此值是訂用帳戶要翻譯工具的 Azure 秘密密鑰。
Ocp-Apim-Subscription-Region	此值是翻譯工具資源的區域。如果資源為，這個值是選擇性的 `global`

以下是使用自定義端點呼叫翻譯工具的範例要求

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

錯誤

標準錯誤回應是 JSON 物件，名稱/值群組名稱為 error。此值也是具有屬性的 JSON 物件：

code：伺服器定義的錯誤碼。
message：字串，提供人類看得懂的錯誤表示法。

例如，一旦免費配額用盡，具有免費試用訂用帳戶的客戶會收到下列錯誤：

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

錯誤碼是6位數的數字，結合3位數 HTTP狀態代碼，後面接著3位數的數位，以進一步分類錯誤。常見的錯誤碼包括：

程式碼	描述
400000	其中一個要求輸入無效。
400001	"scope" 參數無效。
400002	"category" 參數無效。
400003	語言指定名稱遺漏或無效。
400004	目標指令碼指定名稱 ("To script") 遺漏或無效。
400005	輸入文字遺漏或無效。
400006	語言與指令碼的組合無效。
400018	來源指令碼指定名稱 ("From script") 遺漏或無效。
400019	不支援其中一個指定的語言。
400020	輸入文字陣列中的其中一個元素無效。
400021	API 版本參數遺漏或無效。
400023	其中一個指定的語言組無效。
400035	來源語言 ("From" 欄位) 無效。
400036	目標語言 ("To" 欄位) 無效。
400042	其中一個指定的選項 ("Options" 欄位) 無效。
400043	用戶端追蹤識別碼 ID (ClientTraceId 欄位或 X-ClientTranceId 標頭) 遺漏或無效。
400050	輸入文字太長。檢視要求限制。
400064	"translation" 參數遺漏或無效。
400070	目標指令碼 (ToScript 參數) 數目與目標語言 (To 參數) 數目不符。
400071	此值對 TextType 無效。
400072	輸入文字陣列的元素太多。
400073	指令碼參數無效。
400074	要求的本文不是有效的 JSON。
400075	語言組與類別組合無效。
400077	已超過要求大小上限。檢視要求限制。
400079	所要求用來在來源與目標語言之間進行翻譯的自訂系統不存在。
400080	語言或指令碼不支援轉換。
401000	要求未獲得授權，因為認證遺失或無效。
401015	「提供的認證適用於語音 API。此要求需要文字 API 的認證。使用訂用帳戶來翻譯工具」。
403000	不允許此作業。
403001	不允許此作業，因為訂用帳戶已超過其免費配額。
405000	要求的資源不支援要求方法。
408001	正在準備要求的翻譯系統。請在數分鐘後重試。
408002	等待傳入的串流時要求逾時。用戶端未在伺服器準備好等待的時間內產生要求。用戶端可能會在稍後不需要修改的情況下重複要求。
415000	Content-Type 標頭遺失或無效。
429000, 429001, 429002	伺服器因為客戶端已超過要求限制而拒絕要求。
500000	發生未預期的錯誤。如果錯誤持續發生，請報告錯誤日期/時間、響應標頭 X-RequestId 的要求識別碼，以及來自要求標頭 X-ClientTraceId 的用戶端識別碼。
503000	服務暫時無法使用。重試。如果錯誤持續發生，請報告錯誤日期/時間、響應標頭 X-RequestId 的要求識別碼，以及來自要求標頭 X-ClientTraceId 的用戶端識別碼。

計量

計量可讓您在 [計量] 區段底下，檢視 Azure 入口網站中的翻譯工具使用方式和可用性資訊，如下列螢幕快照所示。如需詳細資訊，請參閱數據和平臺計量。

翻譯工具計量

下表列出可用的計量，其中說明如何使用這些計量來監視翻譯 API 呼叫。

計量	描述
TotalCalls	API 呼叫總數。
TotalTokenCalls	使用驗證令牌透過令牌服務呼叫的 API 呼叫總數。
SuccessfulCalls	成功呼叫的數目。
TotalErrors	具有錯誤回應的呼叫數目。
BlockedCalls	超過速率或配額限制的呼叫數目。
ServerErrors	伺服器內部錯誤（5XX）的呼叫數目。
ClientErrors	用戶端錯誤（4XX）的呼叫數目。
延遲	以毫秒為單位完成要求的持續時間。
CharactersTranslated	傳入文字要求中的字元總數。

翻譯工具 3.0 版

新功能

基底 URL

瑞士服務端點

驗證

祕密金鑰

使用全域資源進行驗證

使用區域資源進行驗證

使用多服務資源進行驗證

使用存取權杖進行驗證

使用 Microsoft Entra 識別碼進行驗證

先決條件

標題

翻譯工具 屬性頁 — Azure 入口網站

範例

使用全域端點

使用您的自定義端點

使用受控識別的範例

使用全域端點

使用您的自定義端點

虛擬網路支援

錯誤

計量

其他資源

翻譯工具屬性頁 — Azure 入口網站