Configurar um estágio para uma API REST no API Gateway

Um estágio é uma referência designada para uma implantação, que é um snapshot da API. Use um Stage para gerenciar e otimizar uma implantação específica. Por exemplo, você pode definir configurações do estágio para ativar o cache, personalizar a limitação de solicitação, configurar o registro em log, definir variáveis do estágio ou anexar uma versão de canary para testes. A seção a seguir mostra como criar e configurar seu palco.

Criar um novo estágio

Após a implantação inicial, você pode adicionar mais estágio e associá-los a implantações existentes. Você pode usar o console do API Gateway para criar um estágio ou escolher um estágio existente ao implantar uma API. Em geral, você pode adicionar um novo estágio a uma implantação de API antes de reimplantar essa API. Para criar um estágio usando o console do API Gateway, siga estas etapas:

1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

2. Escolha uma API REST.

3. No painel de navegação principal, selecione Estágios em uma API.

4. No painel de navegação Estágios, selecione Criar estágio.

5. Em Nome do estágio, insira um nome; por exemplo, prod.

   nota

   Nomes de estágio podem conter apenas caracteres alfanuméricos, hífens e sublinhados. O tamanho máximo é de 128 caracteres.

6. (Opcional). Em Descrição, insira uma descrição do estágio.

7. Em Implantação, selecione a data e a hora da implantação de API existente que você deseja associar a esse estágio.

8. Em Configurações adicionais, é possível especificar configurações adicionais para o estágio.

9. Selecione Criar estágio.

Modifique as configurações de armazenamento.

Depois de uma implantação bem-sucedida de uma API, o estágio é preenchido com as configurações padrão. É possível usar o console ou a API REST do API Gateway para alterar as configurações de estágio, incluindo o registro em log e o armazenamento em cache de APIs. As etapas a seguir mostram como fazer isso usando o Editor de estágio do console do API Gateway.

1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

2. Escolha uma API REST.

3. No painel de navegação principal, selecione Estágios em uma API.

4. No painel Estágios, escolha o nome do estágio.

5. Na seção Detalhes do estágio, selecione Editar.

6. (Opcional) Em Descrição do estágio, edite a descrição.

7. Em Configurações adicionais, você vai modificar as seguintes configurações:

   Configurações de cache

   Para habilitar o armazenamento em cache da API para o estágio, ative Provisionar cache de APIs. Depois, configure Armazenamento em cache padrão no nível de método, Capacidade do cache, Criptografar dados do cache, Tempo de vida (TTL) do cache, bem como os requisitos para invalidação de cache por chave.

   O armazenamento em cache não estará ativo até você ativar o cache padrão no nível de método ou ativar o cache no nível de método para um método específico.

   Para obter mais informações sobre as configurações de cache, consulte Configurações de cache para APIs REST no API Gateway.

   nota

   Se você habilitar o armazenamento em cache da API para um estágio da API, sua conta da AWS poderá ser cobrada por armazenamento em cache da API. O armazenamento em cache não está qualificado para o nível gratuito da AWS.

   Configurações de controle de utilização

   Para definir destinos de controle de utilização em nível de estágio para todos os métodos associados a essa API, ative Controle de utilização.

   Em Rate (Taxa), insira uma taxa alvo. Essa é a taxa, em solicitações por segundo, em que os tokens são adicionados ao bucket do token. Essa taxa em nível de estágio não deve ser superior à taxa em nível de conta, conforme especificado em Cotas do API Gateway para configurar e executar uma API REST.

   Em Burst (Intermitência), insira uma taxa de intermitência alvo. A taxa de expansão é a capacidade do bucket do token. Isso permite mais solicitações por um período do que a taxa alvo. Essa taxa de intermitência no nível do estágio não deve ser superior à taxa de intermitência no nível da conta, conforme especificado em Cotas do API Gateway para configurar e executar uma API REST.

   nota

   As taxas de controle de utilização não são limites rígidos e são aplicadas de acordo com os melhores esforços. Em alguns casos, os clientes podem exceder os alvos definidos por você. Não dependa do controle de utilização para controlar custos ou bloquear o acesso a uma API. Considere usar AWS Budgets para monitorar custos e AWS WAF para gerenciar solicitações de APIs.

   Configurações de firewall e certificado

   Para associar uma ACL da web do AWS WAF ao estágio, selecione uma ACL da web na lista suspensa Web ACL. Se desejar, selecione Bloquear solicitações de API se não for possível avaliar a WebACL (Falha - Fechar).

   Para selecionar um certificado de cliente para o estágio, selecione um certificado no menu suspenso Certificado do cliente.

8. Escolha Salvar.

9. Para habilitar o Amazon CloudWatch Logs para todos os métodos associados a esse estágio da API do API Gateway, na seção Logs e rastreamento, selecione Editar.

   nota

   Para habilitar o CloudWatch Logs, também é necessário especificar o ARN de um perfil do IAM que permita ao API Gateway gravar informações no CloudWatch Logs em nome do usuário. Para isso, escolha Settings (Configurações) no painel de navegação principal APIs. Depois, em Perfil do log do CloudWatch, insira o ARN de um perfil do IAM.

   Para cenários de aplicações comuns, a função do IAM poderá anexar a política gerenciada AmazonAPIGatewayPushToCloudWatchLogs, que contém a seguinte instrução de política de acesso:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "logs:CreateLogGroup",
                   "logs:CreateLogStream",
                   "logs:DescribeLogGroups",
                   "logs:DescribeLogStreams",
                   "logs:PutLogEvents",
                   "logs:GetLogEvents",
                   "logs:FilterLogEvents"
               ],
               "Resource": "*"
           }
       ]
   }

   A função do IAM também deve conter a seguinte instrução de relação de confiança:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "Service": "apigateway.amazonaws.com"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }

   Para obter mais informações sobre o CloudWatch, consulte o Guia do usuário do Amazon CloudWatch.

10. Selecione um nível de registro em log no menu suspenso CloudWatch Logs. Os níveis de registro em log são os seguintes:

    • Desativado: o registro em log não está ativado neste estágio.

    • Somente erros: o registro em log está habilitado somente para erros.

    • Logs de erros e informações: o registro em log está habilitado para todos os eventos.

    • Logs completos de solicitações e respostas: o registro em log detalhado está habilitado para todos os eventos. Isso pode ser útil para solucionar problemas de APIs, mas pode resultar no registro de dados confidenciais.

      nota

      Recomendamos que você não use Logs completos de solicitações e respostas para APIs de produção.

11. Selecione Métricas detalhadas para que o API Gateway relate para o CloudWatch as métricas de API de API calls, Latency, Integration latency, 400 errors e 500 errors. Para saber mais sobre o CloudWatch, consulte Monitoramento básico e monitoramento detalhado no Guia do usuário do Amazon CloudWatch.

    Importante

    Sua conta será cobrada pelo acesso a métricas do CloudWatch em nível de método, mas não pelas métricas em nível de API ou estágio.

12. Para habilitar o registro em log de acesso a um destino, ative Registro em log de acesso personalizado.

13. Em ARN de destino de logs de acesso, insira o ARN de um grupo de logs ou um fluxo do Firehose.

    O formato do ARN para o Firehose é arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}. O nome do fluxo do Firehose deve ser amazon-apigateway-{your-stream-name}.

14. Em Formato do log, insira um formato de log. Para saber mais sobre exemplos de formatos de log, consulte Formatos de log do CloudWatch para o API Gateway.

15. Para habilitar o rastreamento AWS X-Ray para o estágio da API, selecione Rastreamento com X-Ray. Para ter mais informações, consulte Rastrear solicitações de usuário para APIs REST usando o X-Ray no API Gateway.

16. Selecione Save changes. Implante a API novamente para que as novas configurações entrem em vigor.

Substituir configurações em nível de estágio

Depois de personalizar as configurações em nível de estágio, você pode substituí-las para cada método de API. Algumas dessas opções podem gerar cobranças adicionais na Conta da AWS.

1. Para configurar substituições de método, expanda o estágio no painel de navegação secundário e selecione um método.

   

2. Em Substituições de método, selecione Editar.

3. Para ativar as configurações do CloudWatch em nível de método, para o CloudWatch Logs, selecione um nível de registro em log.

4. Para ativar as métricas detalhadas em nível de método, selecione Métricas detalhadas. Sua conta será cobrada pelo acesso a métricas do CloudWatch em nível de método, mas não pelas métricas em nível de API ou estágio.

5. Para ativar o controle de utilização em nível de método, selecione Controle de utilização. Insira as opções apropriadas em nível de método. Para saber mais sobre o controle de utilização, consulte Controle de utilização das solicitações das APIs REST para ter um melhor throughput no API Gateway.

6. Para configurar o cache no nível de método, selecione Ativar cache de método. Se você alterar a configuração de armazenamento padrão em cache no nível de método nos Detalhes do estágio, isso não afetará essa configuração.

7. Escolha Salvar.