# Otimizar o desempenho das APIs REST Depois de disponibilizar sua API para ser chamada, você pode perceber que ela precisa ser otimizada para melhorar a capacidade de resposta. O API Gateway fornece algumas estratégias para otimizar sua API, como cache de resposta e compactação de carga. Nesta seção, você pode aprender como habilitar esses recursos. **Topics** + [Configurações de cache para APIs REST no API Gateway](api-gateway-caching.md) + [Compressão de carga útil para APIs REST no API Gateway](api-gateway-gzip-compression-decompression.md) # Configurações de cache para APIs REST no API Gateway É possível habilitar o armazenamento em cache da API no API Gateway para armazenar em cache as respostas do endpoint. Com o armazenamento em cache, você pode reduzir o número de chamadas feitas para o endpoint e também melhorar a latência de solicitações para a sua API. Quando o armazenamento em cache é habilitado para um estágio, o API Gateway armazena em cache as respostas do seu endpoint por um período Time-to-live (TTL – vida útil) especificado, em segundos. Depois, o API Gateway responde à solicitação examinando a resposta do endpoint no cache em vez de fazer uma solicitação ao seu endpoint. O valor de TTL padrão para o armazenamento em cache de APIs é de 300 segundos. O valor de TTL máximo é de 3600 segundos. TTL=0 significa que o armazenamento em cache está desabilitado. **nota** O armazenamento em cache é o melhor esforço. Você pode usar as métricas `CacheHitCount` e `CacheMissCount` no Amazon CloudWatch para monitorar solicitações que o API Gateway atende pelo cache da API. O tamanho máximo de uma resposta que pode ser armazenada em cache é 1.048.576 bytes. A criptografia de dados de cache pode aumentar o tamanho da resposta quando está sendo armazenada em cache. Este é um serviço qualificado da HIPAA. Para obter mais informações sobre a AWS, a Lei de Portabilidade e Responsabilidade de Seguro de Saúde de 1996 dos EUA (HIPAA) e o uso dos serviços da AWS para processar, armazenar e transmitir informações de saúde protegidas (PHI), consulte [Visão geral da HIPAA](https://aws.amazon.com/compliance/hipaa-compliance/). **Importante** Ao habilitar o armazenamento em cache para um estágio, somente métodos `GET` têm o armazenamento em cache habilitado por padrão. Isso ajuda a garantir a segurança e a disponibilidade da sua API. Você pode habilitar o armazenamento em cache para outros métodos, [substituindo as configurações do método](#override-api-gateway-stage-cache-for-method-cache). **Importante** O armazenamento em cache é cobrado por hora com base no tamanho do cache escolhido. O armazenamento em cache não é elegível para o nível gratuito da AWS. Para obter mais informações, consulte [Preços do API Gateway](https://aws.amazon.com/api-gateway/pricing/). ## Habilitar o armazenamento em cache do Amazon API Gateway No API Gateway, é possível habilitar o armazenamento em cache de um estágio específico. Ao habilitar o armazenamento em cache, você deve escolher uma capacidade de cache. Em geral, uma capacidade maior proporciona melhor desempenho, mas também custa mais. Para ver os tamanhos de cache compatíveis, consulte [cacheClusterSize](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html#apigw-CreateStage-request-cacheClusterSize) na *Referência de API do API Gateway*. O API Gateway habilita o armazenamento em cache por meio da criação de uma instância de cache dedicada. Esse processo pode demorar até 4 minutos. O API Gateway altera a capacidade de armazenamento em cache removendo a instância de cache existente e criando uma nova com capacidade modificada. Todos os dados armazenados em cache existentes são excluídos. **nota** A capacidade do cache afeta a CPU, a memória e a largura de banda da rede da instância de cache. Como resultado, a capacidade do cache pode afetar a performance do cache. O API Gateway recomenda que você execute um teste de carga de 10 minutos para verificar se a capacidade do cache é apropriada para sua carga de trabalho. Certifique-se de que o tráfego durante o teste de carga corresponde ao tráfego da produção. Por exemplo, inclua padrões de tráfego crescente, constante e em picos. O teste de carga deve incluir respostas que podem ser servidas a partir do cache, bem como respostas exclusivas que adicionam itens ao cache. Monitore as métricas de latência, 4xx, 5xx, acertos de cache e erros de cache durante o teste de carga. Ajuste a capacidade do cache conforme necessário com base nessas métricas. Para obter mais informações sobre o teste de carga, consulte [Como seleciono a melhor capacidade de cache do Amazon API Gateway para não atingir um limite de taxa?](https://repost.aws/knowledge-center/api-gateway-cache-capacity). ------ #### [ Console de gerenciamento da AWS ] No console do API Gateway, configure o armazenamento em cache na página **Estágios**. Provisione o cache do estágio e especifique uma configuração padrão de cache no nível de método. Se você ativar o cache padrão no nível de método, o armazenamento em cache no nível de método será ativado para todos os métodos `GET` no estágio, a menos que esse método tenha uma substituição de método. Todos os métodos `GET` adicionais que você implantar em seu estágio terão cache no nível de método. Para definir a configuração do armazenamento em cache no nível de método para métodos específicos do seu estágio, você pode usar substituições de método. Para saber mais sobre substituições de método, consulte [Substituir o armazenamento em cache no nível de estágio do API Gateway para armazenamento em cache no nível de método](#override-api-gateway-stage-cache-for-method-cache). **Para configurar o armazenamento em cache de API para um determinado estágio:** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha **Stages (Estágios)**. 1. Na lista **Stages (Estágios)** da API, escolha o estágio. 1. Na seção **Detalhes do estágio**, selecione **Editar**. 1. Em **Configurações adicionais**, para **Configurações de cache**, ative **Provisionar cache de APIs**. Isso provisiona um cluster de cache para seu estágio. 1. Para ativar o armazenamento em cache para seu estágio, ative **Armazenamento em cache padrão no nível de método**. Isso ativa o armazenamento em cache no nível de método para todos os métodos `GET` em seu estágio. Todos os métodos `GET` adicionais que você implantar nesse estágio terão um cache no nível de método. **nota** Se você já tiver uma configuração para um cache no nível de método, alterar a configuração de armazenamento em cache padrão no nível de método não afetará essa configuração existente. ![\[Ative o cache da API de provisionamento e o cache padrão no nível de método.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-caching-stage-flow.png) 1. Escolha **Salvar alterações**. ------ #### [ AWS CLI ] O comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) indicado abaixo atualiza um estágio para provisionar um cache e ativa o armazenamento em cache em nível de método para todos os métodos `GET` em seu estágio: ``` aws apigateway update-stage \ --rest-api-id a1b2c3 \ --stage-name 'prod' \ --patch-operations file://patch.json ``` O conteúdo de `patch.json` é o seguinte: ``` [ { "op": "replace", "path": "/cacheClusterEnabled", "value": "true" }, { "op": "replace", "path": "/cacheClusterSize", "value": "0.5" }, { "op": "replace", "path": "/*/*/caching/enabled", "value": "true" } ] ``` **nota** Se você já tiver uma configuração para um cache no nível de método, alterar a configuração de armazenamento em cache padrão no nível de método não afetará essa configuração existente. ------ **nota** A criação ou exclusão de um cache leva cerca de 4 minutos para ser concluída pelo API Gateway. Quando um cache é criado, o valor de **Cluster de cache** é alterado de `Create in progress` para `Active`. Quando a exclusão do cache é concluída, o valor de **Cluster de cache** é alterado de `Delete in progress` para `Inactive`. Quando você ativa o cache no nível de método para todos os métodos em seu estágio, o valor de **Armazenamento em cache padrão no nível de método** é alterado para `Active`. Se você desativar o cache no nível de método para todos os métodos em seu estágio, o valor de **Armazenamento em cache padrão no nível de método** será alterado para `Inactive`. Se você tiver uma configuração para um cache no nível de método, alterar o status do cache não afetará essa configuração. Ao habilitar o armazenamento em cache dentro das **Configurações de cache** de um estágio, somente métodos `GET` são armazenados em cache. Para garantir a segurança e a disponibilidade da sua API, recomendamos não alterar essa configuração. No entanto, você pode habilitar o armazenamento em cache para outros métodos, [substituindo as configurações do método](#override-api-gateway-stage-cache-for-method-cache). Se quiser verificar se o armazenamento em cache está funcionando como esperado, você tem duas opções gerais: + Inspecionar as métricas do CloudWatch de **CacheHitCount** e **CacheMissCount** para a sua API e estágio. + Colocar um carimbo de data/hora na resposta. **nota** Não use o cabeçalho `X-Cache` da resposta do CloudFront para determinar se a sua API está sendo atendida pela instância de cache do API Gateway. ## Substituir o armazenamento em cache no nível de estágio do API Gateway para armazenamento em cache no nível de método Você pode substituir as configurações de cache no nível de estágio ativando ou desativando o armazenamento em cache para um método específico. Também é possível modificar o período TTL ou ativar e desativar a criptografia para respostas armazenadas em cache. Se houver previsão de que determinado método armazenado em cache receberá dados confidenciais nas respectivas respostas, criptografe os dados de cache. Você pode precisar fazer isso para cumprir vários requisitos de conformidade. Para ter mais informações, consulte [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) no *Guia do usuário do AWS Security Hub*. ------ #### [ Console de gerenciamento da AWS ] Se você alterar a configuração do armazenamento em cache padrão no nível de método nos **Detalhes do estágio**, isso não afetará as configurações de cache no nível de método que têm substituições. Se você antecipar que um determinado método armazenado em cache receberá dados confidenciais em suas respostas, em **Cache Settings (Configurações de cache)**, escolha **Encrypt cache data (Criptografar dados de cache)**. **Para configurar o armazenamento em cache de API para métodos individuais usando o console:** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione a API. 1. Escolha **Stages (Estágios)**. 1. Na lista **Stages (Estágios)** da API, expanda o estágio e escolha um método na API. 1. Na seção **Substituições de método**, escolha **Editar**. 1. Na seção **Configurações do método**, ative ou desative a opção **Ativar cache de método** ou personalize qualquer outra opção desejada. **nota** O armazenamento em cache só estará ativo quando você provisionar um cluster de cache para seu estágio. 1. Escolha **Salvar**. ------ #### [ AWS CLI ] O comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) indicado abaixo desativa o cache somente para o método `GET /pets`: ``` aws apigateway update-stage / --rest-api-id a1b2c3 / --stage-name 'prod' / --patch-operations file://patch.json ``` O conteúdo de `patch.json` é o seguinte: ``` [{ "op": "replace", "path": "/~1pets/GET/caching/enabled", "value": "false" }] ``` ------ ## Usar parâmetros de método ou integração como chaves de cache para indexar respostas em cache É possível usar um método ou parâmetro de integração como chaves de cache para indexar respostas armazenadas em cache. Isso inclui cabeçalhos personalizados, caminhos de URL ou strings de consulta. É possível especificar alguns ou todos esses parâmetros como chave de cache, mas você deve especificar pelo menos um valor. Quando você tem uma chave de cache, o API Gateway armazena em cache as respostas de cada valor de chave separadamente, inclusive quando a chave de cache não está presente. **nota** As chaves de cache são necessárias ao configurar o armazenamento em cache em um recurso. Por exemplo, suponha que você tenha uma solicitação no seguinte formato: ``` GET /users?type=... HTTP/1.1 host: example.com ... ``` Nessa solicitação, `type` pode ter um valor de `admin` ou `regular`. Se você incluir o parâmetro `type` como parte da chave do cache, as respostas de `GET /users?type=admin` serão armazenadas em cache separadamente daquelas de `GET /users?type=regular`. Quando uma solicitação de método ou integração usa mais de um parâmetro, você pode optar por incluir alguns ou todos os parâmetros para criar a chave de cache. Por exemplo, você pode incluir apenas o parâmetro `type` na chave de cache para a seguinte solicitação, feita na ordem listada dentro de um período de TTL: ``` GET /users?type=admin&department=A HTTP/1.1 host: example.com ... ``` A resposta dessa solicitação é armazenada em cache e usada para atender à seguinte solicitação: ``` GET /users?type=admin&department=B HTTP/1.1 host: example.com ... ``` ------ #### [ Console de gerenciamento da AWS ] Para incluir um parâmetro de solicitação de método ou integração como parte de uma chave de cache no console do API Gateway, selecione **Caching (Armazenamento em cache)** depois de adicionar o parâmetro. ![\[Incluir parâmetros de método ou integração como chaves de cache para indexar a resposta em cache\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-caching-including-parameter-as-cache-key-new-console.png) ------ #### [ AWS CLI ] O comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo cria um método `GET` e exige o parâmetro de string de consulta `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" ``` O comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) indicado abaixo cria uma integração para o método `GET` com um endpoint HTTP e especifica que o API Gateway armazene em cache o parâmetro de solicitação do método `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" ``` Para especificar que o API Gateway armazene em cache um parâmetro de solicitação de integração, use `integration.request.location.name` como o parâmetro da chave de cache. ------ ## Liberar o cache de estágio de APIs no API Gateway Quando o armazenamento em cache de APIs está habilitado, você pode liberar o cache do estágio de API para garantir que os clientes da API obtenham as respostas mais recentes dos endpoints de integração. ------ #### [ Console de gerenciamento da AWS ] **Liberar o cache de estágios de API** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API que tenha um estágio com cache. 1. No painel de navegação principal, selecione **Estágios** e escolha seu estágio com cache. 1. Escolha o menu **Ações de estágio** e selecione **Liberar cache do estágio**. ------ #### [ AWS CLI ] O comando [flush-stage-cache](https://docs.aws.amazon.com/cli/latest/reference/apigateway/flush-stage-cache.html) indicado abaixo libera o cache do estágio: ``` aws apigateway flush-stage-cache \ --rest-api-id a1b2c3 \ --stage-name prod ``` ------ **nota** Após o cache ser enviado, as respostas serão atendidas no endpoint de integração até que o cache seja criado novamente. Durante esse período, o número de solicitações enviadas ao endpoint de integração poderá aumentar. Isso pode aumentar temporariamente a latência geral da sua API. ## Invalidar uma entrada de cache do API Gateway Um cliente da sua API pode invalidar uma entrada de cache existente e recarregá-la no endpoint de integração para solicitações individuais. O cliente deve enviar uma solicitação que contenha o cabeçalho `Cache-Control: max-age=0`. O cliente recebe a resposta diretamente do endpoint de integração em vez do cache, desde que o cliente esteja autorizado a fazer isso. Isso substitui a entrada de cache existente pela nova resposta, que é obtida do endpoint de integração. Para conceder permissão a um cliente, anexe uma política com o formato a seguir a uma função de execução do IAM para o usuário. **nota** Não há suporte à invalidação de cache entre contas. ------ #### [ 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" ] } ] } ``` ------ Essa política permite que o serviço de execução do API Gateway invalide o cache para solicitações referentes aos recursos especificados. Para especificar um grupo de recursos direcionados, use um caractere curinga (\$1) para `account-id`, `api-id` e outras entradas no valor de ARN de `Resource`. Para obter mais informações sobre como definir permissões para o serviço de execução do API Gateway, consulte [Controlar o acesso a uma API REST com permissões do IAM](permissions.md). Se você não impuser uma política `InvalidateCache` (ou marcar a caixa de seleção **Require authorization (Exigir autorização)** no console), qualquer cliente poderá invalidar o cache da API. Se a maioria ou todos os clientes invalidarem o cache de API, isso poderá aumentar significativamente a latência da sua API. Quando a política está em vigor, o armazenamento em cache está habilitado e a autorização é necessária. Você pode especificar como o API Gateway lida com solicitações não autorizadas escolhendo entre as seguintes opções: **Recusar a solicitação com o código de status 403** O API Gateway retorna uma resposta `403 Unauthorized`. Para definir essa opção usando a API, use `FAIL_WITH_403`. **Ignorar cabeçalho de controle de cache; adicionar um aviso no cabeçalho de resposta** O API Gateway processa a solicitação e adiciona um cabeçalho de aviso na resposta. Para definir essa opção usando a API, use `SUCCEED_WITH_RESPONSE_HEADER`. **Ignorar cabeçalho de controle de cache** O API Gateway processa a solicitação e não adiciona um cabeçalho de aviso na resposta. Para definir essa opção usando a API, use `SUCCEED_WITHOUT_RESPONSE_HEADER`. Você pode definir o comportamento de tratamento de solicitações não autorizadas usando o console do API Gateway ou a AWS CLI. ------ #### [ Console de gerenciamento da AWS ] **Como especificar de que forma as solicitações não autorizadas são tratadas** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API que tenha um estágio com cache. 1. No painel de navegação principal, selecione **Estágios** e escolha seu estágio com cache. 1. Em **Detalhes do estágio**, escolha **Editar**. 1. Em **Tratamento de solicitações não autorizadas**, selecione uma opção. 1. Escolha **Continuar**. 1. Revise as alterações e selecione **Salvar alterações**. ------ #### [ AWS CLI ] O comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) indicado abaixo atualiza um estágio para lidar com solicitações não autorizadas recusando a solicitação com o código de status 403: ``` aws apigateway update-stage / --rest-api-id a1b2c3 / --stage-name 'prod' / --patch-operations 'op=replace,path=/*/*/caching/unauthorizedCacheControlHeaderStrategy,value="FAIL_WITH_403"' ``` ------ ## Exemplo do CloudFormation de um estágio com cache O modelo CloudFormation a seguir cria um exemplo de API, provisiona um cache de `0.5` GB para o estágio `Prod` e ativa o cache em nível de método para todos os métodos `GET`. **Importante** O armazenamento em cache é cobrado por hora com base no tamanho do cache escolhido. O armazenamento em cache não é elegível para o nível gratuito da AWS. Para obter mais informações, consulte [Preços do API Gateway](https://aws.amazon.com/api-gateway/pricing/). ### Exemplo de modelo 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 ``` # Compressão de carga útil para APIs REST no API Gateway O API Gateway permite que o cliente chame uma API com cargas compactadas usando uma das [codificações de conteúdo compatíveis](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). Por padrão, o API Gateway oferece suporte à descompactação da carga de solicitação do método. No entanto, você deve configurar sua API para habilitar a compactação da carga de resposta do método. Para habilitar a compactação em uma [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), defina a propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize) como um inteiro não negativo entre 0 e 10485760 (10 milhões de bytes) ao criar a API ou depois de criá-la. Para desabilitar a compactação na API, defina `minimumCompressionSize` como nulo ou remova-o por completo. É possível habilitar ou desabilitar a compactação de uma API usando o console do API Gateway, a AWS CLI ou a API REST do API Gateway. Se você deseja que a compactação seja aplicada em cargas de qualquer tamanho, defina o valor de `minimumCompressionSize` como zero. No entanto, a compactação de dados de um volume pequeno pode, na verdade, aumentar o volume final dos dados. Além disso, a compactação no API Gateway e a descompactação no cliente podem aumentar a latência geral e exigir mais tempo de computação. Você deve executar casos de teste com a sua API para determinar um valor ideal. O cliente pode enviar uma solicitação de API com uma carga compactada e um cabeçalho `Content-Encoding` apropriado para que o API Gateway descompacte e aplique os modelos de mapeamento adequados, antes de passar a solicitação para o endpoint de integração. Depois que a compactação for habilitada e a API for implantada, o cliente poderá receber uma resposta da API com uma carga compactada se ela especificar um cabeçalho `Accept-Encoding` apropriado na solicitação do método. Quando o endpoint de integração espera e retorna cargas JSON não compactadas, qualquer modelo de mapeamento que esteja configurado para uma carga JSON não compactada será aplicável para a carga compactada. Para uma carga de solicitação de método compactada, o API Gateway descompacta a carga, aplica o modelo de mapeamento e passa a solicitação mapeada para o endpoint de integração. Para uma carga de resposta de integração não compactada, o API Gateway aplica o modelo de mapeamento, compacta a carga mapeada e retorna a carga compactada para o cliente. **Topics** + [Habilitar a compactação de payload para uma API no API Gateway](api-gateway-enable-compression.md) + [Chamar um método de API com uma payload compactada no API Gateway](api-gateway-make-request-with-compressed-payload.md) + [Receber uma resposta da API com uma payload compactada no API Gateway](api-gateway-receive-response-with-compressed-payload.md) # Habilitar a compactação de payload para uma API no API Gateway É possível habilitar a compactação para uma API usando o console do API Gateway, a AWS CLI ou um SDK da AWS. Para uma API existente, implante a API depois de habilitar a compactação, para que a alteração entre em vigor. Para uma nova API, você pode implantar a API depois que a configuração da API for concluída. **nota** A codificação de conteúdo com a prioridade mais alta deve ser aquela compatível com o API Gateway. Se não for, a compactação não será aplicada à carga da resposta. **Topics** + [Habilitar a compactação de carga para uma API usando o console do API Gateway](#api-gateway-enable-compression-console) + [Habilitar a compactação de carga útil para uma API usando a AWS CLI](#api-gateway-enable-compression-cli) + [Codificação de conteúdo compatível com o API Gateway](#api-gateway-supported-content-encodings) ## Habilitar a compactação de carga para uma API usando o console do API Gateway O procedimento a seguir descreve como habilitar a compactação de carga para uma API. **Como habilitar a compactação de carga usando o console do API Gateway** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API existente ou crie uma nova. 1. No painel de navegação principal, selecione **Configurações da API**. 1. Na seção **Detalhes da API**, escolha **Editar**. 1. Ative a **Codificação de conteúdo** para habilitar a compactação da carga útil. Em **Tamanho mínimo do corpo**, insira um número para o tamanho da compactação (em bytes). Para desativar a compactação, desative a opção **Codificação de conteúdo**. 1. Escolha **Salvar alterações**. ## Habilitar a compactação de carga útil para uma API usando a AWS CLI O comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) indicado abaixo cria uma API com compactação de carga útil: ``` aws apigateway create-rest-api \ --name "My test API" \ --minimum-compression-size 0 ``` O comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) indicado abaixo habilita a compactação de carga útil para uma API existente: ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value=0 ``` A propriedade `minimumCompressionSize` tem um valor inteiro não negativo entre 0 e 10485760 (10 milhões de bytes). Ela mede o limite de compactação. Se o tamanho da carga útil é menor do que esse valor, a compactação ou descompactação não são aplicadas na carga. Ao configurar para zero, a compactação pode ser definida para qualquer tamanho da carga útil. O comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) indicado abaixo desativa a compactação de carga útil: ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value= ``` Você também pode definir `value` como uma string vazia `""` ou omitir a propriedade `value` completamente na chamada anterior. ## Codificação de conteúdo compatível com o API Gateway O API Gateway é compatível com as seguintes codificações de conteúdo: + `deflate` + `gzip` + `identity` O API Gateway também é compatível com o formato de cabeçalho `Accept-Encoding` a seguir, de acordo com a especificação [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4): + `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` # Chamar um método de API com uma payload compactada no API Gateway Para fazer uma solicitação da API com uma carga compactada, o cliente deve definir o cabeçalho `Content-Encoding` com uma das [codificações de conteúdo compatíveis](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). Suponha que você seja um cliente de API e queira chamar o método de API PetStore (`POST /pets`). Não chame o método usando esta saída JSON: ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Length: ... { "type": "dog", "price": 249.99 } ``` Em vez disso, você pode chamar o método com a mesma carga compactada usando a codificação 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 ``` Quando o API Gateway recebe a solicitação, ele verifica se a codificação de conteúdo especificada é compatível. Em seguida, ele tenta descompactar a carga com a codificação de conteúdo especificada. Se a descompactação for bem-sucedida, ele enviará a solicitação para o endpoint de integração. Se a codificação especificada não for compatível ou a carga fornecida não estiver compactada, o API Gateway retornará uma resposta com o erro `415 Unsupported Media Type`. O erro não será registrado em log no CloudWatch Logs se ele ocorrer na fase inicial de descompactação antes de sua API e etapa serem identificadas. # Receber uma resposta da API com uma payload compactada no API Gateway Ao fazer uma solicitação em uma API habilitada para compactação, o cliente pode optar por receber uma carga de resposta compactada de um determinado formato especificando um cabeçalho `Accept-Encoding` com uma [codificação de conteúdo compatível](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). O API Gateway só compacta a carga de resposta quando as seguintes condições são atendidas: + A solicitação de entrada tem o cabeçalho `Accept-Encoding` com uma codificação e formato de conteúdo compatíveis. **nota** Se o cabeçalho não estiver configurado, o valor padrão será `*` conforme definido na [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4). Nesse caso, o API Gateway não compacta a carga. Algum navegador ou cliente pode adicionar `Accept-Encoding` (por exemplo, `Accept-Encoding:gzip, deflate, br`) automaticamente para solicitações habilitadas para compactação. Isso pode ativar a compactação de carga útil no API Gateway. Sem uma especificação explícita dos valores de cabeçalho `Accept-Encoding` compatíveis, o API Gateway não compacta a carga. + A definição de `minimumCompressionSize` na API habilita a compactação. + A resposta de integração não tem um cabeçalho `Content-Encoding`. + O tamanho da carga da resposta de integração, após a aplicação do modelo de mapeamento adequado, é maior ou igual ao valor especificado em `minimumCompressionSize`. O API Gateway aplica qualquer modelo de mapeamento que estiver configurado para a resposta de integração antes de compactar a carga. Se a resposta de integração contiver um cabeçalho `Content-Encoding`, para o API Gateway, a carga da resposta de integração já estará compactada, e o processamento de compactação será ignorado. Como exemplo, veja a API PetStore e a seguinte solicitação: ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept: application/json ``` O backend responde à solicitação com uma carga JSON não compactada que é semelhante à seguinte: ``` 200 OK [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Para receber essa saída como uma carga compactada, o cliente da API pode enviar uma solicitação como esta: ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept-Encoding:gzip ``` O cliente recebe a resposta com um cabeçalho `Content-Encoding` e a carga codificada por GZIP semelhante a esta: ``` 200 OK Content-Encoding:gzip ... ���RP� J�)JV �:P^IeA*������+(�L �X�YZ�ku0L0B7!9��C#�&����Y��a���^�X ``` Quando a carga de resposta é compactada, a cobrança pela transferência de dados leva em conta apenas o tamanho dos dados compactados.