Amazon API Gateway

619 Pages·2017·9.64 MB·English

by  Amazon Web Services

Amazon API Gateway
Guia do desenvolvedor
Amazon API Gateway Guia do desenvolvedor
Amazon API Gateway: Guia do desenvolvedor
Copyright © 2022 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
As marcas comerciais e imagens de marcas da Amazon não podem ser usadas no contexto de nenhum produto
ou serviço que não seja da Amazon, nem de qualquer maneira que possa gerar confusão entre os clientes ou que
deprecie ou desprestigie a Amazon. Todas as outras marcas comerciais que não pertencem à Amazon pertencem a
seus respectivos proprietários, que podem ou não ser afiliados, conectados ou patrocinados pela Amazon.
Amazon API Gateway Guia do desenvolvedor
Table of Contents
O que é o Amazon API Gateway?........................................................................................................ 1
Arquitetura do API Gateway......................................................................................................... 1
Recursos do API Gateway........................................................................................................... 2
Casos de uso do API Gateway ..................................................................................................... 3
Usar o API Gateway para criar APIs REST............................................................................ 3
Usar o API Gateway para criar APIs HTTP ............................................................................ 3
Usar o API Gateway para criar APIs do WebSocket................................................................ 4
Quem usa o API Gateway?................................................................................................. 4
Acessar o API Gateway.............................................................................................................. 5
Parte da infraestrutura sem servidor da AWS................................................................................. 5
Saiba como começar a usar o Amazon API Gateway....................................................................... 6
Conceitos do API Gateway.......................................................................................................... 6
Escolher entre APIs HTTP e REST............................................................................................... 9
........................................................................................................................................ 9
Endpoint type................................................................................................................... 10
Segurança....................................................................................................................... 10
Autorização...................................................................................................................... 10
Gerenciamento de APIs..................................................................................................... 11
Desenvolvimento............................................................................................................... 11
Monitoramento.................................................................................................................. 12
Integrações...................................................................................................................... 12
Pré-requisitos................................................................................................................................... 14
Cadastrar-se em uma Conta da AWS.......................................................................................... 14
Criar um usuário administrador................................................................................................... 14
Conceitos básicos............................................................................................................................. 16
Etapa 1: Criar uma função do Lambda......................................................................................... 16
Etapa 2: criar uma API HTTP..................................................................................................... 17
Etapa 3: testar sua API............................................................................................................. 18
(Opcional) Etapa 4: Limpar......................................................................................................... 18
Próximas etapas....................................................................................................................... 19
Tutoriais e workshops........................................................................................................................ 21
Tutoriais da API REST.............................................................................................................. 21
Criar uma API com integração do Lambda........................................................................... 22
Tutorial: Criar uma API REST importando um exemplo........................................................... 39
Criar uma API com integração HTTP................................................................................... 47
Tutorial: Criar uma API com integração privada..................................................................... 82
Tutorial: Criar uma API com integração da AWS.................................................................... 84
Tutorial: API Calc com três integrações.............................................................................. 89
Tutorial: Criar uma API REST como um proxy do Amazon S3 no API Gateway......................... 109
Tutorial: Criar uma API REST como um proxy do Amazon Kinesis.......................................... 135
Criar uma API REST privada............................................................................................ 174
Tutoriais da API HTTP............................................................................................................. 178
API CRUD com Lambda e DynamoDB............................................................................... 179
Integração privada com o Amazon ECS............................................................................. 186
Tutoriais da API WebSocket..................................................................................................... 192
Aplicação de bate-papo WebSocket................................................................................... 192
Trabalhar com APIs REST............................................................................................................... 197
Desenvolver........................................................................................................................... 197
Criar e configurar............................................................................................................ 197
Controle de acesso......................................................................................................... 230
Integrações.................................................................................................................... 282
Validação da solicitação................................................................................................... 325
Transformações de dados................................................................................................ 338
Respostas do gateway..................................................................................................... 386
iii
Amazon API Gateway Guia do desenvolvedor
CORS............................................................................................................................ 393
Tipos de mídia binária..................................................................................................... 401
Invoke........................................................................................................................... 424
OpenAPI........................................................................................................................ 446
Publicar................................................................................................................................. 456
Implantando uma API REST............................................................................................. 456
Nomes de domínios personalizados................................................................................... 487
Otimizar................................................................................................................................. 509
Configurações de cache................................................................................................... 510
Codificação de conteúdo.................................................................................................. 516
Distribuir................................................................................................................................ 520
Planos de uso................................................................................................................ 520
Documentação de API..................................................................................................... 535
Geração de SDKs........................................................................................................... 579
Portal do desenvolvedor................................................................................................... 595
Vender suas APIs como SaaS.......................................................................................... 603
Proteger................................................................................................................................. 606
TLS mútuo..................................................................................................................... 606
Certificados do cliente...................................................................................................... 611
AWS WAF..................................................................................................................... 638
Limitação....................................................................................................................... 640
APIs privadas................................................................................................................. 642
Monitor.................................................................................................................................. 648
Métricas do CloudWatch.................................................................................................. 649
Logs do CloudWatch....................................................................................................... 655
Kinesis Data Firehose...................................................................................................... 658
X-Ray............................................................................................................................ 660
Trabalhar com APIs HTTP............................................................................................................... 671
Desenvolver........................................................................................................................... 671
Criar uma API HTTP....................................................................................................... 672
Rotas............................................................................................................................ 673
Controle de acesso......................................................................................................... 674
Integrações.................................................................................................................... 683
CORS............................................................................................................................ 696
Mapeamento de parâmetros............................................................................................. 698
OpenAPI........................................................................................................................ 702
Publicar................................................................................................................................. 708
Stages........................................................................................................................... 709
Nomes de domínios personalizados................................................................................... 710
Proteger................................................................................................................................. 715
Limitação....................................................................................................................... 715
TLS mútuo..................................................................................................................... 716
Monitor.................................................................................................................................. 720
Métricas......................................................................................................................... 721
Registro em log.............................................................................................................. 722
Solução de problemas............................................................................................................. 728
Integrações do Lambda.................................................................................................... 728
Autorizadores de JWT..................................................................................................... 730
Trabalhar com APIs WebSocket........................................................................................................ 732
Sobre APIs WebSocket............................................................................................................ 732
Gerenciar usuários conectados e aplicativos do cliente......................................................... 733
Invocar a integração de seu backend................................................................................. 734
Enviar dados dos serviços de backend para clientes conectados............................................ 737
Expressões de seleção do WebSocket............................................................................... 737
Desenvolver........................................................................................................................... 742
Criar e configurar............................................................................................................ 743
Rotas............................................................................................................................ 744
iv
Amazon API Gateway Guia do desenvolvedor
Controle de acesso......................................................................................................... 749
Integrações.................................................................................................................... 752
Validação da solicitação................................................................................................... 757
Transformações de dados................................................................................................ 757
Tipos de mídia binária..................................................................................................... 765
Invoke........................................................................................................................... 765
Publicar................................................................................................................................. 767
Stages........................................................................................................................... 767
Implantar uma API WebSocket.......................................................................................... 769
Nomes de domínios personalizados................................................................................... 771
Proteger................................................................................................................................. 774
Controle de utilização no nível da conta por região.............................................................. 775
Limitação em nível de rota............................................................................................... 775
Monitor.................................................................................................................................. 775
Métricas......................................................................................................................... 776
Registro em log.............................................................................................................. 777
ARNs do API Gateway.................................................................................................................... 781
Recursos de API HTTP e API WebSocket.................................................................................. 781
Recursos de API REST........................................................................................................... 783
execute-api (APIs HTTP, WebSocket e REST)........................................................................ 785
Extensões do OpenAPI.................................................................................................................... 786
x-amazon-apigateway-any-method ..................................................................................... 787
Exemplos de x-amazon-apigateway-any-method.................................................................. 787
x-amazon-apigateway-cors........................................................................................................ 788
Exemplo de x-amazon-apigateway-cors.............................................................................. 788
x-amazon-apigateway-api-key-source.............................................................................. 789
Exemplo de x-amazon-apigateway-api-key-source................................................................ 789
x-amazon-apigateway-auth................................................................................................ 789
Exemplo de x-amazon-apigateway-auth.............................................................................. 790
x-amazon-apigateway-authorizer ..................................................................................... 790
Exemplos de x-amazon-apigateway-authorizer para APIs REST............................................. 792
Exemplos de x-amazon-apigateway-authorizer para APIs HTTP............................................. 794
x-amazon-apigateway-authtype......................................................................................... 795
Exemplo de x-amazon-apigateway-authtype........................................................................ 796
Consulte também............................................................................................................ 797
x-amazon-apigateway-binary-media-type..................................................................................... 797
Exemplo de x-amazon-apigateway-binary-media-types.......................................................... 797
x-amazon-apigateway-documentation......................................................................................... 797
Exemplo de x-amazon-apigateway-documentation................................................................ 798
x-amazon-apigateway-endpoint-configuration............................................................................... 798
Exemplos de x-amazon-apigateway-endpoint-configuration.................................................... 799
x-amazon-apigateway-gateway-responses................................................................................... 799
Exemplo de x-amazon-apigateway-gateway-responses......................................................... 800
x-amazon-apigateway-gateway-responses.gatewayResponse......................................................... 800
Exemplo de x-amazon-apigateway-gateway-responses.gatewayResponse............................... 801
x-amazon-apigateway-gateway-responses.responseParameters..................................................... 801
x-amazon-apigateway-gateway-responses.responseParameters example................................. 801
x-amazon-apigateway-gateway-responses.responseTemplates....................................................... 802
Exemplo de x-amazon-apigateway-gateway-responses.responseTemplates.............................. 802
x-amazon-apigateway-importexport-version................................................................................. 802
x-amazon-apigateway-importexport-version example............................................................. 802
x-amazon-apigateway-integration................................................................................... 803
Exemplos de x-amazon-apigateway-integration.................................................................... 806
x-amazon-apigateway-integrations.............................................................................................. 807
Exemplo de x-amazon-apigateway-integrations.................................................................... 808
x-amazon-apigateway-integration.requestTemplates...................................................................... 809
Exemplo de x-amazon-apigateway-integration.requestTemplates............................................ 809
v
Amazon API Gateway Guia do desenvolvedor
x-amazon-apigateway-integration.requestParameters.................................................................... 810
Exemplo de x-amazon-apigateway-integration.requestParameters......................... 810
x-amazon-apigateway-integration.responses................................................................................ 811
Exemplo de x-amazon-apigateway-integration.responses ........................................ 812
x-amazon-apigateway-integration.response.................................................................................. 812
Exemplo de x-amazon-apigateway-integration.response......................................... 813
x-amazon-apigateway-integration.responseTemplates................................................................... 814
Exemplo de x-amazon-apigateway-integration.responseTemplate............................................ 814
x-amazon-apigateway-integration.responseParameters.................................................................. 814
Exemplo de x-amazon-apigateway-integration.responseParameters....................... 815
x-amazon-apigateway-integration.tlsConfig.................................................................................. 815
Exemplos x-amazon-apigateway-integration.tlsConfig............................................................ 816
x-amazon-apigateway-minimum-compression-size........................................................................ 817
Exemplo de x-amazon-apigateway-minimum-compression-size............................................... 817
x-amazon-apigateway-policy...................................................................................................... 817
Exemplo de x-amazon-apigateway-policy ................................................................... 817
x-amazon-apigateway-request-validator....................................................................................... 818
Exemplo de x-amazon-apigateway-request-validator ............................................... 818
x-amazon-apigateway-request-validators..................................................................................... 818
Exemplo de x-amazon-apigateway-request-validators............................................. 819
x-amazon-apigateway-request-validators.requestValidator.............................................................. 819
Exemplo de x-amazon-apigateway-request-validators.requestValidator.............. 820
x-amazon-apigateway-tag-value................................................................................................. 820
Exemplo de x-amazon-apigateway-tag-value.............................................................. 820
Segurança...................................................................................................................................... 822
Proteção de dados.................................................................................................................. 822
Criptografia de dados...................................................................................................... 823
Privacidade do tráfego entre redes.................................................................................... 824
Identity and Access Management.............................................................................................. 824
Público.......................................................................................................................... 824
Autenticar com identidades............................................................................................... 825
Gerenciamento do acesso usando políticas......................................................................... 827
Como o Amazon API Gateway funciona com o IAM............................................................. 828
Exemplos de políticas baseadas em identidade................................................................... 832
Exemplos de políticas baseadas em recursos...................................................................... 838
Solução de problemas..................................................................................................... 838
Uso de funções vinculadas a serviço................................................................................. 840
Registro em log e monitoramento.............................................................................................. 843
Trabalhar com o AWS CloudTrail...................................................................................... 844
Trabalhar com o AWS Config........................................................................................... 846
Validação de conformidade....................................................................................................... 849
Resiliência.............................................................................................................................. 849
Segurança da infraestrutura...................................................................................................... 850
Análise de configuração e vulnerabilidade................................................................................... 850
Práticas recomendadas............................................................................................................ 850
Atribuição de tags (tagging).............................................................................................................. 852
Recursos do API Gateway que podem ser marcados................................................................... 852
Herança de tags na API do Amazon API Gateway V1.......................................................... 853
Restrições de tags e convenções de uso ............................................................................ 854
Controle de acesso baseado em atributos.................................................................................. 854
Exemplo 1: limitar ações com base em tags de recursos....................................................... 855
Exemplo 2: limitar ações com base em tags na solicitação.................................................... 855
Exemplo 3: negar ações com base em tags de recurso........................................................ 856
Exemplo 4: permitir ações com base em tags de recursos..................................................... 857
Exemplo 5: Permitir ações baseadas em chaves de tag de recurso......................................... 857
Referências de API......................................................................................................................... 859
Cotas e observações importantes...................................................................................................... 860
vi
Amazon API Gateway Guia do desenvolvedor
Cotas no nível da conta do API Gateway, por região.................................................................... 860
Cotas de API HTTP................................................................................................................ 861
.................................................................................................................................... 861
Cotas do API Gateway para configurar e executar uma API de WebSocket...................................... 862
Cotas do API Gateway para configurar e executar uma API REST.................................................. 863
Cotas do API Gateway para criação, implantação e gerenciamento de uma API................................ 865
Observações importantes......................................................................................................... 867
Observações importantes para APIs REST e do WebSocket.................................................. 867
Observações importantes para APIs do WebSocket............................................................. 867
Observações importantes para APIs REST......................................................................... 868
Histórico do documento.................................................................................................................... 872
Atualizações anteriores............................................................................................................ 878
Glossário da AWS........................................................................................................................... 885
vii
Amazon API Gateway Guia do desenvolvedor
Arquitetura do API Gateway
O que é o Amazon API Gateway?
O Amazon API Gateway é um serviço da AWS para criação, publicação, manutenção, monitoramento e
proteção de APIs REST e WebSocket em qualquer escala. Os desenvolvedores de API podem criar APIs
que acessem a AWS ou outros web services, bem como dados armazenados na Nuvem AWS. Como
um desenvolvedor de APIs do API Gateway, é possível criar APIs para uso em suas próprias aplicações
cliente. Ou você pode disponibilizar suas APIs para desenvolvedores de aplicativos de terceiros. Para
obter mais informações, consulte the section called “Quem usa o API Gateway?” (p. 4).
O API Gateway cria APIs RESTful que:
• São baseadas em HTTP.
• Habilitam a comunicação cliente-servidor sem estado.
• Implementam os métodos HTTP padrão, como GET, POST, PUT, PATCH e DELETE.
Para obter mais informações sobre APIs REST do API Gateway e APIs HTTP, consulte the section called
“Escolher entre APIs HTTP e REST ” (p. 9), Trabalhar com APIs HTTP (p. 671), the section called
“Usar o API Gateway para criar APIs REST” (p. 3) e the section called “Criar e configurar” (p. 197).
O API Gateway cria APIs WebSocket que:
• Seguem o protocolo WebSocket, que permite a comunicação full-duplex entre cliente e servidor com
estado.
• Roteiam mensagens recebidas com base no conteúdo da mensagem.
Para obter mais informações sobre APIs WebSocket do API Gateway, consulte the section called
“Usar o API Gateway para criar APIs do WebSocket” (p. 4) e the section called “Sobre APIs
WebSocket” (p. 732).
Tópicos
• Arquitetura do API Gateway (p. 1)
• Recursos do API Gateway (p. 2)
• Casos de uso do API Gateway (p. 3)
• Acessar o API Gateway (p. 5)
• Parte da infraestrutura sem servidor da AWS (p. 5)
• Saiba como começar a usar o Amazon API Gateway (p. 6)
• Conceitos do Amazon API Gateway (p. 6)
• Escolher entre APIs HTTP e REST (p. 9)
Arquitetura do API Gateway
O diagrama a seguir mostra a arquitetura do API Gateway.
1
Amazon API Gateway Guia do desenvolvedor
Recursos do API Gateway
Este diagrama ilustra como as APIs criadas no Amazon API Gateway proporcionam a você ou a
seus clientes desenvolvedores uma experiência de desenvolvedor integrada e consistente para criar
aplicações sem servidor da AWS. O API Gateway processa todas as tarefas relacionadas à aceitação e
ao processamento de até centenas de milhares de chamadas simultâneas de APIs. As tarefas incluem
gerenciamento de tráfego, controle de autorização e acesso, monitoramento e gerenciamento de versão
de APIs.
O API Gateway atua como uma “porta frontal” para aplicações acessarem dados, lógica de negócios
ou funcionalidade de seus serviços de backend, como cargas de trabalho executadas no Amazon
Elastic Compute Cloud (Amazon EC2), código executado no AWS Lambda, qualquer aplicação Web ou
aplicações de comunicação em tempo real.
Recursos do API Gateway
O Amazon API Gateway oferece recursos como os seguintes:
• Suporte para APIs com estado (WebSocket (p. 732)) e sem estado (HTTP (p. 671)) e
REST (p. 197).
• Mecanismos de autenticação (p. 230) poderosos e flexíveis, como políticas do , funções do
autorizador do e grupos de usuários do AWS Identity and Access Management.
• Portal do desenvolvedor (p. 595) para publicar suas APIs.
• Implantações de versão Canary (p. 475) para lançar alterações com segurança.
• Registro em log e monitoramento do CloudTrail (p. 844) do uso e alterações de API.
• Registro de acesso em logs e registro de execução em logs do CloudWatch, incluindo a capacidade
de definir alarmes. Para obter mais informações, consulte the section called “Métricas do
CloudWatch” (p. 649) e the section called “Métricas” (p. 776).
• Capacidade de usar modelos do AWS CloudFormation para permitir a criação de APIs. Para obter mais
informações, consulte Referência de tipos de recursos do Amazon API Gateway e Referência de tipos
de recursos do Amazon API Gateway V2.
• Suporte para nomes de domínio personalizados (p. 487).
• Integração ao AWS WAF (p. 638) para proteger suas APIs contra explorações comuns da web.
• Integração com latências de desempenho AWS X-Ray (p. 660) para compreensão e triagem.
2
Amazon API Gateway Guia do desenvolvedor
Casos de uso do API Gateway
Para obter uma lista completa das versões de recursos do API Gateway, consulte Histórico do
documento (p. 872).
Casos de uso do API Gateway
Tópicos
• Usar o API Gateway para criar APIs REST (p. 3)
• Usar o API Gateway para criar APIs HTTP (p. 3)
• Usar o API Gateway para criar APIs do WebSocket (p. 4)
• Quem usa o API Gateway? (p. 4)
Usar o API Gateway para criar APIs REST
Uma API REST do API Gateway é composta por recursos e métodos. Um recurso é uma entidade lógica
que um aplicativo pode acessar através de um caminho de recurso. Um método corresponde a uma
solicitação de API REST enviada pelo usuário de sua API e a resposta retornada ao usuário.
Por exemplo, /incomes pode ser o caminho de um recurso que representa a renda do usuário do
aplicativo. Um recurso pode ter uma ou mais operações que são definidas por verbos HTTP adequados,
como GET, POST, PUT, PATCH e DELETE. Uma combinação de um caminho de recurso e uma operação
identifica um método da API. Por exemplo, um método POST /incomes pode adicionar uma renda obtida
pelo autor da chamada, e um método GET /expenses pode consultar as despesas relatadas incorridas
pelo autor da chamada.
O aplicativo não precisa saber onde os dados solicitados estão armazenados e de onde são obtidos
no backend. Nas APIs REST do API Gateway, o front-end é encapsulado por solicitações de método e
respostas do método. A API faz interface com o backend usando as solicitações de integração e respostas
de integração.
Por exemplo, com o DynamoDB como o backend, o desenvolvedor de APIs configura a solicitação de
integração para encaminhar a solicitação do método de entrada para o backend escolhido. A configuração
inclui especificações de uma ação adequada do DynamoDB, a função e as políticas do IAM necessárias e
os dados de entrada necessários. O backend retorna o resultado para o API Gateway como uma resposta
da integração.
Para rotear a resposta da integração para uma resposta de método adequada (de um determinado código
de status HTTP) para o cliente, você pode configurar a resposta da integração para mapear os parâmetros
de resposta necessários da integração para o método. Em seguida, você converte o formato dos dados
de saída do backend para o formato do front-end, se necessário. O API Gateway permite que você defina
um esquema ou um modelo para a carga a fim de facilitar a configuração do modelo de mapeamento do
corpo.
O API Gateway fornece a funcionalidade de gerenciamento da API REST da seguinte forma:
• Suporte para gerar SDKs e criar a documentação da API usando extensões do API Gateway para
OpenAPI
• Limitação de solicitações HTTP
Usar o API Gateway para criar APIs HTTP
As APIs HTTP permitem criar APIs RESTful com menor latência e menor custo que as APIs REST.
3