PostText - Amazon Lex V1
Request SyntaxURI 요청 파라미터요청 본문응답 구문응답 요소Errors참고

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

 

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

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

PostText

Amazon Lex에 사용자 입력을 전송합니다. 클라이언트 애플리케이션은 이 API를 사용하여 런타임에 Amazon Lex에 요청을 보낼 수 있습니다. Amazon Lex는 봇용으로 구축한 기계 학습 모델을 사용하여 사용자 입력을 해석합니다.

이에 대한 응답으로 Amazon Lex는 다음 message을 반환하여 표시할 선택적 responseCard를 사용자에게 전달합니다. 다음 예제를 검토하십시오.

  • 사용자가 “피자를 드세요”라고 입력하면 Amazon Lex는 슬롯 데이터를 유도하는 메시지 (예: “어떤 크기의 피자를 드시겠습니까?” PizzaSize) 가 포함된 응답을 반환할 수 있습니다.

  • 사용자가 모든 피자 주문 정보를 제공한 후 Amazon Lex는 사용자 확인을 얻기 위해 "피자 주문을 진행하시겠습니까?"라는 메시지와 함께 응답을 반환할 수 있습니다.

  • 사용자가 확인 프롬프트에 "예"라고 응답하면 Amazon Lex에서 "감사합니다. 치즈 피자가 주문되었습니다."라는 결론문을 반환할 수 있습니다.

모든 Amazon Lex 메시지에 사용자의 응답이 필요한 것은 아닙니다. 예를 들어, 결론문에는 응답이 필요하지 않습니다. 일부 메시지에는 "예" 또는 "아니오" 응답만 필요합니다. Amazon Lex는 message 외에도, 예를 들어, 적절한 클라이언트 사용자 인터페이스를 표시하는 등 클라이언트 동작을 개선하는 데 사용할 수 있는 메시지에 대한 추가 컨텍스트를 제공합니다. 응답의slotToElicit, dialogState, intentName, 및 slots 필드는 다음과 같습니다. 다음 예제를 살펴보세요.

  • 메시지가 슬롯 데이터를 끌어내라는 것이면 Amazon Lex는 다음 컨텍스트 정보를 반환합니다.

    • dialogState로 설정 ElicitSlot

    • intentName을 현재 컨텍스트의 의도 이름으로 설정합니다.

    • slotToElicit은 message가 정보를 이끌어내는 슬롯 이름으로 설정됩니다.

    • slots은 현재 알려진 값을 사용하여 의도에 맞게 구성된 슬롯의 맵으로 설정됩니다.

  • 메시지가 확인 프롬프트인 경우 는 null로 ConfirmIntent 설정되고 SlotToElicit null로 설정됩니다. dialogState

  • 메시지가 사용자 의도를 이해할 수 없음을 나타내는 설명 프롬프트 (인텐트에 맞게 구성됨) 인 경우 는 null로 dialogState ElicitIntent 설정되고 null로 설정됩니다. slotToElicit

또한 Amazon Lex는 애플리케이션별 sessionAttributes 정보도 반환합니다. 자세한 내용은 대화 컨텍스트 관리를 참조하십시오.

Request Syntax

POST /bot/botName/alias/botAlias/user/userId/text HTTP/1.1
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "inputText": "string",
   "requestAttributes": { 
      "string" : "string" 
   },
   "sessionAttributes": { 
      "string" : "string" 
   }
}

URI 요청 파라미터

요청은 다음 URI 파라미터를 사용합니다.

botAlias

Amazon Lex 봇의 별칭.

필수 여부: 예

botName

Amazon Lex 봇의 이름.

필수 여부: 예

userId

클라이언트 애플리케이션 사용자의 ID입니다. Amazon Lex는 이를 사용하여 사용자와 봇의 대화를 식별합니다. 런타임 시 각 요청에는 userID 필드가 포함되어야 합니다.

애플리케이션에 사용할 사용자 ID를 결정하려면 다음 요소를 고려하십시오.

  • userID 필드에는 사용자의 개인 식별 정보(예: 이름, 개인 식별 번호 또는 기타 최종 사용자 개인 정보)가 포함되어서는 안 됩니다.

  • 사용자가 한 기기에서 대화를 시작하고 다른 기기에서 계속하도록 하려면 사용자별 식별자를 사용하세요.

  • 동일한 사용자가 서로 다른 두 기기에서 독립적인 대화를 두 번 할 수 있게 하려면 기기별 식별자를 선택하세요.

  • 사용자는 같은 봇의 서로 다른 두 가지 버전과 독립적인 대화를 두 번 할 수 없습니다. 예를 들어 사용자는 동일한 봇의 PROD 및 BETA 버전과 대화할 수 없습니다. 예를 들어 테스트 중에 사용자가 서로 다른 두 버전과 대화해야 할 것으로 예상되는 경우 사용자 ID에 봇 별칭을 포함하여 두 대화를 구분하십시오.

길이 제약: 최소 길이는 2입니다. 최대 길이는 100.

패턴: [0-9a-zA-Z._:-]+

필수: 예

요청 본문

요청은 JSON 형식으로 다음 데이터를 받습니다.

activeContexts

요청에 대해 활성화된 컨텍스트 목록. 이전 의도가 이행될 때 또는 요청에 컨텍스트를 포함시켜 컨텍스트를 활성화할 수 있습니다.

컨텍스트 목록을 지정하지 않으면 Amazon Lex는 세션의 현재 컨텍스트 목록을 사용합니다. 빈 목록을 지정하면 세션의 모든 컨텍스트가 지워집니다.

타입: ActiveContext 객체 배열

배열 멤버: 최소 항목 수는 0개. 최대 항목 수는 20개.

필수 여부: 아니요

inputText

사용자가 입력한 텍스트(Amazon Lex는 이 텍스트를 해석함).

AWS CLI를 사용하는 경우 --input-text 파라미터에 URL을 전달할 수 없습니다. 대신 --cli-input-json 파라미터를 사용하여 URL을 전달하십시오.

유형: 문자열

길이 제약 조건: 최소 길이는 1입니다. 최대 길이 1024.

필수 여부: 예

requestAttributes

Amazon Lex와 클라이언트 애플리케이션 간에 전달되는 요청별 정보.

네임스페이스 x-amz-lex:는 특수 속성용으로 남겨둡니다. 접두사 x-amz-lex:를 사용하여 요청 속성을 생성하지 마세요.

요청 속성에 대한 자세한 내용은 요청 속성 설정을 참조하십시오.

유형: 문자열 대 문자열 맵

필수 여부: 아니요

sessionAttributes

Amazon Lex와 클라이언트 애플리케이션 간에 전달되는 요청별 정보.

요청 속성에 대한 자세한 내용은 요청 속성 설정을 참조하십시오.

유형: 문자열 간 맵

필수 항목 여부: 아니요

응답 구문

HTTP/1.1 200
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "alternativeIntents": [ 
      { 
         "intentName": "string",
         "nluIntentConfidence": { 
            "score": number
         },
         "slots": { 
            "string" : "string" 
         }
      }
   ],
   "botVersion": "string",
   "dialogState": "string",
   "intentName": "string",
   "message": "string",
   "messageFormat": "string",
   "nluIntentConfidence": { 
      "score": number
   },
   "responseCard": { 
      "contentType": "string",
      "genericAttachments": [ 
         { 
            "attachmentLinkUrl": "string",
            "buttons": [ 
               { 
                  "text": "string",
                  "value": "string"
               }
            ],
            "imageUrl": "string",
            "subTitle": "string",
            "title": "string"
         }
      ],
      "version": "string"
   },
   "sentimentResponse": { 
      "sentimentLabel": "string",
      "sentimentScore": "string"
   },
   "sessionAttributes": { 
      "string" : "string" 
   },
   "sessionId": "string",
   "slots": { 
      "string" : "string" 
   },
   "slotToElicit": "string"
}

응답 요소

작업이 성공하면 서비스가 HTTP 200 응답을 반송합니다.

다음 데이터는 서비스에 의해 JSON 형식으로 반환됩니다.

activeContexts

세션에 대해 활성화된 컨텍스트 목록. 의도가 이행될 때 또는 PostContent, PostText, 또는 PutSession 작업을 호출하여 컨텍스트를 설정할 수 있습니다.

컨텍스트를 사용하여 의도를 추적할 수 있는 의도를 제어하거나 애플리케이션 작업을 수정할 수 있습니다.

타입: ActiveContext 객체 배열

배열 멤버: 최소 항목 수는 0개. 최대 항목 수는 20개.

alternativeIntents

사용자의 의도에 적용할 수 있는 1~4개의 대체 의도.

각 대안에는 Amazon Lex가 의도가 사용자의 의도와 일치한다고 얼마나 확신하는 지를 나타내는 점수가 포함되어 있습니다. 의도는 신뢰도 점수를 기준으로 정렬됩니다.

타입: PredictedIntent 객체 배열

배열 멤버: 최대 항목 수는 4개입니다.

botVersion

대화에 응답한 봇의 버전입니다. 이 정보를 사용하여 한 버전의 봇이 다른 버전보다 성능이 좋은지 확인할 수 있습니다.

유형: 문자열

길이 제약 조건: 최소 길이는 1입니다. 최대 길이는 64.

패턴: [0-9]+|\$LATEST

dialogState

사용자 상호 작용의 현재 상태를 식별합니다. Amazon Lex는 다음 값 중 하나를 dialogState로 반환합니다. 클라이언트는 선택적으로 이 정보를 사용하여 사용자 인터페이스를 사용자 정의할 수 있습니다.

  • ElicitIntent - Amazon Lex는 사용자의 의도를 이끌어내고자 합니다.

    예를 들어, 사용자가 의도("피자를 주문하고 싶어요")를 말할 수 있습니다. Amazon Lex가 이 발언에서 사용자 의도를 유추할 수 없는 경우 이 dialogState를 반환합니다.

  • ConfirmIntent - Amazon Lex는 "예" 또는 "아니요"라는 응답을 기대하고 있습니다.

    예를 들어 Amazon Lex는 의도를 이행하기 전에 사용자 확인을 원합니다.

    사용자는 단순한 "예" 또는 "아니요" 대신 추가 정보로 응답할 수 있습니다. 예를 들어 "네, 하지만 두꺼운 크러스트 피자로 만드세요" 또는 "아니요, 음료를 주문하고 싶어요." Amazon Lex는 이러한 추가 정보를 처리할 수 있습니다 (이 예에서는 크러스트 유형 슬롯 값을 업데이트하거나 인텐트를 에서 OrderPizza 로 변경 OrderDrink).

  • ElicitSlot - Amazon Lex는 현재 의도에 사용할 슬롯의 값을 예상하고 있습니다.

    예를 들어 Amazon Lex가 응답에서 "어떤 크기의 피자를 원하시나요?"라는 메시지를 보낸다고 가정해 보겠습니다. 사용자가 슬롯 값(예: "중간")으로 응답할 수 있습니다. 사용자는 응답 시 추가 정보(예: "중간 두께의 크러스트 피자")를 제공할 수도 있습니다. Amazon Lex는 이러한 추가 정보를 적절하게 처리할 수 있습니다.

  • Fulfilled - 의도에 대해 구성된 Lambda 함수가 성공적으로 이행되었음을 전달합니다.

  • ReadyForFulfillment - 클라이언트가 요청을 이행해야 함을 전달합니다.

  • Failed - 사용자와의 대화가 실패했음을 전달합니다.

    이는 사용자가 서비스의 프롬프트에 적절한 응답을 제공하지 않았거나(Amazon Lex가 사용자에게 특정 정보에 대한 메시지를 표시할 수 있는 횟수를 구성할 수 있음) Lambda 함수가 의도를 이행하지 못한 경우 등 다양한 이유로 발생할 수 있습니다.

타입: 문자열

유효 값: ElicitIntent | ConfirmIntent | ElicitSlot | Fulfilled | ReadyForFulfillment | Failed

intentName

Amazon Lex가 알고 있는 현재 사용자 의도를 나타냅니다.

타입: 문자열

message

사용자에게 전달하는 메시지입니다. 메시지는 봇의 구성 또는 Lambda 함수에서 올 수 있습니다.

의도가 Lambda 함수로 구성되지 않았거나 Lambda 함수가 응답으로 Delegate을 dialogAction.type로 반환하는 경우, Amazon Lex는 다음 액션 코스를 결정하고 현재 상호 작용 컨텍스트를 기반으로 봇의 구성에서 적절한 메시지를 선택합니다. 예를 들어 Amazon Lex가 사용자 입력을 이해할 수 없는 경우 확인 프롬프트 메시지를 사용합니다.

의도를 생성하면 그룹에 메시지를 할당할 수 있습니다. 메시지가 그룹에 할당되면 Amazon Lex는 응답의 각 그룹에서 메시지를 하나씩 반환합니다. 메시지 필드는 메시지가 포함된 이스케이프된 JSON 문자열입니다. 반환된 JSON 문자열의 구조에 대한 자세한 내용은 지원되는 메시지 형식을 참조하세요.

Lambda 함수가 메시지를 반환하면 Amazon Lex는 응답으로 이를 클라이언트에 전달합니다.

유형: 문자열

길이 제약 조건: 최소 길이는 1입니다. 최대 길이는 1,024.

messageFormat

응답 메시지의 형식. 다음 값 중 하나입니다.

  • PlainText - 메시지에 일반 UTF-8 텍스트가 포함됩니다.

  • CustomPayload - 메시지는 Lambda 함수에서 정의되는 사용자 지정 형식입니다.

  • SSML - 메시지에 음성 출력용으로 서식이 지정된 텍스트가 포함됩니다.

  • Composite - 메시지에는 의도 생성 시 메시지가 할당된 그룹의 메시지가 하나 이상 포함된 이스케이프된 JSON 개체가 포함되어 있습니다.

타입: 문자열

유효 값: PlainText | CustomPayload | SSML | Composite

nluIntentConfidence

Amazon Lex가 반환된 의도가 사용자의 의도와 일치한다고 얼마나 확신하는지 나타내는 점수를 제공합니다. 점수는 0.0~1.0 사이입니다. 자세한 내용은 신뢰도 점수를 참조하세요.

점수는 상대 점수이며 절대 점수가 아닙니다. 점수는 Amazon Lex의 개선 사항에 따라 변경될 수 있습니다.

타입: IntentConfidence 객체

responseCard

사용자가 현재 프롬프트에 응답해야 하는 옵션을 나타냅니다. 응답 카드는 봇 구성 (Amazon Lex 콘솔에서, 슬롯 옆의 설정 버튼 선택) 또는 코드 후크(Lambda 함수)에서 가져올 수 있습니다.

타입: ResponseCard 객체

sentimentResponse

표현된 감정과 발언.

봇이 감정 분석을 위해 Amazon Comprehend로 표현을 보내도록 구성된 경우 이 필드에 분석 결과가 포함됩니다.

타입: SentimentResponse 객체

sessionAttributes

세션별 컨텍스트 정보를 나타내는 키-값 페어의 맵입니다.

유형: 문자열-문자열 맵

sessionId

게임 세션에 대한 고유 식별자입니다.

타입: 문자열

slots

Amazon Lex가 대화의 사용자 입력에서 감지한 의도 슬롯.

Amazon Lex는 슬롯에 대한 예상 값을 가진 해결 목록을 생성합니다. 반환되는 값은 슬롯 유형이 생성되거나 업데이트될 때 valueSelectionStrategy에 의해 선택된 값에 따라 결정됩니다. valueSelectionStrategy을 ORIGINAL_VALUE로 설정하면 사용자 값이 슬롯 값과 유사한 경우 사용자가 제공한 값이 반환됩니다. valueSelectionStrategy가 TOP_RESOLUTION로 설정된 경우, Amazon Lex는 해결 목록의 첫 번째 값을 반환하고, 해결 목록이 없는 경우 null을 반환합니다. valueSelectionStrategy를 지정하지 않으면 기본값은 ORIGINAL_VALUE입니다.

유형: 문자열-문자열 맵

slotToElicit

dialogState 값이 ElicitSlot인 경우 Amazon Lex가 값을 추출하는 슬롯의 이름을 반환합니다.

타입: 문자열

Errors

BadGatewayException

Amazon Lex 봇이 아직 구축 중이거나 종속 서비스 중 하나(Amazon Polly, AWS Lambda)가 내부 서비스 오류로 인해 장애가 발생했습니다.

HTTP 상태 코드: 502

BadRequestException

요청 검증이 실패했거나, 컨텍스트에 사용 가능한 메시지가 없거나, 봇 빌드가 실패했거나, 아직 진행 중이거나, 빌드되지 않은 변경 사항이 포함되어 있습니다.

HTTP 상태 코드: 400

ConflictException

두 클라이언트가 동일한 AWS 계정, Amazon Lex 봇 및 사용자 ID를 사용하고 있습니다.

HTTP Status Code: 409

DependencyFailedException

AWS Lambda 또는 Amazon Polly와 같은 종속 서비스 중 하나에서 예외가 발생했습니다. 예를 들어,

  • Amazon Lex에 Lambda 함수를 호출할 수 있는 충분한 권한이 없는 경우.

  • Lambda 함수를 실행하는 데 30초 이상 걸리는 경우.

  • 이행 Lambda 함수가 슬롯 값을 제거하지 않고 Delegate 대화 작업을 반환하는 경우.

HTTP 상태 코드: 424

InternalFailureException

내부 서비스 오류. 호출 재시도.

HTTP 상태 코드: 500

LimitExceededException

제한 초과함.

HTTP Status Code: 429

LoopDetectedException

이 예외는 사용되지 않습니다.

HTTP 상태 코드: 508

NotFoundException

참조된 리소스(예: Amazon Lex 봇 또는 별칭)를 찾을 수 없습니다.

HTTP 상태 코드: 404

참고

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