지원 종료 공지: 2025년 9월 15 AWS 일에는 Amazon Lex V1에 대한 지원을 중단할 예정입니다. 2025년 9월 15일 이후에는 Amazon Lex V1 콘솔 또는 Amazon Lex V1 리소스에 더 이상 액세스할 수 없습니다. Amazon Lex V2를 사용하는 경우 대신 [Amazon Lex V2 가이드를](https://docs.aws.amazon.com/lexv2/latest/dg/what-is.html) 참조하세요. 기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 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`은 현재 알려진 값을 사용하여 의도에 맞게 구성된 슬롯의 맵으로 설정됩니다. + 메시지가 확인 프롬프트인 경우, `dialogState`는 ConfirmIntent로 설정되고 `SlotToElicit`는 null로 설정됩니다. + 메시지가 사용자 의도가 이해되지 않았음을 나타내는 설명 프롬프트(의도에 대해 구성됨)인 경우 `dialogState`은 ElicitIntent로 설정되고 `slotToElicit`는 null로 설정됩니다. 또한 Amazon Lex는 애플리케이션별 `sessionAttributes` 정보도 반환합니다. 자세한 내용은 [대화 컨텍스트 관리](https://docs.aws.amazon.com/lex/latest/dg/context-mgmt.html)를 참조하십시오. ## 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](#API_runtime_PostText_RequestSyntax) ** Amazon Lex 봇의 별칭. 필수 항목 여부: 예 ** [botName](#API_runtime_PostText_RequestSyntax) ** Amazon Lex 봇의 이름. 필수 항목 여부: 예 ** [userId](#API_runtime_PostText_RequestSyntax) ** 클라이언트 애플리케이션 사용자의 ID입니다. Amazon Lex는 이를 사용하여 사용자와 봇의 대화를 식별합니다. 런타임 시 각 요청에는 `userID` 필드가 포함되어야 합니다. 애플리케이션에 사용할 사용자 ID를 결정하려면 다음 요소를 고려하십시오. + `userID` 필드에는 사용자의 개인 식별 정보 (예: 이름, 개인 식별 번호 또는 기타 최종 사용자 개인 정보)가 포함되어서는 안 됩니다. + 사용자가 한 기기에서 대화를 시작하고 다른 기기에서 계속하도록 하려면 사용자별 식별자를 사용하세요. + 동일한 사용자가 서로 다른 두 기기에서 독립적인 대화를 두 번 할 수 있게 하려면 기기별 식별자를 선택하세요. + 사용자는 같은 봇의 서로 다른 두 가지 버전과 독립적인 대화를 두 번 할 수 없습니다. 예를 들어 사용자는 동일한 봇의 PROD 및 BETA 버전과 대화할 수 없습니다. 예를 들어 테스트 중에 사용자가 서로 다른 두 버전과 대화해야 할 것으로 예상되는 경우 사용자 ID에 봇 별칭을 포함하여 두 대화를 구분하십시오. 길이 제약: 최소 길이는 2. 최대 길이는 100. 패턴: `[0-9a-zA-Z._:-]+` 필수 여부: 예 ## 요청 본문 요청은 JSON 형식으로 다음 데이터를 받습니다. ** [activeContexts](#API_runtime_PostText_RequestSyntax) ** 요청에 대해 활성화된 컨텍스트 목록. 이전 의도가 이행될 때 또는 요청에 컨텍스트를 포함시켜 컨텍스트를 활성화할 수 있습니다. 컨텍스트 목록을 지정하지 않으면 Amazon Lex는 세션의 현재 컨텍스트 목록을 사용합니다. 빈 목록을 지정하면 세션의 모든 컨텍스트가 지워집니다. 타입: [ActiveContext](API_runtime_ActiveContext.md)객체 배열 배열 항목: 최소 항목 수는 0개. 최대 항목 수는 20개. 필수 여부: 아니요 ** [inputText](#API_runtime_PostText_RequestSyntax) ** 사용자가 입력한 텍스트(Amazon Lex는 이 텍스트를 해석함). AWS CLI를 사용하는 경우 `--input-text` 파라미터에 URL을 전달할 수 없습니다. 대신 `--cli-input-json` 파라미터를 사용하여 URL을 전달하십시오. 유형: 문자열 길이 제약: 최소 길이 1. 최대 길이는 1,024. 필수 항목 여부: 예 ** [requestAttributes](#API_runtime_PostText_RequestSyntax) ** Amazon Lex와 클라이언트 애플리케이션 간에 전달되는 요청별 정보. 네임스페이스 `x-amz-lex:`는 특수 속성용으로 남겨둡니다. 접두사 `x-amz-lex:`를 사용하여 요청 속성을 생성하지 마세요. 요청 속성에 대한 자세한 내용은 [요청 속성 설정](https://docs.aws.amazon.com/lex/latest/dg/context-mgmt.html#context-mgmt-request-attribs)을 참조하십시오. 유형: 문자열 대 문자열 맵 필수 여부: 아니요 ** [sessionAttributes](#API_runtime_PostText_RequestSyntax) ** Amazon Lex와 클라이언트 애플리케이션 간에 전달되는 요청별 정보. 요청 속성에 대한 자세한 내용은 [요청 속성 설정](https://docs.aws.amazon.com/lex/latest/dg/context-mgmt.html#context-mgmt-session-attribs)을 참조하십시오. 유형: 문자열 대 문자열 맵 필수 항목 여부: 아니요 ## 응답 구문 ``` 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](#API_runtime_PostText_ResponseSyntax) ** 세션에 대해 활성화된 컨텍스트 목록. 의도가 이행될 때 또는 `PostContent`, `PostText`, 또는 `PutSession` 작업을 호출하여 컨텍스트를 설정할 수 있습니다. 컨텍스트를 사용하여 의도를 추적할 수 있는 의도를 제어하거나 애플리케이션 작업을 수정할 수 있습니다. 타입: [ActiveContext](API_runtime_ActiveContext.md)객체 배열 배열 항목: 최소 항목 수는 0개. 최대 항목 수는 20개. ** [alternativeIntents](#API_runtime_PostText_ResponseSyntax) ** 사용자의 의도에 적용할 수 있는 1\~4개의 대체 의도. 각 대안에는 Amazon Lex가 의도가 사용자의 의도와 일치한다고 얼마나 확신하는 지를 나타내는 점수가 포함되어 있습니다. 의도는 신뢰도 점수를 기준으로 정렬됩니다. 타입: [PredictedIntent](API_runtime_PredictedIntent.md)객체 배열 배열 멤버: 최대 항목 수는 4개입니다. ** [botVersion](#API_runtime_PostText_ResponseSyntax) ** 대화에 응답한 봇의 버전입니다. 이 정보를 사용하여 한 버전의 봇이 다른 버전보다 성능이 좋은지 확인할 수 있습니다. 유형: 문자열 길이 제한: 최소 길이는 1. 최대 길이는 64. 패턴: `[0-9]+|\$LATEST` ** [dialogState](#API_runtime_PostText_ResponseSyntax) ** 사용자 상호 작용의 현재 상태를 식별합니다. 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](#API_runtime_PostText_ResponseSyntax) ** Amazon Lex가 알고 있는 현재 사용자 의도를 나타냅니다. 유형: 문자열 ** [message](#API_runtime_PostText_ResponseSyntax) ** 사용자에게 전달하는 메시지입니다. 메시지는 봇의 구성 또는 Lambda 함수에서 올 수 있습니다. 의도가 Lambda 함수로 구성되지 않았거나 Lambda 함수가 응답으로 `Delegate`을 `dialogAction.type`로 반환하는 경우, Amazon Lex는 다음 액션 코스를 결정하고 현재 상호 작용 컨텍스트를 기반으로 봇의 구성에서 적절한 메시지를 선택합니다. 예를 들어 Amazon Lex가 사용자 입력을 이해할 수 없는 경우 설명 프롬프트 메시지를 사용합니다. 의도를 생성하면 그룹에 메시지를 할당할 수 있습니다. 메시지가 그룹에 할당되면 Amazon Lex는 응답의 각 그룹에서 메시지를 하나씩 반환합니다. 메시지 필드는 메시지가 포함된 이스케이프된 JSON 문자열입니다. 반환된 JSON 문자열의 구조에 대한 자세한 내용은 [지원되는 메시지 형식](howitworks-manage-prompts.md#msg-prompts-formats)을 참조하세요. Lambda 함수가 메시지를 반환하면 Amazon Lex는 응답으로 이를 클라이언트에 전달합니다. 유형: 문자열 길이 제약: 최소 길이 1. 최대 길이는 1,024. ** [messageFormat](#API_runtime_PostText_ResponseSyntax) ** 응답 메시지의 형식. 다음 값 중 하나입니다. + `PlainText` - 메시지에 일반 UTF-8 텍스트가 포함됩니다. + `CustomPayload` - 메시지는 Lambda 함수에서 정의되는 사용자 지정 형식입니다. + `SSML` - 메시지에 음성 출력용으로 서식이 지정된 텍스트가 포함됩니다. + `Composite` - 메시지에는 의도 생성 시 메시지가 할당된 그룹의 메시지가 하나 이상 포함된 이스케이프된 JSON 개체가 포함되어 있습니다. 타입: 문자열 유효 값: `PlainText | CustomPayload | SSML | Composite` ** [nluIntentConfidence](#API_runtime_PostText_ResponseSyntax) ** Amazon Lex가 반환된 의도가 사용자의 의도와 일치한다고 얼마나 확신하는지 나타내는 점수를 제공합니다. 점수는 0.0\~1.0 사이입니다. 자세한 내용은 [신뢰도 점수](https://docs.aws.amazon.com/lex/latest/dg/confidence-scores.html)를 참조하세요. 점수는 상대 점수이며 절대 점수가 아닙니다. 점수는 Amazon Lex의 개선 사항에 따라 변경될 수 있습니다. 유형: [IntentConfidence](API_runtime_IntentConfidence.md)객체 ** [responseCard](#API_runtime_PostText_ResponseSyntax) ** 사용자가 현재 프롬프트에 응답해야 하는 옵션을 나타냅니다. 응답 카드는 봇 구성 (Amazon Lex 콘솔에서, 슬롯 옆의 설정 버튼 선택) 또는 코드 후크(Lambda 함수)에서 가져올 수 있습니다. 유형: [ResponseCard](API_runtime_ResponseCard.md)객체 ** [sentimentResponse](#API_runtime_PostText_ResponseSyntax) ** 표현된 감정과 표현. 봇이 감정 분석을 위해 Amazon Comprehend로 표현을 보내도록 구성된 경우 이 필드에 분석 결과가 포함됩니다. 유형: [SentimentResponse](API_runtime_SentimentResponse.md)객체 ** [sessionAttributes](#API_runtime_PostText_ResponseSyntax) ** 세션별 컨텍스트 정보를 나타내는 키-값 페어의 맵입니다. 유형: 문자열 간 맵 ** [sessionId](#API_runtime_PostText_ResponseSyntax) ** 세션에 대한 고유 식별자입니다. 유형: 문자열 ** [slots](#API_runtime_PostText_ResponseSyntax) ** Amazon Lex가 대화의 사용자 입력에서 감지한 의도 슬롯. Amazon Lex는 슬롯에 대한 예상 값을 가진 해결 목록을 생성합니다. 반환되는 값은 슬롯 유형이 생성되거나 업데이트될 때 선택된 `valueSelectionStrategy`에 따라 결정됩니다. `valueSelectionStrategy`을 `ORIGINAL_VALUE`로 설정하면 사용자 값이 슬롯 값과 유사한 경우 사용자가 제공한 값이 반환됩니다. `valueSelectionStrategy`가 `TOP_RESOLUTION`로 설정된 경우, Amazon Lex는 해결 목록의 첫 번째 값을 반환하고, 해결 목록이 없는 경우 null을 반환합니다. `valueSelectionStrategy`를 지정하지 않으면 기본값은 `ORIGINAL_VALUE`입니다. 유형: 문자열 간 맵 ** [slotToElicit](#API_runtime_PostText_ResponseSyntax) ** `dialogState` 값이 `ElicitSlot`인 경우 Amazon Lex가 값을 추출하는 슬롯의 이름을 반환합니다. 유형: 문자열 ## 오류 ** BadGatewayException ** Amazon Lex 봇이 아직 구축 중이거나 종속 서비스 중 하나(Amazon Polly, AWS Lambda) 가 내부 서비스 오류로 인해 장애가 발생했습니다. HTTP 상태 코드: 502 ** BadRequestException ** 요청 검증이 실패했거나, 컨텍스트에 사용 가능한 메시지가 없거나, 봇 빌드가 실패했거나, 아직 진행 중이거나, 빌드되지 않은 변경 사항이 포함되어 있습니다. HTTP 상태 코드: 400 ** ConflictException ** 두 클라이언트가 동일한 AWS 계정, Amazon Lex 봇 및 사용자 ID를 사용하고 있습니다. HTTP 상태 코드: 409 ** DependencyFailedException ** AWS Lambda 또는 Amazon Polly와 같은 종속 서비스 중 하나에서 예외가 발생했습니다. 예를 들어, + Amazon Lex에 Lambda 함수를 호출할 수 있는 충분한 권한이 없는 경우. + Lambda 함수를 실행하는 데 30초 이상 걸리는 경우. + 이행 Lambda 함수가 슬롯 값을 제거하지 않고 `Delegate` 대화 작업을 반환하는 경우. HTTP 상태 코드: 424 ** InternalFailureException ** 내부 서비스 오류. 호출을 다시 시도하세요. HTTP 상태 코드: 500 ** LimitExceededException ** 제한 초과함. HTTP 상태 코드: 429 ** LoopDetectedException ** 이 예외는 사용되지 않습니다. HTTP 상태 코드: 508 ** NotFoundException ** 참조된 리소스(예: Amazon Lex 봇 또는 별칭)를 찾을 수 없습니다. HTTP 상태 코드: 404 ## 참고 언어별 AWS SDKs + [AWS 명령줄 인터페이스 V2](https://docs.aws.amazon.com/goto/cli2/runtime.lex-2016-11-28/PostText) + [AWS .NET V4용 SDK](https://docs.aws.amazon.com/goto/DotNetSDKV4/runtime.lex-2016-11-28/PostText) + [AWS SDK for C\+\+](https://docs.aws.amazon.com/goto/SdkForCpp/runtime.lex-2016-11-28/PostText) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/runtime.lex-2016-11-28/PostText) + [AWS Java V2용 SDK](https://docs.aws.amazon.com/goto/SdkForJavaV2/runtime.lex-2016-11-28/PostText) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/runtime.lex-2016-11-28/PostText) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/runtime.lex-2016-11-28/PostText) + [AWS PHP V3용 SDK](https://docs.aws.amazon.com/goto/SdkForPHPV3/runtime.lex-2016-11-28/PostText) + [AWS Python용 SDK](https://docs.aws.amazon.com/goto/boto3/runtime.lex-2016-11-28/PostText) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/runtime.lex-2016-11-28/PostText)