翻譯工具 3.0：音譯

發行項
09/02/2024

將一種語言的文字從一個腳本轉換成另一個腳本。

要求 URL

將 POST 要求傳送至：

https://api.cognitive.microsofttranslator.com/transliterate?api-version=3.0

請參閱 虛擬網絡 翻譯工具服務選取的網路和私人端點組態和支援。

要求參數

在查詢字串上傳遞的要求參數如下：

查詢參數	描述
api-version	必要參數。用戶端要求的 API 版本。值必須為 `3.0`。
language	必要參數。指定要從一個腳本轉換成另一個腳本的文字語言。可能的語言會列在 `transliteration` 查詢服務所支持語言所取得的範圍中。
fromScript	必要參數。指定輸入文字所使用的文稿。使用範圍查閱支持的語言，以尋找適用於所選語言的輸入 `transliteration` 腳本。
toScript	必要參數。指定輸出文稿。使用`transliteration`範圍查閱支援的語言，以尋找可供所選輸入語言和輸入腳本組合使用的輸出腳本。

要求標頭包括：

標題	描述
驗證標頭	必要的要求標頭。請參閱可用的驗證選項。
內容-類型	必要的要求標頭。指定承載的內容類型。可能的值為： `application/json`
Content-Length	選擇性。要求本文的長度。
X-ClientTraceId	選擇性。用於識別唯一要求的 GUID，由用戶端產生。如果您使用名為 `ClientTraceId`的查詢參數，在查詢字串中包含追蹤標識碼，則可以省略此標頭。

要求本文

要求的主體是 JSON 陣列。每個陣列元素都是 JSON 物件，其具有名為 Text的字串屬性，代表要轉換的字串。

[
    {"Text":"こんにちは"},
    {"Text":"さようなら"}
]

適用下列限制：

陣列最多可以有10個專案。
陣列專案的文字值不能超過1,000個字元，包括空格。
要求中包含的整個文字不能超過5,000個字元，包括空格。

回應本文

成功的回應是 JSON 陣列，輸入數位中的每個元素都有一個結果。結果物件包含下列屬性：

text：將輸入字串轉換成輸出腳本所產生的字串。
script：指定輸出中使用的文稿的字串。

JSON 回應範例如下：

[
    {"text":"konnnichiha","script":"Latn"},
    {"text":"sayounara","script":"Latn"}
]

回應標頭

標題	描述
X-RequestId	服務所產生的值，用來識別要求，並用於疑難解答目的。

回應狀態代碼

以下是要求傳回的可能 HTTP 狀態碼。

狀態碼	描述
200	成功。
400	其中一個查詢參數遺失或無效。重試之前，請先更正要求參數。
401	無法驗證要求。檢查是否已指定認證且有效。
403	要求未獲授權。檢查詳細數據錯誤訊息。此程式代碼通常表示會使用試用版訂用帳戶提供的所有免費翻譯。
429	伺服器因為客戶端超過要求限制而拒絕要求。
500	發生未預期的錯誤。如果錯誤持續發生，請報告失敗的日期和時間、回應標頭的要求標識碼，以及來自要求標頭`X-RequestIdX-ClientTraceId`的用戶端標識符。
503	伺服器暫時無法使用。重試要求。如果錯誤持續發生，請報告失敗的日期和時間、回應標頭的要求標識碼，以及來自要求標頭`X-RequestIdX-ClientTraceId`的用戶端標識符。

如果發生錯誤，要求也會傳回 JSON 錯誤回應。錯誤碼是6位數的數字，結合3位數 HTTP狀態代碼，後面接著3位數的數位，以進一步分類錯誤。 v3 翻譯工具參考頁面上可找到常見的錯誤碼。

範例

下列範例示範如何將兩個日文字符串轉換成羅馬化日文。

此範例中要求的 JSON 承載：

[{"text":"こんにちは","script":"jpan"},{"text":"さようなら","script":"jpan"}]

如果您在不支援 Unicode 字元的命令行視窗中使用 cURL，請採用下列 JSON 承載，並將它儲存到名為 request.txt的檔案中。請務必以編碼方式 UTF-8 儲存盤案。

curl -X POST "https://api.cognitive.microsofttranslator.com/transliterate?api-version=3.0&language=ja&fromScript=Jpan&toScript=Latn" -H "X-ClientTraceId: 875030C7-5380-40B8-8A03-63DACCF69C11" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d @request.txt

共用方式為