# 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 ```