Como configuro o API Gateway com minha própria distribuição do CloudFront?

Breve descrição

Se seus clientes de API estiverem geograficamente dispersos, considere usar um endpoint de API otimizado para borda no API Gateway. Esse tipo de endpoint atua como um endpoint regional com uma distribuição web do CloudFront gerenciada pela AWS para melhorar o tempo de conexão do cliente.

Para usar a rede global de entrega de conteúdo do CloudFront e manter mais controle sobre a distribuição, use uma API regional com uma distribuição web personalizada do CloudFront.

Resolução

Crie uma API regional no API Gateway. Em seguida, faça o seguinte:

Configure um método GET para sua API

1.    No console do API Gateway, selecione o nome da sua nova API regional.

2.    No painel Recursos, selecione Ações. Em seguida, selecione Criar método. Uma lista aparece sob o nó / resource.

3.    Selecione GET na lista. Em seguida, selecione o ícone de marca de seleção.

4.    Em / - GET - Configuração, para Tipo de integração, selecione Simular. Em seguida, selecione Salvar.
Observação: Uma integração simulada responde a qualquer solicitação recebida, o que ajuda nos testes.

Implante sua API e identifique o URL de invocação de sua API

1.    Implante sua API em um estágio.

2.    Na parte superior do painel do Stage Editor, copie o URL de invocação para sua área de transferência.

Exemplo de URL de API de invocação do API Gateway

https://restApiId.execute-api.region.amazonaws.com/stageName.

Teste sua API para obter uma resposta de 200 OK

Para confirmar que sua API retorna uma resposta de 200 OK, teste o URL de invocação da sua API usando o console do API Gateway, o aplicativo Postman ou o curl.

Para testar sua API para obter uma resposta de 200 OK usando curl

Com base no seu sistema operacional, execute um dos seguintes comandos:

Observação: substitua https://restApiId.execute-api.region.amazonaws.com/stageName pelo URL de invocação da sua API antes de executar qualquer um dos comandos a seguir.

Para Linux, use o seguinte comando:

curl -IX GET https://restApiId.execute-api.region.amazonaws.com/stageName

Para o Windows PowerShell, execute o seguinte comando:

curl https://restApiId.execute-api.region.amazonaws.com/stageName

Observação: se você receber um código de status diferente de uma resposta 200 OK, verifique o console para confirmar o seguinte:
Sua API é implantada em seu estágio.
Seu estágio é especificado em seu URL de invocação.

Crie uma distribuição web do CloudFront

1.    No console do CloudFront, selecione Criar distribuição.

2.    Na página Selecionar um método de entrega para seu conteúdo, em Web, selecione Começar.

3.    Na página Criar distribuição, para Nome de domínio de origem, cole o URL de invocação da sua API. Em seguida, exclua o nome provisório.

Exemplo de nome de domínio de origem

https://1a2bc3d456.execute-api.us-east-1.amazonaws.com

4.    Para Caminho de origem, insira o nome provisório da sua API com uma barra na frente (/stageName). Ou, se você mesmo quiser inserir o nome artístico ao invocar o URL, não insira um Caminho de origem.
Observação: inserir um nome artístico incorreto para o Caminho de origem ao invocar a distribuição do CloudFront às vezes produz um erro. Por exemplo, um erro de solicitação não autorizada que retorna a mensagem “Token de autenticação ausente” e um código de resposta 403 Forbidden.

5.    Para o protocolo SSL de origem mínima, é uma prática recomendada escolher o TLSv1.2. Não selecione SSLv3. O API Gateway não oferece suporte ao protocolo SSLv3.

6.    Para a Política de Protocolo de Origem, selecione Somente HTTPS.
Observação: o API Gateway não oferece suporte a endpoints não criptografados (HTTP). Para obter mais informações, consulte Perguntas frequentes sobre o Amazon API Gateway.

7.    (Opcional) Para encaminhar cabeçalhos personalizados para sua origem, insira um ou mais cabeçalhos personalizados para os cabeçalhos personalizados do Origin.
Observação: há vários cabeçalhos personalizados que o CloudFront não pode encaminhar para sua origem.

8.    Siga as instruções na seção Se você estiver usando a autenticação do IAM para sua API ou nomes de domínio personalizados para sua distribuição, se aplicável.

9.    (Opcional) Em Configurações de distribuição, defina as configurações adicionais que você deseja personalizar.

10.    Selecione Criar distribuição.

11.    Aguarde até que sua distribuição seja implantada. Isso leva de 15 a 20 minutos. Quando seu Status aparece como Implantado no console, a distribuição está pronta.

Para obter mais informações, consulte Criação de uma distribuição.

Teste sua distribuição web do CloudFront

1.    No console do CloudFront, copie o nome de domínio da sua distribuição para a área de transferência.

Exemplo de nome de domínio não personalizado

a222222bcdefg5.cloudfront.net.

2.    Teste o nome de domínio para obter uma resposta de 200 OK usando qualquer um dos comandos mencionados anteriormente na seção Teste sua API. Se você receber um código de erro 500 do servidor, talvez a distribuição não seja implantada. Se você não obtiver resposta, o registro DNS do CloudFront ainda não foi propagado. Em ambos os casos, confirme se passaram de 15 a 20 minutos desde que você criou sua distribuição. Em seguida, repita o procedimento.

Importante: se você ativou a autenticação do AWS Identity and Access Management (IAM) em um método para um recurso de API específico, deverá acrescentar o nome do recurso ao final do nome do domínio de distribuição ao invocar sua API. O URL de invocação completo (incluindo o nome do recurso) é semelhante a um dos exemplos a seguir. A saída depende de você ter inserido um Caminho de origem ao criar a distribuição:

Exemplo de URL de API de invocação do API Gateway com um caminho de origem

https://distributionDomainName/stageName/resourceName

Exemplo de URL de API de invocação do API Gateway sem um caminho de origem

https://distributionDomainName/resourceName

Para obter mais informações sobre testes, consulte Como eu ativo a autenticação do IAM para APIs do API Gateway?

Sua API agora usa a distribuição web que você criou. Os recursos estão acessíveis na URL da API CloudFront.

Se você estiver usando autenticação IAM para sua API ou nomes de domínio personalizados para sua distribuição web do CloudFront

Por padrão, o CloudFront não encaminha cabeçalhos de autorização recebidos para a origem (para esse caso de uso, API Gateway). Se você estiver usando a autenticação do IAM para sua API ou nomes de domínio personalizados para sua distribuição, você deve fazer o seguinte:

(Para autenticação do IAM) Adicione o cabeçalho de autorização à sua lista de permissões do CloudFront

1.    Se não tiver sido concluído anteriormente, siga as etapas 1 a 7 na seção Crie uma distribuição web do CloudFront deste artigo.

2.    Na página Criar distribuição, para configurações de cache e solicitação de origem, selecione Usar uma política de cache e uma política de solicitação de origem. Em seguida, em Política de cache, selecione uma política de cache existente ou crie uma nova política de cache que adicione o cabeçalho de autorização à sua lista de permissões do CloudFront.

3.    Se você usar uma política de cache existente, para Cache baseado em cabeçalhos de solicitação selecionados, selecione Lista branca. Em seguida, para cabeçalhos da lista branca, adicione Autorização à lista de cabeçalhos permitidos.

Importante: se você alterar a configuração Cache com base nos cabeçalhos de solicitação selecionados para Todos, ou se você permitir o cabeçalho Host, sua configuração não funcionará. Para obter mais informações, consulte Armazenar conteúdo em cache com base nos cabeçalhos da solicitação.

4.    (Opcional) Para testar a configuração, faça o seguinte:
Crie a assinatura Signature Versão 4 necessária para seu endpoint do API Gateway de maneira programática. Para o valor do host, insira seu URL de invocação do API Gateway. Para o valor do endpoint, insira sua URL de distribuição web do CloudFront.

Exemplo de URL de invocação do API Gateway

<api-id>.execute.<region>.amazon.com

Exemplo de URL de distribuição web do CloudFront

dxxxxx.cloudfront.net

Observação: se você estiver usando o aplicativo Postman, na guia Autorização, em Tipo, selecioneAWS Signature. Em seguida, insira a Chave de acesso e a Chave secreta. Os cabeçalhos necessários são gerados pelo Postman usando as credenciais que você insere.

Em seguida, envie a solicitação de API para a distribuição do CloudFront usando o cabeçalho de autorização (e todos os SignedHeaders) gerados a partir do processo Signature Version 4.

(Para nomes de domínio personalizados ou autenticação IAM) Configure um nome de domínio personalizado regional no API Gateway para acessar sua API

1.    Crie uma nova API regional no API Gateway ou altere sua API de API Gateway otimizada para borda para uma API regional.

2.    Configure um nome de domínio regional personalizado para a API e crie um mapeamento de API para sua API.
Observação: use esse nome de domínio personalizado ao acessar sua API por meio do CloudFront.

3.    Crie uma distribuição web do CloudFront seguindo as instruções na seção Crie uma distribuição web do CloudFront deste artigo, com uma exceção. Na etapa 3, para Nome de domínio de origem, insira seu nome de domínio de destino do API Gateway em vez do URL de invocação da sua API.
Observação: encontre seu nome de domínio de destino do API Gateway na configuração do Endpoint dos detalhes do seu domínio personalizado.

Exemplo de nome de domínio de destino do API Gateway

d-xxxx..execute-api.<region>.amazonaws.com

4.    Na página Criar distribuição, para configurações de cache e solicitação de origem, selecione Usar uma política de cache e uma política de solicitação de origem. Em seguida, em Política de cache, selecione uma política de cache existente ou crie uma nova política de cache que adicione o cabeçalho de autorização e Host à sua lista de permissões do CloudFront.

5.    Se você usar uma política de cache existente, para Cache baseado em cabeçalhos de solicitação selecionados, selecione Lista branca. Em seguida, para cabeçalhos de lista branca, adicione Autorização e Host à lista de cabeçalhos permitidos.

6.    Em Configurações de distribuição, em Nome de domínio alternativo, insira o nome de domínio personalizado que você criou.

7.    Para Certificado SSL, selecione Certificado SSL personalizado. Em seguida, adicione o certificado do AWS Certificate Manager (ACM) para esse domínio.

8. Depois de implantar a distribuição web do CloudFront, configure o registro DNS para mapear o domínio personalizado para a distribuição web do CloudFront. Faça isso criando um alias ou um registro CNAME. Para obter mais informações, consulte Usar URLs personalizados adicionando nomes de domínio alternativos (CNAMEs).

9.    (Opcional) Para testar a configuração, crie uma solicitação assinada do Signature Versão 4 para seu nome de domínio personalizado de forma programática.
Observação: o aplicativo Postman pode ser usado para testar a configuração.

---

Informações relacionadas

Inicializar a configuração da API REST no API Gateway

Selecionar um tipo de endpoint para configurar uma API do API Gateway

Importar uma API otimizada para borda para o API Gateway