API Gateway 매핑 템플릿과 액세스 로깅 변수 참조 - Amazon API Gateway
데이터 모델, 권한 부여자, 매핑 템플릿, CloudWatch 액세스 로깅을 위한 $context 변수$context 변수 템플릿 예제액세스 로깅 전용의 $context 변수$input 변수$input 변수 템플릿 예제$stageVariables$util 변수

API Gateway 매핑 템플릿과 액세스 로깅 변수 참조

이 단원에서는 Amazon API Gateway가 데이터 모델, 권한 부여자, 매핑 템플릿, CloudWatch 액세스 로깅에 사용하기 위해 정의하는 변수 및 함수에 대한 참조 정보를 제공합니다. 이러한 변수와 함수의 자세한 사용 방법은 모델 및 매핑 템플릿 작업 단원을 참조하십시오.

참고

$method 변수와 $integration 변수의 경우 Amazon API Gateway API 요청 및 응답 데이터 매핑 참조 단원을 참조하십시오.

데이터 모델, 권한 부여자, 매핑 템플릿, CloudWatch 액세스 로깅을 위한 $context 변수

다음 $context 변수는 데이터 모델, 권한 부여자, 매핑 템플릿, CloudWatch 액세스 로깅에 사용할 수 있습니다.

CloudWatch 액세스 로깅에만 사용할 수 있는 $context 변수는 액세스 로깅 전용의 $context 변수 단원을 참조하세요.

파라미터 설명
$context.accountId

API 소유자의 AWS 계정 ID입니다.
$context.apiId

식별자 API Gateway가 API에 할당합니다.
$context.authorizer.claims.property

메서드 호출자가 성공적으로 인증된 후 Amazon Cognito 사용자 풀에서 반환된 클레임의 속성입니다. 자세한 내용은 Amazon Cognito 사용자 풀을 권한 부여자로 사용하여 REST API에 대한 액세스 제어 섹션을 참조하세요.

참고

$context.authorizer.claims를 호출하면 null이 반환됩니다.
$context.authorizer.principalId

클라이언트가 전송한 토큰과 연결되고 API Gateway Lambda 권한 부여자(이전에는 사용자 지정 권한 부여자라고 함)에서 반환한 보안 주체 사용자 식별입니다. 자세한 내용은 API Gateway Lambda 권한 부여자 사용 섹션을 참조하세요.
$context.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 권한 부여자 사용 섹션을 참조하세요.
$context.awsEndpointRequestId

AWS 엔드포인트의 요청 ID입니다.
$context.domainName

API를 호출하는 데 사용되는 정식 도메인 이름입니다. 이 이름은 수신되는 Host 헤더와 동일해야 합니다.
$context.domainPrefix

$context.domainName의 첫 번째 레이블입니다.
$context.error.message

API Gateway 오류 메시지가 포함된 문자열입니다. 이 변수는 VTL(Velocity Template Language) 엔진 및 액세스 로깅에서 처리하지 않는 GatewayResponse 본문-매핑 템플릿의 간단한 변수 대체에만 사용할 수 있습니다. 자세한 내용은 CloudWatch 지표로 WebSocket API 실행 모니터링 및 오류 응답을 사용자 지정하도록 게이트웨이 응답 설정 섹션을 참조하세요.
$context.error.messageString $context.error.message의 따옴표 붙은 값, 즉 "$context.error.message"입니다.
$context.error.responseType

GatewayResponse의 유형입니다. 이 변수는 VTL(Velocity Template Language) 엔진 및 액세스 로깅에서 처리하지 않는 GatewayResponse 본문-매핑 템플릿의 간단한 변수 대체에만 사용할 수 있습니다. 자세한 내용은 CloudWatch 지표로 WebSocket API 실행 모니터링 및 오류 응답을 사용자 지정하도록 게이트웨이 응답 설정 섹션을 참조하세요.
$context.error.validationErrorString

세부적인 검증 오류 메시지를 포함하는 문자열입니다.
$context.extendedRequestId API Gateway가 생성하여 API 요청에 할당하는 확장 ID입니다. 확장 요청 ID에는 디버깅 및 문제 해결에 유용한 정보가 포함되어 있습니다.
$context.httpMethod

사용된 HTTP 메서드입니다. 유효한 값에는 DELETE, GET, HEAD, OPTIONS, PATCH, POST 및 PUT이 있습니다.
$context.identity.accountId

요청과 연결된 AWS 계정 ID입니다.
$context.identity.apiKey

API 키가 필요한 API 메서드의 경우, 이 변수는 메서드 요청과 연결된 API 키입니다. API 키가 필요 없는 메서드의 경우, 이 변수는 null입니다. 자세한 내용은 API 키를 사용하여 사용량 계획 생성 및 사용 섹션을 참조하세요.
$context.identity.apiKeyId API 키가 필요한 API 요청과 연결된 API 키 ID입니다.
$context.identity.caller

요청에 서명한 호출자의 보안 주체 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다.
$context.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 개발자 안내서의 연동 자격 증명 사용을 참조하세요.
$context.identity.cognitoAuthenticationType

요청을 작성한 호출자의 Amazon Cognito 인증 유형입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. 가능한 값에는 인증 자격 증명에 대한 authenticated 및 미인증 자격 증명에 대한 unauthenticated이(가) 포함됩니다.
$context.identity.cognitoIdentityId

요청을 작성한 호출자의 Amazon Cognito 자격 증명 ID입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다.
$context.identity.cognitoIdentityPoolId

요청을 작성한 호출자의 Amazon Cognito 자격 증명 풀 ID입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다.
$context.identity.principalOrgId

AWS 조직 ID입니다.
$context.identity.sourceIp

API Gateway 엔드포인트를 요청하는 즉시 TCP 연결의 소스 IP 주소입니다.
$context.identity.clientCert.clientCertPem

상호 TLS 인증 시 클라이언트가 제공한 PEM 인코딩된 클라이언트 인증서입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다.
$context.identity.clientCert.subjectDN

클라이언트가 제공하는 인증서의 주체가 갖는 고유 이름입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다.
$context.identity.clientCert.issuerDN

클라이언트가 제공하는 인증서의 발행자가 갖는 고유 이름입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다.
$context.identity.clientCert.serialNumber

인증서의 일련 번호입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다.
$context.identity.clientCert.validity.notBefore

인증서의 유효 기간이 시작되는 날짜입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다.
$context.identity.clientCert.validity.notAfter

인증서의 유효 기간이 끝나는 날짜입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다.
$context.identity.user

리소스 액세스에 대해 권한을 부여할 사용자의 보안 주체 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다.
$context.identity.userAgent

API 호출자의 User-Agent 헤더입니다.
$context.identity.userArn

인증 후 식별된 실제 사용자의 ARN(Amazon Resource Name)입니다. 자세한 내용은 https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html 섹션을 참조하세요.
$context.path 요청 경로입니다. 예를 들어 https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child의 비 프록시 요청 URL의 경우, $context.path 값은 /{stage}/root/child입니다.
$context.protocol 요청 프로토콜입니다(예: HTTP/1.1).
참고

API Gateway API는 HTTP/2 요청을 수락할 수 있지만 API Gateway는 HTTP/1.1을 사용하여 백엔드 통합에 요청을 보냅니다. 따라서 클라이언트가 HTTP/2를 사용하는 요청을 보내더라도 요청 프로토콜은 HTTP/1.1로 기록됩니다.
$context.requestId

요청의 ID입니다. 클라이언트는 이 요청 ID를 재정의할 수 있습니다. API Gateway가 생성하는 고유한 요청 ID에 대한 $context.extendedRequestId를 사용합니다.
$context.requestOverride.header.header_name

요청 헤더 재정의입니다. 이 파라미터를 정의하면 통합 요청(Integration Request) 창에서 정의한 HTTP 헤더(HTTP Headers) 대신에 사용할 헤더가 포함됩니다. 자세한 내용은 매핑 템플릿을 사용한 API의 요청 및 응답 파라미터와 상태 코드 재정의 섹션을 참조하세요.
$context.requestOverride.path.path_name

요청 경로 재정의입니다. 이 파라미터를 정의하면 통합 요청(Integration Request) 창에서 정의한 URL 경로 파라미터(URL Path Parameters) 대신에 사용할 요청 경로가 포함됩니다. 자세한 내용은 매핑 템플릿을 사용한 API의 요청 및 응답 파라미터와 상태 코드 재정의 섹션을 참조하세요.
$context.requestOverride.querystring.querystring_name

요청 쿼리 문자열 재정의입니다. 이 파라미터를 정의하면 통합 요청(Integration Request) 창에서 정의한 URL 쿼리 문자열 파라미터(URL Query String Parameters) 대신에 사용할 요청 쿼리 문자열이 포함됩니다. 자세한 내용은 매핑 템플릿을 사용한 API의 요청 및 응답 파라미터와 상태 코드 재정의 섹션을 참조하세요.
$context.responseOverride.header.header_name 응답 헤더 재정의입니다. 이 파라미터를 정의하면 통합 요청(Integration Response) 창에서 기본 매핑(Default mapping)으로 정의한 응답 헤더(Response header) 대신에 반환할 헤더가 포함됩니다. 자세한 내용은 매핑 템플릿을 사용한 API의 요청 및 응답 파라미터와 상태 코드 재정의 섹션을 참조하세요.
$context.responseOverride.status 응답 상태 코드 재정의입니다. 이 파라미터를 정의하면 통합 요청(Integration Response) 창에서 기본 매핑(Default mapping)으로 정의한 메서드 응답 상태(Method response status) 대신에 반환할 상태 코드가 포함됩니다. 자세한 내용은 매핑 템플릿을 사용한 API의 요청 및 응답 파라미터와 상태 코드 재정의 섹션을 참조하세요.
$context.requestTime CLF 형식 요청 시간(dd/MMM/yyyy:HH:mm:ss +-hhmm)입니다.
$context.requestTimeEpoch Epoch 형식 요청 시간(밀리초)입니다.
$context.resourceId

API Gateway가 리소스에 할당하는 식별자입니다.
$context.resourcePath

리소스에 대한 경로입니다. 예를 들어 https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child의 비 프록시 요청 URI의 경우, $context.resourcePath 값은 /root/child입니다. 자세한 내용은 자습서: HTTP 비 프록시 통합을 사용하여 REST API 빌드 섹션을 참조하세요.
$context.stage

API 요청의 개발 단계입니다(예: Beta 또는 Prod).
$context.wafResponseCode

AWS WAF에서 받은 응답: WAF_ALLOW 또는 WAF_BLOCK. 스테이지가 웹 ACL과 연결되어 있지 않은 경우 설정되지 않습니다. 자세한 내용은 AWS WAF을 사용하여 API 보호 섹션을 참조하세요.
$context.webaclArn

요청을 허용할지 차단할지 결정하는 데 사용되는 웹 ACL의 전체 ARN입니다. 스테이지가 웹 ACL과 연결되어 있지 않은 경우 설정되지 않습니다. 자세한 내용은 AWS WAF을 사용하여 API 보호 섹션을 참조하세요.

$context 변수 템플릿 예제

API 메서드가 특정 형식의 데이터를 요구하는 백엔드로 구조화된 데이터를 전달하는 경우 매핑 템플릿에 $context 변수를 사용할 수 있습니다.

다음 예제는 받은 $context 변수를, 통합 요청 페이로드에서 약간 다른 이름을 가진 백엔드 변수에 매핑하는 매핑 템플릿을 보여 줍니다.

참고

이러한 변수 중 하나가 API 키입니다. 이 예제는 메서드에서 "API 키 요구"가 활성화되었음을 전제로 합니다.

{
    "stage" : "$context.stage",
    "request_id" : "$context.requestId",
    "api_id" : "$context.apiId",
    "resource_path" : "$context.resourcePath",
    "resource_id" : "$context.resourceId",
    "http_method" : "$context.httpMethod",
    "source_ip" : "$context.identity.sourceIp",
    "user-agent" : "$context.identity.userAgent",
    "account_id" : "$context.identity.accountId",
    "api_key" : "$context.identity.apiKey",
    "caller" : "$context.identity.caller",
    "user" : "$context.identity.user",
    "user_arn" : "$context.identity.userArn"
}

액세스 로깅 전용의 $context 변수

다음 $context 변수는 액세스 로깅에만 사용할 수 있습니다. 자세한 내용은 API Gateway에서 REST API에 대한 CloudWatch 로깅 설정 섹션을 참조하세요. (WebSocket API의 경우 CloudWatch 지표로 WebSocket API 실행 모니터링 단원을 참조하십시오.)

파라미터 설명
$context.authorize.error 권한 부여 오류 메시지입니다.
$context.authorize.latency 권한 부여 지연 시간(ms)입니다.
$context.authorize.status 권한 부여 시도에서 반환된 상태 코드입니다.
$context.authorizer.error 권한 부여자로부터 반환된 오류 메시지입니다.
$context.authorizer.integrationLatency 권한 부여자 지연 시간(ms)입니다.
$context.authorizer.integrationStatus Lambda 권한 부여자로부터 반환된 상태 코드입니다.
$context.authorizer.latency 권한 부여자 지연 시간(ms)입니다.
$context.authorizer.requestId AWS 엔드포인트의 요청 ID입니다.
$context.authorizer.status 권한 부여자로부터 반환된 상태 코드입니다.
$context.authenticate.error 인증 시도에서 반환된 오류 메시지입니다.
$context.authenticate.latency 인증 지연 시간(ms)입니다.
$context.authenticate.status 인증 시도에서 반환된 상태 코드입니다.
$context.customDomain.basePathMatched

들어오는 요청이 일치하는 API 매핑의 경로입니다. 클라이언트가 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 적용할 수 있습니다. 예를 들어 클라이언트가 https://api.example.com/v1/orders/1234에 요청을 보내고 요청이 API 매핑을 경로 v1/orders와(과) 일치시키는 경우 값은 v1/orders입니다. 자세한 내용은 REST API에 대한 API 매핑 작업 단원을 참조하십시오.
$context.integration.error 통합에서 반환된 오류 메시지입니다. $context.integrationErrorMessage와 동일합니다.
$context.integration.integrationStatus Lambda 프록시 통합의 경우 백엔드 Lambda 함수 코드가 아니라 AWS Lambda에서 반환된 상태 코드입니다.
$context.integration.latency 통합 지연 시간(ms)입니다. $context.integrationLatency와 동일합니다.
$context.integration.requestId AWS 엔드포인트의 요청 ID입니다. $context.awsEndpointRequestId와 동일합니다.
$context.integration.status 통합에서 반환된 상태 코드입니다. Lambda 프록시 통합의 경우 Lambda 함수 코드에서 반환된 상태 코드입니다.
$context.integrationErrorMessage

통합 오류 메시지가 포함된 문자열입니다.
$context.integrationLatency 통합 지연 시간(ms)입니다.
$context.integrationStatus Lambda 프록시 통합의 경우 이 파라미터는 백엔드 Lambda 함수 코드가 아니라 AWS Lambda에서 반환된 상태 코드를 나타냅니다.
$context.responseLatency 응답 지연 시간(ms)입니다.
$context.responseLength 바이트로 된 응답 페이로드 길이입니다.
$context.status 메서드 응답 상태입니다.
$context.waf.error AWS WAF에서 반환된 오류 메시지입니다.
$context.waf.latency AWS WAF 지연 시간(ms)입니다.
$context.waf.status AWS WAF에서 반환된 상태 코드입니다.
$context.xrayTraceId

X-Ray 추적의 추적 ID입니다. 자세한 내용은 API Gateway REST API를 사용하여 AWS X-Ray 설정 섹션을 참조하세요.

$input 변수

$input 변수는 매핑 템플릿에서 처리할 메서드 요청 페이로드와 파라미터를 나타냅니다. 이 변수는 네 가지 함수를 제공합니다.

변수 및 함수 설명
$input.body

원시 요청 페이로드를 문자열로 반환합니다.
$input.json(x)

이 함수는 JSONPath 표현식을 평가하고 결과를 JSON 문자열로 반환합니다.

예를 들어, $input.json('$.pets')은 pets 구조를 나타내는 JSON 문자열을 반환합니다.

JSONPath에 대한 자세한 내용은 JSONPath 또는 Java용 JSONPath를 참조하십시오.
$input.params()

모든 요청 파라미터의 맵을 반환합니다. 잠재적인 주입 공격을 방지하기 위해 $util.escapeJavaScript을(를) 사용하여 결과를 삭제하는 것이 좋습니다. 요청 삭제를 완벽하게 제어하려면 템플릿 없이 프록시 통합을 사용하고 통합에서 요청 삭제를 처리합니다.
$input.params(x)

파라미터 이름 문자열 x가 지정된 경로, 쿼리 문자열 또는 헤더 값(순서대로 검색됨)에서 메서드 요청 파라미터 값을 반환합니다. 잠재적인 주입 공격을 방지하기 위해 $util.escapeJavaScript을(를) 사용하여 파라미터를 삭제하는 것이 좋습니다. 파라미터 삭제를 완벽하게 제어하려면 템플릿 없이 프록시 통합을 사용하고 통합에서 요청 삭제를 처리합니다.
$input.path(x)

JSONPath 표현식 문자열 (x)을 가져와서 결과의 JSON 객체로 반환합니다. 이를 통해 기본적으로 Apache Velocity Template Language(VTL)에서 페이로드 요소에 액세스하고 조작할 수 있습니다.

예를 들어, $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 또는 Java용 JSONPath를 참조하십시오.

$input 변수 템플릿 예제

파라미터 매핑 템플릿 예제

다음 파라미터 매핑 예제에서는 path, querystring 및 header를 포함한 모든 파라미터를 JSON 페이로드를 통해 통합 엔드포인트로 전달합니다.

#set($allParams = $input.params())
{
  "params" : {
    #foreach($type in $allParams.keySet())
    #set($params = $allParams.get($type))
    "$type" : {
      #foreach($paramName in $params.keySet())
      "$paramName" : "$util.escapeJavaScript($params.get($paramName))"
      #if($foreach.hasNext),#end
      #end
    }
    #if($foreach.hasNext),#end
    #end
  }
}

사실상 이 매핑 템플릿은 다음과 같이 페이로드의 모든 요청 파라미터를 출력합니다.

{
  "params" : {
     "path" : {    
       "path_name" : "path_value", 
       ...
     }
     "header" : {  
       "header_name" : "header_value",
       ...
     }
     "querystring" : {
       "querystring_name" : "querystring_value",
       ...
     }
   }
}

모델 변수를 사용하거나 사용하지 않고 쿼리 문자열과 요청 본문을 가져오기 위해 $input 변수를 사용할 수 있습니다. 또한 파라미터와 페이로드 또는 페이로드의 하위 섹션을 Lambda 함수로 가져올 수도 있습니다. 다음 예는 이 작업을 수행하는 방법을 보여줍니다.

$input을 사용하는 JSON 매핑 템플릿 예제

다음 예제에서는 매핑을 사용하여 쿼리 문자열에서 이름을 읽은 다음 전체 POST 본문을 요소에 포함하는 방법을 보여줍니다.

{
    "name" : "$input.params('name')",
    "body" : $input.json('$') 
}

JSON 입력에 JavaScript로 구문 분석할 수 없는 이스케이프 처리되지 않은 문자가 포함되어 있으면 400 응답이 반환될 수 있습니다. 위의 $util.escapeJavaScript($input.json('$'))을 적용하면 JSON 입력을 올바르게 구문 분석할 수 있습니다.

$input을 사용하는 매핑 템플릿 예제

다음 예제에서는 JSONPath 표현식을 json() 메서드에 전달하는 방법을 보여줍니다. 마침표 (.)와 속성 이름을 사용하여 요청 본문 객체의 특정 속성을 읽을 수도 있습니다.

{
    "name" : "$input.params('name')",
    "body" : $input.json('$.mykey')  
}

메서드 요청 페이로드에 JavaScript에서 구문 분석할 수 없는 이스케이프되지 않은 문자가 포함되어 있으면 400 응답을 받을 수 있습니다. 이 경우 다음에 표시된 것처럼 매핑 템플릿에서 $util.escapeJavaScript() 함수를 호출해야 합니다.

{
    "name" : "$input.params('name')",
    "body" : $util.escapeJavaScript($input.json('$.mykey')) 
}

$input을 사용하는 요청 및 응답 예제

다음은 세 가지 함수를 모두 사용하는 예입니다.

요청 템플릿:

Resource: /things/{id}

With input template:
{
    "id" : "$input.params('id')",
    "count" : "$input.path('$.things').size()",
    "things" : $util.escapeJavaScript($input.json('$.things'))
}

POST /things/abc
{
    "things" : {
        "1" : {},
        "2" : {},
        "3" : {}
    }
}

응답:

{
  "id": "abc",
  "count": "3",
  "things": {
    "1": {},
    "2": {},
    "3": {}
  }
}

더 많은 매핑 예는 모델 및 매핑 템플릿 작업 단원을 참조하십시오.

$stageVariables

단계 변수는 파라미터 매핑과 매핑 템플릿 및 메서드 통합에 사용되는 ARN 및 URL의 자리 표시자로 사용할 수 있습니다. 자세한 내용은 REST API 배포에 대한 스테이지 변수 설정 섹션을 참조하세요.

구문 설명
$stageVariables.<variable_name>

<variable_name>은 단계 변수 이름을 나타냅니다.
$stageVariables['<variable_name>']

<variable_name>은 모든 단계 변수 이름을 나타냅니다.
${stageVariables['<variable_name>']}

<variable_name>은 모든 단계 변수 이름을 나타냅니다.

$util 변수

$util 변수에는 매핑 템플릿에서 사용할 유틸리티 함수가 포함됩니다.

참고

달리 지정하지 않는 한, 기본 문자 집합은 UTF-8입니다.

함수 설명
$util.escapeJavaScript()

JavaScript 문자열 규칙을 사용하여 문자열의 문자를 이스케이프합니다.

참고

이 함수는 일반 작은따옴표(')를 이스케이프된 작은따옴표(\')로 변환합니다. 그러나 이스케이프된 작은따옴표는 JSON에서 유효하지 않습니다. 따라서 이 함수의 결과를 JSON 속성에서 사용할 경우 이스케이프된 작은따옴표(\')를 다시 일반 작은따옴표(')로 변환해야 합니다. 방법은 다음 예제와 같습니다: 

 $util.escapeJavaScript(data).replaceAll("\\'","'")
$util.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
}
$util.urlEncode()

문자열을 "application/x-www-form-urlencoded" 형식으로 변환합니다.
$util.urlDecode()

"application/x-www-form-urlencoded" 문자열을 디코딩합니다.
$util.base64Encode()

데이터를 base64 인코딩 문자열로 인코딩합니다.
$util.base64Decode()

데이터를 base64 인코딩 문자열에서 디코딩합니다.