# API Gateway에서 WebSocket API의 데이터 변환 API Gateway에서 WebSocket API 메서드 요청은 백엔드의 요구에 따라 해당하는 통합 요청 페이로드에서 여러 유형의 페이로드를 취할 수 있습니다. 마찬가지로 백엔드에서는 프런트 엔드에서 기대하는 메서드 응답 페이로드가 아니라 통합 응답 페이로드를 반환할 수 있습니다. API Gateway에서는 매핑 템플릿 변환을 사용하여 메서드 요청에서 해당 통합 요청으로, 통합 응답에서 해당 메서드 응답으로 페이로드를 매핑할 수 있습니다. 매핑 템플릿을 만들고 템플릿 선택 표현식을 지정하여 필요한 데이터 변환을 수행하는 데 사용할 템플릿을 결정합니다. 데이터 매핑을 사용하면 [라우팅 요청](api-gateway-basic-concept.md#apigateway-definition-route-request)의 데이터를 백엔드 통합에 매핑할 수 있습니다. 자세한 내용은 [API Gateway에서 WebSocket API에 대한 데이터 매핑 설정](websocket-api-data-mapping.md) 단원을 참조하십시오. ## 매핑 템플릿 및 모델 *매핑 템플릿*이란 [VTL(Velocity Template Language)](https://velocity.apache.org/engine/devel/vtl-reference.html)로 표현된 스크립트로, [JSONPath 표현식](https://goessner.net/articles/JsonPath/)을 사용하여 페이로드에 적용됩니다. API Gateway 매핑 템플릿에 대한 자세한 내용은 [API Gateway에서 REST API의 데이터 변환 매핑](models-mappings.md) 단원을 참조하세요. 페이로드는 [JSON 스키마 draft 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04)에 따라 *데이터 모델*을 가질 수 있습니다. 매핑 템플릿을 생성하기 위해 모델을 정의할 필요는 없습니다. 그러나 API Gateway에서는 제공된 모델에 따라 템플릿 블루프린트를 생성하기 때문에 모델이 있으면 템플릿을 생성하는 데 도움이 됩니다. API Gateway 모델에 대한 자세한 내용은 [REST API에 대한 데이터 모델](models-mappings-models.md) 단원을 참조하세요. ## 템플릿 선택 표현식 매핑 템플릿을 사용하여 페이로드를 변환하려면 [통합 요청](apigateway-websocket-api-integration-requests.md) 또는 [통합 응답](apigateway-websocket-api-integration-responses.md)에서 WebSocket API 템플릿 선택 표현식을 지정합니다. 이 표현식은 요청 본문을 (입력 템플릿을 통해) 요청 본문으로 변환하거나 통합 응답 본문을 (출력 템플릿을 통해) 라우팅 응답 본문으로 변환하는 데 사용할 입력 또는 출력 템플릿(있는 경우)를 판별하기 위해 평가됩니다. `Integration.TemplateSelectionExpression`은 `${request.body.jsonPath}`와 정적 값을 지원합니다. `IntegrationResponse.TemplateSelectionExpression`은 `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}` 및 정적 값을 지원합니다. ## 통합 응답 선택 표현식 WebSocket API에 대해 [통합 응답을 설정](apigateway-websocket-api-integration-responses.md)할 때 선택적으로 통합 응답 선택 표현식을 지정할 수 있습니다. 이 표현식은 통합이 반환될 때 어떤 `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)`가 선택되어야 하는지 결정합니다. 이 표현식의 값은 현재 아래에 정의된 대로 API 게이트웨이에 의해 제한됩니다. 이 표현식은 *비 프록시 통합*에만 해당한다는 점에 유의하십시오. 프록시 통합은 모델링이나 수정 없이 단순히 응답 페이로드를 호출자에게 다시 전달하기만 합니다. 이전의 다른 선택 표현식과 달리 이 표현식은 현재 *패턴 일치* 형식을 지원합니다. 표현식은 슬래시로 래핑해야 합니다. 현재 이 값은 `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)`에 따라 고정됩니다. + Lambda 기반 통합의 경우 `$integration.response.body.errorMessage`입니다. + `HTTP` 및 `MOCK` 통합의 경우 `$integration.response.statuscode`입니다. + `HTTP_PROXY` 및 `AWS_PROXY`의 경우 페이로드가 호출자에게 패스스루 되도록 요청하기 때문에 표현식이 사용되지 않습니다. # API Gateway에서 WebSocket API에 대한 데이터 매핑 설정 *데이터 매핑*을 사용하면 [라우팅 요청](api-gateway-basic-concept.md#apigateway-definition-route-request)의 데이터를 백엔드 통합에 매핑할 수 있습니다. **참고** 웹 소켓 API에 대한 데이터 매핑은 에서 지원되지 않습니다AWS Management Console 데이터 매핑을 구성하려면 AWS CLI, AWS CloudFormation 또는 SDK를 사용해야 합니다. **Topics** + [통합 요청 파라미터에 라우팅 요청 데이터 매핑](#websocket-mapping-request-parameters) + [예시](#websocket-data-mapping-examples) ## 통합 요청 파라미터에 라우팅 요청 데이터 매핑 통합 요청 파라미터는 정의된 라우팅 요청 파라미터, 요청 본문, [`context` 또는 ](api-gateway-mapping-template-reference.md#context-variable-reference) [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) 변수 및 정적 값에서 매핑될 수 있습니다. 다음 표에는 통합 요청 데이터 매핑 표현식이 나와 있습니다. 이 표에서 *`PARAM_NAME`*은 지정된 파라미터 유형의 라우팅 요청 파라미터 이름입니다. 정규식 `'^[a-zA-Z0-9._$-]+$]'`와 일치해야 합니다. *JSONPath\$1EXPRESSION*은 요청 본문의 JSON 필드에 대한 JSONPath 표현식입니다. | 매핑된 데이터 소스 | 매핑 표현식 | | --- | --- | | 요청 쿼리 문자열(\$1connect 라우팅의 경우에만 지원) | route.request.querystring.PARAM\$1NAME | | 요청 헤더(\$1connect 라우팅의 경우에만 지원) | route.request.header.PARAM\$1NAME | | 다중 값 요청 쿼리 문자열(\$1connect 라우팅의 경우에만 지원) | route.request.multivaluequerystring.PARAM\$1NAME | | 다중 값 요청 헤더(\$1connect 라우팅의 경우에만 지원) | route.request.multivalueheader.PARAM\$1NAME | | 요청 본문 | route.request.body.JSONPath\$1EXPRESSION | | 단계 변수 | stageVariables.VARIABLE\$1NAME | | 컨텍스트 변수 | context.VARIABLE\$1NAME은 [지원되는 컨텍스트 변수](api-gateway-mapping-template-reference.md#context-variable-reference) 중 하나여야 합니다. | | 정적 값 | 'STATIC\$1VALUE'. STATIC\$1VALUE는 문자열 리터럴이며 작은따옴표로 묶여야 합니다. | AWS CLI로 데이터 매핑을 생성할 때 AWS CLI에서 문자열 리터럴을 사용하는 올바른 형식을 따라야 합니다. 자세한 내용은 *AWS Command Line Interface 사용 설명서*의 [AWS CLI에서 문자열에 따옴표 및 리터럴 사용](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html)을 참조하세요. ## 예시 다음 AWS CLI 예제에서는 데이터 매핑을 구성합니다. CloudFormation 템플릿 예시를 보려면 [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip) 단원을 참조하세요. ### 통합 요청의 헤더에 클라이언트의 connectionId 매핑 다음 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) 명령은 백엔드 통합에 대한 요청의 `connectionId` 헤더에 클라이언트의 `connectionId`를 매핑합니다. ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.connectionId'='context.connectionId' ``` ### 통합 요청의 헤더에 쿼리 문자열 파라미터 매핑 다음 예제 명령은 통합 요청의 `authToken` 헤더에 `authToken` 쿼리 문자열 파라미터를 매핑합니다. 1. 다음 [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) 명령을 사용하여 `authToken` 쿼리 문자열 파라미터를 경로의 요청 파라미터에 추가합니다. ``` aws apigatewayv2 update-route --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameters '{"route.request.querystring.authToken": {"Required": false}}' ``` 1. 다음 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) 명령을 사용하여 쿼리 문자열 파라미터를 백엔드 통합 요청의 `authToken` 헤더에 매핑합니다. ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken' ``` 1. (선택 사항) 필요한 경우 다음 [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html)를 사용하여 경로의 요청 파라미터에서 `authToken` 쿼리 문자열 파라미터를 삭제합니다. ``` aws apigatewayv2 delete-route-request-parameter \ --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameter-key 'route.request.querystring.authToken' ``` # API Gateway용 WebSocket API 매핑 템플릿 참조 이 섹션에서는 현재 API Gateway에서 WebSocket API에 대해 지원되는 변수 집합을 요약합니다. | 파라미터 | 설명 | | --- | --- | | \$1context.connectionId | 클라이언트에 대한 콜백을 만드는 데 사용할 수 있는 고유한 연결 ID입니다. | | \$1context.connectedAt | [Epoch](https://en.wikipedia.org/wiki/Unix_time) 형식 연결 시간입니다. | | \$1context.domainName | WebSocket API의 도메인 이름입니다. 하드 코딩된 값 대신 클라이언트에 콜백하는 데 사용할 수 있습니다. | | \$1context.eventType | 이벤트 유형: `CONNECT`, `MESSAGE` 또는 `DISCONNECT`. | | \$1context.messageId | 메시지의 고유 서버 측 ID. `$context.eventType`이 `MESSAGE`인 경우에만 사용 가능합니다. | | \$1context.routeKey | 선택한 라우팅 키. | | \$1context.requestId | `$context.extendedRequestId`와 동일합니다. | | \$1context.extendedRequestId | API 호출에 대해 자동으로 생성된 ID로 디버깅/문제 해결에 유용한 정보가 포함합니다. | | \$1context.apiId | 식별자 API Gateway가 API에 할당합니다. | | \$1context.authorizer.principalId | 클라이언트가 전송한 토큰과 연결되고 API Gateway Lambda 권한 부여자(이전에는 사용자 지정 권한 부여자라고 함) Lambda 함수에서 반환한 보안 주체 사용자 식별입니다. | | \$1context.authorizer.property | API Gateway Lambda 권한 부여자 함수에서 반환된 `context` 맵의 지정된 키-값 페어의 문자열화된 값입니다. 예를 들어, 권한 부여자는 다음 `context` 맵을 반환합니다. 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
`$context.authorizer.key`를 호출하면 `"value"` 문자열이 반환되고, `$context.authorizer.numKey`를 호출하면 `"1"` 문자열이 반환되고, `$context.authorizer.boolKey`를 호출하면 `"true"` 문자열이 반환됩니다. | | \$1context.error.messageString | \$1context.error.message의 따옴표 붙은 값, 즉 "\$1context.error.message"입니다. | | \$1context.error.validationErrorString | 세부적인 검증 오류 메시지를 포함하는 문자열입니다. | | \$1context.identity.accountId | 요청과 연결된 AWS 계정 ID입니다. | | \$1context.identity.apiKey | 키가 활성화된 API 요청에 연결된 API 소유자 키입니다. | | \$1context.identity.apiKeyId | 키가 활성화된 API 요청에 연결된 API 키 ID입니다. | | \$1context.identity.caller | 요청을 작성한 호출자의 보안 주체 ID입니다. | | \$1context.identity.cognitoAuthenticationProvider | 요청을 작성한 직접 호출자가 사용한 모든 Amazon Cognito 인증 공급자의 쉼표로 구분된 목록입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. 예를 들어, Amazon Cognito 사용자 풀의 자격 증명의 경우 `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` 사용 가능한 Amazon Cognito 인증 공급자에 대한 자세한 내용은 Amazon Cognito 개발자 안내서**의 [페더레이션 자격 증명 사용](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)을 참조하세요. | | \$1context.identity.cognitoAuthenticationType | 요청을 작성한 호출자의 Amazon Cognito 인증 유형입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. 가능한 값에는 인증 자격 증명에 대한 `authenticated` 및 미인증 자격 증명에 대한 `unauthenticated`이(가) 포함됩니다. | | \$1context.identity.cognitoIdentityId | 요청을 작성한 호출자의 Amazon Cognito 자격 증명 ID입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. | | \$1context.identity.cognitoIdentityPoolId | 요청을 작성한 호출자의 Amazon Cognito 자격 증명 풀 ID입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. | | \$1context.identity.sourceIp | API Gateway 엔드포인트를 요청하는 즉시 TCP 연결의 소스 IP 주소입니다. | | \$1context.identity.user | 요청을 작성한 사용자의 보안 주체 ID입니다. | | \$1context.identity.userAgent | API 호출자의 사용자 에이전트입니다. | | \$1context.identity.userArn | 인증 후 식별된 실제 사용자의 ARN(Amazon Resource Name)입니다. | | \$1context.requestTime | [CLF](https://httpd.apache.org/docs/current/logs.html#common) 형식 요청 시간(dd/MMM/yyyy:HH:mm:ss \$1-hhmm)입니다. | | \$1context.requestTimeEpoch | [Epoch](https://en.wikipedia.org/wiki/Unix_time) 형식 요청 시간(밀리초)입니다. | | \$1context.stage | API 호출의 개발 단계입니다(예: 베타 또는 프로덕션). | | \$1context.status | 응답 상태입니다. | | \$1input.body | 원시 페이로드를 문자열로 반환합니다. | | \$1input.json(x) | 이 함수는 JSONPath 표현식을 평가하고 결과를 JSON 문자열로 반환합니다. 예를 들어, `$input.json('$.pets')`은 반려 동물 구조를 나타내는 JSON 문자열을 반환합니다. JSONPath에 대한 자세한 내용은 [JSONPath](https://goessner.net/articles/JsonPath/) 또는 [Java용 JSONPath](https://github.com/json-path/JsonPath)를 참조하십시오. | | \$1input.path(x) | JSONPath 표현식 문자열 (`x`)을 가져와서 결과의 JSON 객체로 반환합니다. 이를 통해 기본적으로 [Apache Velocity Template Language(VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html)에서 페이로드 요소에 액세스하고 조작할 수 있습니다. 예를 들어, `$input.path('$.pets')` 표현식이 다음과 같은 객체를 반환할 경우: 
[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]
`$input.path('$.pets').count()`는 `"3"`을 반환합니다. JSONPath에 대한 자세한 내용은 [JSONPath](http://goessner.net/articles/JsonPath/) 또는 [Java용 JSONPath](https://github.com/jayway/JsonPath)를 참조하십시오. | | \$1stageVariables. | **은 단계 변수 이름을 나타냅니다. | | \$1stageVariables[''] | **은 모든 단계 변수 이름을 나타냅니다. | | \$1\$1stageVariables['']\$1 | **은 모든 단계 변수 이름을 나타냅니다. | | \$1util.escapeJavaScript() | JavaScript 문자열 규칙을 사용하여 문자열의 문자를 이스케이프합니다. 이 함수는 일반 작은따옴표(`'`)를 이스케이프된 작은따옴표(`\'`)로 변환합니다. 그러나 이스케이프된 작은따옴표는 JSON에서 유효하지 않습니다. 따라서 이 함수의 결과를 JSON 속성에서 사용할 경우 이스케이프된 작은따옴표(`\'`)를 다시 일반 작은따옴표(`'`)로 변환해야 합니다. 방법은 다음 예제와 같습니다: 
 $util.escapeJavaScript(data).replaceAll("\\'","'")
| | \$1util.parseJson() | "문자열화된" JSON을 가져와서 결과의 객체 표현을 반환합니다. 이 함수의 결과를 사용하여 기본적으로 Apache VTL(Velocity Template Language)에서 페이로드 요소에 액세스하고 조작할 수 있습니다. 예를 들어 다음과 같은 페이로드가 있고 
{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}
다음 매핑 템플릿을 사용하는 경우 
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
출력은 다음과 같습니다. 
{
   "errorMessageObjKey2ArrVal" : 1
}
| | \$1util.urlEncode() | 문자열을 "application/x-www-form-urlencoded" 형식으로 변환합니다. | | \$1util.urlDecode() | "application/x-www-form-urlencoded" 문자열을 디코딩합니다. | | \$1util.base64Encode() | 데이터를 base64 인코딩 문자열로 인코딩합니다. | | \$1util.base64Decode() | 데이터를 base64 인코딩 문자열에서 디코딩합니다. |