Translator Text API 3.0: TransliterateTranslator Text API 3.0: Transliterate

ある言語のテキストを、あるスクリプトから別のスクリプトに変換します。Converts text in one language from one script to another script.

要求 URLRequest URL

POST 要求の送信先は次のとおりです。Send a POST request to:

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

要求パラメーターRequest parameters

クエリ文字列に渡される要求パラメーターを次に示します。Request parameters passed on the query string are:

Query parameter (クエリ パラメーター)Query parameter 説明Description
api-versionapi-version "*必須のパラメーター*"。*Required parameter*.
クライアントによって要求される API のバージョン。Version of the API requested by the client. 値は `3.0` とする必要があります。Value must be `3.0`.
languagelanguage *必須のパラメーター*。*Required parameter*.
スクリプト間の変換を行うテキストの言語を指定します。Specifies the language of the text to convert from one script to another. 指定可能な言語は、[サポートされている言語](./v3-0-languages.md)をサービスに照会することによって得られる `transliteration` スコープにリストされます。Possible languages are listed in the `transliteration` scope obtained by querying the service for its [supported languages](./v3-0-languages.md).
fromScriptfromScript *必須のパラメーター*。*Required parameter*.
入力テキストによって使用されるスクリプトを指定します。Specifies the script used by the input text. 選択した言語で使用可能な入力スクリプトを確認するには、`transliteration`スコープを使用して[サポートされている言語](./v3-0-languages.md)を検索します。Look up [supported languages](./v3-0-languages.md) using the `transliteration` scope, to find input scripts available for the selected language.
toScripttoScript *必須のパラメーター*。*Required parameter*.
出力スクリプトを指定します。Specifies the output script. 選択した、入力言語と入力スクリプトの組み合わせに対して使用可能な出力スクリプトを確認するには、`transliteration` スコープを使用して [サポートされている言語](./v3-0-languages.md)を検索します。Look up [supported languages](./v3-0-languages.md) using the `transliteration` scope, to find output scripts available for the selected combination of input language and input script.

要求ヘッダーには次のものがあります。Request headers include:

headersHeaders 説明Description
認証ヘッダーAuthentication header(s) "必須の要求ヘッダー" です。Required request header.
認証に使用できるオプションに関するページをご覧ください。See available options for authentication.
Content-TypeContent-Type "*必須の要求ヘッダー*" です。*Required request header*.
ペイロードのコンテンツ タイプを指定します。Specifies the content type of the payload. 次のいずれかの値になります。`application/json`Possible values are: `application/json`.
Content-LengthContent-Length "*必須の要求ヘッダー*" です。*Required request header*.
要求本文の長さです。The length of the request body.
X-ClientTraceIdX-ClientTraceId *省略可能*。*Optional*.
要求を一意に識別する、クライアントで生成された GUID。A client-generated GUID to uniquely identify the request. クエリ パラメーター `ClientTraceId` を使ってクエリ文字列内にトレース ID を含める場合、このヘッダーを省略できることに注意してください。Note that you can omit this header if you include the trace ID in the query string using a query parameter named `ClientTraceId`.

要求本文Request body

要求の本文は JSON 配列です。The body of the request is a JSON array. 各配列要素は、Text という名前の文字列プロパティ (変換する文字列を表す) を持つ JSON オブジェクトです。Each array element is a JSON object with a string property named Text, which represents the string to convert.

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

次の制限事項が適用されます。The following limitations apply:

  • 配列に含めることができる要素は、最大でも 10 個です。The array can have at most 10 elements.
  • 配列要素のテキスト値は、スペースも含めて 1,000 文字を超えてはなりません。The text value of an array element cannot exceed 1,000 characters including spaces.
  • 要求に含めるテキスト全体では、スペースも含めて 5,000 文字を超えてはなりません。The entire text included in the request cannot exceed 5,000 characters including spaces.

応答本文Response body

正常な応答は、入力配列内の要素ごとに 1 つの結果が含まれる JSON 配列となります。A successful response is a JSON array with one result for each element in the input array. 結果オブジェクトには次のプロパティが含まれています。A result object includes the following properties:

  • text:入力文字列を出力スクリプトに変換した結果である文字列。text: A string which is the result of converting the input string to the output script.

  • script:出力で使用されるスクリプトを指定する文字列。script: A string specifying the script used in the output.

JSON 応答の例を次に示します。An example JSON response is:

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

応答ヘッダーResponse headers

headersHeaders 説明Description
X-RequestIdX-RequestId 要求を識別するためにサービスによって生成される値。Value generated by the service to identify the request. トラブルシューティングの目的で使用されます。It is used for troubleshooting purposes.

応答状態コードResponse status codes

要求によって返される可能性のある HTTP 状態コードを次に示します。The following are the possible HTTP status codes that a request returns.

状態コードStatus Code 説明Description
200200 成功。Success.
400400 クエリ パラメーターの 1 つが欠落しているか無効です。One of the query parameters is missing or not valid. 再試行する前に要求パラメーターを修正してください。Correct request parameters before retrying.
401401 要求を認証できませんでした。The request could not be authenticated. 資格情報が指定され、有効であることを確認してください。Check that credentials are specified and valid.
403403 要求が承認されていません。The request is not authorized. 詳細なエラー メッセージを確認してください。Check the details error message. これは、多くの場合、試用版サブスクリプションで提供されるすべての無料翻訳が使い果たされたことを示します。This often indicates that all free translations provided with a trial subscription have been used up.
429429 クライアントが要求の制限を超えたため、サーバーは要求を拒否しました。The server rejected the request because the client has exceeded request limits.
500500 予期しないエラーが発生しました。An unexpected error occurred. エラーが解決しない場合は、エラー発生の日時、応答ヘッダー `X-RequestId` からの要求識別子、要求ヘッダー `X-ClientTraceId` からのクライアント識別子を添えてその旨をご報告ください。If the error persists, report it with: date and time of the failure, request identifier from response header `X-RequestId`, and client identifier from request header `X-ClientTraceId`.
503503 サーバーが一時的に使用できません。Server temporarily unavailable. 要求をやり直してください。Retry the request. エラーが解決しない場合は、エラー発生の日時、応答ヘッダー `X-RequestId` からの要求識別子、要求ヘッダー `X-ClientTraceId` からのクライアント識別子を添えてその旨をご報告ください。If the error persists, report it with: date and time of the failure, request identifier from response header `X-RequestId`, and client identifier from request header `X-ClientTraceId`.

エラーが発生した場合は、要求の結果として JSON エラー応答も返されます。If an error occurs, the request will also return a JSON error response. このエラーコードは 3 桁の HTTP ステータス コードの後に、エラーをさらに分類するための 3 桁の数字を続けた 6 桁の数字です。The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. 一般的なエラー コードは、v3 Translator Text API のリファレンス ページで確認できます。Common error codes can be found on the v3 Translator Text API reference page.

Examples

次の例では、2 つの日本語文字列をローマ字化された日本語に変換する方法を示します。The following example shows how to convert two Japanese strings into Romanized Japanese.

この例の要求に対する JSON ペイロードを次に示します。The JSON payload for the request in this example:

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

Unicode 文字をサポートしていないコマンドライン ウィンドウで cURL を使用する場合は、次の JSON ペイロードを取得して、request.txt という名前のファイルに保存します。If you are using cURL in a command-line window that does not support Unicode characters, take the following JSON payload and save it into a file named request.txt. 必ずファイルは UTF-8 エンコードで保存してください。Be sure to save the file with UTF-8 encoding.

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