翻譯工具 3.0 版

  • 發行項

新功能

翻譯工具 3.0 版提供以 JSON 為基礎的新式 Web API。 其藉由將現有功能合併成較少的作業來提升可用性和效能，並提供新功能。

  • 轉換功能，可將某種語言的文字從某個字集轉換成另一個字集。
  • 透過一個要求即可翻譯成多種語言。
  • 透過一個要求即可進行語言偵測、翻譯和轉換。
  • 可查閱字詞替代翻譯、找到反向翻譯及顯示字詞實際應用範例的字典。
  • 包含更多資訊的語言偵測結果。

基底 URL

在大部分情況下，對翻譯工具的要求會由最接近要求起源的資料中心負責處理。 如果在使用全域端點時發生資料中心失敗，則可能會在地理位置外路由要求。

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

[地理位置] 基底 URL (地理端點) 資料中心
全域 (non-regional) api.cognitive.microsofttranslator.com 最接近可用的資料中心
亞太地區 api-apc.cognitive.microsofttranslator.com 南韓南部、日本東部、東南亞及澳大利亞東部
歐洲 api-eur.cognitive.microsofttranslator.com 北歐、西歐
美國 api-nam.cognitive.microsofttranslator.com 美國東部、美國中南部、美國中西部和美國西部 2

1 資源位於瑞士北部或瑞士西部的客戶，可確保在瑞士內提供其文字 API 要求。 為了確保在瑞士處理要求，請在「資源區域」「瑞士北部」或 Switzerland West 中建立翻譯工具資源，然後在您的 API 要求中使用資源的自訂端點。 例如：如果您在Azure 入口網站中建立翻譯工具資源，並將 「資源區域」設定為 「瑞士北部」，而您的資源名稱為 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

2 自訂翻譯工具目前不適用於瑞士。

驗證

訂閱翻譯工具或 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 分鐘) 要求新存取權杖。

利用 Azure Active Directory (Azure AD) 進行的驗證

翻譯工具 3.0 版支援 Azure AD 驗證，也就是 Microsoft 的雲端式身分識別和存取管理解決方案。 授權標頭可讓翻譯工具服務驗證提出要求的用戶端是否已獲授權使用資源並完成要求。

先決條件

標頭

頁首 值
授權 此值是 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.'}]"

使用受控識別的範例

翻譯工具 3.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")，也無法使用存取權杖進行驗證。

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

  1. 在 Azure 入口網站中瀏覽至 [翻譯工具] 資源。

  2. 從 [資源管理] 區段中選取 [網路]。

  3. 在 [防火牆與虛擬網路] 索引標籤下，選擇 [選取的網路與私人端點]。

    Azure 入口網站中虛擬網路設定的螢幕擷取畫面。

  4. 選取 [儲存] 來套用您的變更。

  5. 從 [資源管理] 區段中選取 [金鑰和端點]。

  6. 選取 [虛擬網路] 索引標籤。

  7. 該處列出的是文字翻譯和文件翻譯的端點。

    虛擬網路端點的螢幕擷取畫面。

標題 描述
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?'}]"

Errors

標準錯誤回應是名稱/值組為 error 的 JSON 物件。 此值也可以是具有下列屬性的 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 「提供的認證是 Speech 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 呼叫。

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