Translator Text API 3.0: DetectTranslator Text API 3.0: Detect

テキストの一部の言語を識別します。Identifies the language of a piece of text.

要求 URLRequest URL

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

https://api.cognitive.microsofttranslator.com/detect?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`.

要求ヘッダーには次のものがあります。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. 言語の検出は、Text プロパティの値に適用されます。Language detection is applied to the value of the Text property. サンプルの要求本文は次のようになります。A sample request body looks like that:

[
    { "Text": "Ich würde wirklich gern Ihr Auto um den Block fahren ein paar Mal." }
]

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

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

応答本文Response body

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

  • language:検出された言語のコードです。language: Code of the detected language.

  • score:結果内の信頼度を示す浮動小数点値です。score: A float value indicating the confidence in the result. スコアは 0 から 1 の範囲であり、低いスコアは低い信頼度を示します。The score is between zero and one and a low score indicates a low confidence.

  • isTranslationSupported:検出された言語がテキスト翻訳でサポートされている言語の 1 つである場合に true になるブール値です。isTranslationSupported: A boolean value which is true if the detected language is one of the languages supported for text translation.

  • isTransliterationSupported:検出された言語が音訳でサポートされている言語の 1 つである場合に true になるブール値です。isTransliterationSupported: A boolean value which is true if the detected language is one of the languages supported for transliteration.

  • alternatives:利用可能な他の言語の配列です。alternatives: An array of other possible languages. 配列の各要素は、上記にリストしたのと同じプロパティ (languagescoreisTranslationSupportedisTransliterationSupported) を持つ別のオブジェクトです。Each element of the array is another object with the same properties listed above: language, score, isTranslationSupported and isTransliterationSupported.

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

[
  {
    "language": "de",
    "score": 0.92,
    "isTranslationSupported": true,
    "isTransliterationSupported": false,
    "alternatives": [
      {
        "language": "pt",
        "score": 0.23,
        "isTranslationSupported": true,
        "isTransliterationSupported": false
      },
      {
        "language": "sk",
        "score": 0.23,
        "isTranslationSupported": true,
        "isTransliterationSupported": false
      }
    ]
  }
]

応答ヘッダー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

次の例では、テキスト翻訳でサポートされている言語を取得する方法を示します。The following example shows how to retrieve languages supported for text translation.

curl -X POST "https://api.cognitive.microsofttranslator.com/detect?api-version=3.0" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'What language is this text written in?'}]"