PutBot - Amazon Lex V1
요청 구문URI 요청 파라미터요청 본문응답 구문응답 요소Errors참고

Amazon Lex V2를 사용하는 경우 Amazon Lex V2 가이드를 대신 참조하십시오.

 

Amazon Lex V1을 사용하는 경우 봇을 Amazon Lex V2로 업그레이드하는하는 것이 좋습니다. 더 이상 V1에 새로운 기능을 추가하지 않으므로 모든 새 봇에 V2를 사용할 것을 강력히 권장합니다.

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

PutBot

Amazon Lex 대화형 봇을 생성하거나 기존 봇을 교체합니다. 봇을 생성하거나 업데이트할 때는 이름, 로캘, 봇이 13세 미만의 어린이를 대상으로 하는지 여부만 지정하면 됩니다. 이를 사용하여 나중에 의도를 추가하거나 기존 봇에서 의도를 제거할 수 있습니다. 최소 정보로 봇을 생성하면 봇이 생성되거나 업데이트되지만 Amazon Lex는 응답을 반환합니다FAILED. 하나 이상의 의도를 추가한 후 봇을 구축할 수 있습니다. 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은 이러한 의도 중 하나일 수 있습니다. 이 의도에는 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)을 준수하는지를 childDirected 필드의 true 또는 false를 지정하여 지정해야 합니다. childDirected 필드에 true을 지정함으로써 사용자는 Amazon Lex 사용이 13세 미만 및 COPPA 적용 대상 아동 전체 또는 일부를 대상으로 하는 웹 사이트, 프로그램 또는 기타 애플리케이션과 관련이 있음을 확인합니다. childDirected 필드에 false을 지정함으로써 사용자는 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는 런타임 시 다음과 같은 세 가지 경우에 400 잘못된 요청 예외를 반환합니다.

  • 후속 프롬프트 - 사용자가 후속 프롬프트에 응답하지만, 의도를 제공하지 않는 경우 예를 들어, "오늘 다른 것을 원하시나요?"라는 후속 프롬프트에 대한 응답으로 사용자가 "예"라고 한 경우 Amazon Lex에 사용자의 의도를 파악하기 위한 확인 프롬프트가 없기 때문에 400 잘못된 요청 예외가 반환됩니다.

  • Lambda 함수 - Lambda 함수를 사용하는 경우 ElicitIntent 대화 상자 유형을 반환합니다. Amazon Lex에 사용자의 의도를 파악하기 위한 확인 프롬프트가 없기 때문에 400 잘못된 요청 예외가 반환됩니다.

  • PutSession 오퍼레이션 - PutSession 오퍼레이션을 사용할 때 ElicitIntent 다이얼로그 유형을 전송합니다. Amazon Lex에 사용자의 의도를 파악하기 위한 확인 프롬프트가 없기 때문에 400 잘못된 요청 예외가 반환됩니다.

타입: Prompt 객체

필수 여부: 아니요

createVersion

true로 설정하면 번호가 매겨진 새 버전의 봇이 생성됩니다. 이는 CreateBotVersion 오퍼레이션을 호출하는 것과 같습니다. createVersion를 지정하지 않으면 기본값은 false입니다.

타입: 부울

필수 항목 여부: 아니요

description

봇에 대한 설명.

타입: 문자열

길이 제약 조건: 최소 길이는 0입니다. 최대 길이는 200.

필수 여부: 아니요

detectSentiment

true로 설정하면 감성 분석을 위해 사용자 표현이 Amazon Comprehend로 전송됩니다. detectSentiment를 지정하지 않으면 기본값은 false입니다.

타입: 부울

필수 항목 여부: 아니요

enableModelImprovements

자연어 이해 개선에 대한 액세스를 가능하게 true로 설정합니다.

enableModelImprovements 매개변수를 true로 설정하면 nluIntentConfidenceThreshold 매개변수를 사용하여 신뢰도 점수를 구성할 수 있습니다. 자세한 내용은 신뢰도 점수를 참조하세요.

특정 지역에서만 enableModelImprovements 매개변수를 설정할 수 있습니다. 매개변수를 true로 설정하면 봇이 정확도 개선에 액세스합니다.

en-US 로캘에 enableModelImprovements 매개변수를 false로 설정할 수 있는 지역은 다음과 같습니다.

  • 미국 동부(버지니아 북부)(us-east-1)

  • 미국 서부(오레곤)(us-west-2)

  • 아시아 태평양(시드니)(ap-southeast-2)

  • EU(아일랜드)(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

or PostText응답에서 대체 인텐트를 반환할 때 Amazon Lex가 AMAZON.FallbackIntentAMAZON.KendraSearchIntent, 또는 둘 다를 삽입할 임계값을 결정합니다. PostContent AMAZON.FallbackIntent봇용으로 구성된 경우에만 삽입됩니다. AMAZON.KendraSearchIntent

다음 지역의 신뢰도 점수를 사용하려면 enableModelImprovements 매개변수를 true로 설정해야 합니다.

  • 미국 동부(버지니아 북부)(us-east-1)

  • 미국 서부(오레곤)(us-west-2)

  • 아시아 태평양(시드니)(ap-southeast-2)

  • EU(아일랜드)(eu-west-1)

다른 지역 및 로캘에서는 enableModelImprovements 매개변수가 기본적으로 true로 설정됩니다.

예를 들어, 봇이 신뢰 임계값 0.80 및 AMAZON.FallbackIntent으로 구성되어 있다고 가정하겠습니다. Amazon Lex는 IntentA(0.70), IntentB(0.60), IntentC(0.50) 라는 신뢰도 점수를 가진 세 가지 대체 의도를 반환합니다. PostText 작업에 대한 응답은 다음과 같습니다.

  • 아마존. FallbackIntent

  • IntentA

  • IntentB

  • IntentC

유형: Double

유효한 범위: 최소값 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 음성을 참조하세요.

타입: 문자열

필수 항목 여부: 아니요

응답 구문

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)을 준수하는지를 childDirected 필드의 true 또는 false를 지정하여 지정해야 합니다. childDirected 필드에 true을 지정함으로써 사용자는 Amazon Lex 사용이 13세 미만 및 COPPA 적용 대상 아동 전체 또는 일부를 대상으로 하는 웹 사이트, 프로그램 또는 기타 애플리케이션과 관련이 있음을 확인합니다. childDirected 필드에 false을 지정함으로써 사용자는 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

봇이 생성된 날짜입니다.

타입: Timestamp

createVersion

봇의 새 버전이 생성된 경우 True. 요청에서 createVersion 필드를 지정하지 않은 경우 응답에서 createVersion 필드는 거짓으로 설정됩니다.

타입: 부울

description

봇에 대한 설명입니다.

타입: 문자열

길이 제약 조건: 최소 길이는 0입니다. 최대 길이는 200.

detectSentiment

봇이 감정 분석을 위해 사용자 발언을 Amazon Comprehend로 보내도록 구성된 경우 true. 요청에서 detectSentiment 필드를 지정하지 않은 경우 응답에서 detectSentiment 필드는 false입니다.

타입: 부울

enableModelImprovements

봇이 정확도 개선을 사용하는지 여부를 나타냅니다. true은 봇이 개선 사항을 사용하고 있음을 나타내며, 그렇지 않으면, false입니다.

타입: 부울

failureReason

만약 status이 FAILED라면, Amazon Lex는 봇 구축에 실패한 이유를 제공합니다.

타입: 문자열

idleSessionTTLInSeconds

Amazon Lex가 대화에서 수집된 데이터를 보관하는 최대 시간입니다. 자세한 설명은 PutBot 섹션을 참조하세요.

타입: 정수

유효한 범위: 최소값 60. 최대값은 86,400.

intents

Intent 객체 어레이. 자세한 내용은 PutBot을 참조하세요.

유형: Intent 객체 배열

lastUpdatedDate

봇이 생성된 날짜입니다. 리소스를 생성할 때 생성 날짜 및 최종 업데이트 날짜가 동일합니다.

타입: Timestamp

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

또는 PostText응답에서 대체 인텐트를 반환할 때 Amazon Lex가 AMAZON.FallbackIntentAMAZON.KendraSearchIntent, 또는 둘 다를 삽입하는 PostContent위치를 결정하는 점수입니다. AMAZON.FallbackIntent모든 인텐트에 대한 신뢰도 점수가 이 값보다 낮은 경우 삽입됩니다. AMAZON.KendraSearchIntent봇용으로 구성된 경우에만 삽입됩니다.

유형: Double

유효한 범위: 최소값 0. 최댓값은 1.

status

processBehavior이 BUILD로 설정된 봇 생성 요청을 보내면 Amazon Lex는 status 응답 요소를 BUILDING로 설정합니다.

READY_BASIC_TESTING 상태에서는 슬롯 유형에서 봇의 의도와 값에 대해 구성된 표현과 정확히 일치하는 사용자 입력으로 봇을 테스트할 수 있습니다.

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을 참조하세요.

타입: 문자열

Errors

BadRequestException

요청이 제대로 구성되지 않았습니다. 예를 들어, 값이 유효하지 않거나 필수 필드가 누락된 경우입니다. 필드 값을 확인한 후 다시 시도하세요.

HTTP Status Code: 400

ConflictException

요청을 처리하는 동안 충돌이 발생했습니다. 다시 요청해 보세요.

HTTP Status Code: 409

InternalFailureException

내부 Amazon Lex 오류가 발생했습니다. 요청을 다시 시도하세요.

HTTP Status Code: 500

LimitExceededException

요청이 한도를 초과했습니다. 다시 요청해 보세요.

HTTP Status Code: 429

PreconditionFailedException

변경하려는 리소스의 체크섬이 요청의 체크섬과 일치하지 않습니다. 리소스의 체크섬을 확인한 후 다시 시도하세요.

HTTP 상태 코드: 412

참고

언어별 AWS SDK 중 하나에서 이 API를 사용하는 방법에 대한 자세한 내용은 다음을 참조하십시오.