Tutorial: Criar uma API REST de calculadora com duas integrações de serviços da AWS e uma integração sem proxy do Lambda
O Tutorial: Crie uma API REST com uma integração de não proxy do Lambda usa a integração Lambda Function
exclusivamente. A integração Lambda Function
é um caso especial do tipo de integração do AWS
Service
que executa grande parte da configuração de integração para você, como adicionar automaticamente as permissões necessárias com base em recursos para invocar a função do Lambda. Aqui, duas das três integrações usam a integração AWS Service
Nesse tipo de integração, você tem mais controle, mas precisará executar tarefas manualmente, como criar e especificar uma função do IAM que contém as permissões adequadas.
Neste tutorial, você criará uma função do Lambda Calc
que implementa operações aritméticas básicas, aceitando e retornando a entrada e a saída formatadas em JSON. Você vai criar uma API REST e integrá-la à função do Lambda das seguintes formas:
-
Ao expor um método
GET
no recurso/calc
para invocar a função do Lambda, fornecendo a entrada como parâmetros de string de consulta. (IntegraçãoAWS Service
) -
Ao expor um método
POST
no recurso/calc
para invocar a função do Lambda, fornecendo a entrada na carga de solicitação do método. (IntegraçãoAWS Service
) -
Ao expor um
GET
em recursos/calc/{operand1}/{operand2}/{operator}
aninhados para invocar a função do Lambda, fornecendo a entrada como parâmetros de caminho. (IntegraçãoLambda Function
)
Além de experimentar este tutorial, talvez você queira estudar o arquivo de definição do OpenAPI para a API Calc
, que pode ser importado para o API Gateway seguindo as instruções em Desenvolver APIs REST usando OpenAPI no API Gateway.
Tópicos
- Criar uma função do IAM que pode ser assumida
- Criar uma função do Lambda Calc
- Testar a função do Lambda Calc
- Criar uma API Calc
- Integração 1: Criar um método GET com parâmetros de consulta para chamar a função do Lambda
- Integração 2: Criar um método POST com uma carga JSON para chamar a função do Lambda
- Integração 3: Criar um método GET com parâmetros de caminho para chamar a função do Lambda
- Definições do OpenAPI da API demonstrativa integrada com uma função do Lambda
Criar uma função do IAM que pode ser assumida
Para que sua API invoque sua função do Lambda Calc
, você precisará ter uma função do IAM do API Gateway que pode ser assumida, que é uma função do IAM com o seguinte relacionamento confiável:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
A função criada precisará ter uma permissão do Lambda InvokeFunction. Caso contrário, o autor da chamada de API receberá uma resposta 500 Internal Server Error
. Para conceder essa permissão à função, você anexará a política do IAM a ela:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" } ] }
Veja a seguir como fazer isso:
Criar uma função do IAM do API Gateway que possa ser assumida
-
Faça login no console do IAM.
-
Escolha Roles.
-
Selecione Create Role.
-
Em Select type of trusted entity (Selecionar tipo de entidade confiável), selecione AWS Serviço.
-
Em Choose the service that will use this role (Escolha o serviço que usará essa função), escolha Lambda.
-
Escolha Next: Permissions (Próximo: Permissões).
-
Selecione Create Policy (Criar política).
Uma nova janela do console Create Policy (Criar Política) será aberta. Nessa janela, faça o seguinte:
-
Na guia JSON, substitua a política existente pela política a seguir:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" } ] }
-
Escolha Review policy (Revisar política).
-
Em Review Policy (Revisar política), faça o seguinte:
-
Em Name, digite um nome de usuário, como
lambda_execute
. -
Selecione Create Policy (Criar política).
-
-
-
Na janela do console Create Role (Criar função) original, faça o seguinte:
-
Em Attach permissions policies (Anexar permissões políticas), escolha a política
lambda_execute
na lista suspensa.Se você não vir a política na lista, selecione o botão Atualizar na parte superior da lista. (Não atualize a página do navegador.)
-
Selecione Next: Tags (Próximo: tags).
-
Selecione Next:Review (Próximo: análise).
-
Em Role name (Nome da função), digite um nome como
lambda_invoke_function_assume_apigw_role
. -
Selecione Create role.
-
-
Escolha
lambda_invoke_function_assume_apigw_role
na lista de funções. -
Selecione a guia Trust relationships (Relações de confiança).
-
Escolha Edit trust relationship (Editar relação de confiança).
-
Substitua a política existente pela seguinte:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": [ "lambda.amazonaws.com", "apigateway.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] }
-
Escolha Update Trust Policy.
-
Anote o ARN da função para a função que acabou de criar. Você precisará disso mais tarde.
Criar uma função do Lambda Calc
Depois, você criará uma função do Lambda usando o console do Lambda.
-
No console do Lambda, escolha Create function (Criar função).
-
Escolha Author from Scratch.
-
Em Name (Nome), insira
Calc
. -
Em Tempo de execução, escolha o último runtime Node.js ou Python compatível.
-
Escolha a opção Criar função.
-
Copie a função do Lambda a seguir em seu runtime preferido e cole-a no editor de código do console do Lambda.
-
Em Execution role (Função de execução), selecione Choose an existing role (Selecionar uma função existente).
-
Insira o ARN da função para a função
lambda_invoke_function_assume_apigw_role
que você criou anteriormente. -
Escolha Deploy (Implantar).
Essa função requer dois operandos (a
e b
) e um operador (op
) a partir do parâmetro de entrada event
. A entrada é um objeto JSON no seguinte formato:
{ "a": "Number" | "String", "b": "Number" | "String", "op": "String" }
Essa função retorna o resultado calculado (c
) e a entrada. Para uma entrada inválida, a função retorna o valor nulo ou a string "Invalid op" como resultado. A saída é do seguinte formato JSON:
{ "a": "Number", "b": "Number", "op": "String", "c": "Number" | "String" }
É necessário testar a função no console do Lambda antes de integrá-la à API na próxima etapa.
Testar a função do Lambda Calc
Veja a seguir como testar a função Calc
no console do Lambda:
-
Selecione a guia Testar.
-
Para o nome de evento de teste, insira
calc2plus5
. -
Substitua a definição de eventos de teste pelo seguinte:
{ "a": "2", "b": "5", "op": "+" }
-
Escolha Save (Salvar).
-
Escolha Test (Testar).
-
Expanda Execution result: succeeded (Resultado da execução: com êxito). Você deve ver o seguinte:
{ "a": 2, "b": 5, "op": "+", "c": 7 }
Criar uma API Calc
O procedimento a seguir mostra como criar uma API para a função do Lambda Calc
que você acabou de criar. Nas seções a seguir, você adicionará recursos e métodos a ela.
Como criar uma API
Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway
. -
Se esta for a primeira vez que você usa o API Gateway, você verá uma página com os recursos do serviço. Em REST API, escolha Build (Criar). Quando o pop-up Create Example API (Criar API de exemplo) for exibido, escolha OK.
Se essa não for a primeira vez que você usa o API Gateway, escolha Create API (Criar API). Em REST API, escolha Build (Criar).
Em API name (Nome da API), insira
LambdaCalc
.(Opcional) Em Description (Descrição), insira uma descrição.
Mantenha Tipo de endpoint da API definido como Regional.
Selecione Create API (Criar API).
Integração 1: Criar um método GET
com parâmetros de consulta para chamar a função do Lambda
Ao criar um método GET
que transmita parâmetros de string de consulta para a função do Lambda, habilite a API para ser invocada de um navegador. Essa abordagem pode ser útil, especialmente para APIs que permitem acesso aberto.
Depois de criar uma API, você criará um recurso. Normalmente, os recursos da API são organizados em uma árvore de recursos, de acordo com a lógica do aplicativo. Para esta etapa, você vai criar um recurso /calc.
Como criar um recurso /calc
Selecione Criar recurso.
Mantenha Recurso proxy desativado.
Mantenha Caminho do recurso como
/
.Em Resource Name (Nome do recurso), insira
calc
.Mantenha CORS (Compartilhamento de recursos de origem cruzada) desativado.
Selecione Criar recurso.
Ao criar um método GET
que transmita parâmetros de string de consulta para a função do Lambda, habilite a API para ser invocada de um navegador. Essa abordagem pode ser útil, especialmente para APIs que permitem acesso aberto.
Neste método, o Lambda requer que a solicitação POST
seja usada para invocar qualquer função do Lambda. Esse exemplo mostra que o método HTTP em uma solicitação de método de front-end pode ser diferente da solicitação de integração no backend.
Como criar um método GET
Selecione o recurso /calc e Criar método.
Em Tipo de método, selecione GET.
Em Tipo de integração, selecione Serviço da AWS.
Em Região da AWS, selecione a Região da AWS onde você criou a função do Lambda.
Em Serviço da AWS, selecione Lambda.
Mantenha o subdomínio da AWS em branco.
Em Método HTTP, selecione POST.
Em Tipo de ação, escolha Usar substituição de caminho. Essa opção nos permite especificar o ARN da ação Invoke para executar nossa função
Calc
.Em Substituição de caminho, digite
2015-03-31/functions/arn:aws:lambda:
. Emus-east-2
:account-id
:function:Calc/invocationsaccount-id
, insira a Região da AWS onde você criou a função do Lambda.us-east-2
Em Perfil de execução, digite o ARN do perfil para
lambda_invoke_function_assume_apigw_role
.Não altere as configurações do Cache de credenciais e do Tempo limite padrão.
Escolha Configurações de solicitação de método.
Em Validador de solicitação, selecione Validar parâmetros de string de consulta e cabeçalhos.
Essa configuração fará com que uma mensagem de erro seja gerada se o cliente não especificar os parâmetros necessários.
Selecione Parâmetros de string de consulta de URL.
Agora configure parâmetros de string de consulta para o método GET no recurso /calc para que ele possa receber a entrada em nome da função do Lambda de back-end.
Para criar parâmetros de string de consulta, faça o seguinte:
Escolha Add query string (Adicionar string de consulta).
Em Nome, digite
operand1
.Ative a opção Obrigatório.
Mantenha Armazenamento em cache desativado.
Repita as mesmas etapas e crie uma string de consulta chamada
operand2
e uma string de consulta chamadaoperator
.Escolha Criar método.
Agora, você vai criar um modelo de mapeamento para converter as strings de consulta fornecidas pelo cliente na carga útil de solicitações de integração, conforme exigido pela função Calc
. Esse modelo associa os três parâmetros de consulta declarados em Solicitação de método a valores de propriedade designados do objeto JSON como entrada para a função do Lambda de back-end. O objeto JSON transformado será incluído como a carga útil da solicitação de integração.
Como associar parâmetros de entrada à solicitação de integração
Na guia Solicitação de integração, em Configurações de solicitação de integração, selecione Editar.
Em Passagem do corpo da solicitação, selecione Quando não há modelos definidos (recomendado).
Selecione Modelos de mapeamento.
Escolha Add mapping template (Adicionar modelo de mapeamento).
Em Tipo de conteúdo, insira
application/json
.Em Corpo do modelo, insira o seguinte código:
{ "a": "$input.params('operand1')", "b": "$input.params('operand2')", "op": "$input.params('operator')" }
Escolha Salvar.
Agora, é possível testar o método GET
para verificar se ele foi configurado corretamente para invocar a função do Lambda:
Como testar o método GET
-
Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
Em Strings de consulta, digite
operand1=2&operand2=3&operator=+
.-
Escolha Test (Testar).
Os resultados devem ser semelhantes ao seguinte:
Integração 2: Criar um método POST
com uma carga JSON para chamar a função do Lambda
Depois da criação de um método POST
com uma carga JSON para chamar a função do Lambda, o cliente deve enviar a entrada necessária para a função de backend no corpo da solicitação. Para garantir que o cliente faça upload dos dados de entrada corretos, você habilitará a validação de solicitações na carga.
Como criar um método POST
com uma carga útil do JSON
Selecione o recurso /calc e Criar método.
Em Tipo de método, selecione POST.
Em Tipo de integração, selecione Serviço da AWS.
Em Região da AWS, selecione a Região da AWS onde você criou a função do Lambda.
Em Serviço da AWS, selecione Lambda.
Mantenha o subdomínio da AWS em branco.
Em Método HTTP, selecione POST.
Em Tipo de ação, escolha Usar substituição de caminho. Essa opção nos permite especificar o ARN da ação Invoke para executar nossa função
Calc
.Em Substituição de caminho, digite
2015-03-31/functions/arn:aws:lambda:
. Emus-east-2
:account-id
:function:Calc/invocationsaccount-id
, insira a Região da AWS onde você criou a função do Lambda.us-east-2
Em Perfil de execução, digite o ARN do perfil para
lambda_invoke_function_assume_apigw_role
.Não altere as configurações do Cache de credenciais e do Tempo limite padrão.
Escolha Criar método.
Agora você vai criar um modelo de entrada para descrever a estrutura de dados de entrada e validar o corpo da solicitação recebida.
Como criar o modelo de entrada
-
No painel de navegação principal, selecione Modelos.
-
Escolha Criar modelo.
-
Em Nome, digite
input
. -
Em Tipo de conteúdo, insira
application/json
.Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira
$default
. -
Em Esquema do modelo, insira o seguinte modelo:
{ "type":"object", "properties":{ "a":{"type":"number"}, "b":{"type":"number"}, "op":{"type":"string"} }, "title":"input" }
Escolha Criar modelo.
Agora você vai criar um modelo de saída. Esse modelo descreve a estrutura de dados da saída calculada do backend. Ele pode ser usado para mapear dados de resposta de integração para um modelo diferente. Este tutorial depende do comportamento de passagem direta e não usa este modelo.
Como criar um modelo de saída
-
Escolha Criar modelo.
-
Em Nome, digite
output
. -
Em Tipo de conteúdo, insira
application/json
.Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira
$default
. -
Em Esquema do modelo, insira o seguinte modelo:
{ "type":"object", "properties":{ "c":{"type":"number"} }, "title":"output" }
Escolha Criar modelo.
Agora você vai criar um modelo de resultado. Esse modelo descreve a estrutura de dados dos dados de resposta retornados. Ele faz referência aos esquemas de entrada e de saída definidos na API.
Como criar um modelo de resultado
-
Escolha Criar modelo.
-
Em Nome, digite
result
. -
Em Tipo de conteúdo, insira
application/json
.Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira
$default
. -
Em Esquema do modelo, insira o modelo a seguir com o
restapi-id
. Orestapi-id
está listado entre parênteses na parte superior do console no seguinte fluxo:API Gateway > APIs > LambdaCalc (
abc123
).{ "type":"object", "properties":{ "input":{ "$ref":"https://apigateway.amazonaws.com/restapis/
restapi-id
/models/input" }, "output":{ "$ref":"https://apigateway.amazonaws.com/restapis/restapi-id
/models/output" } }, "title":"result" } Escolha Criar modelo.
Agora, você vai configurar a solicitação do método POST para habilitar a validação de solicitações no corpo da solicitação recebida.
Habilitar a validação da solicitação no método POST
-
No painel de navegação principal, selecione Recursos e, depois, selecione o método
POST
na árvore de recursos. -
Na guia Solicitação de método, em Configurações de solicitação de método, escolha Editar.
Em Validador de solicitação, selecione Validar corpo.
Selecione Corpo da solicitação e, depois, Adicionar modelo.
Em Tipo de conteúdo, insira
application/json
.Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira
$default
.Em Modelo, selecione entrada.
Escolha Salvar.
Agora, é possível testar o método POST
para verificar se ele foi configurado corretamente para invocar a função do Lambda:
Como testar o método POST
-
Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
Em Corpo da solicitação, insira a carga útil do JSON a seguir.
{ "a": 1, "b": 2, "op": "+" }
-
Escolha Testar.
A seguinte saída deverá ser mostrada:
{ "a": 1, "b": 2, "op": "+", "c": 3 }
Integração 3: Criar um método GET
com parâmetros de caminho para chamar a função do Lambda
Agora, você criará um método GET
em um recurso especificado por uma sequência de parâmetros de caminho para chamar a função do Lambda de backend. Os valores de parâmetros de caminho especificam os dados de entrada para a função do Lambda. Você usará um modelo de mapeamento para mapear os valores de parâmetro de caminho de entrada para a carga necessária de solicitação de integração.
A aparência da estrutura de recursos de API resultante será semelhante a esta:
![Criar uma API no API Gateway como um proxy do Lambda](images/aws_proxy_lambda_create_api_resources_new_console.png)
Como criar um recurso/{operand1}/{operand2}/{operator}
Selecione Criar recurso.
Em Caminho do recurso, selecione
/calc
.Em Resource Name (Nome do recurso), insira
{operand1}
.Mantenha CORS (Compartilhamento de recursos de origem cruzada) desativado.
Selecione Criar recurso.
Em Caminho do recurso, selecione
/calc/{operand1}/
.Em Resource Name (Nome do recurso), insira
{operand2}
.Mantenha CORS (Compartilhamento de recursos de origem cruzada) desativado.
Selecione Criar recurso.
Em Caminho do recurso, selecione
/calc/{operand1}/{operand2}/
.Em Resource Name (Nome do recurso), insira
{operator}
.Mantenha CORS (Compartilhamento de recursos de origem cruzada) desativado.
Selecione Criar recurso.
Dessa vez, você usará a integração do Lambda incorporada no console do API Gateway para configurar a integração do método.
Como configurar uma integração de método
Selecione o recurso /{operand1}/{operand2}/{operator} e, depois, escolha Criar método.
Em Tipo de método, selecione GET.
Em Tipo de integração, selecione Lambda.
Mantenha a opção Integração do proxy do Lambda desativada.
Em Função do Lambda, selecione a Região da AWS onde você criou a função do Lambda e insira
Calc
.Mantenha o Tempo limite padrão ativado.
Escolha Criar método.
Agora, você vai criar um modelo de mapeamento para associar os três parâmetros de caminho de URL, declarados quando o recurso /calc/{operand1}/{operand2}/{operator} foi criado, a valores de propriedade designados no objeto JSON. Como os caminhos de URL devem ser codificados em URL, o operador de divisão deve ser especificado como %2F
em vez de /
. Esse modelo converte o %2F
em '/'
antes de transferi-lo para a função do Lambda.
Como criar um modelo de mapeamento
Na guia Solicitação de integração, em Configurações de solicitação de integração, selecione Editar.
Em Passagem do corpo da solicitação, selecione Quando não há modelos definidos (recomendado).
Selecione Modelos de mapeamento.
Em Tipo de conteúdo, insira
application/json
.Em Corpo do modelo, insira o seguinte código:
{ "a": "$input.params('operand1')", "b": "$input.params('operand2')", "op": #if($input.params('operator')=='%2F')"/"#{else}"$input.params('operator')"#end }
Escolha Salvar.
Agora, é possível testar o método GET
para verificar se ele foi configurado corretamente para invocar a função do Lambda e passar a saída original pela resposta de integração sem mapeamento.
Como testar o método GET
-
Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
-
Para o Caminho, faça o seguinte:
Em operand1, insira
1
.Em operand2, insira
1
.Em operador, insira
+
.
-
Escolha Test (Testar).
-
O resultado deve ser semelhante ao seguinte:
Depois, você modelará a estrutura de dados da carga útil de resposta de método após o esquema result
.
Por padrão, o corpo de resposta de método recebe um modelo vazio. Isso fará com que o corpo de resposta de integração seja repassado sem mapeamento. No entanto, quando você gerar um SDK para uma das linguagens de tipo forte, como Java ou Objective-C, os usuários do seu SDK receberão um objeto vazio como resultado. Para garantir que tanto o cliente REST quanto os clientes do SDK recebam o resultado desejado, você deve modelar os dados de resposta usando uma esquema predefinido. Aqui, você definirá um modelo para o corpo de resposta de método e para construir um modelo de mapeamento a fim de traduzir o corpo da resposta de integração no corpo da resposta de método.
Como criar uma resposta de método
-
Na guia Resposta de método, em Resposta 200, selecione Editar.
-
Em Corpo da resposta, selecione Adicionar modelo.
-
Em Tipo de conteúdo, insira
application/json
. -
Em Modelo, selecione o resultado.
-
Escolha Salvar.
Definir o modelo result
para o corpo da resposta de método garante que os dados da resposta serão convertidos no objeto de um determinado SDK. Para garantir que os dados de resposta de integração sejam mapeados de acordo, você precisará de um modelo de mapeamento.
Como criar um modelo de mapeamento
Na guia Resposta de integração, em Padrão - Resposta, selecione Editar.
Selecione Modelos de mapeamento.
Em Tipo de conteúdo, insira
application/json
.Em Corpo do modelo, insira o seguinte código:
#set($inputRoot = $input.path('$')) { "input" : { "a" : $inputRoot.a, "b" : $inputRoot.b, "op" : "$inputRoot.op" }, "output" : { "c" : $inputRoot.c } }
Escolha Salvar.
Como testar o modelo de mapeamento
-
Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
-
Para o Caminho, faça o seguinte:
Em operand1, insira
1
.Em operand2, insira
2
.Em operador, insira
+
.
-
Escolha Testar.
-
O resultado terá esta aparência:
{ "input": { "a": 1, "b": 2, "op": "+" }, "output": { "c": 3 } }
Nesse momento, somente é possível chamar a API usando o atributo Testar no console do API Gateway. Para disponibilizá-la para os clientes, será necessário implantar a API. Certifique-se de reimplantar sua API sempre que você adicionar, modificar ou excluir um recurso ou método, atualizar um mapeamento de dados ou atualizar as configurações de estágio. Caso contrário, novos atributos ou atualizações não estarão disponíveis para clientes da API.
Para implantar a API
Escolha Implantar API.
Em Estágio, selecione Novo estágio.
Em Stage name (Nome do estágio), insira
Prod
.(Opcional) Em Description (Descrição), insira uma descrição.
Escolha Implantar.
-
(Opcional) Em Detalhes do estágio, para Invocar URL, é possível selecionar o ícone de cópia para copiar o URL de invocação da API. Você pode usá-lo com ferramentas, como Postman
e cURL para testar sua API.
nota
Reimplante a API sempre que você adicionar, modificar ou excluir um recurso ou um método, atualizar um mapeamento de dados ou atualizar as configurações de estágio. Caso contrário, novos recursos ou atualizações não estarão disponíveis para clientes de sua API.