Tutorial: Criar uma API REST do API Gateway com integração da AWS

Os tópicos Tutorial: Criar uma API REST Hello World com integração de proxy do Lambda e Criar uma API REST do API Gateway com integração do Lambda descrevem como criar uma API do API Gateway para expor a função do Lambda integrada. Além disso, é possível criar uma API do API Gateway para expor outros serviços da AWS, como Amazon SNS, Amazon S3, Amazon Kinesis e até mesmo o AWS Lambda. Isso é possível através da integração da AWS. A integração do Lambda ou a integração de proxy do Lambda é um caso especial, em que a invocação da função do Lambda é exposta por meio da API do API Gateway.

Todos os serviços da AWS são compatíveis com APIs dedicadas para exposição de seus recursos. No entanto, os protocolos de aplicativos ou interfaces de programação provavelmente diferem de serviço para serviço. Uma API do API Gateway com integração da AWS tem a vantagem de fornecer um protocolo de aplicação consistente para que seu cliente acesse diferentes serviços da AWS.

Nesta demonstração, criamos uma API para expor o Amazon SNS. Para obter mais exemplos de integração de uma API a outros serviços da AWS, consulte Tutoriais e workshops do Amazon API Gateway.

Diferentemente da integração de proxy do Lambda não há integração de proxy correspondente para outros serviços da AWS. Portanto, um método de API é integrado a uma única ação da AWS. Para obter mais flexibilidade, semelhante à integração de proxy, é possível configurar uma integração de proxy do Lambda. A função do Lambda então analisa e processa as solicitações para outras ações da AWS.

O API Gateway não tenta novamente quando o endpoint atinge o tempo limite. O autor da chamada da API deve implementar lógica de novas tentativas para lidar com tempos limite do endpoint.

Este passo a passo se baseia nas instruções e nos conceitos em Criar uma API REST do API Gateway com integração do Lambda. Se você ainda não concluiu esse passo-a-passo, sugerimos que faça isso primeiro.

Pré-requisitos

Antes de iniciar esta demonstração, você deve fazer o seguinte:

1. Siga as etapas em Pré-requisitos para começar a usar o API Gateway.

2. Criar uma nova API chamada MyDemoAPI. Para obter mais informações, consulte Tutorial: Criar uma API REST com integração não proxy HTTP.

3. Implante a API pelo menos uma vez em um estágio denominado test. Para obter mais informações, consulte Implantar a API em Criar uma API REST do API Gateway com integração do Lambda.

4. Conclua as demais etapas em Criar uma API REST do API Gateway com integração do Lambda.

5. Crie pelo menos um tópico no Amazon Simple Notification Service (Amazon SNS). Você usará a API implantada para obter uma lista de tópicos no Amazon SNS que estão associados à sua conta da AWS. Para saber como criar um tópico no Amazon SNS, consulte Criar um tópico. (Não é necessário copiar o ARN do tópico mencionado na etapa 5.)

Etapa 1: Criar o perfil de execução do proxy de serviço da AWS

Para que a API invoque ações do Amazon SNS, é necessário que as políticas do IAM apropriadas sejam associadas a um perfil do IAM.

Como criar o perfil de execução do proxy de serviço da AWS

1. Faça login em AWS Management Console e abra o console do IAM em https://console.aws.amazon.com/iam/.

2. Escolha Roles.

3. Selecione Criar função.

4. Selecione Serviço da AWS em Selecionar tipo de entidade confiável, selecione API Gateway e Permite que o API Gateway envie logs ao CloudWatch Logs.

5. Selecione Próximo e, depois Próximo.

6. Em Role name (Nome da função), digite APIGatewaySNSProxyPolicy e escolha Create role (Criar função).

7. Na lista Roles (Funções), escolha a função que você acaba de criar. Talvez seja necessário rolar a página ou usar a barra de pesquisa para encontrar o perfil.

8. Para a função escolhida, selecione a guia Adicionar permissões.

9. Selecione Anexar políticas na lista suspensa.

10. Na barra de pesquisa, insira AmazonSNSReadOnlyAccess e selecione Adicionar permissões.

    nota

    Este tutorial usa uma política gerenciada em prol da simplicidade. Como prática recomendada, você deve criar sua própria política do IAM para conceder as permissões mínimas necessárias.

11. Anote o ARN do perfil recém-criado, você o usará posteriormente.

Etapa 2: Criar o recurso

Nesta etapa, crie um recurso que permite que o proxy de serviço da AWS interaja com o serviço da AWS.

Para criar o recurso

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

2. Selecione a API.

3. Selecione o recurso raiz, /, representado por uma única barra (/) e, depois, selecione Criar recurso.

4. Mantenha Recurso proxy desativado.

5. Mantenha Caminho do recurso como /.

6. Em Resource Name (Nome do recurso), insira mydemoawsproxy.

7. Mantenha CORS (Compartilhamento de recursos de origem cruzada) desativado.

8. Selecione Criar recurso.

Etapa 3: Criar o método GET

Nesta etapa, crie um método GET que permite que o proxy de serviço da AWS interaja com o serviço da AWS.

Como criar o método GET

1. Selecione o recurso /mydemoawsproxy e Criar método.

2. Em tipo de método, selecione GET.

3. Em Tipo de integração, selecione AWS service (Serviço da AWS).

4. Em Região da AWS, selecione a Região da AWS onde você criou o tópico do Amazon SNS.

5. Para AWS service (Serviço da AWS), selecione Amazon SNS.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, selecione GET.

8. Em Tipo de ação, selecione Usar nome da ação.

9. Em Nome da ação, insira ListTopics.

10. Em Perfil de execução, digite o ARN do perfil para APIGatewaySNSProxyPolicy.

11. Escolha Criar método.

Etapa 4: Especificar configurações de método e testar o método

Agora, é possível testar o método GET para verificar se ele foi configurado corretamente para listar os tópicos do Amazon SNS.

Como testar o método GET

1. Selecione a guia Test (Testar). Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

2. Escolha Test (Testar).

   O resultado exibe uma resposta semelhante ao seguinte:

   {
     "ListTopicsResponse": {
       "ListTopicsResult": {
         "NextToken": null,
         "Topics": [
           {
             "TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-1"
           },
           {
             "TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-2"
           },
           ...
           {
             "TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-N"
           }
         ]
       },
       "ResponseMetadata": {
         "RequestId": "abc1de23-45fa-6789-b0c1-d2e345fa6b78"
       }
     }
   }

Etapa 5: implantar a API

Nesta etapa, você implantará a API para poder chamá-la de fora do console do API Gateway.

Para implantar a API

1. Escolha Deploy API (Implantar API).

2. Em Estágio, selecione Novo estágio.

3. Em Stage name (Nome do estágio), insira test.

4. (Opcional) Em Description (Descrição), insira uma descrição.

5. Escolha Deploy (Implantar).

Etapa 6: testar a API

Nesta etapa, você sairá do console do API Gateway e usará seu proxy de serviço da AWS para interagir com o serviço Amazon SNS.

1. No painel de navegação principal, selecione Estágio.

2. Em Detalhes do estágio, escolha o ícone de cópia para copiar o URL de invocação da API.

   A aparência deve ser semelhante a esta:

   https://my-api-id.execute-api.region-id.amazonaws.com/test

3. Cole o URL na caixa de endereço de uma nova guia do navegador.

4. Acrescente /mydemoawsproxy para que o URL tenha a seguinte aparência:

   https://my-api-id.execute-api.region-id.amazonaws.com/test/mydemoawsproxy

   Navegue até a URL. Devem ser exibidas informações semelhante às seguintes:

   {"ListTopicsResponse":{"ListTopicsResult":{"NextToken": null,"Topics":[{"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-1"},{"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-2"},...{"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-N}]},"ResponseMetadata":{"RequestId":"abc1de23-45fa-6789-b0c1-d2e345fa6b78}}}

Etapa 7: Limpeza

É possível excluir os recursos da IAM necessários que o proxy de serviço da AWS precisa para trabalhar.

Atenção

Se você excluir um recurso do IAM do qual o proxy de serviço da AWS depende, esse proxy de serviço da AWS e qualquer API que depender dele deixarão de funcionar. A exclusão de um recurso do IAM não pode ser desfeita. Se quiser usar o recurso do IAM novamente, será necessário recriá-lo.

Como excluir os recursos do IAM associados

1. Abra o console do IAM em https://console.aws.amazon.com/iam/.

2. Na área Details (Detalhes), escolha Roles (Funções).

3. Selecione APIGatewayAWSProxyExecRole e, depois, escolha Role Actions (Ações da função), Delete Role (Excluir função). Quando solicitado, escolha Yes, Delete (Sim, excluir).

4. Na área Details (Detalhes), escolha Policies (Políticas).

5. Selecione APIGatewayAWSProxyExecPolicy e, depois, escolha Policy Actions (Ações da política), Delete (Excluir). Quando solicitado, escolha Delete (Excluir).

Você chegou ao final deste passo a passo. Para discussões mais detalhadas sobre como criar uma API como um proxy de serviço da AWS, consulte Tutorial: Criar uma API REST como um proxy do Amazon S3 no API Gateway, Tutorial: Crie uma API Calc REST com duas integrações AWS de serviços e uma integração Lambda sem proxy, ou Tutorial: Criar uma API REST como um proxy do Amazon Kinesis no API Gateway.