# API Gateway의 REST API 캐시 설정
API Gateway에서 API 캐싱을 활성화하여 엔드포인트의 응답을 캐싱할 수 있습니다. 캐싱을 사용하면 엔드포인트에 대한 호출 수를 줄이고 API에 대한 요청 지연 시간을 개선할 수 있습니다.
단계에 대한 캐싱을 활성화할 경우 API Gateway에서는 지정된 TTL(Time-to-Live) 기간(초) 동안 엔드포인트에 대한 응답을 캐싱합니다. 그런 다음 API Gateway는 엔드포인트에 요청하는 대신 캐시에서 엔드포인트 응답을 조회하여 요청에 응답합니다. API 캐싱에 대한 기본 TTL 값은 300초입니다. 최대 TTL 값은 3600초입니다. TTL=0이면 캐싱이 비활성화됩니다.
**참고**
캐싱은 최선의 작업을 기반으로 이루어집니다. Amazon CloudWatch의 `CacheHitCount` 및 `CacheMissCount` 지표를 사용하여 API 캐시에서 API Gateway가 전달하는 요청을 모니터링할 수 있습니다.
캐싱할 수 있는 응답의 최대 크기는 1048576바이트입니다. 캐시 데이터 암호화는 캐싱할 경우 응답의 크기를 증가시킬 수 있습니다.
이것은 HIPAA 적격 서비스입니다. AWS, 1996년 미국 HIPAA(Health Insurance Portability and Accountability Act) 및 AWS 서비스를 사용하여 보호되는 건강 정보(PHI)를 처리, 저장 및 전송하는 방법에 대한 자세한 내용은 [HIPAA 개요](https://aws.amazon.com/compliance/hipaa-compliance/)를 참조하십시오.
**중요**
단계에 대한 캐싱을 활성화할 경우, `GET` 메서드만 기본적으로 캐싱을 활성화합니다. 이렇게 하면 API의 안전성 및 가용성이 보장됩니다. [메서드 설정을 재정의](#override-api-gateway-stage-cache-for-method-cache)함으로써 다른 메서드에 대해 캐싱을 활성화할 수 있습니다.
**중요**
캐싱의 경우 선택한 캐시 크기에 따라 시간 단위로 요금이 청구됩니다. 캐싱은 AWS 프리 티어에서 제공되지 않습니다. 자세한 내용은 [API Gateway 요금](https://aws.amazon.com/api-gateway/pricing/)을 참조하세요.
## Amazon API Gateway 캐싱 활성화
API Gateway에서 지정된 단계의 모든 메서드에 대해 캐싱을 활성화할 수 있습니다.
캐싱을 활성화할 경우 캐시 용량을 선택해야 합니다. 일반적으로 용량이 클수록 성능이 우수하지만 비용이 더 높습니다. 지원되는 캐시 크기는 *API Gateway API 참조의* [cacheClusterSize](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html#apigw-CreateStage-request-cacheClusterSize)를 참조하세요.
API Gateway에서 전용 캐시 인스턴스를 생성하여 캐싱을 활성화합니다. 이 프로세스에는 최대 4분이 걸릴 수 있습니다.
API Gateway에서 기존 캐시 인스턴스를 제거하고 수정된 용량으로 새 캐시 인스턴스를 생성하여 캐싱 용량을 변경합니다. 캐시된 모든 기존 데이터가 삭제됩니다.
**참고**
캐시 용량은 캐시 인스턴스의 CPU, 메모리 및 네트워크 대역폭에 영향을 미칩니다. 따라서 캐시 용량이 캐시 성능에 영향을 줄 수 있습니다.
API Gateway에서는 10분 로드 테스트를 실행하여 캐시 용량이 워크로드에 적합한지 확인하는 것이 좋습니다. 로드 테스트 중 트래픽이 프로덕션 트래픽을 미러링하는지 확인합니다. 예를 들어, 램프 업, 상수 트래픽 및 트래픽 급증을 포함합니다. 로드 테스트에는 캐시에서 제공 할 수 있는 응답과 캐시에 항목을 추가하는 고유 응답이 포함되어야 합니다. 로드 테스트 중에 지연 시간, 4xx, 5xx, 캐시 적중 및 캐시 누락 지표를 모니터링합니다. 이러한 지표를 기반으로 필요에 따라 캐시 용량을 조정합니다. 부하 테스트에 대한 자세한 내용은 [속도 제한에 도달하지 않도록 최상의 API Gateway 캐시 용량을 선택하려면 어떻게 하나요?](https://repost.aws/knowledge-center/api-gateway-cache-capacity)를 참조하세요.
------
#### [ AWS Management Console ]
API 게이트웨이 콘솔의 **스테이지** 페이지에서 캐싱을 구성합니다. 스테이지 캐시를 프로비저닝하고 기본 메서드 수준 캐시 설정을 지정합니다. 기본 메서드 수준 캐시를 켜면 해당 메서드에 메서드 재정의가 없는 한 스테이지의 모든 `GET` 메서드에 대해 메서드 수준 캐싱이 설정됩니다. 스테이지에 배포하는 추가 `GET` 메서드에는 모두 메서드 수준 캐시가 있습니다. 스테이지의 특정 메서드에 대한 메서드 수준 캐싱 설정을 구성하려면 메서드 재정의를 사용할 수 있습니다. 메서드, 재정의에 대한 자세한 내용은 [메서드 수준 캐싱에 대한 API Gateway 단계 수준 캐싱 재정의](#override-api-gateway-stage-cache-for-method-cache) 섹션을 참조합니다.
**지정된 단계에 API 캐싱을 설정하려면 다음을 수행합니다.**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. **단계**를 선택합니다.
1. API에 대한 **단계** 목록에서 단계를 선택합니다.
1. **스테이지 세부 정보** 섹션에서 **편집**을 선택합니다.
1. **추가 설정**의 **캐시 설정**에서 **프로비저닝 API 캐시**를 켭니다.
이렇게 하면 스테이지에 캐시 클러스터가 프로비저닝됩니다.
1. 스테이지에 대한 캐싱을 활성화하려면 **기본 메서드 수준 캐싱**을 켭니다.
이렇게 하면 스테이지의 모든 `GET` 메서드에 대해 메서드 수준 캐싱이 활성화됩니다. 이 단계에 배포하는 추가 `GET` 메서드에는 모두 메서드 수준 캐시가 있습니다.
**참고**
메서드 수준 캐시에 대한 기존 설정이 있는 경우 기본 메서드 수준 캐싱 설정을 변경해도 기존 설정에는 영향을 주지 않습니다.
![\[프로비저닝 API 캐시 및 기본 메서드 수준 캐싱을 활성화합니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/api-caching-stage-flow.png)
1. **변경 사항 저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 명령은 스테이지를 업데이트하여 캐시를 프로비저닝하고 스테이지의 모든 `GET` 메서드에 대해 메서드 수준 캐싱을 켭니다.
```
aws apigateway update-stage \
--rest-api-id a1b2c3 \
--stage-name 'prod' \
--patch-operations file://patch.json
```
다음은 `patch.json`의 내용입니다.
```
[
{
"op": "replace",
"path": "/cacheClusterEnabled",
"value": "true"
},
{
"op": "replace",
"path": "/cacheClusterSize",
"value": "0.5"
},
{
"op": "replace",
"path": "/*/*/caching/enabled",
"value": "true"
}
]
```
**참고**
메서드 수준 캐시에 대한 기존 설정이 있는 경우 기본 메서드 수준 캐싱 설정을 변경해도 기존 설정에는 영향을 주지 않습니다.
------
**참고**
API Gateway에서 캐시 생성 또는 삭제를 완료하는 데 4분 정도 걸립니다.
캐시가 생성되면 **캐시 클러스터** 값이 `Create in progress`에서 `Active`로 변경됩니다. 캐시 삭제가 완료되면 **캐시 클러스터** 값이 `Delete in progress`에서 `Inactive`로 변경됩니다.
스테이지의 모든 메서드에 대해 메서드 수준 캐싱을 켜면 **기본 메서드 수준 캐싱** 값이 `Active`로 변경됩니다. 스테이지의 모든 메서드에 대해 메서드 수준 캐싱을 끄면 **기본 메서드 수준 캐싱** 값이 `Inactive`로 변경됩니다. 메서드 수준 캐시에 대한 기존 설정이 있는 경우 캐시 상태를 변경해도 해당 설정에는 영향을 주지 않습니다.
스테이지의 **캐시 설정**에서 캐싱을 활성화할 때 `GET` 메서드만 캐시됩니다. API의 안전성 및 가용성을 확보하려면 이 설정을 변경하지 않는 것이 좋습니다. 그러나 [메서드 설정을 재정의](#override-api-gateway-stage-cache-for-method-cache)함으로써 다른 메서드에 대해 캐싱을 활성화할 수 있습니다.
캐싱이 예상한 대로 작동하는지 확인하려면 두 가지 일반적인 옵션이 있습니다.
+ API 및 단계에 대한 **CacheHitCount** 및 **CacheMissCount**의 CloudWatch 측정치를 검사합니다.
+ 타임스탬프를 응답에 넣습니다.
**참고**
API Gateway 캐시 인스턴스에서 API가 제공되는지 확인하기 위해 CloudFront 응답에서 `X-Cache` 헤더를 사용하지 마세요.
## 메서드 수준 캐싱에 대한 API Gateway 단계 수준 캐싱 재정의
특정 방법에 대한 캐싱을 켜거나 꺼서 스테이지 수준 캐시 설정을 재정의할 수 있습니다. TL 기간을 늘리거나 줄이거나 캐싱된 응답에 대해 암호화를 켜거나 끕니다.
캐싱하는 메서드가 중요 데이터를 응답으로 수신할 경우 캐시 데이터를 암호화합니다. 다양한 규정 준수 프레임워크를 준수하기 위해 이 작업을 수행해야 할 수 있습니다. 자세한 내용은 *AWS Security Hub 사용 설명서*에서 [Amazon API Gateway 제어](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)를 참조하세요.
------
#### [ AWS Management Console ]
**스테이지 세부 정보**에서 기본 메서드 수준 캐싱 설정을 변경해도 재정의가 있는 메서드 수준 캐시 설정에는 영향을 주지 않습니다.
캐싱하는 메서드가 중요 데이터를 응답으로 수신할 경우 **Cache Settings(캐시 설정)**에서 **Encrypt cache data(캐시 데이터 암호화)**를 선택합니다.
**콘솔을 사용하여 개별 메서드에 대한 API 캐싱을 구성하려면 다음을 수행합니다.**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. API를 선택합니다.
1. **단계**를 선택합니다.
1. 이를 위해 **단계** 보조 탐색 창에서 단계를 확장하고 메서드를 선택합니다.
1. **메서드 재정의** 섹션에서 **편집**을 선택합니다.
1. **메서드 설정** 섹션에서 **메서드 캐시 활성화**를 설정 또는 해제하거나 기타 원하는 옵션을 사용자 지정합니다.
**참고**
스테이지에 캐시 클러스터를 프로비전할 때까지는 캐싱이 활성화되지 않습니다.
1. **저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 명령은 `GET /pets` 메서드에 대해서만 캐시를 끕니다.
```
aws apigateway update-stage /
--rest-api-id a1b2c3 /
--stage-name 'prod' /
--patch-operations file://patch.json
```
다음은 `patch.json`의 내용입니다.
```
[{
"op": "replace",
"path": "/~1pets/GET/caching/enabled",
"value": "false"
}]
```
------
## 메서드/통합 파라미터를 캐시 키로 사용하여 캐시된 응답 인덱싱
메서드 또는 통합 파라미터를 캐시 키로 사용하여 캐시된 응답을 인덱싱할 수 있습니다. 여기에는 사용자 지정 헤더, URL 경로 또는 쿼리 문자열이 포함됩니다. 이러한 파라미터 중 일부 또는 전부를 캐시 키로 지정할 수 있지만 반드시 하나 이상의 값을 지정해야 합니다. 캐시 키가 있는 경우 API Gateway는 캐시 키가 없는 경우를 포함하여 각 키 값의 응답을 개별적으로 캐시합니다.
**참고**
리소스의 캐싱을 설정하려면 캐시 키가 필요합니다.
예를 들어 다음과 같은 형식의 요청이 있다고 가정하겠습니다.
```
GET /users?type=... HTTP/1.1
host: example.com
...
```
이 요청에서 `type`은 `admin` 또는 `regular` 값을 가질 수 있습니다. `type` 파라미터가 캐시 키의 일부로 포함되어 있는 경우, `GET /users?type=admin`의 응답은 `GET /users?type=regular`의 응답과 별도로 캐싱됩니다.
메서드 또는 통합 요청에서 두 개 이상의 파라미터를 취하는 경우 파라미터의 일부 또는 모두를 포함하여 캐시 키를 생성하도록 선택할 수 있습니다. 예를 들어 TTL 기간 내에 나열된 순서로 생성되는 다음 요청에 대해 캐시 키에 `type` 파라미터만 포함할 수 있습니다.
```
GET /users?type=admin&department=A HTTP/1.1
host: example.com
...
```
이 요청의 응답은 캐싱되어 다음 요청을 처리하는 데 사용됩니다.
```
GET /users?type=admin&department=B HTTP/1.1
host: example.com
...
```
------
#### [ AWS Management Console ]
메서드 또는 통합 요청 파라미터를 API Gateway 콘솔에서 캐시 키의 일부로 포함하려면 파라미터를 추가한 후 **캐싱**을 선택합니다.
![\[메서드/통합 파라미터를 캐시 키로 포함하여 캐시된 응답 인덱싱\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/api-caching-including-parameter-as-cache-key-new-console.png)
------
#### [ AWS CLI ]
다음 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 명령은 `GET` 메서드를 생성하고 `type` 쿼리 문자열 파라미터가 필요합니다.
```
aws apigateway put-method /
--rest-api-id a1b2c3 /
--resource-id aaa111 /
--http-method GET /
--authorization-type "NONE" /
--request-parameters "method.request.querystring.type=true"
```
다음 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) 명령은 HTTP 엔드포인트와 `GET` 메서드에 대한 통합을 생성하고 API Gateway가 `type` 메서드 요청 파라미터를 캐싱하도록 지정합니다.
```
aws apigateway put-integration /
--rest-api-id a1b2c3 /
--resource-id aaa111 /
--http-method GET /
--type HTTP /
--integration-http-method GET /
--uri 'https://example.com' /
--cache-key-parameters "method.request.querystring.type"
```
API Gateway가 통합 요청 파라미터를 캐싱하도록 지정하려면 `integration.request.location.name`을 캐시 키 파라미터로 사용합니다.
------
## API Gateway에서 API 단계 캐시 비우기
API 캐싱을 활성화한 경우 API 클라이언트가 통합 엔드포인트에서 최신 응답을 가져오도록 API 단계의 캐시를 비울 수 있습니다.
------
#### [ AWS Management Console ]
**API 스테이지 캐시를 비우려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 캐시가 포함된 스테이지가 있는 API를 선택합니다.
1. 기본 탐색 창에서 **스테이지**를 선택한 후 캐시가 있는 스테이지를 선택합니다.
1. **스테이지 작업** 메뉴를 선택한 다음 **스테이지 캐시 비우기**를 선택합니다.
------
#### [ AWS CLI ]
다음 [flush-stage-cache](https://docs.aws.amazon.com/cli/latest/reference/apigateway/flush-stage-cache.html) 명령은 스테이지 캐시를 비웁니다.
```
aws apigateway flush-stage-cache \
--rest-api-id a1b2c3 \
--stage-name prod
```
------
**참고**
캐시가 플러시되면 캐시가 다시 빌드될 때까지 통합 엔드포인트에서 응답이 처리됩니다. 이 기간 동안 통합 엔드포인트에 전송되는 요청 수가 증가할 수 있습니다. 이로 인해 API의 전체 지연 시간이 일시적으로 증가할 수 있습니다.
## API Gateway 캐시 항목 무효화
API의 클라이언트는 기존 캐시 엔트리를 무효화하고 개별 요청에 대해 통합 엔드포인트에서 캐시 엔트리를 다시 로드할 수 있습니다. 클라이언트는 `Cache-Control: max-age=0` 헤더를 포함하는 요청을 전송해야 합니다. 클라이언트는 캐시 대신 통합 엔드포인트에서 직접 응답을 수신합니다(클라이언트에게 해당 권한이 부여된 경우). 이 경우 기존 캐시 엔트리를 통합 엔드포인트에서 가져오는 새 응답으로 대체합니다.
클라이언트에게 권한을 부여하려면 다음과 같은 형식의 정책을 사용자에 대한 IAM 실행 역할에 추가합니다.
**참고**
교차 계정 캐시 무효화는 지원되지 않습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:InvalidateCache"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/stage-name/GET/resource-path-specifier"
]
}
]
}
```
------
이 정책은 API Gateway 실행 서비스에서 지정된 리소스 요청에 대한 캐시를 무효화하도록 허용합니다. 타겟 리소스 그룹을 지정하려면 `account-id`, `api-id` 및 `Resource` ARN 값의 기타 엔트리에 대해 와일드카드(\$1) 문자를 사용합니다. API Gateway 실행 서비스에 대한 권한을 설정하는 방법에 대한 자세한 내용은 [IAM 권한을 사용하여 REST API에 대한 액세스 제어](permissions.md) 단원을 참조하세요.
`InvalidateCache` 정책을 적용하지 않은 경우(또는 콘솔에서 **Require authorization(권한 부여 필요)** 확인란을 선택한 경우), 모든 클라이언트가 API 캐시를 무효화할 수 있습니다. 대부분의 클라이언트가 API 캐시를 무효화할 경우 API의 지연 시간이 일시적으로 증가할 수 있습니다.
정책이 적용되면 캐싱이 활성화되어 권한 부여가 필요합니다.
다음 옵션 중에서 선택하여 API Gateway가 무단 요청을 처리하는 방법을 지정할 수 있습니다.
**403 상태 코드로 요청 실패**
API Gateway가 `403 Unauthorized` 응답을 반환합니다.
API를 사용하여 이 옵션을 설정하려면 `FAIL_WITH_403`을 사용합니다.
**캐시 제어 헤더 무시, 응답 헤더에 경고 추가**
API Gateway는 요청을 처리하고 응답에 경고 헤더를 추가합니다.
API를 사용하여 이 옵션을 설정하려면 `SUCCEED_WITH_RESPONSE_HEADER`을 사용합니다.
**캐시 제어 헤더 무시**
API Gateway는 요청을 처리하고 응답에 경고 헤더를 추가하지 않습니다.
API를 사용하여 이 옵션을 설정하려면 `SUCCEED_WITHOUT_RESPONSE_HEADER`을 사용합니다.
API Gateway 콘솔 또는 AWS CLI를 사용하여 무단 요청 처리 동작을 설정할 수 있습니다.
------
#### [ AWS Management Console ]
**무단 요청 처리 방법을 지정하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 캐시가 포함된 스테이지가 있는 API를 선택합니다.
1. 기본 탐색 창에서 **스테이지**를 선택한 후 캐시가 있는 스테이지를 선택합니다.
1. **스테이지 세부 정보**에서 **편집**을 선택합니다.
1. **무단 요청 처리**에서 옵션을 선택합니다.
1. **계속**을 선택합니다.
1. 변경 사항을 검토하고 **변경 사항 저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 명령은 403 상태 코드로 요청에 실패하여 승인되지 않은 요청을 처리하도록 스테이지를 업데이트합니다.
```
aws apigateway update-stage /
--rest-api-id a1b2c3 /
--stage-name 'prod' /
--patch-operations 'op=replace,path=/*/*/caching/unauthorizedCacheControlHeaderStrategy,value="FAIL_WITH_403"'
```
------
## 캐시가 있는 스테이지의 CloudFormation 예
다음 CloudFormation 템플릿은 예제 API를 생성하고, `Prod` 스테이지에 대한 `0.5` GB 캐시를 프로비저닝하고, 모든 `GET` 메서드에 대해 메서드 수준 캐싱을 켭니다.
**중요**
캐싱의 경우 선택한 캐시 크기에 따라 시간 단위로 요금이 청구됩니다. 캐싱은 AWS 프리 티어에서 제공되지 않습니다. 자세한 내용은 [API Gateway 요금](https://aws.amazon.com/api-gateway/pricing/)을 참조하세요.
### 예제 CloudFormation 템플릿
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: cache-example
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: true
AuthorizationType: NONE
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
ApiStage:
Type: 'AWS::ApiGateway::Stage'
Properties:
StageName: Prod
Description: Prod Stage with a cache
RestApiId: !Ref Api
DeploymentId: !Ref ApiDeployment
CacheClusterEnabled: True
CacheClusterSize: 0.5
MethodSettings:
- ResourcePath: /*
HttpMethod: '*'
CachingEnabled: True
```