# API Gateway의 데이터 변환을 위한 변수 파라미터 매핑을 만들 때 컨텍스트 변수를 데이터 소스로 사용할 수 있습니다. 매핑 템플릿 변환을 만들 때 [Velocity Template Language(VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html)로 작성하는 스크립트에서 컨텍스트 변수, 입력 및 유틸리티 변수를 사용할 수 있습니다. 이러한 참조 변수를 사용하는 예제 매핑 템플릿을 알아보려면 [API Gateway의 템플릿 변환 매핑에 변수를 사용하는 예제](api-gateway-mapping-variable-examples.md) 섹션을 참조하시기 바랍니다. 액세스 로깅을 위한 참조 변수 목록을 알아보려면 [API Gateway에 대한 액세스 로깅 변수](api-gateway-variables-for-access-logging.md) 섹션을 참조하시기 바랍니다. ## 데이터 변환용 컨텍스트 변수 데이터 변환에 다음 대소문자 구분 `$context` 변수를 사용할 수 있습니다. | 파라미터 | 설명 | | --- | --- | | \$1context.accountId | API 소유자의 AWS 계정 ID입니다. | | \$1context.apiId | 식별자 API Gateway가 API에 할당합니다. | | \$1context.authorizer.claims.property | 메서드 호출자가 성공적으로 인증된 후 Amazon Cognito 사용자 풀에서 반환된 클레임의 속성입니다. 자세한 내용은 [Amazon Cognito 사용자 풀을 권한 부여자로 사용하여 REST API에 대한 액세스 제어](apigateway-integrate-with-cognito.md) 단원을 참조하세요. `$context.authorizer.claims`를 호출하면 null이 반환됩니다. | | \$1context.authorizer.principalId | 클라이언트가 전송한 토큰과 연결되고 API Gateway Lambda 권한 부여자(이전에는 사용자 지정 권한 부여자라고 함)에서 반환한 보안 주체 사용자 식별입니다. 자세한 내용은 [API Gateway Lambda 권한 부여자 사용](apigateway-use-lambda-authorizer.md) 단원을 참조하세요. | | \$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"` 문자열이 반환됩니다. *속성*의 경우 지원되는 특수 문자는 밑줄 `(_)` 문자뿐입니다. 자세한 내용은 [API Gateway Lambda 권한 부여자 사용](apigateway-use-lambda-authorizer.md) 섹션을 참조하세요. | | \$1context.awsEndpointRequestId | AWS 엔드포인트의 요청 ID입니다. | | \$1context.deploymentId | API 배포의 ID입니다. | | \$1context.domainName | API를 호출하는 데 사용되는 정식 도메인 이름입니다. 이 이름은 수신되는 `Host` 헤더와 동일해야 합니다. | | \$1context.domainPrefix | `$context.domainName`의 첫 번째 레이블입니다. | | \$1context.error.message | API Gateway 오류 메시지가 포함된 문자열입니다. 이 변수는 VTL(Velocity Template Language) 엔진 및 액세스 로깅에서 처리하지 않는 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 본문-매핑 템플릿의 간단한 변수 대체에만 사용할 수 있습니다. 자세한 내용은 [CloudWatch 지표로 WebSocket API 실행 모니터링](apigateway-websocket-api-logging.md) 및 [오류 응답을 사용자 지정하도록 게이트웨이 응답 설정](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) 섹션을 참조하세요. | | \$1context.error.messageString | \$1context.error.message의 따옴표 붙은 값, 즉 "\$1context.error.message"입니다. | | \$1context.error.responseType | [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)의 [유형](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType)입니다. 이 변수는 VTL(Velocity Template Language) 엔진 및 액세스 로깅에서 처리하지 않는 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 본문-매핑 템플릿의 간단한 변수 대체에만 사용할 수 있습니다. 자세한 내용은 [CloudWatch 지표로 WebSocket API 실행 모니터링](apigateway-websocket-api-logging.md) 및 [오류 응답을 사용자 지정하도록 게이트웨이 응답 설정](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) 섹션을 참조하세요. | | \$1context.error.validationErrorString | 세부적인 검증 오류 메시지를 포함하는 문자열입니다. | | \$1context.extendedRequestId | API Gateway가 생성하여 API 요청에 할당하는 확장 ID입니다. 확장 요청 ID에는 디버깅 및 문제 해결에 유용한 정보가 포함되어 있습니다. | | \$1context.httpMethod | 사용된 HTTP 메서드입니다. 유효한 값에는 `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` 및 `PUT`이 있습니다. | | \$1context.identity.accountId | 요청과 연결된 AWS 계정 ID입니다. | | \$1context.identity.apiKey | API 키가 필요한 API 메서드의 경우, 이 변수는 메서드 요청과 연결된 API 키입니다. API 키가 필요 없는 메서드의 경우, 이 변수는 null입니다. 자세한 내용은 [API Gateway의 REST API 사용량 계획 및 API 키](api-gateway-api-usage-plans.md) 단원을 참조하세요. | | \$1context.identity.apiKeyId | API 키가 필요한 API 요청과 연결된 API 키 ID입니다. | | \$1context.identity.caller | 요청에 서명한 호출자의 보안 주체 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다. | | \$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.principalOrgId | [AWS 조직 ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html)입니다. | | \$1context.identity.sourceIp | API Gateway 엔드포인트를 요청하는 즉시 TCP 연결의 소스 IP 주소입니다. | | \$1context.identity.clientCert.clientCertPem | 상호 TLS 인증 시 클라이언트가 제공한 PEM 인코딩된 클라이언트 인증서입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. | | \$1context.identity.clientCert.subjectDN | 클라이언트가 제공하는 인증서의 주체가 갖는 고유 이름입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. | | \$1context.identity.clientCert.issuerDN | 클라이언트가 제공하는 인증서의 발행자가 갖는 고유 이름입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. | | \$1context.identity.clientCert.serialNumber | 인증서의 일련 번호입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. | | \$1context.identity.clientCert.validity.notBefore | 인증서의 유효 기간이 시작되는 날짜입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. | | \$1context.identity.clientCert.validity.notAfter | 인증서의 유효 기간이 끝나는 날짜입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. | | \$1context.identity.vpcId | API Gateway 엔드포인트를 요청하는 VPC의 VPC ID입니다. | | \$1context.identity.vpceId | API Gateway 엔드포인트를 요청하는 VPC 엔드포인트의 VPC 엔드포인트 ID입니다. 프라이빗 API가 있는 경우에만 존재합니다. | | \$1context.identity.user | 리소스 액세스에 대해 권한을 부여할 사용자의 보안 주체 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다. | | \$1context.identity.userAgent | API 호출자의 [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 헤더입니다. | | \$1context.identity.userArn | 인증 후 식별된 실제 사용자의 ARN(Amazon Resource Name)입니다. 자세한 내용은 [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) 섹션을 참조하세요. | | \$1context.isCanaryRequest | 요청이 canary로 전달된 경우 `true`, 요청이 canary로 전달되지 않은 경우 `false`를 반환합니다. canary를 활성화한 경우에만 존재합니다. | | \$1context.path | 요청 경로입니다. 예를 들어 https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child의 비 프록시 요청 URL의 경우, \$1context.path 값은 /\$1stage\$1/root/child입니다. | | \$1context.protocol | 요청 프로토콜입니다(예: HTTP/1.1). API Gateway API는 HTTP/2 요청을 수락할 수 있지만 API Gateway는 HTTP/1.1을 사용하여 백엔드 통합에 요청을 보냅니다. 따라서 클라이언트가 HTTP/2를 사용하는 요청을 보내더라도 요청 프로토콜은 HTTP/1.1로 기록됩니다. | | \$1context.requestId | 요청의 ID입니다. 클라이언트는 이 요청 ID를 재정의할 수 있습니다. API Gateway가 생성하는 고유한 요청 ID에 대한 `$context.extendedRequestId`를 사용합니다. | | \$1context.requestOverride.header.header\$1name | 요청 헤더 재정의입니다. 이 파라미터를 정의하면 **통합 요청(Integration Request)** 창에서 정의한 **HTTP 헤더(HTTP Headers)** 대신에 사용할 헤더가 포함됩니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 단원을 참조하세요. | | \$1context.requestOverride.path.path\$1name | 요청 경로 재정의입니다. 이 파라미터를 정의하면 **통합 요청(Integration Request)** 창에서 정의한 **URL 경로 파라미터(URL Path Parameters)** 대신에 사용할 요청 경로가 포함됩니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 단원을 참조하세요. | | \$1context.requestOverride.querystring.querystring\$1name | 요청 쿼리 문자열 재정의입니다. 이 파라미터를 정의하면 **통합 요청(Integration Request)** 창에서 정의한 **URL 쿼리 문자열 파라미터(URL Query String Parameters)** 대신에 사용할 요청 쿼리 문자열이 포함됩니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 단원을 참조하세요. | | \$1context.responseOverride.header.header\$1name | 응답 헤더 재정의입니다. 이 파라미터를 정의하면 통합 요청(Integration Response) 창에서 기본 매핑(Default mapping)으로 정의한 응답 헤더(Response header) 대신에 반환할 헤더가 포함됩니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 단원을 참조하세요. | | \$1context.responseOverride.status | 응답 상태 코드 재정의입니다. 이 파라미터를 정의하면 통합 요청(Integration Response) 창에서 기본 매핑(Default mapping)으로 정의한 메서드 응답 상태(Method response status) 대신에 반환할 상태 코드가 포함됩니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 단원을 참조하세요. | | \$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.resourceId | API Gateway가 리소스에 할당하는 식별자입니다. | | \$1context.resourcePath | 리소스에 대한 경로입니다. 예를 들어 `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`의 비 프록시 요청 URI의 경우, `$context.resourcePath` 값은 `/root/child`입니다. 자세한 내용은 [자습서: HTTP 비 프록시 통합을 통해 REST API 생성](api-gateway-create-api-step-by-step.md) 단원을 참조하세요. | | \$1context.stage | API 요청의 개발 단계입니다(예: `Beta` 또는 `Prod`). | | \$1context.wafResponseCode | [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html)에서 받은 응답: `WAF_ALLOW` 또는 `WAF_BLOCK`. 스테이지가 웹 ACL과 연결되어 있지 않은 경우 설정되지 않습니다. 자세한 내용은 [API Gateway에서 AWS WAF를 사용하여 REST API 보호](apigateway-control-access-aws-waf.md) 단원을 참조하세요. | | \$1context.webaclArn | 요청을 허용할지 차단할지 결정하는 데 사용되는 웹 ACL의 전체 ARN입니다. 스테이지가 웹 ACL과 연결되어 있지 않은 경우 설정되지 않습니다. 자세한 내용은 [API Gateway에서 AWS WAF를 사용하여 REST API 보호](apigateway-control-access-aws-waf.md) 섹션을 참조하세요. | ## 입력 변수 다음 대소문자 구분 `$input` 변수를 사용하여 메서드 요청 페이로드 및 메서드 요청 파라미터를 참조할 수 있습니다. 다음과 같은 기능을 사용할 수 있습니다. | 변수 및 함수 | 설명 | | --- | --- | | \$1input.body | 원시 요청 페이로드를 문자열로 반환합니다. `$input.body`를 사용하여 전체 부동 소수점 숫자를 보존할 수 있습니다(예: `10.00`). | | \$1input.json(x) | 이 함수는 JSONPath 표현식을 평가하고 결과를 JSON 문자열로 반환합니다. 예를 들어, `$input.json('$.pets')`은 `pets` 구조를 나타내는 JSON 문자열을 반환합니다. JSONPath에 대한 자세한 내용은 [JSONPath](https://goessner.net/articles/JsonPath/) 또는 [Java용 JSONPath](https://github.com/json-path/JsonPath)를 참조하세요. | | \$1input.params() | 모든 요청 파라미터의 맵을 반환합니다. 잠재적인 주입 공격을 방지하기 위해 `$util.escapeJavaScript`을(를) 사용하여 결과를 삭제하는 것이 좋습니다. 요청 삭제를 완벽하게 제어하려면 템플릿 없이 프록시 통합을 사용하고 통합에서 요청 삭제를 처리합니다. | | \$1input.params(x) | 파라미터 이름 문자열 `x`가 지정된 경로, 쿼리 문자열 또는 헤더 값(순서대로 검색됨)에서 메서드 요청 파라미터 값을 반환합니다. 잠재적인 주입 공격을 방지하기 위해 `$util.escapeJavaScript`을(를) 사용하여 파라미터를 삭제하는 것이 좋습니다. 파라미터 삭제를 완벽하게 제어하려면 템플릿 없이 프록시 통합을 사용하고 통합에서 요청 삭제를 처리합니다. | | \$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').size()`는 을 반환합니다.`"3"` JSONPath에 대한 자세한 내용은 [JSONPath](https://goessner.net/articles/JsonPath/) 또는 [Java용 JSONPath](https://github.com/json-path/JsonPath)를 참조하세요. | ## 단계 변수 메서드 통합에서 다음 단계 변수를 ARN 및 URL의 자리 표시자로 사용할 수 있습니다. 자세한 내용은 [API Gateway에서 REST API용 스테이지 변수 사용](stage-variables.md) 섹션을 참조하세요. | 구문 | 설명 | | --- | --- | | \$1stageVariables.variable\$1name,\$1stageVariables['variable\$1name'] 또는 \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name*은 단계 변수 이름을 나타냅니다. | ## 유틸리티 변수 다음 대소문자 구분 `$util` 변수를 사용하여 매핑 탬플릿용 유틸리티 함수를 사용할 수 있습니다. 달리 지정하지 않는 한, 기본 문자 집합은 UTF-8입니다. | 함수 | 설명 | | --- | --- | | \$1util.escapeJavaScript() | JavaScript 문자열 규칙을 사용하여 문자열의 문자를 이스케이프합니다. 이 함수는 일반 작은따옴표(`'`)를 이스케이프된 작은따옴표(`\'`)로 변환합니다. 그러나 이스케이프된 작은따옴표는 JSON에서 유효하지 않습니다. 따라서 이 함수의 결과를 JSON 속성에서 사용할 경우 이스케이프된 작은따옴표(`\'`)를 다시 일반 작은따옴표(`'`)로 변환해야 합니다. 방법은 다음 예제와 같습니다: 
 "input" : "$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 인코딩 문자열에서 디코딩합니다. |