PutBot - Amazon Lex V1
リクエストの構文URI リクエストパラメータリクエストボディレスポンスの構文レスポンス要素エラー以下の資料も参照してください。

サポート終了通知: 2025 年 9 月 15 日、 AWS は Amazon Lex V1 のサポートを終了します。 V1 2025 年 9 月 15 日以降、Amazon Lex V1 コンソールまたは Amazon Lex V1 リソースにアクセスできなくなります。Amazon Lex V2 を使用している場合は、代わりに Amazon Lex V2 ガイドを参照してください。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

PutBot

Amazon Lex 会話ボットを作成、または既存のボットを置き換えます。ボットを作成または更新する際に必要なのは、名前、ロケール、およびボットが 13 歳未満の子供を対象としているかどうかを指定することだけです。これにより、後からインテントを追加したり、既存のボットからインテントを削除したりすることができます。最低限の情報でボットを作成した場合、ボットの作成や更新は行われますが、Amazon Lex は の応答 FAILED を返します。1 つ以上のインテントを追加すると、ボットを構築できます。Amazon Lex ボットの詳細については、「Amazon Lex: 仕組み」を参照してください。

既存のボットの名前を指定した場合、リクエストのフィールドは、$LATEST バージョンのボットの既存の値に置き換えられます。　 Amazon Lex ではリクエストで値が入力されていないフィールドは削除されますが、idleTTLInSeconds と privacySettings のフィールドはデフォルト値に設定されます。必須フィールドに値を指定しない場合、Amazon Lex は例外をスローします。

このオペレーションには、lex:PutBot アクションに対するアクセス許可が必要です。詳細については、「Amazon Lex のための Identity and Access Management」を参照してください。

リクエストの構文

PUT /bots/name/versions/$LATEST HTTP/1.1
Content-type: application/json

{
   "abortStatement": { 
      "messages": [ 
         { 
            "content": "string",
            "contentType": "string",
            "groupNumber": number
         }
      ],
      "responseCard": "string"
   },
   "checksum": "string",
   "childDirected": boolean,
   "clarificationPrompt": { 
      "maxAttempts": number,
      "messages": [ 
         { 
            "content": "string",
            "contentType": "string",
            "groupNumber": number
         }
      ],
      "responseCard": "string"
   },
   "createVersion": boolean,
   "description": "string",
   "detectSentiment": boolean,
   "enableModelImprovements": boolean,
   "idleSessionTTLInSeconds": number,
   "intents": [ 
      { 
         "intentName": "string",
         "intentVersion": "string"
      }
   ],
   "locale": "string",
   "nluIntentConfidenceThreshold": number,
   "processBehavior": "string",
   "tags": [ 
      { 
         "key": "string",
         "value": "string"
      }
   ],
   "voiceId": "string"
}

URI リクエストパラメータ

リクエストでは、次の URI パラメータを使用します。

name

ボットの名前。キースペース名では、大文字と小文字は区別されません。

長さの制限: 最小長は 2 です。最大長は 50 です。

パターン: ^([A-Za-z]_?)+$

必須: はい

リクエストボディ

リクエストは以下の JSON 形式のデータを受け入れます。

abortStatement

Amazon Lexは、ユーザーが入力したコンテキストを理解できない場合、何度か情報を聞き出そうとします。Amazon Lex は次に abortStatement で定義されたメッセージをユーザーに送信してから、会話をキャンセルします。リトライの回数を設定するには、スロットタイプの valueElicitationPrompt フィールドを使用します。

例えば、ピザ注文ボットでは、Amazon Lex がユーザーに「どんな種類のクラストが欲しいですか？」と尋ねるかもしれません。ユーザーの回答が想定される回答 (例えば、「薄い生地」、「ディープディッシュ」など) ではない場合、Amazon Lex はさらに数回質問をし、正しい回答を引き出そうとします。

例えば、ピザを注文するアプリケーションでは、OrderPizza がインテントの 1 つになります。このインテントには、CrustType スロットを必要かもしれません。CrustType スロットの作成時に valueElicitationPrompt フィールドを指定します。

フォールバックインテントを定義している場合、キャンセルステートメントはユーザーに送信されず、代わりにフォールバックインテントが使用されます。詳細については、「AMAZON.FallbackIntent」を参照してください。

型: Statement オブジェクト

必須: いいえ

checksum

$LATEST バージョンの特定のリビジョンを識別します。

新しいボットを作成する場合は、checksum フィールドを空白にします。チェックサムを指定した場合、BadRequestException の例外が発生します。

ボットを更新する場合は、checksum フィールドに $LATEST バージョンの最新リビジョンのチェックサムを設定します。 checksum フィールドを指定しない場合や、チェックサムが $LATEST バージョンと一致しない場合は、PreconditionFailedException 例外が発生します。

タイプ: 文字列

必須: いいえ

childDirected

Amazon Lex Model·Building·Service で作成された各 Amazon Lex ボットについて、Amazon Lex 全体または一部の使用が、13 歳未満の児童を対象とするウェブサイト、プログラム、その他のアプリケーションに関連しており、COPPA (Children's Online Privacy Protection Act) の対象となっているかどうかを、childDirected フィールドに true または false を指定する必要があります。true のフィールド中の childDirected を指定することで、Amazon Lex の使用が、全体あるいは一部が 13 歳未満の子どもに向けられた、あるいはターゲットとし、また COPPA の対象となるウェブサイト、プログラムと、関係して いる ことに同意します。false のフィールド中の childDirected を指定することで、Amazon Lex の使用が、全体あるいは一部が 13 歳未満の子どもに向けられた、あるいはターゲットとし、また COPPA の対象となるウェブサイト、プログラムと、関係して いない ことに同意します。Amazon Lex の全体または一部の使用が、13歳未満の児童を対象にしており、COPPAの対象となるウェブサイト、プログラム、またはその他のアプリケーションに関連するかどうかを正確に設定するために、childDirected フィールドにデフォルト値を指定することはできません。

Amazon Lex 全体または一部の使用が、13 歳未満の児童を対象とするウェブサイト、プログラム、その他のアプリケーションに関連する場合は、COPPA により必要とされる検証可能な保護者の同意が必要です。13 歳未満の児童を対象とするウェブサイト、プログラム、またはその他のアプリケーションに関連する Amazon Lex の全体または一部の使用についての詳細は、「Amazon Lex FAQ」を参照してください。

型: ブール値

必須: はい

clarificationPrompt

Amazon Lex がユーザーのインテントを理解できない場合、このメッセージを使用して明確化します。Amazon Lex が明確化のプロンプトを何回繰り返すかを maxAttempts フィールドで指定します。それでも Amazon Lex が理解できない場合は、abortStatement フィールドでメッセージを送信します。

明瞭化のためのプロンプトを作成する際には、ユーザーからの正しい回答を示唆するようにしてください。例えば、ピザとドリンクを注文するボットの場合は、このような明確化のためのプロンプトを作成します。「どうなさいますか？ 「ピザを注文」または「飲み物を注文」と話してください」

フォールバックインテントを定義している場合は、maxAttempts フィールドで定義された回数だけ明確化のプロンプトが繰り返された場合に起動されます。詳細については、「AMAZON.FallbackIntent」を参照してください。

明示的なプロンプトを定義しない場合、実行時に Amazon Lex は 3 つのケースで 400 Bad Request の例外を返します。

  • フォローアッププロンプト - ユーザーがフォローアッププロンプトに応答しても、インテントが提供されない場合。例えば、「今日は他に何かご希望はありますか？」というフォローアッププロンプトに応答して、ユーザーが「はい」答えた場合。Amazon Lexは、インテントを取得するためにユーザーへ送る明確なプロンプトがないため、400 Bad Request例外を返します。

  • Lambda 関数 - Lambda 関数を使用する場合、ElicitIntent のダイアログタイプを返します。Amazon Lex には、ユーザーからインテントを取得するための明確化プロンプトがないため、400 Bad Request 例外が返されます。

  • PutSession operation - PutSession オペレーションを使用するときは、ElicitIntent ダイアログタイプを送信します。Amazon Lex には、ユーザーからインテントを取得するための明確化プロンプトがないため、400 Bad Request 例外が返されます。

型: Prompt オブジェクト

必須: いいえ

createVersion

true に設定すると、新しく採番されたバージョンのボットが作成されます。これは、CreateBotVersion のオペレーションを呼び出すのと同じです。createVersion を指定しなかった場合、デフォルトは false です。

型: ブール値

必須: いいえ

description

ボットの説明。

タイプ: 文字列

長さの制約: 最小長は 0 です。最大長は 200 です。

必須: いいえ

detectSentiment

true に設定すると、ユーザーの発話はセンチメント分析のために Amazon Comprehend へ送られます。detectSentiment を指定しなかった場合、デフォルトは false です。

型: ブール値

必須: いいえ

enableModelImprovements

true に設定すると、自然言語理解の向上にアクセスできるようになります。

enableModelImprovements パラメータを true に設定すると、nluIntentConfidenceThreshold パラメータを使って信頼度スコアを設定できます。詳細については、「Confidence Scores」(信頼スコア) を参照してください。

enableModelImprovements パラメータは、特定のリージョンでしか設定できません。パラメータを true に設定すると、ボットは精度の向上にアクセスできるようになります。

en-US ロケールで enableModelImprovements パラメータを false に設定できるリージョンは、以下の通りです。

  • 米国東部 (バージニア北部) (us-east-1)

  • 米国西部 (オレゴン) (us-west-2)

  • アジアパシフィック (シドニー) (ap-southeast-2)

  • 欧州 (アイルランド) (eu-west-1)

他のリージョンとロケールでは、enableModelImprovements パラメータはデフォルトで true に設定されています。これらのリージョンとロケールでは、パラメータを false に設定すると ValidationException の例外が発生します。

型: ブール値

必須: いいえ

idleSessionTTLInSeconds

Amazon Lex が会話で収集したデータを保持する最大時間 (秒) です。

ユーザーインタラクションセッションは、指定された時間の間はアクティブのままです。この間に会話が発生しない場合、セッションは期限切れになり、Amazon Lex はタイムアウト前に提供されたデータをすべて削除します。

例えば、ユーザーが OrderPizza のインテントを選択したものの、注文を途中で止めてしまったとします。ユーザーは指定した時間内に注文を完了をできなかった場合、Amazon Lex は収集したスロット情報を破棄し、ユーザーは最初からやり直す必要があります。

PutBot オペレーションリクエストに idleSessionTTLInSeconds 要素を含まない場合、Amazon Lex はデフォルト値を使用します。これは、リクエストが既存のボットを置き換える場合も同様です。

デフォルトは 300 秒 (5 分) です。

型: 整数

有効範囲: 最小値 は 60 です。最大値は 86400 です。

必須: いいえ

intents

Intent オブジェクトの配列。各インテントは、ユーザーが表現できるコマンドを表しています。例えば、ピザを注文するボットは、OrderPizza インテントをサポートしています。詳細については、「Amazon Lex: 仕組み」を参照してください。

型: Intent オブジェクトの配列

必須: いいえ

locale

ボットのターゲットロケールを指定します。ボットで使用するインテントは、ボットのロケールと互換性がある必要があります。

デフォルトは en-US です。

型: 文字列

有効な値：de-DE | en-AU | en-GB | en-IN | en-US | es-419 | es-ES | es-US | fr-FR | fr-CA | it-IT | ja-JP | ko-KR

必須: はい

nluIntentConfidenceThreshold

Amazon Lex が PostContent または PostText レスポンスで代替インテントを返す際に、AMAZON.FallbackIntent、AMAZON.KendraSearchIntent、またはその両方を挿入するしきい値を決定します。AMAZON.FallbackIntent および AMAZON.KendraSearchIntent は、ボットに設定されている場合にのみ挿入されます。

以下のリージョンで信頼性スコアを使用するには、enableModelImprovements パラメータを true に設定する必要があります。

  • 米国東部 (バージニア北部) (us-east-1)

  • 米国西部 (オレゴン) (us-west-2)

  • アジアパシフィック (シドニー) (ap-southeast-2)

  • 欧州 (アイルランド) (eu-west-1)

他のリージョンでは、enableModelImprovements パラメータはデフォルトで true に設定されています。

例えば、信頼度の閾値が 0.80 で、AMAZON.FallbackIntent を設定したボットがあったとします。Amazon Lex は、以下の 3 つの代替インテントを返します：IntentA (0.70)、IntentB (0.60)、intentC (0.50)。PostText オペレーションからのレスポンスは次のようになります。

  • AMAZON.FallbackIntent

  • IntentA

  • IntentB

  • IntentC

型: 倍精度浮動小数点数

有効範囲: 最小値 は 0 です。最大値は 1 です。

必須: いいえ

processBehavior

processBehavior 要素を BUILD に設定すると、Amazon Lex は実行可能なボットを構築します。要素を SAVE にした場合、Amazon Lex はボットを保存しますが、構築はしません。

この値を指定しない場合、デフォルト値は BUILD です。

型: 文字列

有効な値：SAVE | BUILD

必須：いいえ

tags

ボットに追加するタグのリスト。タグの追加は、ボットの作成時にのみ可能で、PutBot のオペレーションでボットのタグを更新することはできません。タグを更新するには、TagResource のオペレーションを使用します。

型: Tag オブジェクトの配列

配列メンバー: 最小数は 0 項目です。最大数は 200 項目です。

必須: いいえ

voiceId

Amazon Lex がユーザーとの音声対話に使用する Amazon Polly の音声ID です。音声に設定されたロケールは、ボットのロケールと一致する必要があります。Amazon Polly の詳細については、「Amazon Polly Developer Guide」(Amazon Polly デベロッパーガイド) の「Voices in Amazon Polly」(Amazon Polly における音声) を参照してください。

タイプ: 文字列

必須: いいえ

レスポンスの構文

HTTP/1.1 200
Content-type: application/json

{
   "abortStatement": { 
      "messages": [ 
         { 
            "content": "string",
            "contentType": "string",
            "groupNumber": number
         }
      ],
      "responseCard": "string"
   },
   "checksum": "string",
   "childDirected": boolean,
   "clarificationPrompt": { 
      "maxAttempts": number,
      "messages": [ 
         { 
            "content": "string",
            "contentType": "string",
            "groupNumber": number
         }
      ],
      "responseCard": "string"
   },
   "createdDate": number,
   "createVersion": boolean,
   "description": "string",
   "detectSentiment": boolean,
   "enableModelImprovements": boolean,
   "failureReason": "string",
   "idleSessionTTLInSeconds": number,
   "intents": [ 
      { 
         "intentName": "string",
         "intentVersion": "string"
      }
   ],
   "lastUpdatedDate": number,
   "locale": "string",
   "name": "string",
   "nluIntentConfidenceThreshold": number,
   "status": "string",
   "tags": [ 
      { 
         "key": "string",
         "value": "string"
      }
   ],
   "version": "string",
   "voiceId": "string"
}

レスポンス要素

アクションが成功すると、サービスは HTTP 200 レスポンスを返します。

サービスから以下のデータが JSON 形式で返されます。

abortStatement

Amazon Lex が会話をキャンセルするために使用するメッセージ。詳細については、「PutBot」を参照してください。

型: Statement オブジェクト

checksum

作成したボットのチェックサム。

タイプ: 文字列

childDirected

Amazon Lex Model·Building·Service で作成された各 Amazon Lex ボットについて、Amazon Lex 全体または一部の使用が、13 歳未満の児童を対象とするウェブサイト、プログラム、その他のアプリケーションに関連しており、COPPA (Children's Online Privacy Protection Act) の対象となっているかどうかを、childDirected フィールドに true または false を指定する必要があります。true のフィールド中の childDirected を指定することで、Amazon Lex の使用が、全体あるいは一部が 13 歳未満の子どもに向けられた、あるいはターゲットとし、また COPPA の対象となるウェブサイト、プログラムと、関係して いる ことに同意します。false のフィールド中の childDirected を指定することで、Amazon Lex の使用が、全体あるいは一部が 13 歳未満の子どもに向けられた、あるいはターゲットとし、また COPPA の対象となるウェブサイト、プログラムと、関係して いない ことに同意します。Amazon Lex の全体または一部の使用が、13歳未満の児童を対象にしており、COPPAの対象となるウェブサイト、プログラム、またはその他のアプリケーションに関連するかどうかを正確に設定するために、childDirected フィールドにデフォルト値を指定することはできません。

Amazon Lex 全体または一部の使用が、13 歳未満の児童を対象とするウェブサイト、プログラム、その他のアプリケーションに関連する場合は、COPPA により必要とされる検証可能な保護者の同意が必要です。13 歳未満の児童を対象とするウェブサイト、プログラム、またはその他のアプリケーションに関連する Amazon Lex の全体または一部の使用についての詳細は、「Amazon Lex FAQ」を参照してください。

型: ブール値

clarificationPrompt

Amazon Lex がユーザーのインテントを理解できない場合に、使用するプロンプト。詳細については、「PutBot」を参照してください。

型: Prompt オブジェクト

createdDate

ボットが作成された日付。

型: タイムスタンプ

createVersion

新しいバージョンのボットが作成された場合の True。リクエストで createVersion フィールドが指定されていない場合は、レスポンスで createVersion フィールドが false に設定されます。

型: ブール値

description

ボットの説明。

タイプ: 文字列

長さの制約: 最小長は 0 です。最大長は 200 です。

detectSentiment

センチメント分析のためにユーザーの発話を Amazon Comprehend に送信するようにボットが設定されている場合の true。リクエストで detectSentiment フィールドが指定されていない場合、detectSentiment フィールドはレスポンスでは false になります。

型: ブール値

enableModelImprovements

ボットが精度向上を使用しているかどうかを示します。true はボットが精度向上を使用していることを示し、それ以外は false となります。

型: ブール値

failureReason

status が FAILED の場合、Amazon Lex はボットの構築に失敗した理由を提示します。

タイプ: 文字列

idleSessionTTLInSeconds

Amazon Lex が会話の中で収集したデータを保持する最大時間。詳細については、「PutBot」を参照してください。

型: 整数

有効範囲: 最小値 は 60 です。最大値は 86400 です。

intents

Intent オブジェクトの配列。詳細については、「PutBot」を参照してください。

型: Intent オブジェクトの配列

lastUpdatedDate

ボットが更新された日付。リソースを作成すると、作成日と最終更新日は同じ日付になります。

型: タイムスタンプ

locale

ボットのターゲットロケール。

型: 文字列

有効な値：de-DE | en-AU | en-GB | en-IN | en-US | es-419 | es-ES | es-US | fr-FR | fr-CA | it-IT | ja-JP | ko-KR

name

ボットの名前。

タイプ: 文字列

長さの制限: 最小長は 2 です。最大長は 50 です。

パターン: ^([A-Za-z]_?)+$

nluIntentConfidenceThreshold

Amazon Lex が PostContent または PostText レスポンスで代替インテントを返す際に、AMAZON.FallbackIntent、AMAZON.KendraSearchIntent、またはその両方を挿入する場所を決定するスコアです。AMAZON.FallbackIntent は、すべてのインテントの信頼性スコアがこの値を下回る場合に挿入されます。AMAZON.KendraSearchIntent は、ボットに設定されている場合のみ挿入されます。

型: 倍精度浮動小数点数

有効範囲: 最小値 は 0 です。最大値は 1 です。

status

processBehavior を BUILD に設定したボット作成リクエストを送信すると、Amazon Lexは status レスポンス要素を BUILDING に設定します。

READY_BASIC_TESTING の状態では、スロットタイプでボットの意図や値として設定された発話と正確に一致するユーザーの入力でボットをテストすることができます。

Amazon Lex がボットを構築できない場合、Amazon Lex は status を FAILED に設定します。Amazon Lex は、failureReason レスポンス要素に失敗の理由を返します。

processBehavior を SAVE に設定すると、Amazon Lex はステータスコードを NOT BUILT に設定します。

ボットが READY の状態になったら、ボットをテストして公開することができます。

型: 文字列

有効な値：BUILDING | READY | READY_BASIC_TESTING | FAILED | NOT_BUILT

tags

ボットに関連付けられているタグのリスト。

型: Tag オブジェクトの配列

配列メンバー: 最小数は 0 項目です。最大数は 200 項目です。

version

ボットのバージョン。新規のボットの場合、バージョンは常に $LATEST です。

タイプ: 文字列

長さの制約: 最小長は 1 です。最大長 64

パターン: \$LATEST|[0-9]+

voiceId

Amazon Lex がユーザーとの音声対話に使用する Amazon Polly 音声 ID。詳細については、「PutBot」を参照してください。

タイプ: 文字列

エラー

BadRequestException

リクエストが適切にフォーマットされていません。例えば、値が無効であったり、必須項目が設定されていない場合です。フィールドの値を確認して、再度お試しください。

HTTP ステータスコード: 400

ConflictException

リクエストの処理中に競合が発生しました。リクエストを再試行してください。

HTTP ステータスコード: 409

InternalFailureException

Amazon Lex 内部エラーが発生しました。リクエストを再試行してください。

HTTP ステータスコード: 500

LimitExceededException

リクエストが制限を超えました。リクエストを再試行してください。

HTTP ステータスコード: 429

PreconditionFailedException

変更しようとしているリソースのチェックサムがリクエストのチェックサムと一致しません。リソースのチェックサムを確認して、もう一度お試しください。

HTTP ステータスコード: 412

以下の資料も参照してください。

言語固有の AWS SDKs のいずれかでこの API を使用する方法の詳細については、以下を参照してください。