Tutorial: Creación de una API de REST de calculadora con dos integraciones de servicios de AWS y una integración de Lambda sin proxy
El Tutorial: Creación de una API de REST con una integración no de proxy de Lambda solamente utiliza la integración de Lambda Function
. La integración de Lambda Function
es un caso especial del tipo de integración de AWS
Service
que configura por usted la mayor parte de la integración; por ejemplo, la incorporación automática de los permisos basados en recursos necesarios para invocar la función de Lambda. Aquí, dos de las tres integraciones usan integración de AWS Service
. En este tipo de integración, tiene más control, pero tendrá que realizar manualmente tareas como la creación y especificación de un rol de IAM que contenga los permisos adecuados.
En este tutorial, creará una función Calc
de Lambda que implementa operaciones aritméticas básicas, aceptando y devolviendo entradas y salidas con formato JSON. A continuación, creará una API REST y la integrará con la función de Lambda de la siguiente forma:
-
Exponiendo un método de
GET
en el recurso/calc
para invocar la función de Lambda, proporcionando la entrada como parámetros de cadena de consulta. (Integración deAWS Service
) -
Exponiendo un método de
POST
en el recurso/calc
para invocar la función de Lambda, proporcionando la entrada en la carga de la solicitud del método. (Integración deAWS Service
) -
Exponiendo un método
GET
en recursos/calc/{operand1}/{operand2}/{operator}
anidados para invocar la función de Lambda, proporcionando la entrada como parámetros de ruta. (Integración deLambda Function
)
Además de probar con este tutorial, sugerimos que estudie el archivo de definición de OpenAPI para la API de Calc
, que puede importar a API Gateway siguiendo las instrucciones de Desarrollo de API de REST mediante OpenAPI en API Gateway.
Temas
- Crear un rol de IAM asumible
- Creación de una función Calc de Lambda
- Probar la función Calc de Lambda
- Cree una API de Calc
- Integración 1: Crear un método GET con parámetros de consulta para llamar a la función de Lambda
- Integración 2: Crear un método POST con una carga JSON para llamar a la función de Lambda
- Integración 3: Crear un método GET con parámetros de ruta para llamar a la función de Lambda
- Definiciones de OpenAPI de una API de ejemplo integrada con una función de Lambda
Crear un rol de IAM asumible
Para que su API invoque su función Calc
de Lambda, necesitará tener un rol de IAM asumible por API Gateway, que es un rol de IAM con la siguiente relación de confianza:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
El rol que cree tendrá que tener el permiso InvokeFunction de Lambda. De lo contrario, el intermediario de la API recibirá una respuesta 500 Internal Server Error
. Para dar al rol este permiso, asociará la siguiente política de IAM:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" } ] }
A continuación, se explica cómo realizar todo esto:
Crear un rol de IAM asumible por API Gateway
-
Inicie sesión en la consola de IAM.
-
Elija Roles.
-
Elija Create Role.
-
En Select type of trusted entity (Seleccionar el tipo de entidad de confianza), elija AWS Service (Servicio de AWS).
-
En Choose the service that will use this role (Elegir el servicio que usará este rol), elija Lambda.
-
Elija Next: Permissions (Siguiente: permisos).
-
Elija Create Policy (Crear política).
Se abrirá una nueva ventana de consola Create Policy (Crear política). En esa ventana, haga lo siguiente:
-
En la pestaña JSON, reemplace la política existente por la siguiente:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" } ] }
-
Elija Review policy (Revisar política).
-
En Review Policy (Revisar política) haga lo siguiente:
-
En Nombre, escriba un nombre, como
lambda_execute
. -
Elija Create Policy (Crear política).
-
-
-
En la ventana de consola Create Role (Crear rol) original, haga lo siguiente:
-
En Attach permissions policies (Asociar políticas de permisos), elija la política
lambda_execute
de la lista desplegable.Si no ve su política en la lista, haga clic en el botón Refresh (Actualizar) en la parte superior de la lista. (¡No actualice la página del navegador!)
-
Elija Next: Tags (Siguiente: Etiquetas).
-
Elija Next: Review.
-
En Role name (Nombre de rol), escriba un nombre como
lambda_invoke_function_assume_apigw_role
. -
Elija Create role (Crear rol).
-
-
Elija el rol
lambda_invoke_function_assume_apigw_role
de la lista de roles. -
Seleccione la pestaña Trust Relationships (Relaciones de confianza).
-
Elija Edit trust relationship (Editar relación de confianza).
-
Reemplace la política existente por la siguiente:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": [ "lambda.amazonaws.com", "apigateway.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] }
-
Elija Update Trust Policy.
-
Anote el ARN del rol que acaba de crear. Lo necesitará más adelante.
Creación de una función Calc
de Lambda
A continuación, creará una función de Lambda con la consola de Lambda.
-
En la consola de Lambda, elija Create function (Crear función).
-
Elija Author from Scratch (Crear desde cero).
-
En Name (Nombre) escriba
Calc
. -
En Tiempo de ejecución, elija el último tiempo de ejecución de Node.js o Python compatible.
-
Elija Crear función.
-
Copie la siguiente función de Lambda en el tiempo de ejecución de su preferencia y péguela en el editor de código en la consola de Lambda.
-
Bajo Execution role (Rol de ejecución) elija Choose an existing role (Elegir un rol existente).
-
Escriba el ARN del rol para el rol
lambda_invoke_function_assume_apigw_role
que creó anteriormente. -
Elija Deploy (Implementar).
Esta función requiere dos operandos (a
y b
) y un operador (op
) del parámetro de entrada event
. La entrada es un objeto JSON con el siguiente formato:
{ "a": "Number" | "String", "b": "Number" | "String", "op": "String" }
Esta función devuelve el resultado calculado (c
) y la entrada. Si se trata de una entrada no válida, la función devuelve el valor null o la cadena "Invalid op" como resultado. La salida tiene el siguiente formato JSON:
{ "a": "Number", "b": "Number", "op": "String", "c": "Number" | "String" }
Debe probar la función en la consola de Lambda antes de integrarla con la API en el siguiente paso.
Probar la función Calc
de Lambda
Indicamos aquí como probar la función Calc
en la consola de Lambda.
-
Elija la pestaña Prueba.
-
Para el nombre del evento de prueba, escriba
calc2plus5
. -
Sustituya la definición del evento de prueba por lo siguiente:
{ "a": "2", "b": "5", "op": "+" }
-
Seleccione Save.
-
Seleccione Test (Probar).
-
Expanda Execution result: succeeded (Resultado de la ejecución: correcta). Debería ver lo siguiente:
{ "a": 2, "b": 5, "op": "+", "c": 7 }
Cree una API de Calc
El procedimiento siguiente describe cómo crear una API para la función Calc
de Lambda que acaba de crear. En las siguientes secciones, añadirá recursos y métodos.
Creación de una API
Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway
. -
Si es la primera vez que utiliza API Gateway, verá una página en la que aparecen las características del servicio. En REST API, elija Build (Compilación). Cuando aparezca el menú emergente Create Example API (Crear API de ejemplo), elija OK (Aceptar).
Si esta no es la primera vez que utiliza API Gateway, elija Create API (Crear API). En REST API, elija Build (Compilación).
En API name (Nombre de la API), escriba
LambdaCalc
.(Opcional) En Description (Descripción), introduzca una descripción.
Mantenga Tipo de punto de conexión de la API establecido en Regional.
Seleccione Create API (Crear API).
Integración 1: Crear un método GET
con parámetros de consulta para llamar a la función de Lambda
Mediante la creación de un método GET
que pasa los parámetros de cadenas de consulta a la función de Lambda, habilita la API que se va a invocar desde un navegador. Este método puede ser útil, en especial para las API que permiten acceso abierto.
Después de crear una API, se crea un recurso. Normalmente, los recursos de la API están organizados en un árbol de recursos de acuerdo con la lógica de la aplicación. Para este paso, debe crear un recurso /calc.
Para crear un recurso /calc
Elija Crear recurso.
Mantenga Recurso proxy desactivado.
Mantenga Ruta del recurso en
/
.En Nombre del recurso, escriba
calc
.Mantenga desactivado CORS (uso compartido de recursos entre orígenes).
Elija Crear recurso.
Mediante la creación de un método GET
que pasa los parámetros de cadenas de consulta a la función de Lambda, habilita la API que se va a invocar desde un navegador. Este método puede ser útil, en especial para las API que permiten acceso abierto.
En este método, Lambda requiere que se use la solicitud POST
para invocar cualquier función de Lambda. Este ejemplo muestra que el método HTTP en una solicitud de método del frontend puede diferir de la solicitud de integración en el backend.
Para crear un método GET
Seleccione el recurso calc y, a continuación, elija Crear método.
En Tipo de método, seleccione GET.
En Tipo de integración, seleccione Servicio de AWS.
En Región de AWS, seleccione la Región de AWS donde creó la función de Lambda.
En Servicio de AWS, seleccione Lambda.
Deje Subdominio de AWS en blanco.
En Método HTTP, seleccione POST.
En Tipo de acción, elija Usar sustitución de ruta. Esta opción nos permite especificar el ARN de la acción Invoke para ejecutar nuestra función
Calc
.En Sustitución de ruta, escriba
2015-03-31/functions/arn:aws:lambda:
. Enus-east-2
:account-id
:function:Calc/invocationsaccount-id
, introduzca la Región de AWS donde creó la función de Lambda.us-east-2
En Rol de ejecución, escriba el ARN del rol para
lambda_invoke_function_assume_apigw_role
.No cambie la configuración de Caché de credenciales ni Tiempo de espera predeterminado.
Elija Configuración de solicitud de método.
En Validador de solicitud, seleccione Validar parámetros de cadena de consulta y encabezados.
Esta configuración hará que se devuelva un mensaje de error si el cliente no especifica los parámetros requeridos.
Elija Parámetros de cadenas de consulta de URL.
Ahora, debe configurar los parámetros de cadena de consulta para el método GET en el recurso /calc para que pueda recibir la entrada en nombre de la función de Lambda del backend.
Para crear parámetros de cadena de consulta, haga lo siguiente:
Elija Add query string (Añadir cadena de consulta).
En Nombre, escriba
operand1
.Active la opción Obligatorio.
Mantenga Almacenamiento en caché desactivado.
Repita los mismos pasos y cree una cadena de consulta llamada
operand2
y una cadena de consulta llamadaoperator
.Elija Crear método.
Ahora, vamos a crear una plantilla de mapeo para convertir las cadenas de consulta proporcionadas por el cliente en la carga de la solicitud de integración, tal y como requiere la función Calc
. Esta plantilla mapea los tres parámetros de cadena de consulta declarados en Solicitud de método en los valores de propiedad designados del objeto JSON como entrada a la función de Lambda del backend. El objeto JSON transformado se incluirá como la carga de la solicitud de integración.
Para mapear los parámetros de entrada a la solicitud de integración
En la pestaña Solicitud de integración, en Configuración de la solicitud de integración, seleccione Editar.
En Acceso directo de cuerpo de la solicitud, elija Cuando no haya plantillas definidas (recomendado).
Elija Plantillas de mapeo.
Elija Add mapping template (Añadir plantilla de asignación).
En Tipo de contenido, ingrese
application/json
.En Cuerpo de la plantilla, introduzca el siguiente código:
{ "a": "$input.params('operand1')", "b": "$input.params('operand2')", "op": "$input.params('operator')" }
Seleccione Guardar.
Ahora puede probar el método GET
para verificar que se ha configurado correctamente para invocar la función de Lambda.
Para probar el método GET
-
Elija la pestaña Prueba. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.
En Cadenas de consulta, escriba
operand1=2&operand2=3&operator=+
.-
Seleccione Test (Probar).
El resultado debe ser parecido al siguiente:
Integración 2: Crear un método POST
con una carga JSON para llamar a la función de Lambda
Al crear un método POST
con una carga JSON para llamar a la función de Lambda, lo hace de tal manera que el cliente debe proporcionar la entrada necesaria a la función del backend en el cuerpo de la solicitud. Para garantizar que el cliente carga los datos de entrada correctos, habilitará la validación de solicitudes en la carga.
Para crear un método POST
con una carga JSON
Seleccione el recurso calc y, a continuación, elija Crear método.
En Tipo de método, seleccione POST.
En Tipo de integración, seleccione Servicio de AWS.
En Región de AWS, seleccione la Región de AWS donde creó la función de Lambda.
En Servicio de AWS, seleccione Lambda.
Deje Subdominio de AWS en blanco.
En Método HTTP, seleccione POST.
En Tipo de acción, elija Usar sustitución de ruta. Esta opción nos permite especificar el ARN de la acción Invoke para ejecutar nuestra función
Calc
.En Sustitución de ruta, escriba
2015-03-31/functions/arn:aws:lambda:
. Enus-east-2
:account-id
:function:Calc/invocationsaccount-id
, introduzca la Región de AWS donde creó la función de Lambda.us-east-2
En Rol de ejecución, escriba el ARN del rol para
lambda_invoke_function_assume_apigw_role
.No cambie la configuración de Caché de credenciales ni Tiempo de espera predeterminado.
Elija Crear método.
Ahora vamos a crear un modelo de entrada para describir la estructura de los datos de entrada y validar el cuerpo de la solicitud entrante.
Para crear el modelo de entrada
-
En el panel de navegación principal, elija Modelos.
-
Seleccione Crear modelo.
-
En Nombre, escriba
input
. -
En Tipo de contenido, ingrese
application/json
.Si no se encuentra ningún tipo de contenido coincidente, no se realiza la validación de la solicitud. Para utilizar el mismo modelo independientemente del tipo de contenido, introduzca
$default
. -
En Esquema del modelo, escriba el siguiente modelo:
{ "type":"object", "properties":{ "a":{"type":"number"}, "b":{"type":"number"}, "op":{"type":"string"} }, "title":"input" }
Seleccione Crear modelo.
Ahora cree un modelo de salida. Este modelo describe la estructura de datos de la salida calculada desde el backend. Se puede utilizar para asignar los datos de la respuesta de integración a un modelo diferente. Este tutorial se basa en el comportamiento de paso a través y no utiliza este modelo.
Para crear un modelo de salida
-
Seleccione Crear modelo.
-
En Nombre, escriba
output
. -
En Tipo de contenido, ingrese
application/json
.Si no se encuentra ningún tipo de contenido coincidente, no se realiza la validación de la solicitud. Para utilizar el mismo modelo independientemente del tipo de contenido, introduzca
$default
. -
En Esquema del modelo, escriba el siguiente modelo:
{ "type":"object", "properties":{ "c":{"type":"number"} }, "title":"output" }
Seleccione Crear modelo.
Ahora cree un modelo de resultados. Este modelo describe la estructura de datos de los datos de respuesta devueltos. Hace referencia a los esquemas de entrada y salida definidos en su API.
Para crear un modelo de resultados
-
Seleccione Crear modelo.
-
En Nombre, escriba
result
. -
En Tipo de contenido, ingrese
application/json
.Si no se encuentra ningún tipo de contenido coincidente, no se realiza la validación de la solicitud. Para utilizar el mismo modelo independientemente del tipo de contenido, introduzca
$default
. -
En Esquema del modelo, introduzca el siguiente modelo con su
restapi-id
. Elrestapi-id
aparece entre paréntesis en la parte superior de la consola en el siguiente flujo: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" } Seleccione Crear modelo.
Ahora configure la solicitud de método de su método POST para habilitar la validación de la solicitud en el cuerpo de la solicitud entrante.
Habilitación de la validación de solicitudes en el método POST
-
En el panel de navegación principal, seleccione Recursos y, a continuación, seleccione el método
POST
en el árbol de recursos. -
En la pestaña Solicitud de método, en Configuración de solicitud de método, elija Editar.
En Validador de solicitudes, seleccione Validar cuerpo.
Seleccione Cuerpo de la solicitud y, a continuación, seleccione Añadir modelo.
En Tipo de contenido, ingrese
application/json
.Si no se encuentra ningún tipo de contenido coincidente, no se realiza la validación de la solicitud. Para utilizar el mismo modelo independientemente del tipo de contenido, introduzca
$default
.En Modelo, seleccione entrada.
Seleccione Guardar.
Ahora puede probar el método POST
para verificar que se ha configurado correctamente para invocar la función de Lambda.
Para probar el método POST
-
Elija la pestaña Prueba. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.
En Cuerpo de la solicitud, pegue la siguiente carga JSON.
{ "a": 1, "b": 2, "op": "+" }
-
Seleccione Probar.
Debería ver los siguientes datos de salida:
{ "a": 1, "b": 2, "op": "+", "c": 3 }
Integración 3: Crear un método GET
con parámetros de ruta para llamar a la función de Lambda
Ahora creará un método GET
en un recurso especificado por una secuencia de parámetros de ruta para llamar a la función de Lambda del backend. Los valores de los parámetros de ruta especifican los datos de entrada a la función de Lambda. Definirá una plantilla de asignación para asignar los valores de los parámetros de ruta entrantes a la carga de la solicitud de integración necesaria.
La estructura de recursos de la API resultante será como la siguiente:
![Crear una API en API Gateway como proxy de Lambda](images/aws_proxy_lambda_create_api_resources_new_console.png)
Para crear un recurso /{operand1}/{operand2}/{operator}
Elija Crear recurso.
En Ruta de recurso, seleccione
/calc
.En Nombre del recurso, escriba
{operand1}
.Mantenga desactivado CORS (uso compartido de recursos entre orígenes).
Elija Crear recurso.
En Ruta de recurso, seleccione
/calc/{operand1}/
.En Nombre del recurso, escriba
{operand2}
.Mantenga desactivado CORS (uso compartido de recursos entre orígenes).
Elija Crear recurso.
En Ruta de recurso, seleccione
/calc/{operand1}/{operand2}/
.En Nombre del recurso, escriba
{operator}
.Mantenga desactivado CORS (uso compartido de recursos entre orígenes).
Elija Crear recurso.
Esta vez utilizará la integración de Lambda incorporada en la consola de API Gateway para configurar la integración del método.
Para configurar una integración del método
Seleccione el recurso /{operand1}/{operand2}/{operator} y, a continuación, elija Crear método.
En Tipo de método, seleccione GET.
En Tipo de integración, seleccione Lambda.
Mantenga desactivada la Integración de proxy Lambda.
En Función de Lambda, seleccione la Región de AWS donde creó su función de Lambda e introduzca
Calc
.Mantenga activado Tiempo de espera predeterminado.
Elija Crear método.
Ahora debe crear una plantilla de mapeo para mapear los tres parámetros de la ruta de la URL, declarados cuando se creó el recurso /calc/{operand1}/{operand2}/{operator}, con los valores de propiedad designados en el objeto JSON. Como las rutas URL deben estar codificadas como direcciones URL, el operador de división debe especificarse como %2F
en lugar de /
. Esta plantilla traduce %2F
en '/'
antes de pasarlo a la función de Lambda.
Para crear una plantilla de mapeo
En la pestaña Solicitud de integración, en Configuración de la solicitud de integración, seleccione Editar.
En Acceso directo de cuerpo de la solicitud, elija Cuando no haya plantillas definidas (recomendado).
Elija Plantillas de mapeo.
En Tipo de contenido, ingrese
application/json
.En Cuerpo de la plantilla, introduzca el siguiente código:
{ "a": "$input.params('operand1')", "b": "$input.params('operand2')", "op": #if($input.params('operator')=='%2F')"/"#{else}"$input.params('operator')"#end }
Seleccione Guardar.
Ahora puede probar el método GET
para verificar que se ha configurado correctamente para invocar la función de Lambda y pasar el resultado original a través de la respuesta de integración sin mapear.
Para probar el método GET
-
Elija la pestaña Prueba. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.
-
Para Ruta, haga lo siguiente:
En operand1, introduzca
1
.En operand2, introduzca
1
.En operator, introduzca
+
.
-
Seleccione Test (Probar).
-
El resultado debe tener el siguiente aspecto:
A continuación, creará el modelo de la estructura de datos de la carga de la respuesta del método detrás del esquema result
.
De forma predeterminada, el cuerpo de la respuesta del método se asigna a un modelo vacío. Esto hará que el cuerpo de la respuesta de integración se transfiera sin asignación. Sin embargo, cuando genere un SDK para alguno de los lenguajes con establecimiento inflexible de tipos, como Java u Objective-C, los usuarios del SDK recibirán un objeto vacío como resultado. Para garantizar que el cliente REST y los clientes del SDK reciban el resultado deseado, debe crear los datos de la respuesta mediante un esquema predefinido. A continuación, definirá un modelo para el cuerpo de la respuesta del método y cómo crear una plantilla de asignación para traducir el cuerpo de la respuesta de integración al cuerpo de la respuesta del método.
Para crear una respuesta del método
-
En la pestaña Respuesta del método, en Respuesta 200, elija Editar.
-
En Cuerpo de la respuesta, seleccione Agregar modelo.
-
En Tipo de contenido, ingrese
application/json
. -
En Modelo, seleccione resultado.
-
Seleccione Guardar.
Al configurar el modelo para el cuerpo de la respuesta del método, nos aseguramos de que los datos de la respuesta se emitan en el objeto result
de un determinado SDK. Para asegurarse de que los datos de la respuesta de integración se asignen según corresponda, necesitará una plantilla de asignación.
Para crear una plantilla de mapeo
En la pestaña Respuesta de integración, en Predeterminado: respuesta, seleccione Editar.
Elija Plantillas de mapeo.
En Tipo de contenido, ingrese
application/json
.En Cuerpo de la plantilla, introduzca el siguiente código:
#set($inputRoot = $input.path('$')) { "input" : { "a" : $inputRoot.a, "b" : $inputRoot.b, "op" : "$inputRoot.op" }, "output" : { "c" : $inputRoot.c } }
Seleccione Guardar.
Para probar la plantilla de mapeo
-
Elija la pestaña Prueba. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.
-
Para Ruta, haga lo siguiente:
En operand1, introduzca
1
.En operand2, introduzca
2
.En operator, introduzca
+
.
-
Seleccione Probar.
-
El resultado será parecido al siguiente:
{ "input": { "a": 1, "b": 2, "op": "+" }, "output": { "c": 3 } }
En este momento, solo puede llamar a la API utilizando la característica Prueba de la consola de API Gateway. Para hacer que esté disponible para los clientes, debe implementar la API. Asegúrese siempre para volver a implementar la API, cada vez que agrega, modifica o elimina un recurso o un método, actualizar una asignación de datos o actualiza la configuración de la etapa. De lo contrario, las nuevas características o actualizaciones no estarán disponibles para los clientes de la API.
Para implementar la API
Elija Deploy API (Implementar API).
En Etapa, seleccione Nueva etapa.
En Stage name (Nombre de etapa), escriba
Prod
.(Opcional) En Description (Descripción), introduzca una descripción.
Elija Implementar.
-
(Opcional) En Detalles de la etapa, para URL de invocación, puede elegir el icono de copia para copiar la URL de invocación de su API. Puede utilizar esto con herramientas como Postman
y cURL para probar la API.
nota
Vuelva a implementar la API cada vez que agrega, modifica o elimina un recurso o un método, actualiza una asignación de datos o actualiza la configuración de la etapa. De lo contrario, las nuevas características o actualizaciones no estarán disponibles para los clientes de la API.