Translator Text API 3.0: BreakSentenceTranslator Text API 3.0: BreakSentence

文章内で文の境界の位置を識別します。Identifies the positioning of sentence boundaries in a piece of text.

要求 URLRequest URL

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

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

要求パラメーターRequest parameters

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

Query parameter (クエリ パラメーター)Query parameter 説明Description
api-versionapi-version "*必須のクエリ パラメーター*" です。*Required query parameter*.
クライアントによって要求される API のバージョン。Version of the API requested by the client. 値は `3.0` とする必要があります。Value must be `3.0`.
languagelanguage "*省略可能なクエリ パラメーター*" です。*Optional query parameter*.
入力テキストの言語を示す言語タグ。Language tag identifying the language of the input text. コードを指定しないと、言語の自動検出が適用されます。If a code is not specified, automatic language detection will be applied.
scriptscript "*省略可能なクエリ パラメーター*" です。*Optional query parameter*.
入力テキストで使われているスクリプトを示すスクリプト タグ。Script tag identifying the script used by the input text. スクリプトを指定しないと、言語の既定のスクリプトと見なされます。If a script is not specified, the default script of the language will be assumed.

要求ヘッダーには次のものがあります。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 プロパティの値に対して計算されます。Sentence boundaries are computed for the value of the Text property. 1 つのテキストを含む要求本文の例を次に示します。A sample request body with one piece of text looks like that:

[
    { "Text": "How are you? I am fine. What did you do today?" }
]

次の制限事項が適用されます。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.
  • language クエリ パラメーターを指定する場合は、すべての配列要素が同じ言語である必要があります。If the language query parameter is specified, then all array elements must be in the same language. 指定しないと、言語の自動検出が配列の各要素に個別に適用されます。Otherwise, language auto-detection is applied to each array element independently.

応答本文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:

  • sentLen:テキスト要素内の文の長さを表す整数の配列です。sentLen: An array of integers representing the lengths of the sentences in the text element. 配列の長さは文の数であり、値は各文の長さです。The length of the array is the number of sentences, and the values are the length of each sentence.

  • detectedLanguage:次のプロパティによって、検出された言語を説明するオブジェクトです。detectedLanguage: An object describing the detected language through 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.

    detectedLanguage プロパティは、言語の自動検出が要求された場合に限り、結果オブジェクト内に存在することに注意してください。Note that the detectedLanguage property is only present in the result object when language auto-detection is requested.

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

[
  {
    "sentenceLengths": [ 13, 11, 22 ]
    "detectedLanguage": {
      "language": "en",
      "score": 401
    },
  }
]

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

次の例では、1 つの文に対する文の境界を取得する方法を示します。The following example shows how to obtain sentence boundaries for a single sentence. 文の言語は、サービスによって自動的に検出されます。The language of the sentence is automatically detected by the service.

curl -X POST "https://api.cognitive.microsofttranslator.com/breaksentence?api-version=3.0" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'How are you? I am fine. What did you do today?'}]"