# API Gateway에서 HTTP API에 대한 API 요청 및 응답 변환
백엔드 통합에 도달하기 전에 클라이언트의 API 요청을 수정할 수 있습니다. API Gateway가 클라이언트에 응답을 반환하기 전에 통합에서 응답을 변경할 수도 있습니다. *파라미터 매핑*을 사용하여 HTTP API에 대한 API 요청 및 응답을 수정합니다. 파라미터 매핑을 사용하려면 수정할 API 요청 또는 응답 파라미터를 지정하고 이러한 파라미터를 수정하는 방법을 지정합니다.
## API 요청 변환
요청 파라미터를 사용하여 요청이 백엔드 통합에 도달하기 전에 요청을 변경합니다. 헤더, 쿼리 문자열 또는 요청 경로를 수정할 수 있습니다.
요청 파라미터는 키-값 맵입니다. 키는 변경할 요청 파라미터의 위치와 변경 방법을 식별합니다. 이 값은 파라미터에 대한 새 데이터를 지정합니다.
다음 표에는 지원되는 키가 나와 있습니다.
| 유형 | 구문 |
| --- | --- |
| 헤더 | append\$1overwrite\$1remove:header.headername |
| 쿼리 문자열 | append\$1overwrite\$1remove:querystring.querystring-name |
| 경로 | overwrite:path |
다음 표에서는 파라미터에 매핑할 수 있는 지원되는 값을 보여 줍니다.
| 유형 | 구문 | 참고 |
| --- | --- | --- |
| 헤더 값 | \$1request.header.name 또는 \$1\$1request.header.name\$1 | 헤더 이름은 대/소문자를 구분하지 않습니다. API Gateway는 쉼표를 사용하여 여러 헤더 값을 결합합니다(예: "header1": "value1,value2"). 일부 헤더는 예약되어 있습니다. 자세한 내용은 [예약된 헤더](#http-api-mapping-reserved-headers) 단원을 참조하세요. |
| 쿼리 문자열 값 | \$1request.querystring.name 또는 \$1\$1request.querystring.name\$1 | 쿼리 문자열 이름은 대/소문자를 구분합니다. API Gateway는 쉼표를 사용하여 여러 값을 결합합니다(예: "querystring1" "Value1,Value2"). |
| 요청 본문 | \$1request.body.name 또는 \$1\$1request.body.name\$1 | JSON 경로 표현식입니다. 재귀적 하강(\$1request.body..name)) 및 필터 표현식(?(expression))은 지원되지 않습니다. JSON 경로를 지정하면 API Gateway가 요청 본문을 100KB로 잘라낸 다음 선택 표현식을 적용합니다. 100KB보다 큰 페이로드를 보내려면 `$request.body`을(를) 지정합니다. |
| 요청 경로 | \$1request.path 또는 \$1\$1request.path\$1 | 단계 이름이 없는 요청 경로입니다. |
| 경로 파라미터 | \$1request.path.name 또는 \$1\$1request.path.name\$1 | 요청에 포함된 경로 파라미터의 값입니다. 예를 들어 라우팅이 /pets/\$1petId\$1인 경우 요청의 petId 파라미터를 \$1request.path.petId(으)로 매핑할 수 있습니다. |
| 컨텍스트 변수 | \$1context.variableName 또는 \$1\$1context.variableName\$1 | [컨텍스트 변수](http-api-logging-variables.md)의 값입니다.특수 문자 `.` 및 `_`만 지원됩니다. |
| 단계 변수 | \$1stageVariables.variableName 또는 \$1\$1stageVariables.variableName\$1 | [스테이지 변수](http-api-stages.stage-variables.md)의 값입니다. |
| 정적 값 | string | 상수 값입니다. |
**참고**
선택 표현식에 여러 변수를 사용하려면 변수를 괄호로 묶습니다. 예: `${request.path.name} ${request.path.id}`.
## API 응답 변환
응답 파라미터를 사용하여 클라이언트에 응답을 반환하기 전에 백엔드 통합에서 HTTP 응답을 변환합니다. API Gateway가 클라이언트에 응답을 반환하기 전에 응답의 헤더 또는 상태 코드를 수정할 수 있습니다.
통합에서 반환하는 각 상태 코드에 대한 응답 파라미터를 구성합니다. 응답 파라미터는 키-값 맵입니다. 키는 변경할 요청 파라미터의 위치와 변경 방법을 식별합니다. 이 값은 파라미터에 대한 새 데이터를 지정합니다.
다음 표에는 지원되는 키가 나와 있습니다.
| 유형 | 구문 |
| --- | --- |
| 헤더 | append\$1overwrite\$1remove:header.headername |
| 상태 코드 | overwrite:statuscode |
다음 표에서는 파라미터에 매핑할 수 있는 지원되는 값을 보여 줍니다.
| 유형 | 구문 | 참고 |
| --- | --- | --- |
| 헤더 값 | \$1response.header.name 또는 \$1\$1response.header.name\$1 | 헤더 이름은 대/소문자를 구분하지 않습니다. API Gateway는 쉼표를 사용하여 여러 헤더 값을 결합합니다(예: "header1": "value1,value2"). 일부 헤더는 예약되어 있습니다. 자세한 내용은 [예약된 헤더](#http-api-mapping-reserved-headers) 단원을 참조하세요. |
| 응답 본문 | \$1response.body.name 또는 \$1\$1response.body.name\$1 | JSON 경로 표현식. 재귀적 하강(\$1response.body..name) 및 필터 표현식(?(expression))은 지원되지 않습니다. JSON 경로를 지정하면 API Gateway가 응답 본문을 100KB로 잘라낸 다음 선택 표현식을 적용합니다. 100KB보다 큰 페이로드를 보내려면 `$response.body`을(를) 지정합니다. |
| 컨텍스트 변수 | \$1context.variableName 또는 \$1\$1context.variableName\$1 | 지원되는 [컨텍스트 변수](http-api-logging-variables.md)의 값입니다. |
| 단계 변수 | \$1stageVariables.variableName 또는 \$1\$1stageVariables.variableName\$1 | [스테이지 변수](http-api-stages.stage-variables.md)의 값입니다. |
| 정적 값 | string | 상수 값입니다. |
**참고**
선택 표현식에 여러 변수를 사용하려면 변수를 괄호로 묶습니다. 예: `${request.path.name} ${request.path.id}`.
## 예약된 헤더
다음 헤더가 예약되어 있습니다. 이러한 헤더에 대한 요청 또는 응답 매핑은 구성할 수 없습니다.
+ access-control-\$1
+ apigw-\$1
+ 승인
+ 연결
+ Content-Encoding
+ Content-Length
+ Content-Location
+ 전달됨
+ Keep-Alive
+ Origin
+ 프록시-인증
+ Proxy-Authorization
+ TE
+ 트레일러
+ Transfer-Encoding
+ 업그레이드
+ x-amz-\$1
+ x-amzn-\$1
+ X-Forwarded-For
+ X-Forwarded-Host
+ X-Forwarded-Proto
+ Via
## 예시
다음 AWS CLI 예제에서는 파라미터 매핑을 구성합니다. CloudFormation 템플릿 예는 [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates)를 참조하세요.
### API 요청에 헤더 추가
다음 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 백엔드 통합에 도달하기 전에 API 요청에 `header1`이라는 헤더를 생성합니다. API Gateway는 요청 ID로 헤더를 채웁니다.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header1": "$context.requestId" }'
```
### 요청 헤더 이름 바꾸기
다음 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 요청 헤더의 이름을 `header1`에서 `header2`로 변경합니다.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header2": "$request.header.header1", "remove:header.header1": "''"}'
```
### 통합에서 응답 변경
다음 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 통합에 대한 응답 파라미터를 구성합니다. 통합에서 500 상태 코드를 반환하면 API Gateway가 상태 코드를 403으로 변경하고 응답에 `header1`1을 추가합니다. 통합에서 404 상태 코드를 반환하면 API Gateway는 응답에 `error` 헤더를 추가합니다.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"} }'
```
### 구성된 파라미터 매핑 제거
다음 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 `append:header.header1`에 대해 이전에 구성된 요청 파라미터를 제거합니다. 또한 200 상태 코드에 대해 이전에 구성된 응답 파라미터를 제거합니다.
```
aws apigatewayv2 update-integration \
--api-id abcdef123 \
--integration-id hijk456 \
--request-parameters '{"append:header.header1" : ""}' \
--response-parameters '{"200" : {}}'
```