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

포커스 모드

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

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

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

주제

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

참고

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

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

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

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.deploymentId`	API 배포의 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 Gateway의 REST API 사용량 계획 및 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 인증 공급자에 대한 자세한 내용은 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.vpcId`	API Gateway 엔드포인트를 요청하는 VPC의 VPC ID입니다.
`$context.identity.vpceId`	API Gateway 엔드포인트를 요청하는 VPC 엔드포인트의 VPC 엔드포인트 ID입니다. 프라이빗 API가 있는 경우에만 존재합니다.
`$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.isCanaryRequest`	요청이 canary로 전달된 경우 `true`, 요청이 canary로 전달되지 않은 경우 `false`를 반환합니다. canary를 활성화한 경우에만 존재합니다.
`$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과 연결되어 있지 않은 경우 설정되지 않습니다. 자세한 내용은 API Gateway에서 AWS WAF를 사용하여 REST API 보호 단원을 참조하십시오.
`$context.webaclArn`	요청을 허용할지 차단할지 결정하는 데 사용되는 웹 ACL의 전체 ARN입니다. 스테이지가 웹 ACL과 연결되어 있지 않은 경우 설정되지 않습니다. 자세한 내용은 API Gateway에서 AWS WAF를 사용하여 REST 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"
}

이 매핑 템플릿의 출력은 다음과 같아야 합니다.


{
  stage: 'prod',
  request_id: 'abcdefg-000-000-0000-abcdefg',
  api_id: 'abcd1234',
  resource_path: '/',
  resource_id: 'efg567',
  http_method: 'GET',
  source_ip: '192.0.2.1',
  user-agent: 'curl/7.84.0',
  account_id: '111122223333',
  api_key: 'MyTestKey',
  caller: 'ABCD-0000-12345',
  user: 'ABCD-0000-12345',
  user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}

액세스 로깅 전용의 `$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`입니다. 자세한 내용은 API 스테이지를 REST API에 대한 사용자 지정 도메인 이름에 매핑 단원을 참조하십시오.
`$context.endpointType`	API의 엔드포인트 유형입니다.
`$context.integration.error`	통합에서 반환된 오류 메시지입니다.
`$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.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.body`를 사용하여 전체 부동 소수점 숫자를 보존할 수 있습니다(예: `10.00`).
`$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').size()`는 `"3"`을 반환합니다. JSONPath에 대한 자세한 내용은 JSONPath 또는 Java용 JSONPath를 참조하십시오.

`$input` 변수 템플릿 예제

다음 예는 매핑 템플릿에서 $input 변수를 사용하는 방법을 보여줍니다. 입력 이벤트를 API Gateway에 반환하는 모의 통합 또는 Lambda 비프록시 통합을 사용하여 이러한 예제를 사용해 볼 수 있습니다.

파라미터 매핑 템플릿 예제

다음 파라미터 매핑 예제에서는 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
  }
}

다음 입력 파라미터를 포함하는 요청의 경우

myparam이라는 경로 매개변수
쿼리 문자열 파라미터 querystring1=value1,value2&querystring2=value3
헤더 "header1" : "value1", "header2" : "value2", "header3" : "value3".

이 매핑 템플릿의 출력은 다음과 같아야 합니다.


{
  "params" : {
        "path" : {
            "path" : "myparam"
                }
    ,        "querystring" : {
            "querystring1" : "value1,value2"
      ,            "querystring2" : "value3"
                }
    ,        "header" : {
            "header3" : "value3"
      ,            "header2" : "value2"
      ,            "header1" : "value1"
                }
          }
}

JSON 매핑 템플릿 예시

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

다음 예제에서는 매핑 템플릿을 사용하여 페이로드의 하위 섹션을 가져옵니다. 이 예제에서는 입력 파라미터 name을 가져온 다음 전체 POST 본문을 가져옵니다.


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

쿼리 문자열 name=Bella&type=dog 파라미터와 다음 본문이 포함된 요청의 경우:


{
    "Price" : "249.99",
    "Age": "6"
}

이 매핑 템플릿의 출력은 다음과 같아야 합니다.


{
    "name" : "Bella",
    "body" : {"Price":"249.99","Age":"6"}
}

JSON 입력에 이스케이프 처리되지 않은 문자가 포함되어 있고 이 문자가 자바스크립트로 구문 분석할 수 없는 경우 API 게이트웨이에서 400 응답을 반환할 수 있습니다. $util.escapeJavaScript($input.json('$'))을 적용하면 JSON 입력을 올바르게 구문 분석할 수 있습니다.

$util.escapeJavaScript($input.json('$'))이 적용된 이전 예는 다음과 같습니다.


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

이 경우 이 매핑 템플릿의 출력은 다음과 같아야 합니다.


{
    "name" : "Bella",
    "body": {\"Price\":\"249.99\",\"Age\":\"6\"}
}

JSONPath 표현식 예제

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


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

쿼리 문자열 name=Bella&type=dog 파라미터와 다음 본문이 포함된 요청의 경우:


{
    "Price" : "249.99",
    "Age": "6"
}

이 매핑 템플릿의 출력은 다음과 같아야 합니다.


{
    "name" : "Bella",
    "body" : "6"
}

메서드 요청 페이로드에 이스케이프 처리되지 않은 문자가 포함되어 있고 이 문자가 자바스크립트로 구문 분석할 수 없는 경우 API Gateway에서 400 응답을 반환할 수 있습니다. $util.escapeJavaScript()을 적용하면 JSON 입력을 올바르게 구문 분석할 수 있습니다.

$util.escapeJavaScript($input.json('$.Age'))이 적용된 이전 예는 다음과 같습니다.


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

이 경우 이 매핑 템플릿의 출력은 다음과 같아야 합니다.


{
    "name" : "Bella",
    "body": "\"6\""
}

요청 및 응답 예제

다음 예제에서는 경로가 /things/{id}인 리소스에 대해 $input.params(), $input.path(), $input.json()을 사용합니다:


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

경로 123 매개변수와 다음 본문이 포함된 요청의 경우:


{
      "things": {
            "1": {},
            "2": {},
            "3": {}
      }
}

이 매핑 템플릿의 출력은 다음과 같아야 합니다.


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

$util.escapeJavaScript($input.json('$.things'))이 적용된 이전 예는 다음과 같습니다.


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

이 매핑 템플릿의 출력은 다음과 같아야 합니다.


{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}

더 많은 매핑 예는 REST API용 매핑 템플릿 단원을 참조하십시오.

`$stageVariables`

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

구문	설명
`$stageVariables.<variable_name>`,`$stageVariables['<variable_name>']` 또는 `${stageVariables['<variable_name>']}`	`<variable_name>`은 단계 변수 이름을 나타냅니다.

`$util` 변수

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

참고

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

함수	설명
`$util.escapeJavaScript()`	JavaScript 문자열 규칙을 사용하여 문자열의 문자를 이스케이프합니다. 참고 이 함수는 일반 작은따옴표(`'`)를 이스케이프된 작은따옴표(`\'`)로 변환합니다. 그러나 이스케이프된 작은따옴표는 JSON에서 유효하지 않습니다. 따라서 이 함수의 결과를 JSON 속성에서 사용할 경우 이스케이프된 작은따옴표(`\'`)를 다시 일반 작은따옴표(`'`)로 변환해야 합니다. 방법은 다음 예제와 같습니다: `"input" : "$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 인코딩 문자열에서 디코딩합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

통합 패스스루 동작

게이트웨이 응답

이 페이지에서

쿠키 기본 설정 선택

쿠키 기본 설정 사용자 지정

필수

성능

기능

광고

쿠키 기본 설정을 저장할 수 없음

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

주제

참고

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

참고

참고

`$context` 변수 템플릿 예제

참고

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

`$input` 변수

`$input` 변수 템플릿 예제

파라미터 매핑 템플릿 예제

JSON 매핑 템플릿 예시

JSONPath 표현식 예제

요청 및 응답 예제

`$stageVariables`

`$util` 변수

참고

참고

이 페이지에서

Related resources

페이지 내용이 도움이 되었습니까?

Related resources

다음 주제:

이전 주제:

도움이 필요하십니까?