# REST API의 성능 최적화 API를 호출할 수 있도록 한 후 응답성을 향상하기 위해 API를 최적화해야 할 수 있습니다. API Gateway는 응답 캐싱 및 페이로드 압축과 같은 API를 최적화하기 위한 몇 가지 전략을 제공합니다. 이 섹션에서는 이러한 기능을 활성화하는 방법을 배울 수 있습니다. **Topics** + [API Gateway의 REST API 캐시 설정](api-gateway-caching.md) + [API Gateway의 REST API 페이로드 압축](api-gateway-gzip-compression-decompression.md) # 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 ``` # API Gateway의 REST API 페이로드 압축 API Gateway를 통해 클라이언트는 [지원되는 콘텐츠 코딩](api-gateway-enable-compression.md#api-gateway-supported-content-encodings) 중 하나를 사용하여 압축된 페이로드로 API를 호출할 수 있습니다. 기본적으로 API Gateway는 메서드 요청 페이로드의 압축 해제를 지원합니다. 하지만 메서드 응답 페이로드의 압축을 활성화하도록 API를 구성해야 합니다. [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)에서 압축을 활성화하려면 API를 생성할 때나 API를 생성한 이후에 [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize) ​​속성을 0에서 10485760(1천만 바이트) 사이의 음이 아닌 정수로 설정하세요. API에서 압축을 비활성화하려면 `minimumCompressionSize`를 null로 설정하거나 제거하십시오. API Gateway 콘솔, AWS CLI 또는 API Gateway REST API를 사용하여 API에서 압축을 활성화하거나 비활성화할 수 있습니다. 크기에 상관없이 페이로드에서 압축을 적용하려면 `minimumCompressionSize` 값을 0으로 설정하십시오. 하지만 크기가 작은 데이터를 압축하면 실제로 최종 데이터 크기가 늘어날 수도 있습니다. 뿐만 아니라 API Gateway에서의 압축과 클라이언트에서의 압축 해제로 전체 지연 시간과 필요한 컴퓨팅 시간이 늘어날 수 있습니다. API에 대해 테스트 케이스를 실행하여 최적의 값을 결정해야 합니다. 클라이언트가 압축된 페이로드와 적절한 `Content-Encoding` 헤더와 함께 API 요청을 제출하면 API Gateway는 해당 요청을 통합 엔드포인트에 전달하기 전에 관련 매핑 템플릿을 압축 해제하고 적용할 수 있습니다. 압축이 활성화되고 API가 배포된 후 메서드 요청에서 적절한 `Accept-Encoding` 헤더가 지정된 경우, 클라이언트는 압축된 페이로드가 포함된 API 응답을 수신할 수 있습니다. 통합 엔드포인트가 압축되지 않은 JSON 페이로드를 예상하고 반환하면 압축되지 않은 JSON 페이로드를 위해 구성된 모든 매핑 템플릿을 압축된 페이로드에 적용할 수 있습니다. 압축된 메서드 요청 페이로드의 경우, API Gateway는 페이로드 압축을 해제하고 매핑 템플릿을 적용하며 매핑된 요청을 통합 엔드포인트에 전달합니다. 압축되지 않은 통합 응답 페이로드의 경우, API Gateway는 매핑 템플릿을 적용하고 매핑된 페이로드를 압축해 압축된 페이로드를 클라이언트에게 반환합니다. **Topics** + [API Gateway에서 API에 대한 페이로드 압축 활성화](api-gateway-enable-compression.md) + [API Gateway에서 압축된 페이로드가 포함된 API 메서드 호출](api-gateway-make-request-with-compressed-payload.md) + [API Gateway에서 압축된 페이로드가 포함된 API 응답 수신](api-gateway-receive-response-with-compressed-payload.md) # API Gateway에서 API에 대한 페이로드 압축 활성화 API Gateway 콘솔, AWS CLI 또는 AWS SDK를 사용하여 API에서 압축을 활성화할 수 있습니다. 기존 API에서는 변경 내용이 효과를 발휘하려면 압축을 활성화한 후 API를 배포해야 합니다. 새 API의 경우, API 설정이 완료된 후 API를 배포할 수 있습니다. **참고** 우선 순위가 가장 높은 콘텐츠 인코딩은 API Gateway에 의해 지원되는 인코딩이어야 합니다. 그렇지 않은 경우 압축은 응답 페이로드에 적용되지 않습니다. **Topics** + [API Gateway 콘솔을 사용하여 API에서 페이로드 압축 활성화](#api-gateway-enable-compression-console) + [AWS CLI를 사용해 API에 대한 페이로드 압축 활성화](#api-gateway-enable-compression-cli) + [API Gateway가 지원하는 콘텐츠 코딩](#api-gateway-supported-content-encodings) ## API Gateway 콘솔을 사용하여 API에서 페이로드 압축 활성화 다음 절차는 API에서 페이로드 압축을 활성화하는 방법을 설명합니다. **API Gateway 콘솔을 사용하여 페이로드 압축을 활성화하려면** 1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다. 1. 기존 API를 선택하거나 새 API를 생성합니다. 1. 기본 탐색 창에서 **API 설정**을 선택합니다. 1. **API 세부 정보** 섹션에서 **편집**을 선택합니다. 1. **콘텐츠 인코딩**을 켜서 페이로드 압축을 활성화합니다. **최소 본문 크기** 옆에 최소 압축 크기(바이트)에 해당하는 숫자를 입력합니다. 압축을 해제하려면 **콘텐츠 인코딩** 옵션을 끕니다. 1. **Save changes**(변경 사항 저장)를 선택합니다. ## AWS CLI를 사용해 API에 대한 페이로드 압축 활성화 다음 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 명령은 페이로드 압축을 사용하여 API를 생성합니다. ``` aws apigateway create-rest-api \ --name "My test API" \ --minimum-compression-size 0 ``` 다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 기존 API에 대한 페이로드 압축을 활성화합니다. ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value=0 ``` `minimumCompressionSize` 속성의 음수가 아닌 정수 값은 0에서 10485760(10M바이트) 사이입니다. 압축 임계값을 측정합니다. 페이로드 크기가 이 값보다 작으면 페이로드에 압축 또는 압축 해제가 적용되지 않습니다. 이 값을 0으로 설정하면 모든 페이로드 크기에 압축이 허용됩니다. 다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 페이로드 압축을 끕니다. ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value= ``` 이전 호출에서 `value`를 빈 문자열 `""`로 설정하거나 `value` 속성을 모두 생략할 수도 있습니다. ## API Gateway가 지원하는 콘텐츠 코딩 API Gateway가 지원하는 콘텐츠 코딩은 다음과 같습니다. + `deflate` + `gzip` + `identity` [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4) 사양에 따르면 API Gateway는 다음의 `Accept-Encoding` 헤더 형식도 지원합니다. + `Accept-Encoding:deflate,gzip` + `Accept-Encoding:` + `Accept-Encoding:*` + `Accept-Encoding:deflate;q=0.5,gzip;q=1.0` + `Accept-Encoding:gzip;q=1.0,identity;q=0.5,*;q=0` # API Gateway에서 압축된 페이로드가 포함된 API 메서드 호출 압축된 페이로드가 포함된 API 요청을 하려면 클라이언트는 [지원되는 콘텐츠 코딩](api-gateway-enable-compression.md#api-gateway-supported-content-encodings) 중 하나를 사용하여 `Content-Encoding` 헤더를 설정해야 합니다. API 클라이언트이고 PetStore API 메서드(`POST /pets`)를 호출하려 한다고 가정해 보십시오. 다음의 JSON 출력을 사용하여 메서드를 호출하지 마십시오. ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Length: ... { "type": "dog", "price": 249.99 } ``` 그 대신 GZIP 코딩을 사용하여 압축된 동일한 페이로드가 포함된 메서드를 호출할 수 있습니다. ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Encoding:gzip Content-Length: ... ���RPP*�,HU�RPJ�OW��e&���L,�,-y�j ``` API Gateway는 요청을 수신하면 지정된 콘텐츠 코딩이 지원되는지 확인합니다. 그런 다음 지정된 콘텐츠 코딩으로 페이로드 압축을 해제하려 시도합니다. 압축 해제에 성공하면 통합 엔드포인트에 요청을 발송합니다. 지정된 코딩이 지원되지 않거나 제공된 페이로드가 지정된 코딩으로 압축되지 않은 경우, API Gateway는 `415 Unsupported Media Type` 오류 응답을 반환합니다. API 및 스테이지가 식별되기 전에 압축 해제의 초기 단계에서 오류가 발생한 경우, 오류가 CloudWatch Logs에 기록되지 않습니다. # API Gateway에서 압축된 페이로드가 포함된 API 응답 수신 압축이 활성화된 API에서 요청을 할 때 클라이언트는 [지원되는 콘텐츠 코딩](api-gateway-enable-compression.md#api-gateway-supported-content-encodings)으로 `Accept-Encoding` 헤더를 지정하여 특정 형식의 압축된 응답 페이로드를 수신할 수 있습니다. API Gateway는 다음 조건이 충족되는 경우에만 응답 페이로드를 압축합니다. + 수신되는 요청에는 지원되는 코딩 및 형식의 `Accept-Encoding` 헤더가 있습니다. **참고** 헤더가 설정되지 않은 경우, 기본값은 [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4)에 정의된 대로 `*`입니다. 이러한 경우 API Gateway는 페이로드를 압축하지 않습니다. 일부 브라우저 또는 클라이언트는 압축이 활성화된 요청에 `Accept-Encoding`(예: `Accept-Encoding:gzip, deflate, br`)을 자동으로 추가할 수 있습니다. 그러면 API Gateway에서 페이로드 압축이 활성화될 수 있습니다. 지원되는 `Accept-Encoding` 헤더 값을 명시적으로 지정하지 않으면 API Gateway가 페이로드를 압축하지 않습니다. + API에서 `minimumCompressionSize`가 설정되어 압축을 활성화합니다. + 통합 응답에는 `Content-Encoding` 헤더가 없습니다. + 관련 매핑 템플릿이 적용된 후의 통합 응답 페이로드의 크기는 지정된 `minimumCompressionSize` 값보다 크거나 같습니다. API Gateway는 페이로드를 압축하기 전에 통합 응답을 위해 구성된 모든 매핑 템플릿을 적용합니다. 통합 응답에 `Content-Encoding` 헤더가 포함된 경우, API Gateway는 합 응답 페이로드가 이미 압축되어 있다고 가정하고 압축 처리를 건너뜁니다. 한 가지 예는 PetStore API 예와 다음의 요청입니다. ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept: application/json ``` 백엔드는 다음과 비슷한 압축되지 않은 JSON 페이로드가 포함된 요청에 응답합니다. ``` 200 OK [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` API 클라이언트는 이 출력을 압축된 페이로드로 수신하기 위해 다음과 같이 요청을 제출할 수 있습니다. ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept-Encoding:gzip ``` 클라이언트는 다음과 비슷한 `Content-Encoding` 헤더 및 GZIP 인코딩된 페이로드가 포함된 응답을 수신합니다. ``` 200 OK Content-Encoding:gzip ... ���RP� J�)JV �:P^IeA*������+(�L �X�YZ�ku0L0B7!9��C#�&����Y��a���^�X ``` 응답 페이로드가 압축되면 데이터 전송 요금은 압축된 데이터 크기에 대해서만 청구됩니다.