Amazon API Gateway

Guía del desarrollador

 Amazon API Gateway Guía del desarrollador

Amazon API Gateway: Guía del desarrollador

Copyright © 2021 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Las marcas comerciales y la imagen comercial de Amazon no se pueden utilizar en relación con ningún producto
o servicio que no sea de Amazon, de ninguna manera que pueda causar confusión entre los clientes y de ninguna
manera que menosprecie o desacredite a Amazon. Todas las demás marcas comerciales que no son propiedad de
Amazon son propiedad de sus respectivos propietarios, que pueden o no estar afiliados, conectados o patrocinados
por Amazon.
 Amazon API Gateway Guía del desarrollador

Table of Contents
¿Qué es Amazon API Gateway? .......................................................................................................... 1
Arquitectura de API Gateway ....................................................................................................... 1
Características de API Gateway ................................................................................................... 2
Casos de uso de API Gateway ..................................................................................................... 3
Uso de API Gateway para crear API HTTP ............................................................................ 3
Uso de API Gateway para crear API REST ............................................................................ 3
Uso de API Gateway para crear API de WebSocket ................................................................ 4
¿Quiénes utilizan API Gateway? ........................................................................................... 4
Acceso a API Gateway ............................................................................................................... 5
Parte de la infraestructura sin servidor de AWS .............................................................................. 5
Cómo comenzar a usar Amazon API Gateway ................................................................................ 6
Conceptos de API Gateway ......................................................................................................... 6
Elección entre API HTTP o API de REST ...................................................................................... 9
........................................................................................................................................ 9
Precios de API Gateway ............................................................................................................ 11
Requisitos previos ............................................................................................................................. 13
Introducción ..................................................................................................................................... 14
Paso 1: Crear una función Lambda ............................................................................................. 14
Paso 2: crear una API HTTP ...................................................................................................... 15
Paso 3: probar la API ................................................................................................................ 15
(Opcional) Paso 4: limpiar .......................................................................................................... 16
Pasos siguientes ....................................................................................................................... 17
Tutoriales y talleres ........................................................................................................................... 18
Tutoriales sobre API HTTP ......................................................................................................... 18
API CRUD con Lambda y DynamoDB ................................................................................. 18
Tutoriales sobre API REST ........................................................................................................ 26
Desarrollo de una API con la integración de Lambda ............................................................. 26
Tutorial: Crear una API de REST importando un ejemplo ........................................................ 43
Desarrollo de una API con integración de HTTP .................................................................... 51
Tutorial: Creación de una API con integración privada ............................................................ 87
Tutorial: Creación de una API con integración de AWS ........................................................... 89
Tutorial: API Calc con tres integraciones ............................................................................. 94
Tutorial: Crear una API de REST como proxy de Amazon S3 en API Gateway .......................... 113
Tutorial: Creación de una API de REST como proxy de Amazon Kinesis .................................. 139
Uso de API HTTP ........................................................................................................................... 179
Desarrollo .............................................................................................................................. 179
Creación de una API HTTP .............................................................................................. 179
Rutas ............................................................................................................................ 180
Control de acceso ........................................................................................................... 182
Integraciones .................................................................................................................. 190
CORS ............................................................................................................................ 203
Asignación de parámetros ................................................................................................ 204
OpenAPI ........................................................................................................................ 209
Publicación ............................................................................................................................. 215
Etapas ........................................................................................................................... 215
Nombres de dominio personalizados .................................................................................. 217
Proteger ................................................................................................................................. 219
Limitación controlada ....................................................................................................... 220
TLS mutua ..................................................................................................................... 221
Monitoreo ............................................................................................................................... 224
Métricas ......................................................................................................................... 225
Registro de .................................................................................................................... 226
Solución de problemas ............................................................................................................. 232
Integraciones de Lambda ................................................................................................. 232

iii
 Amazon API Gateway Guía del desarrollador

Autorizadores de JWT ..................................................................................................... 234

Uso de API de REST ...................................................................................................................... 236
Desarrollo .............................................................................................................................. 236
Crear y configurar ........................................................................................................... 236
Control de acceso ........................................................................................................... 269
Integraciones .................................................................................................................. 331
Validación de solicitudes .................................................................................................. 376
Transformaciones de datos ............................................................................................... 389
Respuestas de gateway ................................................................................................... 438
CORS ............................................................................................................................ 445
Tipos de medios binarios ................................................................................................. 453
Invocación ...................................................................................................................... 477
OpenAPI ........................................................................................................................ 500
Publicación ............................................................................................................................. 510
Implementación de una API de REST ................................................................................ 510
Nombres de dominio personalizados .................................................................................. 542
Optimizar ............................................................................................................................... 564
Configuración de caché .................................................................................................... 564
Codificación de contenido ................................................................................................. 570
Distribuir ................................................................................................................................ 574
Planes de uso ................................................................................................................ 574
Documentación de la API ................................................................................................. 589
Generación de SDK ........................................................................................................ 633
Portal para desarrolladores ............................................................................................... 649
Vender sus API como SaaS ............................................................................................. 657
Proteger ................................................................................................................................. 660
TLS mutua ..................................................................................................................... 661
Certificados de cliente ...................................................................................................... 664
AWS WAF ..................................................................................................................... 683
Limitación controlada ....................................................................................................... 685
API privadas ................................................................................................................... 688
Monitoreo ............................................................................................................................... 695
Métricas de CloudWatch .................................................................................................. 696
CloudWatch Logs ............................................................................................................ 702
Kinesis Data Firehose ...................................................................................................... 705
X-Ray ............................................................................................................................ 706
Trabajar con API de WebSocket ....................................................................................................... 717
Acerca de las API de WebSocket .............................................................................................. 717
Administración de usuarios conectados y aplicaciones cliente ................................................ 718
Invocación de la integración del backend ............................................................................ 719
Envío de datos de los servicios de backend a los clientes conectados ..................................... 722
Expresiones de selección de WebSocket ............................................................................ 722
Desarrollo .............................................................................................................................. 727
Crear y configurar ........................................................................................................... 728
Rutas ............................................................................................................................ 729
Control de acceso ........................................................................................................... 734
Integraciones .................................................................................................................. 737
Validación de solicitudes .................................................................................................. 742
Transformaciones de datos ............................................................................................... 743
Tipos de medios binarios ................................................................................................. 751
Invocación ...................................................................................................................... 751
Publicación ............................................................................................................................. 753
Implementación de una API de WebSocket ......................................................................... 753
Nombres de dominio personalizados .................................................................................. 755
Proteger ................................................................................................................................. 758
Limitaciones de nivel de cuenta por región .......................................................................... 758
Limitación controlada de nivel de ruta ................................................................................ 759

iv
 Amazon API Gateway Guía del desarrollador

Monitoreo ............................................................................................................................... 759

Métricas ......................................................................................................................... 760
Registro de .................................................................................................................... 761
ARN de API Gateway ...................................................................................................................... 766
Recursos de API de HTTP y API de WebSocket .......................................................................... 766
Recursos de API de REST ....................................................................................................... 768
execute-api (API de HTTP, API de WebSocket y API de REST) ................................................. 770
Extensiones de OpenAPI ................................................................................................................. 771
x-amazon-apigateway-any-method ..................................................................................... 772
Ejemplos de x-amazon-apigateway-any-method ................................................................... 772
x-amazon-apigateway-cors ........................................................................................................ 773
Ejemplo de x-amazon-apigateway-cors ............................................................................... 773
x-amazon-apigateway-api-key-source .............................................................................. 774
Ejemplo de x-amazon-apigateway-api-key-source ................................................................. 774
x-amazon-apigateway-auth ................................................................................................ 774
Ejemplo de x-amazon-apigateway-auth ............................................................................... 775
x-amazon-apigateway-authorizer ..................................................................................... 775
Ejemplos de x-amazon-apigateway-authorizer para API REST ............................................... 777
Ejemplos de x-amazon-apigateway-authorizer para API HTTP ................................................ 779
x-amazon-apigateway-authtype ......................................................................................... 780
Ejemplo de x-amazon-apigateway-authtype ......................................................................... 781
Véase también ................................................................................................................ 782
x-amazon-apigateway-binary-media-type ..................................................................................... 782
Ejemplo de x-amazon-apigateway-binary-media-types ........................................................... 782
x-amazon-apigateway-documentation ......................................................................................... 782
Ejemplo de x-amazon-apigateway-documentation ................................................................. 783
x-amazon-apigateway-endpoint-configuration ............................................................................... 783
Ejemplos de x-amazon-apigateway-endpoint-configuration ..................................................... 784
x-amazon-apigateway-gateway-responses ................................................................................... 784
Ejemplo de x-amazon-apigateway-gateway-responses .......................................................... 785
x-amazon-apigateway-gateway-responses.gatewayResponse ......................................................... 785
Ejemplo de x-amazon-apigateway-gateway-responses.gatewayResponse ................................ 786
x-amazon-apigateway-gateway-responses.responseParameters ..................................................... 786
Ejemplo de x-amazon-apigateway-gateway-responses.repsonseParameters ............................. 786
x-amazon-apigateway-gateway-responses.responseTemplates ....................................................... 787
Ejemplo de x-amazon-apigateway-gateway-responses.responseTemplates ............................... 787
x-amazon-apigateway-importexport-version ................................................................................. 787
Ejemplo de x-amazon-apigateway-importexport-version ......................................................... 788
x-amazon-apigateway-integration ................................................................................... 788
Ejemplos de x-amazon-apigateway-integration ..................................................................... 791
x-amazon-apigateway-integrations .............................................................................................. 792
Ejemplo de x-amazon-apigateway-integrations ..................................................................... 793
x-amazon-apigateway-integration.requestTemplates ...................................................................... 794
Ejemplo de x-amazon-apigateway-integration.requestTemplates ............................................. 794
x-amazon-apigateway-integration.requestParameters .................................................................... 795
Ejemplo de x-amazon-apigateway-integration.requestParameters .......................... 796
x-amazon-apigateway-integration.responses ................................................................................ 796
Ejemplo de x-amazon-apigateway-integration.responses ......................................... 797
x-amazon-apigateway-integration.response .................................................................................. 797
Ejemplo de x-amazon-apigateway-integration.response .......................................... 798
x-amazon-apigateway-integration.responseTemplates ................................................................... 799
Ejemplo de x-amazon-apigateway-integration.responseTemplate ............................................ 799
x-amazon-apigateway-integration.responseParameters .................................................................. 799
Ejemplo de x-amazon-apigateway-integration.responseParameters ........................ 800
x-amazon-apigateway-integration.tlsConfig .................................................................................. 800
Ejemplos de x-amazon-apigateway-integration.tlsConfig ........................................................ 801
x-amazon-apigateway-minimum-compression-size ........................................................................ 802

v
 Amazon API Gateway Guía del desarrollador

Ejemplo de x-amazon-apigateway-minimum-compression-size ................................................ 802

x-amazon-apigateway-policy ...................................................................................................... 802
Ejemplo de x-amazon-apigateway-policy .................................................................... 802
x-amazon-apigateway-request-validator ....................................................................................... 803
Ejemplo de x-amazon-apigateway-request-validator ................................................ 803
x-amazon-apigateway-request-validators ..................................................................................... 803
Ejemplo de x-amazon-apigateway-request-validators .............................................. 804
x-amazon-apigateway-request-validators.requestValidator .............................................................. 804
Ejemplo de x-amazon-apigateway-request-validators.requestValidator ............... 805
x-amazon-apigateway-tag-value ................................................................................................. 805
Ejemplo de x-amazon-apigateway-tag-value ............................................................... 805
Seguridad ...................................................................................................................................... 807
Protección de los datos ............................................................................................................ 807
Cifrado de datos ............................................................................................................. 808
Privacidad del tráfico entre redes ...................................................................................... 809
Administración de identidades y accesos .................................................................................... 809
Público .......................................................................................................................... 809
Autenticación con identidades ........................................................................................... 810
Administración de acceso mediante políticas ....................................................................... 812
Cómo funciona Amazon API Gateway con IAM .................................................................... 813
Ejemplos de políticas basadas en identidades ..................................................................... 817
Ejemplos de políticas basadas en recursos ......................................................................... 818
Solución de problemas ..................................................................................................... 818
Uso de roles vinculados a servicios ................................................................................... 820
Registro y monitoreo ............................................................................................................... 823
Trabajar con AWS CloudTrail ............................................................................................ 824
Trabajar con AWS Config ................................................................................................. 826
Validación de la conformidad .................................................................................................... 829
Resiliencia .............................................................................................................................. 829
Seguridad de la infraestructura .................................................................................................. 830
Configuración y análisis de vulnerabilidades ................................................................................ 830
Prácticas recomendadas .......................................................................................................... 830
Etiquetado ...................................................................................................................................... 832
Recursos de API Gateway que se pueden etiquetar ..................................................................... 832
Herencia de etiquetas en la API V1 de Amazon API Gateway ................................................ 833
Restricciones de etiquetas y convenciones de uso ............................................................... 834
Control de acceso basado en etiquetas ...................................................................................... 834
Ejemplo 1: Limitar acciones en función de etiquetas de recursos ............................................ 835
Ejemplo 2: Limitar acciones en función de etiquetas en la solicitud .......................................... 835
Ejemplo 3: Denegar acciones en función de etiquetas de recursos .......................................... 836
Ejemplo 4: Permitir acciones en función de etiquetas de recursos ........................................... 837
Ejemplo 5: Permitir acciones en función de las claves de etiquetas de recursos ......................... 837
Referencias de API ......................................................................................................................... 839
Cuotas y notas importantes .............................................................................................................. 840
Cuotas de nivel de cuenta de API Gateway, por región ................................................................. 840
Cuotas de API HTTP ............................................................................................................... 841
.................................................................................................................................... 841
Cuotas de API Gateway para configurar y ejecutar una API de WebSocket ...................................... 842
Cuotas de Amazon para configurar y ejecutar una API REST ........................................................ 843
Cuotas de API Gateway para crear, implementar y administrar una API ........................................... 845
Notas importantes ................................................................................................................... 847
Notas importantes para las API de REST y WebSocket ........................................................ 847
Notas importantes para las API WebSocket ........................................................................ 847
Notas importantes para las API de REST ........................................................................... 848
Historial de revisión ......................................................................................................................... 852
Actualizaciones anteriores ........................................................................................................ 858
Glosario de AWS ............................................................................................................................ 865

vi
 Amazon API Gateway Guía del desarrollador

............................................................................................................................................... dccclxvi

vii
 Amazon API Gateway Guía del desarrollador
Arquitectura de API Gateway

¿Qué es Amazon API Gateway?

Amazon API Gateway es un servicio de AWS para la creación, publicación, mantenimiento, monitoreo
y protección de API REST, HTTP y WebSocket a cualquier escala. Los desarrolladores pueden crear
API que accedan a AWS o a otros servicios web, así como los datos almacenados en la nube de AWS.
Como desarrollador de API de API Gateway, puede crear API para su uso en sus propias aplicaciones de
cliente. También puede ofrecer sus API a otros desarrolladores de aplicaciones externos. Para obtener
más información, consulte the section called “¿Quiénes utilizan API Gateway?” (p. 4).

API Gateway crea API RESTful que:

• Se basan en HTTP.
• Habilitan la comunicación entre cliente y servidor sin estado.
• Implementan métodos HTTP estándar como, por ejemplo, GET, POST, PUT, PATCH y DELETE.

Para obtener más información acerca de las API REST de API Gateway y las API HTTP, consulte
the section called “Elección entre API HTTP o API de REST ” (p. 9), Uso de API HTTP (p. 179),
the section called “Uso de API Gateway para crear API REST” (p. 3) y the section called “Crear y
configurar” (p. 236).

API Gateway crea API de WebSocket que:

• Cumplen el protocolo WebSocket, que permite la comunicación entre el cliente y el servidor de dúplex
completo con estado.
• Dirigen mensajes entrantes en función del contenido de los mensajes.

Para obtener más información sobre las API de WebSocket de API Gateway, consulte the section called
“Uso de API Gateway para crear API de WebSocket” (p. 4) y the section called “Acerca de las API de
WebSocket” (p. 717).

Temas
• Arquitectura de API Gateway (p. 1)
• Características de API Gateway (p. 2)
• Casos de uso de API Gateway (p. 3)
• Acceso a API Gateway (p. 5)
• Parte de la infraestructura sin servidor de AWS (p. 5)
• Cómo comenzar a usar Amazon API Gateway (p. 6)
• Conceptos de Amazon API Gateway (p. 6)
• Elección entre API HTTP y API de REST (p. 9)
• Precios de API Gateway (p. 11)

Arquitectura de API Gateway

En el siguiente diagrama se muestra la arquitectura de API Gateway.

1
 Amazon API Gateway Guía del desarrollador
Características de API Gateway

Este diagrama ilustra cómo las API que crea en Amazon API Gateway le proporcionan a usted o a sus
clientes desarrolladores una experiencia de desarrollador integrada y coherente para crear aplicaciones
sin servidor de AWS. API Gateway gestiona todas las tareas relacionadas con la aceptación y el
procesamiento de centenares de miles de llamadas simultáneas a la API. Estas tareas incluyen la
administración del tráfico, el control de la autorización y el acceso, el monitoreo y la administración de
versiones de la API.

API Gateway actúa como una "puerta principal" para que las aplicaciones accedan a datos, lógica
empresarial o funcionalidad desde sus servicios backend, como cargas de trabajo que se ejecutan en
Amazon Elastic Compute Cloud (Amazon EC2), código que se ejecuta en AWS Lambda, cualquier
aplicación web o aplicaciones de comunicación en tiempo real.

Características de API Gateway

Amazon API Gateway ofrece características como las siguientes:

• Compatibilidad con las API con estado (WebSocket (p. 717)) y las API (HTTP (p. 179) y
REST (p. 236)).
• Mecanismos de autenticación (p. 269) potentes y flexibles, como las políticas de AWS Identity and
Access Management, las funciones de autorización de Lambda y los grupos de usuarios de Amazon
Cognito.
• Portal para desarrolladores (p. 649) para la publicación de sus API.
• Implementaciones de la versión Canary (p. 529) para el despliegue de cambios de forma segura.
• Registro de CloudTrail (p. 824) y monitoreo del uso y de los cambios en las API.
• Registro de acceso y registro de ejecución de CloudWatch, que incluye la posibilidad de establecer
alarmas. Para obtener más información, consulte the section called “Métricas de CloudWatch” (p. 696)
y the section called “Métricas” (p. 760).
• Posibilidad de utilizar plantillas de AWS CloudFormation para habilitar la creación de las API. Para
obtener más información, consulte Referencia de tipos de recursos de Amazon API Gateway y
Referencia de tipos de recursos de Amazon API Gateway V2.
• Soporte para los nombres de dominio personalizados (p. 542).
• Integración con AWS WAF (p. 683) para la protección de sus API frente a ataques web comunes.
• Integración con AWS X-Ray (p. 706) para comprender y cribar latencias de rendimiento.

2
 Amazon API Gateway Guía del desarrollador
Casos de uso de API Gateway

Para obtener una lista completa de lanzamientos de características de API Gateway, consulte Historial de
revisión (p. 852).

Casos de uso de API Gateway

Temas
• Uso de API Gateway para crear API HTTP (p. 3)
• Uso de API Gateway para crear API REST (p. 3)
• Uso de API Gateway para crear API de WebSocket (p. 4)
• ¿Quiénes utilizan API Gateway? (p. 4)

Uso de API Gateway para crear API HTTP

Las API HTTP le permiten crear API de RESTful con menor latencia y menor costo que las API de REST.

Puede utilizar API HTTP para enviar solicitudes a funciones de AWS Lambda o a cualquier punto de
enlace HTTP públicamente direccionable.

Por ejemplo, puede crear una API HTTP que se integre con una función de Lambda en el backend.
Cuando un cliente llama a la API, API Gateway envía la solicitud a la función de Lambda y devuelve la
respuesta de la función al cliente.

Las API HTTP son compatibles con la autorización de OpenID Connect y OAuth 2.0. Vienen con soporte
integrado para el uso compartido de recursos entre orígenes (CORS) y las implementaciones automáticas.

Para obtener más información, consulte the section called “Elección entre API HTTP o API de REST
” (p. 9).

Uso de API Gateway para crear API REST

Una API REST de API Gateway está formada por recursos y métodos. Un recurso es una entidad lógica a
la que una aplicación puede acceder a través de una ruta de recursos. Un método se corresponde con una
solicitud de la API de REST enviada por el usuario de la API y la respuesta devuelta al usuario.

Por ejemplo, /incomes podría ser la ruta de un recurso que representa los ingresos del usuario de
la aplicación. Un recurso puede tener una o varias operaciones, las cuales definen los verbos HTTP
correspondientes, por ejemplo, GET, POST PUT, PATCH y DELETE. Una combinación de una ruta de
recurso y una operación identifica un método de la API. Por ejemplo, un método POST /incomes podría
añadir una ganancia devengada por el intermediario y un método GET /expenses podría consultar los
gastos en los que ha incurrido el intermediario.

La aplicación no necesita saber dónde se almacenan y de dónde se obtienen los datos solicitados en el
backend. En las API REST de API Gateway, el frontend se encapsula mediante solicitudes de métodos
y respuestas de métodos. La API se conecta con el backend por medio de solicitudes de integración y
respuestas de integración.

Por ejemplo, con DynamoDB como backend, el desarrollador de la API configura la solicitud de integración
para reenviar la solicitud del método de entrada al backend elegido. La configuración incluye las
especificaciones de acción de DynamoDB adecuadas y los roles y políticas de IAM necesarios, así como
la transformación de los datos de entrada correcta. El backend devuelve el resultado a API Gateway como
una respuesta de integración.

Para dirigir la respuesta de integración a una respuesta de método adecuada (de un determinado código
de estado HTTP) al cliente, puede configurar la respuesta de integración para que mapee los parámetros

3
 Amazon API Gateway Guía del desarrollador
Uso de API Gateway para crear API de WebSocket

de respuesta necesarios desde la integración del método. A continuación, si fuera necesario, convierta el
formato de los datos de salida del backend al del frontend. API Gateway le permite definir un esquema o
modelo de carga para facilitar la configuración de la plantilla de mapeo de cuerpo.

API Gateway proporciona funcionalidad de administración de la API REST, como a siguiente:

• Soporte para generar SDK y crear la documentación de API mediante extensiones de OpenAPI de API
Gateway
• Limitación controlada de solicitudes HTTP

Uso de API Gateway para crear API de WebSocket

En una API de WebSocket, el cliente y el servidor pueden enviarse mensajes entre sí en cualquier
momento. Los servidores de backend pueden enviar fácilmente datos a los usuarios y dispositivos
conectados, lo que evita la necesidad de implementar complejos mecanismos de sondeo.

Por ejemplo, podría crear una aplicación sin servidor utilizando una API de WebSocket de API Gateway y
AWS Lambda para enviar y recibir mensajes entre usuarios individuales o grupos de usuarios de una sala
de chat. También puede invocar servicios de backend como por ejemplo AWS Lambda, Amazon Kinesis o
un punto de enlace HTTP basándose en el contenido de los mensajes.

Puede utilizar la API de WebSocket de API Gateway para crear aplicaciones seguras de comunicación
en tiempo real sin tener que aprovisionar ni administrar servidores para administrar las conexiones o los
intercambios de datos a gran escala. Los casos de uso focalizados incluyen aplicaciones en tiempo real,
como la siguiente:

• Aplicaciones de chat
• Paneles en tiempo real como los de cotizaciones bursátiles
• Alertas y notificaciones en tiempo real

API Gateway proporciona funcionalidad de administración de la API de WebSocket, como la siguiente:

• Monitoreo y limitación controlada de las conexiones y los mensajes

• Uso de AWS X-Ray para rastrear los mensajes que se transfieren a través de las API a los servicios de
backend
• Integración sencilla con puntos de enlace HTTP/HTTPS

¿Quiénes utilizan API Gateway?

Existen dos tipos de desarrolladores que utilizan API Gateway: los desarrolladores de API y los
desarrolladores de aplicaciones.

Un desarrollador de API crea e implementa una API para habilitar la funcionalidad necesaria en API
Gateway. El desarrollador de API debe ser un usuario de IAM en la cuenta de AWS que posee la API.

Un desarrollador de aplicaciones diseña una aplicación funcional que llama a los servicios de AWS
invocando una API de WebSocket o de REST creada por un desarrollador de API en API Gateway.

El desarrollador de aplicaciones es el cliente del desarrollador de API. El desarrollador de aplicaciones

no necesita tener una cuenta de AWS, siempre que la API no requiera permisos de IAM o bien admita
la autorización de usuarios a través proveedores de identidad federada de terceros admitidos por la
federación de identidades de grupos de usuarios de Amazon Cognito. Los proveedores de identidad
incluyen a Amazon, el grupo de usuarios de Amazon Cognito, Facebook y Google.

4
 Amazon API Gateway Guía del desarrollador
Acceso a API Gateway

Creación y administración de una API de API Gateway

Para crear, configurar e implementar una API, un desarrollador de API trabaja con el componente del
servicio de API Gateway para administración de la API, denominado apigateway.

Como desarrollador de API, puede crear y administrar una API mediante la consola de API Gateway tal
y como se describe en Introducción a la API de API Gateway (p. 14) o llamando a la Referencias de
API (p. 839). Existen varias maneras de llamar a esta API. Incluyen el uso de la interfaz de línea de
comandos (CLI) de AWS o un SDK de AWS. Además, puede habilitar la creación de la API con plantillas
de AWS CloudFormation o (en el caso de las API REST y API HTTP) Trabajar con extensiones de API
Gateway para OpenAPI (p. 771).

Para obtener una lista de las regiones en las que API Gateway está disponible, así como los puntos de
enlace del servicio de control asociados, consulte Cuotas y puntos de enlace de Amazon API Gateway.

Llamadas a un API de API Gateway

Un desarrollador de aplicaciones trabaja con el componente de servicio de API Gateway para ejecución
de la API, denominado execute-api, para invocar una API que se ha creado o implementado en API
Gateway. La API creada expone las entidades de programación subyacentes. Existen varias maneras de
llamar a dicha API. Para obtener más información, consulte Invocación de una API REST en Amazon API
Gateway (p. 477) y Invocación de una API de WebSocket (p. 751).

Acceso a API Gateway

Puede obtener acceso a Amazon API Gateway de las siguientes formas:

• Consola de administración de AWS: los procedimientos de esta guía explican cómo utilizar la consola de
administración de AWS para realizar tareas de la consola de administración de AWS.
• SDK de AWS: si utiliza un lenguaje de programación para el que AWS proporciona un SDK, puede
usar un SDK para obtener acceso a API Gateway. Los SDK simplifican la autenticación, se integran
fácilmente con su entorno de desarrollo y proporcionan acceso a los comandos de API Gateway. Para
obtener más información, consulte Herramientas para Amazon Web Services.
• API de API Gateway V1 y V2: si utiliza un lenguaje de programación para el que no haya un SDK
disponible, consulte la Referencia de la API de Amazon API Gateway versión 1 y la Referencia de la API
de Amazon API Gateway versión 2.
• Interfaz de la línea de comandos de AWS: para obtener más información, consulte Configuración de la
interfaz de la línea de comandos de AWS en la guía del usuario de la interfaz de la línea de comandos
de AWS.
• Herramientas de AWS para Windows PowerShell: para obtener más información, consulte Configuración
de las herramientas de AWS para Windows PowerShell en la guía del usuario de AWS Tools for
Windows PowerShell.

Parte de la infraestructura sin servidor de AWS

Junto con AWS Lambda, API Gateway es la parte de la infraestructura sin servidor de AWS orientada a la
aplicación.

Para que una aplicación llame a los servicios de AWS disponibles públicamente, puede utilizar Lambda
para interactuar con los servicios necesarios y exponer las funciones de Lambda a través de los métodos
de API de API Gateway. AWS Lambda ejecuta el código en una infraestructura informática de alta
disponibilidad. Realiza todos los procesos de ejecución y administración que necesitan los recursos

5
 Amazon API Gateway Guía del desarrollador
Cómo comenzar a usar Amazon API Gateway

informáticos. Para habilitar las aplicaciones sin servidor, API Gateway es compatible con las integraciones
de proxy optimizadas (p. 336) con puntos de enlace de AWS Lambda y HTTP.

Cómo comenzar a usar Amazon API Gateway

Para obtener una introducción a Amazon API Gateway, consulte lo siguiente:

• Introducción (p. 14), que proporciona una explicación para crear una API HTTP.
• Serverless land, que proporciona videos instructivos.

Conceptos de Amazon API Gateway

API Gateway

API Gateway es un servicio de AWS que admite lo siguiente:

• Crear, implementar y administrar una interfaz de programación de aplicaciones (API) RESTful para
exponer los puntos de enlace HTTP del backend, funciones AWS Lambda u otros servicios de AWS.
• Crear, implementar y administrar una API de WebSocket para exponer funciones de AWS Lambda u
otros servicios de AWS.
• Invocar los métodos de API expuestos a través de los puntos de enlace HTTP y WebSocket del
frontend.
API REST de API Gateway

Una colección de recursos y métodos HTTP que se integran con puntos de enlace HTTP del backend,
funciones de Lambda u otros servicios de AWS. Puede implementar esta colección en una o más
etapas. Normalmente, los recursos de la API están organizados en un árbol de recursos de acuerdo
con la lógica de la aplicación. Cada recurso de la API puede exponer uno o varios métodos de la API
que tienen verbos HTTP únicos admitidos por API Gateway.
API HTTP de API Gateway

Colección de rutas y métodos integrados con los puntos de enlace HTTP de backend o funciones de
Lambda. Puede implementar esta colección en una o más etapas. Cada ruta puede exponer uno o
varios métodos de la API que tienen verbos HTTP únicos admitidos por API Gateway.
API de WebSocket de API Gateway

Una colección de rutas y claves de ruta de WebSocket que se integran con puntos de enlace HTTP
del backend, funciones de Lambda u otros servicios de AWS. Puede implementar esta colección en
una o más etapas. Los métodos de la API se invocan a través de conexiones WebSocket del frontend
que se pueden asociar a un nombre de dominio personalizado registrado.
Implementación de API

Una instantánea de un momento dado de la API de API Gateway. Para que los clientes puedan utilizar
la implementación, esta debe asociarse a una o más etapas de API.
Desarrollador de la API

Su cuenta de AWS que posee una implementación de API Gateway (por ejemplo, un proveedor de
servicios que también admite el acceso mediante programación).
Punto de enlace de la API

Un nombre de host para una API de API Gateway que se implementa en una región específica.
El nombre de host tiene el formato {api-id}.execute-api.{region}.amazonaws.com. Se
admiten los siguientes tipos de puntos de enlace de API:

6
 Amazon API Gateway Guía del desarrollador
Conceptos de API Gateway

• Punto de enlace de API optimizada para límites (p. 7)

• Punto de enlace de API privada (p. 8)
• Punto de enlace de API regional (p. 9)
Clave de API

Cadena alfanumérica que API Gateway utiliza para identificar a un desarrollador de aplicaciones que
utiliza su API REST o de WebSocket. API Gateway puede generar claves de API en su nombre o
usted puede importarlas desde un archivo CSV. Puede utilizar claves de API junto con autorizadores
de Lambda (p. 305) o planes de uso (p. 574) para controlar el acceso a sus API.

Consulte los puntos de enlace de API (p. 6).

Propietario de API

Consulte Desarrollador de la API (p. 6).

Etapa de API

Una referencia lógica a un estado del ciclo de vida de la API (por ejemplo, 'dev', 'prod', 'beta', 'v2'). Las
etapas de API se identifican por un ID y un nombre de etapa de API.
Desarrolladores de aplicaciones

Un creador de aplicaciones que puede tener o no una cuenta de AWS y que interactúa con la API que
usted, el desarrollador de API, ha implementado. Los desarrolladores de aplicaciones son sus clientes.
Un desarrollador de aplicaciones suele identificarse por una clave de API (p. 7).
URL de devolución de llamada

Cuando un cliente nuevo se conecta a través de una conexión WebSocket, se puede llamar a una
integración en API Gateway para almacenar la URL de devolución de llamada del cliente. Esa URL de
devolución de llamada se puede utilizar para enviar mensajes al cliente desde el sistema backend.
Portal para desarrolladores

Una aplicación que permite a los clientes registrarse, encontrar y suscribirse a los productos de API
(planes de uso de API Gateway) ofrecidos por usted, administrar sus claves de API y ver sus métricas
de uso para las API.
Punto de enlace de API optimizada para límites

El nombre de host predeterminado de una API de API Gateway implementada en la región

especificada utilizando una distribución de CloudFront para facilitar el acceso de los clientes,
normalmente desde otras regiones de AWS. Las solicitudes de API se dirigen al punto de presencia
de CloudFront más cercano, que normalmente mejora el tiempo de conexión para clientes en distintas
ubicaciones geográficas.

Consulte los puntos de enlace de API (p. 6).

Solicitud de integración

La interfaz interna de una ruta de API de WebSocket o un método de API REST en API Gateway, en
la que se asignará el cuerpo de una solicitud de ruta o los parámetros y el cuerpo de una solicitud de
método a los formatos requeridos por el backend.
Respuesta de integración

La interfaz interna de una ruta de API de WebSocket o un método de API REST en API Gateway, en
la que se asignarán los códigos de estado, los encabezados y la carga que se reciben del backend al
formato de respuesta que se devuelve a una aplicación cliente.
Plantilla de asignación

Un script escrito en Velocity Template Language (VTL), que transforma un cuerpo de la solicitud del
formato de datos del frontend al formato de datos del backend o viceversa (en el caso del cuerpo de
la respuesta). Las plantillas de asignación se pueden especificar en la solicitud de integración o en la

7
 Amazon API Gateway Guía del desarrollador
Conceptos de API Gateway

respuesta de integración. Pueden hacer referencia a datos disponibles en tiempo de ejecución como
contexto y variables de etapa.

La asignación puede ser tan sencilla como una transformación de identidad que transfiere los
encabezados o el cuerpo a través de la integración tal cual desde el cliente al backend para una
solicitud. Lo mismo sucede con la respuesta, en la que la carga se transmite desde el backend al
cliente.
Solicitud de método

La interfaz pública de un método de una API de API Gateway que define los parámetros y el cuerpo
que un desarrollador de aplicaciones debe enviar en las solicitudes para acceder al backend a través
de la API.
Respuesta de método

La interfaz pública de una API de REST que define los códigos de estado, los encabezados y los
modelos de cuerpo que un desarrollador de aplicaciones debería esperar en las respuestas de la API.
Integración simulada

En una integración simulada, las respuestas de la API se generan directamente a partir de API
Gateway, sin necesidad de un backend de integración. Como desarrollador de una API, puede decidir
cómo API Gateway responde a una solicitud de integración simulada. Para ello, configura la solicitud
de integración y la respuesta de integración del método para asociar una respuesta a un código de
estado determinado.
Modelo

Un esquema de datos que especifica la estructura de datos de una solicitud o carga de respuesta.
Es necesario un modelo para generar un SDK con establecimiento inflexible de tipos de una API.
También se utiliza para validar cargas. Un modelo es cómodo para generar una plantilla de asignación
de muestra para iniciar la creación de una plantilla de asignación de producción. Aunque es útil, no se
requiere para crear una plantilla de asignación.
API privado

Consulte Punto de enlace de API privada (p. 8)

Punto de enlace de API privada

Un punto de enlace de API que se expone a través de puntos de enlace de la VPC de tipo interfaz y
permite que un cliente obtenga acceso seguro a los recursos de una API privada dentro de una VPC.
Las API privadas están aisladas de la red pública de Internet y solo se puede obtener acceso a ellas a
través de los puntos de enlace de la VPC de API Gateway a los que se les ha concedido acceso.
Integración privada

Tipo de integración de API Gateway que permite que un cliente tenga acceso a los recursos que se
encuentran en la VPC de un usuario a través de un punto de enlace de una API REST privada sin
exponerlos a la red pública de Internet.
Integración de proxy

Una configuración simplificada de integración de API Gateway. Puede configurar una integración de
proxy como una integración de proxy HTTP o como una integración de proxy de Lambda.

En el caso de la integración de proxy HTTP, API Gateway transmite toda la solicitud y la respuesta
entre el frontend y un backend HTTP. Para la integración de proxy Lambda, API Gateway envía
toda la solicitud como entrada a una función de Lambda de backend. A continuación, API Gateway
transforma el resultado de la función de Lambda en una respuesta HTTP del frontend.

En las API de REST, la integración de proxy se utiliza normalmente con un recurso de proxy, que
se representa mediante una variable de ruta expansiva (por ejemplo, {proxy+}) combinada con un
método catch-all ANY.

8
 Amazon API Gateway Guía del desarrollador
Elección entre API HTTP o API de REST

Creación rápida

Puede utilizar la creación rápida para simplificar la creación de una API HTTP. La creación rápida crea
una API con una integración de Lambda o HTTP, una ruta de método catch-all predeterminada y una
etapa predeterminada configurada para implementar automáticamente los cambios. Para obtener más
información, consulte the section called “Crear una API HTTP mediante la CLI de AWS” (p. 180).
Punto de enlace de API regional

El nombre de host de una API implementada en la región especificada y pensada para prestar servicio
a clientes, como, por ejemplo, instancias EC2, de la misma región de AWS. Las solicitudes de API
se dirigen directamente a la API de API Gateway específica de la región sin pasar por ninguna
distribución de CloudFront. Para las solicitudes destinadas a la misma región, existe un punto de
enlace regional que evita el trayecto innecesario de ida y vuelta a una distribución de CloudFront.

Además, puede aplicar el direccionamiento basado en latencia a los puntos de enlace regionales
para implementar una API en varias regiones con la misma configuración de punto de enlace de
API regional, establecer el mismo nombre de dominio personalizado para cada API implementada y
configurar registros de DNS basados en latencia en Route 53 para dirigir las solicitudes de los clientes
a la región que tiene la mínima latencia.

Consulte los puntos de enlace de API (p. 6).

Ruta

Se utiliza una ruta de WebSocket en API Gateway para direccionar los mensajes entrantes a una
integración determinada, como una función de AWS Lambda, en función del contenido de los
mensajes. Al definir la API de WebSocket, se especifica un clave de ruta y un backend de integración.
La clave de ruta es un atributo del cuerpo del mensaje. Cuando se encuentra una coincidencia para la
clave de ruta en un mensaje entrante, se invoca el backend de integración.

También se puede establecer una ruta predeterminada para las claves de ruta no coincidentes o para
especificar un modelo de proxy que transfiera el mensaje tal cual a los componentes del backend que
realizan el direccionamiento y procesan la solicitud.
Solicitud de ruta

La interfaz pública de un método de API de WebSocket en API Gateway que define el cuerpo que un
desarrollador de aplicaciones debe enviar en las solicitudes para obtener acceso al backend a través
de la API.
Respuesta de ruta

La interfaz pública de una API de WebSocket que define los códigos de estado, los encabezados y los
modelos de cuerpo que un desarrollador de aplicaciones debería esperar de API Gateway.
Plan de uso

Un plan de uso (p. 574) ofrece a determinados clientes de la API acceso a una o varias API de
WebSocket o de REST implementadas. Puede utilizar un plan de uso para configurar la limitación
controlada y los límites de cuota que se ejecutarán en claves de API de cliente individual.
Conexión WebSocket

API Gateway mantiene una conexión persistente entre los clientes y API Gateway. No hay conexión
persistente entre API Gateway y las integraciones de backend, como las funciones de Lambda. Los
servicios de backend se invocan según sea necesario, en función del contenido de los mensajes
recibidos de los clientes.

Elección entre API HTTP y API de REST

9
 Amazon API Gateway Guía del desarrollador
Elección entre API HTTP o API de REST

Las API HTTP se diseñan para integraciones rentables y de baja latencia con servicios de AWS, incluido
AWS Lambda y puntos de enlace HTTP. Las API HTTP admiten la autorización de OIDC y OAuth 2.0 e
incluyen soporte integrado para CORS e implementaciones automáticas. Las API REST de generación
anterior ofrecen más funciones actualmente.

En las siguientes tablas se resumen las características principales disponibles en las API HTTP y las API
de REST.

Autorizadores API HTTP API REST

AWS Lambda ✓ ✓

IAM ✓ ✓

Amazon Cognito ✓* ✓

OpenID Connect/OAuth 2.0 ✓

nativa

* Puede utilizar Amazon Cognito como emisor de JWT.

Integración API HTTP API REST

HTTP ✓ ✓

Lambda ✓ ✓

Servicios de AWS ✓ ✓

Integración privada ✓ ✓

Simulada ✓

Administración de API API HTTP API REST

Planes de uso ✓

Claves de API ✓

Nombres de dominio ✓* ✓
personalizados

* Las API HTTP no admiten TLS 1.0.

Desarrollo API HTTP API REST

Almacenamiento en caché de la ✓
API

Transformación de solicitudes ✓ ✓

Validación de solicitudes/ ✓
respuestas

Invocación de prueba ✓

10
 Amazon API Gateway Guía del desarrollador
Precios de API Gateway

Desarrollo API HTTP API REST

Configuración de CORS ✓ ✓*

Implementaciones automáticas ✓

Etapa predeterminada ✓

Ruta predeterminada ✓

Respuestas de gateway ✓
personalizadas (p. 438)

* Puede combinar diferentes características de las API de REST para que admitan CORS. Para obtener
más información, consulte the section called “CORS” (p. 445).

Seguridad API HTTP API REST

Autenticación TLS mutua ✓ ✓

Certificados para autenticación ✓

de backend (p. 664)

AWS WAF ✓

Políticas de recursos ✓

Tipo de API API HTTP API REST

Regional ✓ ✓

Optimizada para borde ✓

Private ✓

Monitoreo API HTTP API REST

Registros de acceso a Amazon ✓ ✓

CloudWatch Logs

Registros de acceso a Amazon ✓

Kinesis Data Firehose

Registros de ejecución ✓

Métricas de Amazon CloudWatch ✓ ✓

AWS X-Ray ✓

Precios de API Gateway

Para obtener información general sobre precios específicos en la región de API Gateway, consulte Precios
de Amazon API Gateway.

11
 Amazon API Gateway Guía del desarrollador
Precios de API Gateway

A continuación, se enumeran las excepciones al esquema general de precios:

• El almacenamiento en caché de API en Amazon API Gateway no está disponible en la Capa gratuita de
AWS.
• Las solicitudes no se cobran por errores de autorización y autenticación.
• Las llamadas a métodos que requieran claves de API no se cobrarán si faltan las claves de API o no son
válidas.
• Las solicitudes limitadas por API Gateway no se cobran si la tasa de solicitudes o de ráfagas supera los
límites preconfigurados.
• Las solicitudes de uso limitadas por el plan no se cobran si los límites de tarifa o la cuota superan los
límites preconfigurados.

12
 Amazon API Gateway Guía del desarrollador

Requisitos previos para comenzar

con API Gateway
Para utilizar API Gateway y otros servicios de AWS, necesita una cuenta de AWS. Si no dispone de una
cuenta de AWS, vaya a aws.amazon.com y elija Create an AWS Account (Crear una cuenta de AWS).
Para obtener instrucciones detalladas, consulte Crear y activar una cuenta de AWS.

Como práctica recomendada, también debe crear un usuario de AWS Identity and Access Management
(IAM) con permisos de administrador y utilizarlo para todo el trabajo que no requiera credenciales raíz.
Cree una contraseña para el acceso a la consola y claves de acceso para utilizar herramientas de línea de
comandos. Consulte Creación del primer grupo y usuario de administrador de IAM en la Guía del usuario
de IAM para obtener instrucciones.

13
 Amazon API Gateway Guía del desarrollador
Paso 1: Crear una función Lambda

Introducción a la API de API Gateway

En este ejercicio introductorio, creará una API sin servidor. Las API sin servidor permiten centrarse en
las aplicaciones, en lugar de dedicar tiempo a aprovisionar y administrar servidores. Este ejercicio tarda
menos de 20 minutos en completarse y se puede realizar dentro de la capa gratuita de AWS.

En primer lugar, crea una función de Lambda con la consola de AWS Lambda. A continuación, crea una
API HTTP mediante la consola de API Gateway. Luego, invoca su API.

Cuando invoca su API HTTP, API Gateway enruta la solicitud a su función de Lambda. Lambda ejecuta la
función de Lambda y devuelve una respuesta a API Gateway. API Gateway, a continuación, le devuelve
una respuesta.

Para completar este ejercicio, necesita una cuenta de AWS y un usuario de AWS Identity and Access
Management con acceso a la consola. Para obtener más información, consulte Requisitos previos (p. 13).

Temas
• Paso 1: Crear una función Lambda (p. 14)
• Paso 2: crear una API HTTP (p. 15)
• Paso 3: probar la API (p. 15)
• (Opcional) Paso 4: limpiar (p. 16)
• Pasos siguientes (p. 17)

Paso 1: Crear una función Lambda

Usa una función de Lambda para el backend de su API. Lambda ejecuta su código solo cuando es
necesario y escala de manera automática, desde unas pocas solicitudes por día hasta miles por segundo.

Para este ejemplo, utilice la función Node.js predeterminada de la consola de Lambda.

Para crear una función Lambda, realice el siguiente procedimiento:

1. Inicie sesión en la consola de Lambda en https://console.aws.amazon.com/lambda/.

2. Elija Create function (Crear función).
3. En Function name (Nombre de función), escriba my-function.
4. Elija Create function (Crear función).

La función de ejemplo devuelve una 200 respuesta a los clientes y el texto Hello from Lambda!.

14
 Amazon API Gateway Guía del desarrollador
Paso 2: crear una API HTTP

Puede modificar su función de Lambda, siempre y cuando la respuesta de la función se alinea con el
formato que requiere API Gateway (p. 194).

El código predeterminado de la función de Lambda debe ser similar al siguiente:

exports.handler = async (event) => {

const response = {
statusCode: 200,
body: JSON.stringify('Hello from Lambda!'),
};
return response;
};

Paso 2: crear una API HTTP

A continuación, cree una API HTTP. API Gateway también admite API REST y API WebSocket, pero
una API HTTP es la mejor opción para este ejercicio. Las API HTTP tienen menor latencia y menor costo
que las API REST. Las API WebSocket mantienen conexiones persistentes con los clientes para la
comunicación dúplex completo, lo cual no es necesario para este ejemplo.

La API HTTP proporciona un punto de enlace HTTP para su función de Lambda. API Gateway enruta las
solicitudes a su función de Lambda y, a continuación, devuelve la respuesta de la función a los clientes.

Para crear una API HTTP

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Aplique alguna de las siguientes acciones:
• Para crear su primera API, para HTTP API (API HTTP), elija Build (Crear).
• Si ha creado una API antes, elija Create API (Crear API) y, a continuación, elija Build (Crear) para
HTTP API (API HTTP).
3. Para Integrations (Integraciones), elija Add integration (Agregar integración).
4. Elija Lambda.
5. Para Lambda function (función de Lambda), escriba my-function.
6. En API name (Nombre de la API), escriba my-http-api.
7. Elija Next (Siguiente).
8. Revise la ruta que API Gateway crea para usted y, a continuación, elija Next (Siguiente).
9. Revise la etapa que API Gateway crea para usted y, a continuación, elija Next (Siguiente).
10. Seleccione Create (Crear).

Ahora ha creado una API HTTP con una integración de Lambda que está lista para recibir solicitudes de
clientes.

Paso 3: probar la API

A continuación, pruebe su API para asegurarse de que se encuentra en funcionamiento. Para mayor
simplicidad, utilice un navegador web para invocar la API.

Para probar la API

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

15
 Amazon API Gateway Guía del desarrollador
(Opcional) Paso 4: limpiar

2. Elija la API.
3. Tenga en cuenta la URL de invocación de la API.

4. Copie la URL de invocación de la API y escríbala en un navegador web. Agregue el nombre de

la función de Lambda a la URL de invocación para llamar a su función de Lambda. De forma
predeterminada, la consola de API Gateway crea una ruta con el mismo nombre que su función de
Lambda, my-function.

La URL completa debería verse así https://abcdef123.execute-api.us-

east-2.amazonaws.com/my-function.

Su navegador envía una GET solicitud a la API.

5. Verifique la respuesta de la API. Debería ver el texto "Hello from Lambda!" en el navegador.

(Opcional) Paso 4: limpiar

Para evitar costos innecesarios, elimine los recursos creados como parte de este ejercicio introductorio.
Los siguientes pasos eliminan la API HTTP, la función de Lambda y los recursos asociados.

Para eliminar una API HTTP

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. En la página API, seleccione una API. Seleccione Actions y, luego, Delete.
3. Elija Eliminar.

Para eliminar una función de Lambda

1. Inicie sesión en la consola de Lambda en https://console.aws.amazon.com/lambda/.

2. En la página Functions (Funciones), seleccione una función. Seleccione Actions y, luego, Delete.
3. Elija Eliminar.

16
 Amazon API Gateway Guía del desarrollador
Pasos siguientes

Para eliminar el grupo de registro de una función de Lambda

1. En la consola de Amazon CloudWatch, abra la página de grupos de registro.

2. En la página Grupos de registro, seleccione el grupo de registro de la función (/aws/lambda/my-
function). Elija Actions (Acciones) y, a continuación, elija Delete log group (Eliminar grupo de
registro).
3. Elija Eliminar.

Para eliminar el rol de ejecución de una función de Lambda

1. En la consola de AWS Identity and Access Management, abra la página de roles.

2. Seleccione el rol de la función, por ejemplo, my-function-31exxmpl.
3. Elija Delete role (Eliminar rol).
4. Elija Sí, eliminar.

Puede automatizar la creación y limpieza de recursos de AWS mediante AWS CloudFormation o

AWS SAM. Por ejemplo, plantillas de AWS CloudFormation, consulte el ejemplo de plantillas de AWS
CloudFormation.

Pasos siguientes
Para este ejemplo, utilizó la consola de administración de AWS para crear una API HTTP simple. La API
HTTP invoca una función de Lambda y devuelve una respuesta a los clientes.

A continuación se indican los pasos siguientes a medida que continúa trabajando con API Gateway.

• Configure tipos adicionales de integraciones de API, (p. 190) entre los que se incluyen:
• Puntos de enlace HTTP (p. 195)
• Recursos privados en una VPC, como los servicios ECS de Amazon (p. 201)
• Servicios de AWS como Amazon Simple Queue Service, AWS Step Functions y Kinesis Data
Streams (p. 195)
• Controlar el acceso a las API (p. 182)
• Habilitar el registro de las API (p. 226)
• Configurar la limitación de las API (p. 220)
• Configurar dominios personalizados para las API (p. 217)

Para obtener ayuda de la comunidad con Amazon API Gateway, consulte el foro de debate de API
Gateway. Cuando entre en este foro, es posible que AWS requiera que inicie sesión.

Para obtener ayuda sobre API Gateway directamente en AWS, consulte las distintas opciones de soporte
que se ofrecen en la página de AWS Support.

Consulte también nuestras preguntas frecuentes o contacte con nosotros directamente.

17
 Amazon API Gateway Guía del desarrollador
Tutoriales sobre API HTTP

Tutoriales y talleres sobre Amazon

API Gateway
Los siguientes tutoriales y talleres proporcionan ejercicios prácticos para obtener información sobre API
Gateway.

Tutoriales sobre API HTTP

• Tutorial: Creación de una API CRUD con Lambda y DynamoDB (p. 18)

Tutoriales sobre API REST

• Desarrollo de una API de REST de API Gateway con integración Lambda (p. 26)
• Tutorial: Crear una API de REST importando un ejemplo (p. 43)
• Desarrollo de una API de REST de API Gateway con integración HTTP (p. 51)
• Tutorial: Crear una API REST con la integración privada de API Gateway (p. 87)
• Tutorial: Creación de una API de REST de API Gateway con integración de AWS (p. 89)
• Tutorial: Crear una API REST Calc con dos integraciones de servicios de AWS y una integración de
Lambda sin proxy (p. 94)
• Tutorial: Crear una API de REST como proxy de Amazon S3 en API Gateway (p. 113)
• Tutorial: Creación de una API de REST como proxy de Amazon Kinesis en API Gateway (p. 139)

Talleres

• Desarrollo de una aplicación web sin servidor 

• CI/CD para aplicaciones sin servidor
• Taller sobre seguridad sin servidor
• Administración, autenticación y autorización de identidades sin servidor

Tutoriales sobre API HTTP de Amazon API

Gateway
Los siguientes tutoriales proporcionan ejercicios prácticos para saber más sobre las API HTTP de API
Gateway.

Temas
• Tutorial: Creación de una API CRUD con Lambda y DynamoDB (p. 18)

Tutorial: Creación de una API CRUD con Lambda y

DynamoDB
En este tutorial, creará una API sin servidor para crear, leer, actualizar y eliminar elementos de una tabla
de DynamoDB. DynamoDB es un servicio de bases de datos NoSQL completamente administrado que

18
 Amazon API Gateway Guía del desarrollador
API CRUD con Lambda y DynamoDB

proporciona un rendimiento rápido y predecible, así como una escalabilidad óptima. Completar este tutorial
lleva aproximadamente 30 minutos y puede hacerse dentro de la capa gratuita de AWS.

En primer lugar, se crea una tabla de DynamoDB con la consola de DynamoDB. Luego, se crea una
función de Lambda con la consola de AWS Lambda. A continuación, crea una API HTTP mediante la
consola de API Gateway. Por último, se prueba la API.

Cuando invoca su API HTTP, API Gateway enruta la solicitud a su función de Lambda. La función
de Lambda interactúa con DynamoDB y devuelve una respuesta a API Gateway. API Gateway, a
continuación, le devuelve una respuesta.

Para completar este ejercicio, necesita una cuenta de AWS y un usuario de AWS Identity and Access
Management con acceso a la consola. Para obtener más información, consulte Requisitos previos (p. 13).

En este tutorial, se utiliza la consola de administración de AWS. Para obtener una plantilla de AWS SAM
que cree esta API y todos los recursos relacionados, consulte template.yaml.

Temas
• Paso 1: crear una tabla de DynamoDB (p. 19)
• Paso 2: crear una función de Lambda (p. 19)
• Paso 3: crear una API HTTP (p. 21)
• Paso 4: crear rutas (p. 21)
• Paso 5: crear una integración (p. 22)
• Paso 6: asociar la integración a las rutas (p. 23)
• Paso 7: probar la API (p. 24)
• Paso 8: Eliminar (p. 25)
• Próximos pasos: automatizar con AWS SAM o AWS CloudFormation (p. 26)

Paso 1: crear una tabla de DynamoDB

Se utiliza una tabla de DynamoDB destinada a almacenar datos para la API.

Cada elemento tiene un ID único, que usamos como clave de partición para la tabla.

Cree una tabla de DynamoDB

1. Abra la consola de DynamoDB en https://console.aws.amazon.com/dynamodb/.

2. Seleccione Create table.
3. En Table name (Nombre de la tabla), escriba http-crud-tutorial-items.
4. En Primary key (Clave principal) escriba id.
5. Seleccione Create (Crear).

Paso 2: crear una función de Lambda

Se crea una función de Lambda para el backend de la API. Esta función de Lambda crea, lee, actualiza y
elimina elementos de DynamoDB. La función utiliza eventos de API Gateway (p. 191) para determinar

19
 Amazon API Gateway Guía del desarrollador
API CRUD con Lambda y DynamoDB

cómo interactuar con DynamoDB. Para simplificar el proceso, este tutorial utiliza una sola función de
Lambda. Como práctica recomendada, se deben crear funciones separadas para cada ruta.

Para crear una función Lambda, realice el siguiente procedimiento:

1. Inicie sesión en la consola de Lambda en https://console.aws.amazon.com/lambda/.

2. Elija Create function (Crear función).
3. En Function name (Nombre de función), escriba http-crud-tutorial-function.
4. En Permissions (Permisos), seleccione Change default execution role (Cambiar el rol de ejecución
predeterminado).
5. Seleccione Create a new role from AWS policy templates (Crear un nuevo rol a partir de plantillas de
políticas de AWS).
6. En Role name (Nombre del rol), escriba http-crud-tutorial-role.
7. En Policy templates (Plantillas de políticas), seleccione Simple microservice permissions.
Esta política concede a la función de Lambda permiso para interactuar con DynamoDB.
Note

Para simplificar el proceso, este tutorial utiliza una política administrada. Como práctica
recomendada, se deben crear políticas de IAM propias para conceder los permisos mínimos
requeridos.
8. Elija Create function (Crear función).
9. Abra index.js en el editor de código de la consola y reemplace su contenido con el siguiente código.
Seleccione Deploy (Implementar) para actualizar la función.

const AWS = require("aws-sdk");

const dynamo = new AWS.DynamoDB.DocumentClient();

exports.handler = async (event, context) => {

let body;
let statusCode = 200;
const headers = {
"Content-Type": "application/json"
};

try {
switch (event.routeKey) {
case "DELETE /items/{id}":
await dynamo
.delete({
TableName: "http-crud-tutorial-items",
Key: {
id: event.pathParameters.id
}
})
.promise();
body = `Deleted item ${event.pathParameters.id}`;
break;
case "GET /items/{id}":
body = await dynamo
.get({
TableName: "http-crud-tutorial-items",
Key: {
id: event.pathParameters.id
}
})
.promise();

20
 Amazon API Gateway Guía del desarrollador
API CRUD con Lambda y DynamoDB

break;
case "GET /items":
body = await dynamo.scan({ TableName: "http-crud-tutorial-items" }).promise();
break;
case "PUT /items":
let requestJSON = JSON.parse(event.body);
await dynamo
.put({
TableName: "http-crud-tutorial-items",
Item: {
id: requestJSON.id,
price: requestJSON.price,
name: requestJSON.name
}
})
.promise();
body = `Put item ${requestJSON.id}`;
break;
default:
throw new Error(`Unsupported route: "${event.routeKey}"`);
}
} catch (err) {
statusCode = 400;
body = err.message;
} finally {
body = JSON.stringify(body);
}

return {
statusCode,
body,
headers
};
};

Paso 3: crear una API HTTP

La API HTTP proporciona un punto de enlace HTTP para su función de Lambda. En este paso, se crea
una API vacía. En los siguientes pasos, se configuran rutas e integraciones para conectar la API y la
función de Lambda.

Para crear una API HTTP

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Seleccione Create API (Crear API)y, a continuación, en API HTTP, seleccione Build (Crear).
3. En API name (Nombre de la API), escribahttp-crud-tutorial-api.
4. Elija Next (Siguiente).
5. En Configure routes (Configurar rutas), seleccione Next (Siguiente) para omitir la creación de rutas. Se
crearán rutas más adelante.
6. Revise la etapa que crea API Gateway y, a continuación, seleccione Next (Siguiente).
7. Seleccione Create (Crear).

Paso 4: crear rutas

Las rutas son una manera de enviar solicitudes entrantes de API a los recursos de backend. Las rutas
constan de dos partes: un método HTTP y una ruta de recurso, por ejemplo, GET /items. Para este
ejemplo de API, creamos cuatro rutas:

21
 Amazon API Gateway Guía del desarrollador
API CRUD con Lambda y DynamoDB

• GET /items/{id}
• GET /items
• PUT /items
• DELETE /items/{id}

Para crear rutas

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija la API.
3. Elija Routes (Rutas).
4. Seleccione Create (Crear).
5. En Method (Método), seleccione GET.
6. Para la ruta, escriba /items/{id}. El {id} al final de la ruta es un parámetro de ruta que API
Gateway recupera de la ruta de solicitud cuando un cliente realiza una solicitud.
7. Seleccione Create (Crear).
8. Repita los pasos 4 a 7 para GET /items, DELETE /items/{id} y PUT /items.

Paso 5: crear una integración

Se crea una integración para conectar una ruta a los recursos de backend. Para este ejemplo de API, se
crea una integración de Lambda que se utiliza para todas las rutas.

Para crear una integración

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija la API.
3. Seleccione Integrations (Integraciones).

22
 Amazon API Gateway Guía del desarrollador
API CRUD con Lambda y DynamoDB

4. Seleccione Manage integrations (Administrar integraciones) y, a continuación, seleccione Create

(Crear).
5. Omita Attach this integration to a route (Asociar esta integración a una ruta). Esta etapa se completará
más adelante.
6. En Integration type (Tipo de integración), elija Lambda function (Función Lambda).
7. En Lambda function (Función de Lambda), escriba http-crud-tutorial-function.
8. Seleccione Create (Crear).

Paso 6: asociar la integración a las rutas

Para este ejemplo de API, se utiliza la misma integración de Lambda para todas las rutas. Después de
asociar la integración a todas las rutas de la API, la función de Lambda se invoca cuando un cliente llama a
cualquiera de sus rutas.

Para asociar integraciones a rutas

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija la API.
3. Seleccione Integrations (Integraciones).
4. Seleccione una ruta.
5. En Choose an existing integration (Elegir una integración existente), seleccione http-crud-
tutorial-function.
6. Seleccione Attach integration (Asociar integración).
7. Repita los pasos 4 a 6 para todas las rutas.

Todas las rutas muestran que se asoció una integración de AWS Lambda.

Ahora que se tiene una API HTTP con rutas e integraciones, se puede probar la API.

23
 Amazon API Gateway Guía del desarrollador
API CRUD con Lambda y DynamoDB

Paso 7: probar la API

Para asegurarse de que la API funciona, se utiliza curl.

Para obtener la URL para invocar la API

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija la API.
3. Tenga en cuenta la URL de invocación de la API. Aparece en Invoke URL (Invocar URL) en la página
Details (Detalles).

4. Copie la URL de invocación de la API.

La totalidad de la URL se parece a https://abcdef123.execute-api.us-

west-2.amazonaws.com.

Para crear o actualizar un elemento

• Utilice el siguiente comando para crear o actualizar un elemento. El comando incluye un cuerpo de
solicitud con el ID, el precio y el nombre del elemento.

curl -v -X "PUT" -H "Content-Type: application/json" -d "{\"id\": \"abcdef234\",

\"price\": 12345, \"name\": \"myitem\"}" https://abcdef123.execute-api.us-
west-2.amazonaws.com/items

Para ver todos los elementos

• Utilice el siguiente comando para enumerar todos los elementos.

curl -v https://abcdef123.execute-api.us-west-2.amazonaws.com/items

Para ver un elemento

• Utilice el siguiente comando para ver un elemento por su ID.

24
 Amazon API Gateway Guía del desarrollador
API CRUD con Lambda y DynamoDB

curl -v https://abcdef123.execute-api.us-west-2.amazonaws.com/items/abcdef234

Para eliminar un elemento

1. Utilice el siguiente comando para eliminar un elemento.

curl -v -X "DELETE" https://abcdef123.execute-api.us-west-2.amazonaws.com/

items/abcdef234

2. Vea todos los elementos para verificar que el elemento se eliminó.

curl -v https://abcdef123.execute-api.us-west-2.amazonaws.com/items

Paso 8: Eliminar
Para evitar costos innecesarios, elimine los recursos creados como parte de este ejercicio introductorio.
Los siguientes pasos eliminan la API HTTP, la función de Lambda y los recursos asociados.

Para eliminar una tabla de DynamoDB

1. Abra la consola de DynamoDB en https://console.aws.amazon.com/dynamodb/.

2. Seleccione la tabla.
3. Elija Delete table (Eliminar tabla).
4. Confirme la elección y seleccione Delete (Eliminar).

Para eliminar una API HTTP

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. En la página API, seleccione una API. Seleccione Actions y, luego, Delete.
3. Elija Eliminar.

Para eliminar una función de Lambda

1. Inicie sesión en la consola de Lambda en https://console.aws.amazon.com/lambda/.

2. En la página Functions (Funciones), seleccione una función. Seleccione Actions y, luego, Delete.
3. Elija Eliminar.

Para eliminar el grupo de registro de una función de Lambda

1. En la consola de Amazon CloudWatch, abra la página de grupos de registro.

2. En la página Log groups (Grupos de registro), seleccione el grupo de registro de la función (/aws/
lambda/http-crud-tutorial-function). Elija Actions (Acciones) y, a continuación, elija Delete
log group (Eliminar grupo de registro).
3. Elija Eliminar.

Para eliminar el rol de ejecución de una función de Lambda

1. En la consola de AWS Identity and Access Management, abra la página de roles.

25
 Amazon API Gateway Guía del desarrollador
Tutoriales sobre API REST

2. Seleccione el rol de la función, por ejemplo, http-crud-tutorial-role.

3. Elija Delete role (Eliminar rol).
4. Elija Sí, eliminar.

Próximos pasos: automatizar con AWS SAM o AWS

CloudFormation
Puede automatizar la creación y limpieza de recursos de AWS mediante AWS CloudFormation o AWS
SAM. Para obtener un ejemplo de plantilla de AWS SAM para este tutorial, consulte template.yaml.

Por ejemplo, plantillas de AWS CloudFormation, consulte el ejemplo de plantillas de AWS CloudFormation.

Tutoriales sobre API REST de Amazon API

Gateway
Los siguientes tutoriales proporcionan ejercicios prácticos para saber más sobre las API REST de API
Gateway.

Temas
• Desarrollo de una API de REST de API Gateway con integración Lambda (p. 26)
• Tutorial: Crear una API de REST importando un ejemplo (p. 43)
• Desarrollo de una API de REST de API Gateway con integración HTTP (p. 51)
• Tutorial: Crear una API REST con la integración privada de API Gateway (p. 87)
• Tutorial: Creación de una API de REST de API Gateway con integración de AWS (p. 89)
• Tutorial: Crear una API REST Calc con dos integraciones de servicios de AWS y una integración de
Lambda sin proxy (p. 94)
• Tutorial: Crear una API de REST como proxy de Amazon S3 en API Gateway (p. 113)
• Tutorial: Creación de una API de REST como proxy de Amazon Kinesis en API Gateway (p. 139)

Desarrollo de una API de REST de API Gateway con

integración Lambda
Para desarrollar una API con integraciones de Lambda puede utilizar la integración de proxy de Lambda o
la integración de Lambda no de proxy.

Con la integración de proxy de Lambda, la entrada para la función de Lambda integrada se puede expresar
como cualquier combinación de encabezados de solicitud, variables de ruta, parámetros de cadena de
consulta y cuerpo. Además, la función de Lambda puede utilizar los valores de configuración de la API
para influir en su lógica de ejecución. Para un desarrollador de API, la configuración de una integración
de proxy de Lambda es sencilla. Además de elegir una función de Lambda específica en una región
determinada, no hay mucho que pueda hacer. API Gateway configura la solicitud de integración y la
respuesta de integración por usted. Una vez configurado, el método de API integrado puede evolucionar
con el backend sin modificar la configuración existente. Esto es posible porque el desarrollador de la
función de Lambda del backend analiza los datos de la solicitud entrante y responde al cliente con los
resultados deseados cuando todo va bien o con mensajes de error cuando algo va mal.

En la integración de Lambda no de proxy, debe asegurarse de que la entrada a la función de Lambda

se proporcione como la carga de solicitud de integración. Esto implica que usted, como desarrollador de

26
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

la API, debe asignar los datos de entrada que el cliente proporcionó como parámetros de solicitud en el
cuerpo de solicitud de integración adecuado. Es posible que también deba traducir el cuerpo de solicitud
proporcionado por el cliente a un formato reconocido por la función de Lambda.

Temas
• Tutorial: Desarrollo de una API de REST Hello World con integración de proxy de Lambda (p. 27)
• Tutorial: Desarrollo de una API de REST de API Gateway con integración de proxy de Lambda entre
cuentas (p. 32)
• Tutorial: Desarrollo de una API de REST de API Gateway con integración no de proxy de
Lambda (p. 34)

Tutorial: Desarrollo de una API de REST Hello World con

integración de proxy de Lambda
La integración de proxy de Lambda (p. 340) es un tipo de integración de API de API Gateway ligera y
flexible que le permite integrar un método de API, o la totalidad de la API, con una función de Lambda. La
función de Lambda se puede escribir en cualquier lenguaje que admitida Lambda. Debido a que se trata de
una integración de proxy, puede cambiar la implementación de la función de Lamba en cualquier momento
sin tener que volver a implementar la API.

En este tutorial, aprenderá a hacer lo siguiente:

• Creación de una función Hello, World! Función de Lambda para que sea el backend de la API.
• Creación y prueba de una función "Hello, World!" API con integración de proxy de Lambda.

Temas
• Creación de una función Hello, World! Lambda function (p. 27)
• Creación de una función Hello, World! API (p. 29)
• Implementación y pruebas de API (p. 30)

Creación de una función Hello, World! Lambda function

Esta función devuelve un saludo al intermediario como un objeto JSON en el siguiente formato:

{
"greeting": "Good {time}, {name} of {city}.[ Happy {day}!]"
}

Creación de una función Hello, World! Función de Lambda en la consola de Lambda

1. Inicie sesión en la consola de Lambda en https://console.aws.amazon.com/lambda/.

2. En la barra de navegación de AWS, elija una región [por ejemplo, EE. UU. Este (Norte de Virginia)].
Note

Anote la región en la que ha creado la función de Lambda. La necesitará al crear la API.

3. Elija Functions (Funciones) en el panel de navegación.
4. Elija Create function.
5. Elija Author from scratch.
6. Bajo Basic information (Información básica), haga lo siguiente:

27
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

a. Bajo Function name (Nombre de función), escriba GetStartedLambdaProxyIntegration.

b. En la lista desplegable Runtime (Tiempo de ejecución), elija un tiempo de ejecución de Node.js
compatible.
c. En Permissions (Permisos), expanda Choose or create an execution role (Seleccionar o crear un
rol de ejecución). En la lista desplegable Execution role (Rol de ejecución), elija Create new role
from AWS policy templates (Crear un nuevo rol desde las plantillas de política de AWS).
d. En Role name (Nombre del rol), escriba GetStartedLambdaBasicExecutionRole.
e. Deje el campo Policy templates (Plantillas de política) en blanco.
f. Elija Create function.
7. En Function code (Código de la función), en el editor de código integrado, copie/pegue el código
siguiente:

'use strict';
console.log('Loading hello world function');

exports.handler = async (event) => {

let name = "you";
let city = 'World';
let time = 'day';
let day = '';
let responseCode = 200;
console.log("request: " + JSON.stringify(event));

if (event.queryStringParameters && event.queryStringParameters.name) {

console.log("Received name: " + event.queryStringParameters.name);
name = event.queryStringParameters.name;
}

if (event.queryStringParameters && event.queryStringParameters.city) {

console.log("Received city: " + event.queryStringParameters.city);
city = event.queryStringParameters.city;
}

if (event.headers && event.headers['day']) {

console.log("Received day: " + event.headers.day);
day = event.headers.day;
}

if (event.body) {
let body = JSON.parse(event.body)
if (body.time)
time = body.time;
}

let greeting = `Good ${time}, ${name} of ${city}.`;

if (day) greeting += ` Happy ${day}!`;

let responseBody = {
message: greeting,
input: event
};

// The output from a Lambda proxy integration must be

// in the following JSON object. The 'headers' property
// is for custom response headers in addition to standard
// ones. The 'body' property must be a JSON string. For
// base64-encoded payload, you must also set the 'isBase64Encoded'
// property to 'true'.
let response = {
statusCode: responseCode,
headers: {

28
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

"x-custom-header" : "my custom header value"

},
body: JSON.stringify(responseBody)
};
console.log("response: " + JSON.stringify(response))
return response;
};

8. Elija Deploy (Implementar).

Creación de una función Hello, World! API

Ahora cree una API para la función de Lamba "Hello, World!" con la consola de API Gateway.

Crear la API API

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. 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).
3. Cree una API vacía tal y como se indica a continuación:

a. En Create new API (Crear nueva API), elija New API (Nueva API).
b. En Settings (Configuración):

• En API name (Nombre de la API), escriba LambdaSimpleProxy.

• Si lo desea, escriba una descripción en el campo Description (Descripción); de lo contrario, deje
la opción vacía.
• Deje Endpoint Type (Tipo de punto de enlace) establecido en Regional (Regional).
c. Seleccione Create API (Crear API).
4. Cree el recurso helloworld de la siguiente manera:

a. Elija el recurso raíz (/) en el árbol Resources (Recursos).

b. En el menú desplegable Actions (Acciones), elija Create Resource (Crear recurso).
c. Deje Configure as proxy resource (Configurar como recurso de proxy) sin marcar.
d. En Resource Name (Nombre del recurso), escriba helloworld.
e. Deje Resource Path (Ruta del recurso) establecido en /helloworld.
f. Deje Enable API Gateway CORS (Habilitar API Gateway CORS) sin marcar.
g. Elija Create Resource (Crear recurso).
5. En una integración de proxy, toda la solicitud se envía a la función de Lambda del backend tal y
como está, a través de un método catch-all ANY que representa cualquier método HTTP. El método
HTTP real lo especifica el cliente en tiempo de ejecución. El método ANY le permite usar una sola
configuración de métodos de API para todos los métodos HTTP admitidos: DELETE, GET, HEAD,
OPTIONS, PATCH, POST y PUT.

Para configurar el método ANY, haga lo siguiente:

a. En la lista Resources (Recursos), elija /helloworld.

b. En el menú Actions (Acciones), elija Create method (Crear método).
c. Seleccione ANY (CUALQUIERA) en el menú desplegable y, a continuación, seleccione el icono
de marca de verificación.
29
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

d. Deje Integration type (Tipo de integración) establecido en Lambda Function (Función de Lambda).
e. Seleccione Use Lambda Proxy integration (Usar integración de proxy de Lambda).
f. Desde el menú desplegable Lambda Region (Región de Lambda), seleccione la región en la que
ha creado la función de Lambda GetStartedLambdaProxyIntegration.
g. En el campo Lambda Function (Función de Lambda), escriba cualquier carácter y elija
GetStartedLambdaProxyIntegration en el menú desplegable.
h. Deje la casilla Use Default Timeout (Usar tiempo de espera predeterminado) desactivada.
i. Seleccione Save.
j. Elija OK (Aceptar) cuando se le solicite Add Permission to Lambda Function (Agregar permiso a la
función de Lambda).

Implementación y pruebas de API

Implementación de la API en la consola de API Gateway

1. Elija Deploy API (Implementar API) en el menú desplegable Actions (Acciones).

2. En Deployment stage (Etapa de implementación), elija [new stage] (nueva etapa).
3. En Stage name (Nombre de etapa), escriba test.
4. Si lo desea, escriba una Stage description (Descripción de la etapa).
5. Si lo desea, escriba una Deployment description (Descripción de la implementación).
6. Elija Deploy (Implementar).
7. Anote el valor de Invoke URL (URL de invocación) de la API.

Uso del navegador y cURL para probar una API con integración de proxy de Lambda

Puede utilizar un navegador o cURL para probar la API.

Para probar solicitudes GET utilizando solo los parámetros de cadenas de consulta, puede escribir la
URL para el recurso helloworld de la API en la barra de direcciones del navegador. Por ejemplo:
https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld?name=John&city=Seattle

Para otros métodos, debe utilizar utilidades de prueba de la API de REST más avanzadas, tales como
POSTMAN o cURL. En este tutorial se utiliza cURL. Los ejemplos de comandos de cURL que aparecen a
continuación se presupone que cURL está instalado en su equipo.

Para probar la API implementada mediante cURL:

1. Abra una ventana de terminal.

2. Copie el siguiente comando cURL y péguelo en la ventana de terminal, sustituyendo r275xc9bmd por
el ID de la API de la API y us-east-1 por la región en la que se implementa la API.

curl -v -X POST \
'https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld?
name=John&city=Seattle' \
-H 'content-type: application/json' \
-H 'day: Thursday' \
-d '{ "time": "evening" }'

Note

Si está ejecutando el comando en Windows, utilice esta sintaxis:

30
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

curl -v -X POST "https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/

helloworld?name=John&city=Seattle" -H "content-type: application/json" -H "day:
Thursday" -d "{ \"time\": \"evening\" }"

Debería recibir una respuesta correcta con una carga similar a la siguiente:

{
"message":"Good evening, John of Seattle. Happy Thursday!",
"input":{
"resource":"/helloworld",
"path":"/helloworld",
"httpMethod":"POST",
"headers":{"Accept":"*/*",
"content-type":"application/json",
"day":"Thursday",
"Host":"r275xc9bmd.execute-api.us-east-1.amazonaws.com",
"User-Agent":"curl/7.64.0",
"X-Amzn-Trace-Id":"Root=1-1a2b3c4d-a1b2c3d4e5f6a1b2c3d4e5f6",
"X-Forwarded-For":"72.21.198.64",
"X-Forwarded-Port":"443",
"X-Forwarded-Proto":"https"},
"multiValueHeaders":{"Accept":["*/*"],
"content-type":["application/json"],
"day":["Thursday"],
"Host":["r275xc9bmd.execute-api.us-east-1.amazonaws.com"],
"User-Agent":["curl/0.0.0"],
"X-Amzn-Trace-Id":["Root=1-1a2b3c4d-a1b2c3d4e5f6a1b2c3d4e5f6"],
"X-Forwarded-For":["11.22.333.44"],
"X-Forwarded-Port":["443"],
"X-Forwarded-Proto":["https"]},
"queryStringParameters":{"city":"Seattle",
"name":"John"
},
"multiValueQueryStringParameters":{
"city":["Seattle"],
"name":["John"]
},
"pathParameters":null,
"stageVariables":null,
"requestContext":{
"resourceId":"3htbry",
"resourcePath":"/helloworld",
"htt* Connection #0 to host r275xc9bmd.execute-api.us-east-1.amazonaws.com left intact
pMethod":"POST",
"extendedRequestId":"a1b2c3d4e5f6g7h=",
"requestTime":"20/Mar/2019:20:38:30 +0000",
"path":"/test/helloworld",
"accountId":"123456789012",
"protocol":"HTTP/1.1",
"stage":"test",
"domainPrefix":"r275xc9bmd",
"requestTimeEpoch":1553114310423,
"requestId":"test-invoke-request",
"identity":{"cognitoIdentityPoolId":null,
"accountId":null,
"cognitoIdentityId":null,
"caller":null,
"sourceIp":"test-invoke-source-ip",
"accessKey":null,
"cognitoAuthenticationType":null,
"cognitoAuthenticationProvider":null,
"userArn":null,

31
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

"userAgent":"curl/0.0.0","user":null
},
"domainName":"r275xc9bmd.execute-api.us-east-1.amazonaws.com",
"apiId":"r275xc9bmd"
},
"body":"{ \"time\": \"evening\" }",
"isBase64Encoded":false
}
}

Si cambia POST a PUT en la solicitud de método anterior, debería recibir la misma respuesta.

Para probar el método GET, copie el siguiente comando cURL y péguelo en la ventana de terminal,
sustituyendo r275xc9bmd por el ID de la API de la API y us-east-1 por la región en la que se
implementa la API.

curl -X GET \
'https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld?
name=John&city=Seattle' \
-H 'content-type: application/json' \
-H 'day: Thursday'

Debería obtener una respuesta similar al resultado de la solicitud POST anterior, con la salvedad de que la
solicitud GET no tiene ninguna carga. Entonces, el parámetro body será null.

Tutorial: Desarrollo de una API de REST de API Gateway con

integración de proxy de Lambda entre cuentas
Ahora puede usar una función de AWS Lambda procedente de una cuenta AWS distinta a la del backend
de integración de su API. Cada cuenta puede estar en cualquier región en la que Amazon API Gateway
esté disponible. Esto permite administrar y compartir de forma centralizada funciones de backend de
Lambda en varias API.

En esta sección mostramos cómo configurar una integración de proxy de Lambda entre cuentas con la
consola de Amazon API Gateway.

En primer lugar, crearemos la API de ejemplo del tema the section called “Tutorial: Crear una API de REST
importando un ejemplo” (p. 43) en una cuenta. A continuación, crearemos una función de Lambda en
otra cuenta. Por último, utilizaremos la integración de Lambda entre cuentas para permitir a la API de
ejemplo utilizar la función de Lambda que hemos creado en la segunda cuenta.

Creación de una API de API Gateway para la integración de Lambda entre

cuentas
En primer lugar, creará la API de ejemplo tal y como se describe en the section called “Tutorial: Crear una
API de REST importando un ejemplo” (p. 43).

Para crear la API de ejemplo

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. 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).
3. En Create new API (Crear nueva API), elija Example API (API de ejemplo).
4. Elija Import (Importar) para crear la API de ejemplo.

32
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

Creación de una función de integración de Lambda en otra cuenta

Ahora, creará una función de Lambda en una cuenta distinta de la que usó para crear la API de ejemplo.

Creación de una función de Lambda en otra cuenta

1. Inicie sesión en la consola de Lambda de una cuenta distinta de la que utilizó para crear la API de API
Gateway.
2. Elija Create function (Crear función).
3. Elija Author from scratch (Crear desde cero).
4. En Author from scratch (Crear desde cero), haga lo siguiente:

a. En Function name (Nombre de función), escriba un nombre.

b. En la lista desplegable Runtime (Tiempo de ejecución), elija un tiempo de ejecución de Node.js
compatible.
c. En Permissions (Permisos), expanda Choose or create an execution role (Seleccionar o crear un
rol de ejecución). Puede crear un rol o elegir uno existente.
d. Elija Create function (Crear función) para continuar.
5. Desplácese hacia abajo en el panel Function code (Código de la función).
6. Copie y pegue la implementación de la función de Node.js dethe section called “Tutorial: API Hello
World con integración de proxy de Lambda” (p. 27).
7. Elija Deploy (Implementar).
8. Anote el ARN completo de la función (se encuentra en la esquina superior derecha del panel de la
función de Lambda). Lo necesitará al crear la integración de Lambda entre cuentas.

Configuración de la integración de Lambda entre cuentas

Una vez que tenga una función de integración de Lambda en otra cuenta, puede utilizar la consola de API
Gateway para agregarla a la API de la primera cuenta.
Note

Si está configurando un autorizador entre regiones y cuentas, el valor sourceArn que se agrega
a la función de destino debe utilizar la región de la función, no la región de la API.

Para configurar la integración de Lambda entre cuentas

1. En la consola de API Gateway, elija su API.

2. Elija Resources (Recursos).
3. En el panel Resources (Recursos), elija el método GET de nivel superior.
4. En el panel Method Execution (Ejecución del método), elija Integration Request (Solicitud de
integración).
5. En Integration type (Tipo de integración), elija Lambda function (Función Lambda).
6. Seleccione Use Lambda Proxy integration (Usar integración de proxy de Lambda).
7. Deje Lambda Region (Región de Lambda) establecido en la región de su cuenta.
8. Para Lambda Function (Función de Lambda), copie y pegue el ARN completo de la función de
Lambda que ha creado en su segunda cuenta y elija la marca de verificación.
9. Verá un mensaje con este texto: Add Permission to Lambda Function: You have selected a Lambda
function from another account (Agregar permiso para función de Lambda: ha seleccionado una función
de Lambda de otra cuenta). Please ensure that you have the appropriate Function Policy on this
function. (Asegúrese de que tiene la política de función apropiada en esta función.) Para ello, ejecute
el siguiente comando de la CLI de AWS desde la cuenta 123456789012:, seguido de una cadena de
comandos aws lambda add-permission.

33
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

10. Copie y pegue la cadena de comandos aws lambda add-permission en una ventana de la CLI de
AWS configurada para la segunda cuenta. Esto concederá a su primera cuenta acceso a la función de
Lambda de la segunda cuenta.
11. En el mensaje emergente del paso anterior, haga clic en OK (Aceptar).
12. Para ver la política actualizada para la función en la consola de Lambda:

a. Elija la función de integración.

b. Elija Permissions.

Debería ver una política Allow con una cláusula Condition en la que AWS:SourceArn es el ARN
del método GET de la API.

Tutorial: Desarrollo de una API de REST de API Gateway con

integración no de proxy de Lambda
En este tutorial utilizaremos la consola de API Gateway para crear una API que permita a un cliente
llamar a funciones de Lambda a través de la integración de Lambda no de proxy (conocida también como
integración personalizada). Para obtener más información sobre las funciones de AWS Lambda y Lambda,
consulte la guía para desarrolladores de AWS Lambda.

Para facilitar el aprendizaje, elegimos una función de Lambda sencilla con una configuración de API
mínima para guiarlo para desarrollar una API de API Gateway con la integración de Lambda personalizada.
Cuando sea necesario, describiremos parte de la lógica. Para ver un ejemplo más detallado de la
integración de Lambda personalizada, consulte Tutorial: Crear una API REST Calc con dos integraciones
de servicios de AWS y una integración de Lambda sin proxy (p. 94).

Antes de crear la API, configure el backend de Lambda creando una función de Lambda en AWS Lambda,
lo cual se describe a continuación.

Temas
• Creación de una función de Lambda para la integración de Lambda no de proxy (p. 34)
• Creación de una API con la integración de Lambda no de proxy (p. 38)
• Prueba que invoca el método de API (p. 40)
• Implementar la API (p. 41)
• Pruebe la API en una etapa de implementación (p. 42)
• Eliminar recursos (p. 43)

Creación de una función de Lambda para la integración de Lambda no de proxy

Note

La creación de funciones de Lambda puede suponer cargos en su cuenta de AWS.

En este paso creará una función de Lambda del tipo "Hello, World!" para la integración personalizada de
Lambda. En esta tutorial, la función se denomina GetStartedLambdaIntegration.

La implementación Node.js de esta función de Lambda GetStartedLambdaIntegration es la

siguiente:

'use strict';
var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];

var times = ['morning', 'afternoon', 'evening', 'night', 'day'];

34
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

console.log('Loading function');

exports.handler = function(event, context, callback) {

// Parse the input for the name, city, time and day property values
let name = event.name === undefined ? 'you' : event.name;
let city = event.city === undefined ? 'World' : event.city;
let time = times.indexOf(event.time)<0 ? 'day' : event.time;
let day = days.indexOf(event.day)<0 ? null : event.day;

// Generate a greeting
let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. ';
if (day) greeting += 'Happy ' + day + '!';

// Log the greeting to CloudWatch

console.log('Hello: ', greeting);

// Return a greeting to the caller

callback(null, {
"greeting": greeting
});
};

Para la integración de Lambda personalizada, API Gateway transmite la entrada a la función de Lambda
del cliente como cuerpo de solicitud de integración. El objeto event de gestión de la función de Lambda es
la entrada.

Nuestra función de Lambda es simple. Analiza el objeto de entrada event para las propiedades name,
city, time y day. Entonces, devuelve un saludo, como un objeto JSON de {"message":greeting},
al intermediario. El mensaje se encuentra en el patrón "Good [morning|afternoon|day], [name|
you] in [city|World]. Happy day!". Se supone que la entrada a la función de Lambda es del
siguiente objeto JSON:

{
"city": "...",
"time": "...",
"day": "...",
"name" : "..."
}

Para obtener más información, consulte la guía para desarrolladores de AWS Lambda.

Además, la función registra su ejecución en Amazon CloudWatch llamando a console.log(...).

Esto es útil para rastrear llamadas cuando se depura la función. Para permitir que la función
GetStartedLambdaIntegration registre la llamada, establezca un rol de IAM con las políticas
apropiadas para la función de Lambda para crear los flujos de CloudWatch y agregar entradas de registro
a los flujos. La consola de Lambda lo guía para crear los roles y políticas de IAM requeridos.

Si configura la API sin utilizar la consola de API Gateway (por ejemplo, si importa una API de un archivo
de OpenAPI), tendrá que crear de forma explícita, si es necesario, y configurar un rol y una política de
invocación para que API Gateway invoque las funciones de Lambda. Para obtener más información sobre
cómo configurar los roles de ejecución e invocación de Lambda para una API de API Gateway, consulte
Control del acceso a una API con permisos de IAM (p. 287).

En comparación con GetStartedLambdaProxyIntegration, la función de Lambda para la integración

de proxy de Lambda, la función de Lambda GetStartedLambdaIntegration para la integración
personalizada de Lambda solo toma entradas del cuerpo de solicitud de integración de API de API
Gateway. La función puede devolver una salida de cualquier objeto JSON, una cadena, un número, un
booleano o incluso un blob binario. Por el contrario, la función de Lambda de la integración de proxy
de Lambda puede tomar la entrada de cualquier dato solicitado, pero debe devolver una salida de un

35
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

objeto JSON específico. La función GetStartedLambdaIntegration de la integración de Lambda

personalizada puede tener los parámetros de solicitud de API como entrada, siempre que API Gateway
asigne los parámetros de solicitud de API requeridos al cuerpo de solicitud de la integración antes de
reenviar la solicitud del cliente al backend. Para que esto ocurra, el desarrollador de la API debe crear una
plantilla de mapeo y debe configurarla en el método de API durante la creación de la API.

Ahora, cree la función de Lambda GetStartedLambdaIntegration.

Para crear la función de Lambda GetStartedLambdaIntegration para la integración

personalizada de Lambda

1. Abra la consola de AWS Lambda en https://console.aws.amazon.com/lambda/.

2. Aplique alguna de las siguientes acciones:

• Si aparece la página de bienvenida, elija Get Started Now (Empezar ahora) y, a continuación, elija
Create function (Crear función).
• Si aparece la página de lista Lambda > Functions (Lambda > Funciones), elija Create function
(Crear función).
3. Elija Author from scratch.
4. En el panel Author from scratch (Crear desde cero), haga lo siguiente:

a. En Name (Nombre), escriba GetStartedLambdaIntegration como nombre de la función de

Lambda.
b. En Runtime (Tiempo de ejecución), elija un tiempo de ejecución de Node.js compatible.
c. Para Execution Role (Rol de ejecución), elija Create a new role from AWS policy templates (Crear
un rol a partir de las plantillas de políticas de AWS).
d. En Role name (Nombre de la función), escriba un nombre para la función (por ejemplo,
GetStartedLambdaIntegrationRole).
e. En Policy templates (Plantillas de política), elija Simple microservice permissions (Permisos para
microservicios sencillos).
f. Elija Create function.
5. En el panel Configure function (Configurar función), en Function code (Código de función), configure
los campos siguientes:

a. Copie el código de la función de Lambda que aparece al comienzo de esta sección y péguelo en
el editor del código en línea.
b. Deje las opciones predeterminadas para todos los demás campos en esta sección.
c. Elija Deploy (Implementar).
6. Para probar la función recién creada, elija Configure test events (Configurar eventos de prueba) en
Select a test event... (Seleccionar un evento de prueba...).

a. En Create new event (Crear nuevo evento), sustituya todas las instrucciones de código
predeterminadas por lo siguiente, escriba HelloWorldTest para el nombre de evento y, a
continuación, elija Create (Crear).

{
"name": "Jonny",
"city": "Seattle",
"time": "morning",
"day": "Wednesday"
}

b. Elija Test (Probar) para invocar la función. Se muestra la sección Execution result: succeeded
(Resultado de ejecución: realizada correctamente). Expanda Detail (Detalles) y verá el siguiente
resultado.

36
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

{
"greeting": "Good morning, Jonny of Seattle. Happy Wednesday!"
}

La salida también se escribe en CloudWatch Logs.

Como ejercicio secundario, puede utilizar la consola de Lambda para ver el rol de Lambda
(GetStartedLambdaIntegrationRole) creado al crear la función de Lambda. Este rol de IAM posee
dos políticas en línea asociadas. Una de ellas estipula los permisos más básicos para la ejecución de
Lambda. Permite llamar a CreateLogGroup de CloudWatch para cualquier recurso de CloudWatch de
su cuenta en la región donde se crea la función de Lambda. Esta política también permite crear flujos de
CloudWatch y registrar eventos para la función de Lambda HelloWorldForLambdaIntegration.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:CreateLogGroup",
"Resource": "arn:aws:logs:region:account-id:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:region:account-id:log-group:/aws/lambda/
GetStartedLambdaIntegration:*"
]
}
]
}

El documento de la otra política se aplica para invocar otro servicio de AWS que no se utiliza en este
ejemplo. Puede omitirla por ahora.

Asociada con el rol de IAM hay una entidad de confianza, que es lambda.amazonaws.com. Aquí se
encuentra la relación de confianza:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}

La combinación de esta relación de confianza y la política en línea hace que sea posible para la función de
Lambda invocar una función console.log() para registrar los eventos en CloudWatch Logs.

37
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

Si no utilizó la consola de administración de AWS para crear la función de Lambda, deberá seguir estos
ejemplos para crear el rol y las políticas de IAM requeridas y, a continuación, asociará manualmente el rol
a su función.

Creación de una API con la integración de Lambda no de proxy

Con la función de Lambda (GetStartedLambdaIntegration) creada y probada, está listo para exponer
la función a través de una API de API Gateway. Para fines ilustrativos, expondremos la función de Lambda
con un método HTTP genérico. Utilizamos el cuerpo de solicitud, una variable de ruta de la URL, una
cadena de consulta y un encabezado para recibir los datos de entrada requeridos del cliente. Activamos
el validador de la solicitud de API Gateway para que la API asegure que todos los datos requeridos se
definen y especifican de forma adecuada. Configuramos una plantilla de mapeo para que API Gateway
transforme los datos de solicitud proporcionados por el cliente a un formato válido, según lo requiera la
función de Lambda del backend.

Para crear una API con integración de Lambda personalizada con una función de Lambda

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. 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).

a. Elija New API (Nueva API).

b. Introduzca un nombre en API Name (Nombre de la API).
c. Opcionalmente, añada una descripción breve en Description (Descripción).
d. Seleccione Create API (Crear API).
3. Elija el recurso raíz (/) en Resources (Recursos). En el menú Actions (Acciones), elija Create
Resource (Crear recurso).

a. Escriba city en Resource Name (Nombre de recurso).

b. Reemplace Resource Path (Ruta del recurso) con {city}. Este es un ejemplo de la variable
de ruta basada en plantilla que se utiliza para tomar la entrada del cliente. Más adelante
mostraremos cómo asignar esta variable de ruta en la entrada de la función de Lambda mediante
una plantilla de mapeo.
c. Seleccione la opción Enable API Gateway Cors (Habilitar CORS en API Gateway).
d. Elija Create Resource (Crear recurso).
4. Con el /{city} recurso recién creado destacado, elija Create Method (Crear método) en Actions
(Acciones).

a. Elija ANY en el menú desplegable del método HTTP. El verbo ANY de HTTP es un marcador para
un método HTTP válido que un cliente envía en el tiempo de ejecución. Este ejemplo muestra que
el método ANY se puede utilizar para la integración de Lambda personalizada y para la integración
de proxy de Lambda.
b. Para guardar la configuración, elija la marca de verificación.
5. En Method Execution (Ejecución del método), para el método /{city} ANY, haga lo siguiente:

a. Elija Lambda Function (Función de Lambda) para Integration type.

b. Deje la casilla Use Lambda Proxy integration (Usar integración de proxy de Lambda) desactivada.
c. Elija la región donde creó la función de Lambda, por ejemplo, us-west-2.
d. Escriba el nombre de su función de Lambda en Lambda Function (Función de Lambda); por
ejemplo, GetStartedLambdaIntegration.

38
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

e. Deje la casilla Use Default timeout (Usar tiempo de espera predeterminado) desactivada.
f. Elija Save (Guardar).
g. Elija OK (Aceptar) en la ventana emergente Add Permission to Lambda Function (Agregar
permiso a función de Lambda) para que API Gateway configure los permisos de acceso
necesarios para que la API invoque la función de Lambda integrada.
6. En este paso, configurará lo siguiente:

• Un parámetro de cadena de consulta (time)

• Un parámetro de encabezado (day)
• Una propiedad de carga (callerName)

En el tiempo de ejecución, el cliente puede utilizar estos parámetros de solicitud y el cuerpo de

solicitud para proporcionar el momento del día, el día de la semana y el nombre del intermediario. Ya
configuró la variable de ruta /{city}.

a. En Method Execution (Ejecución de método), elija el enlace Method Request (Solicitud de

método).
b. Expanda la sección URL Query String Parameters (Parámetros de cadena de consulta URL).
Elija Add query string (Añadir cadena de consulta). Escriba time en Name (Nombre). Seleccione
la opción Required (Obligatorio) y haga clic en el icono de marca de verificación para guardar
la configuración. Deje Caching (Almacenamiento en caché) en blanco para evitar un cobro
innecesario por este ejercicio.
c. Expanda la sección HTTP Request Headers (Encabezados de solicitud HTTP). Elija Add
header (Añadir encabezado). Escriba day en Name (Nombre). Seleccione la opción Required
(Obligatorio) y haga clic en el icono de marca de verificación para guardar la configuración.
Deje Caching (Almacenamiento en caché) en blanco para evitar un cobro innecesario por este
ejercicio.
d. Para definir la carga de solicitud del método, haga lo siguiente:

i. Para definir un modelo, elija Models (Modelos) en la API del panel de navegación primaria de
API Gateway y luego elija Create (Crear).
ii. Escriba GetStartedLambdaIntegrationUserInput en Model name (Nombre del
modelo).
iii. Escriba application/json en Content type (Tipo de contenido).
iv. Deje Model description (Descripción del modelo) en blanco.
v. Copie la siguiente definición de esquema en el editor Model schema (Esquema del modelo):

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "GetStartedLambdaIntegrationInputModel",
"type": "object",
"properties": {
"callerName": { "type": "string" }
}
}

vi. Elija Create model (Crear modelo) para finalizar la definición del modelo de entrada.
vii. Elija Resources (Recursos), elija el método /{city} ANY, elija Method Request (Solicitud
de método) y después expanda Request body (Cuerpo de solicitud). Elija Add model
(Añadir modelo). Escriba application/json en Content type (Tipo de contenido). Elija
GetStartedLambdaIntegrationInput para Model name (Nombre del modelo). Haga clic
en el icono de marca de verificación para guardar la configuración.
7. Elija el método /{city} ANY y elija Integration Request (Solicitud de integración) para configurar
una plantilla de asignación de cuerpo. En este paso asignará el parámetro de solicitud del método
39
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

configurado previamente de nameQuery o nameHeader a la carga JSON, según lo requiera la función

de Lambda del backend:

a. Expanda la sección Mapping Templates (Plantillas de asignación). Elija Add mapping template
(Añadir plantilla de asignación). Escriba application/json para Content-Type. Haga clic en el
icono de marca de verificación para guardar la configuración.
b. En la ventana emergente que aparece, elija Yes, secure this integration (Sí, proteger esta
integración).
c. Consulte el código When there are no templates defined recomendado para Request
body passthrough (Acceso directo al cuerpo de la solicitud).
d. Elija GetStartedLambaIntegrationUserInput en Generate template (Generar plantilla)
para generar una plantilla de asignación inicial. Esta opción está disponible porque definió un
esquema modelo, sin el cual tendría que escribir la plantilla de mapeo desde cero.
e. Reemplace el script de asignación generado el editor de la plantilla de asignación por lo siguiente:

#set($inputRoot = $input.path('$'))
{
"city": "$input.params('city')",
"time": "$input.params('time')",
"day": "$input.params('day')",
"name": "$inputRoot.callerName"
}

f. Elija Save (Guardar).

Prueba que invoca el método de API

La consola de API Gateway proporciona un servicio de pruebas para que pueda probar la invocación a la
API antes de que se implemente. Puede utilizar la característica Prueba de la consola para probar la API
mediante el envío de la siguiente solicitud:

POST /Seattle?time=morning
day:Wednesday

{
"callerName": "John"
}

En esta solicitud de prueba, configurará ANY en POST, establecerá {city} en Seattle, asignará
Wednesday como el valor del encabezado day y asignará "John" como el valor callerName.

Para probar la invocación del método ANY /{city}

1. En Method Execution (Ejecución del método), elija Test (Probar).

2. Elija POST en la lista desplegable Method (Método).
3. En Path (Ruta), escriba Seattle.
4. En Query Strings (Cadenas de consulta), escriba time=morning.
5. En Headers (Encabezados), escriba day:Wednesday.
6. En Request Body (Cuerpo de solicitud), escriba { "callerName":"John" }.
7. Elija Test.
8. Compruebe que la carga de respuesta devuelta sea la siguiente:

{
"greeting": "Good morning, John of Seattle. Happy Wednesday!"

40
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

9. También puede ver los registros para ver cómo API Gateway procesa la solicitud y la respuesta.

Execution log for request test-request

Thu Aug 31 01:07:25 UTC 2017 : Starting execution for request: test-invoke-request
Thu Aug 31 01:07:25 UTC 2017 : HTTP Method: POST, Resource Path: /Seattle
Thu Aug 31 01:07:25 UTC 2017 : Method request path: {city=Seattle}
Thu Aug 31 01:07:25 UTC 2017 : Method request query string: {time=morning}
Thu Aug 31 01:07:25 UTC 2017 : Method request headers: {day=Wednesday}
Thu Aug 31 01:07:25 UTC 2017 : Method request body before transformations:
{ "callerName": "John" }
Thu Aug 31 01:07:25 UTC 2017 : Request validation succeeded for content type
application/json
Thu Aug 31 01:07:25 UTC 2017 : Endpoint request URI: https://
lambda.us-west-2.amazonaws.com/2015-03-31/functions/arn:aws:lambda:us-
west-2:123456789012:function:GetStartedLambdaIntegration/invocations
Thu Aug 31 01:07:25 UTC 2017 : Endpoint request
headers: {x-amzn-lambda-integration-tag=test-request,
Authorization=************************************************************************************
X-Amz-Date=20170831T010725Z, x-amzn-apigateway-api-id=beags1mnid, X-Amz-
Source-Arn=arn:aws:execute-api:us-west-2:123456789012:beags1mnid/null/POST/
{city}, Accept=application/json, User-Agent=AmazonAPIGateway_beags1mnid,
X-Amz-Security-Token=FQoDYXdzELL//////////wEaDMHGzEdEOT/VvGhabiK3AzgKrJw
+3zLqJZG4PhOq12K6W21+QotY2rrZyOzqhLoiuRg3CAYNQ2eqgL5D54+63ey9bIdtwHGoyBdq8ecWxJK/
YUnT2Rau0L9HCG5p7FC05h3IvwlFfvcidQNXeYvsKJTLXI05/
yEnY3ttIAnpNYLOezD9Es8rBfyruHfJfOqextKlsC8DymCcqlGkig8qLKcZ0hWJWVwiPJiFgL7laabXs
++ZhCa4hdZo4iqlG729DE4gaV1mJVdoAagIUwLMo+y4NxFDu0r7I0/
EO5nYcCrppGVVBYiGk7H4T6sXuhTkbNNqVmXtV3ch5bOlh7 [TRUNCATED]
Thu Aug 31 01:07:25 UTC 2017 : Endpoint request body after transformations: {
"city": "Seattle",
"time": "morning",
"day": "Wednesday",
"name" : "John"
}
Thu Aug 31 01:07:25 UTC 2017 : Sending request to https://lambda.us-
west-2.amazonaws.com/2015-03-31/functions/arn:aws:lambda:us-
west-2:123456789012:function:GetStartedLambdaIntegration/invocations
Thu Aug 31 01:07:25 UTC 2017 : Received response. Integration latency: 328 ms
Thu Aug 31 01:07:25 UTC 2017 : Endpoint response body before transformations:
{"greeting":"Good morning, John of Seattle. Happy Wednesday!"}
Thu Aug 31 01:07:25 UTC 2017 : Endpoint response headers: {x-amzn-Remapped-Content-
Length=0, x-amzn-RequestId=c0475a28-8de8-11e7-8d3f-4183da788f0f, Connection=keep-
alive, Content-Length=62, Date=Thu, 31 Aug 2017 01:07:25 GMT, X-Amzn-Trace-
Id=root=1-59a7614d-373151b01b0713127e646635;sampled=0, Content-Type=application/json}
Thu Aug 31 01:07:25 UTC 2017 : Method response body after transformations:
{"greeting":"Good morning, John of Seattle. Happy Wednesday!"}
Thu Aug 31 01:07:25 UTC 2017 : Method response headers: {X-Amzn-Trace-
Id=sampled=0;root=1-59a7614d-373151b01b0713127e646635, Content-Type=application/json}
Thu Aug 31 01:07:25 UTC 2017 : Successfully completed execution
Thu Aug 31 01:07:25 UTC 2017 : Method completed with status: 200

Los registros muestran la solicitud entrante antes del mapeo y la solicitud de integración después del
mapeo. Cuando una prueba falla, los registros son útiles para evaluar si la entrada original es correcta
o si la plantilla de mapeo funciona correctamente.

Implementar la API
La invocación de prueba es una simulación que tiene limitaciones. Por ejemplo, elude cualquier
mecanismo de autorización promulgado en la API. Para probar la ejecución de la API en tiempo real,
primero debe implementar la API. Para implementar una API, usted crea una etapa para crear una

41
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con la integración de Lambda

snapshot de la API en ese momento. El nombre de etapa también define la ruta de base después del
nombre de host predeterminado de la API. El recurso raíz de la API se agrega después del nombre de la
etapa. Al modificar la API, debe volver a implementarla a una etapa nueva o existente antes de que los
cambios surtan efecto.

Para implementar la API en una etapa

1. Elija la API en el panel APIs o elija un recurso o método en el panel Resources (Recursos). Elija
Deploy API (Implementar API) en el menú desplegable Actions (Acciones).
2. En Deployment stage (Etapa de implementación), elija New Stage (Nueva etapa).
3. En Stage name (Nombre de etapa), escriba un nombre, por ejemplo, test.
Note

La entrada debe tener texto cifrado UTF-8 (es decir, no localizado).

4. En Stage description (Descripción de etapa), escriba una descripción o déjelo en blanco.
5. En Deployment description (Descripción de implementación), escriba una descripción o déjelo en
blanco.
6. Elija Deploy (Implementar). Después de que la API se ha implementado correctamente, verá la URL
base de la API (el nombre de host predeterminado más el nombre de la etapa) que se muestra como
Invoke URL (URL de invocación) en la parte superior de Stage Editor (Editor de etapas). El patrón
general de esta URL base es https://api-id.region.amazonaws.com/stageName. Por
ejemplo, la URL base de la API (beags1mnid) creada en la región us-west-2 e implementada en la
etapa test es https://beags1mnid.execute-api.us-west-2.amazonaws.com/test.

Pruebe la API en una etapa de implementación

Puede probar una API implementada de diferentes maneras. Para las solicitudes GET que solo utilizan
variables de ruta URL o parámetros de cadena de consulta, puede escribir la URL del recurso de la API en
un explorador. Para otros métodos, debe utilizar utilidades de prueba de la API de REST más avanzadas,
tales como POSTMAN o cURL.

Para probar la API mediante cURL

1. Abra una ventana de la terminal en su equipo local conectado a Internet.

2. Para probar POST /Seattle?time=evening:

Copie el siguiente comando cURL y péguelo en la ventana de la terminal.

curl -v -X POST \
'https://beags1mnid.execute-api.us-west-2.amazonaws.com/test/Seattle?time=evening' \
-H 'content-type: application/json' \
-H 'day: Thursday' \
-H 'x-amz-docs-region: us-west-2' \
-d '{
"callerName": "John"
}'

Debería recibir una respuesta correcta con la siguiente carga:

{"greeting":"Good evening, John of Seattle. Happy Thursday!"}

Si cambia POST a PUT en esta solicitud de método, recibe la misma respuesta.

42
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST importando un ejemplo

Eliminar recursos
Si ya no necesita las funciones de Lambda que ha creado para este tutorial, puede eliminarlas ahora.
También puede eliminar los recursos de IAM asociados.
Warning

Si tiene previsto completar el resto de tutoriales de esta serie, no elimine el rol de ejecución de
Lambda ni el rol de invocación de Lambda. Si elimina una función de Lambda que usan sus API,
esas API dejarán de funcionar. La eliminación de una función de Lambda no se puede deshacer.
Si desea utilizar la función de Lambda de nuevo, debe volver a crearla.
Si elimina un recurso de Lambda que usa una función de Lambda, esa función de Lambda dejará
de funcionar y las API que dependen de esa función tampoco funcionarán. La eliminación de un
recurso de IAM no se puede deshacer. Si desea utilizar el recurso de IAM de nuevo, debe volver a
crearlo.

Para eliminar las funciones de Lambda

1. Inicie sesión en la consola de administración de AWS y abra la consola de AWS Lambda en https://
console.aws.amazon.com/lambda/.
2. En la lista de funciones, elija GetHelloWorld, elija Actions (Acciones) y, a continuación, Delete function
(Eliminar función). Cuando se le pregunte, elija Delete (Eliminar) otra vez.
3. En la lista de funciones, elija GetHelloWithName, Actions (Acciones) y, a continuación, Delete function
(Eliminar función). Cuando se le pregunte, elija Delete (Eliminar) otra vez.

Para eliminar los recursos de IAM asociados

1. Abra la consola de IAM en https://console.aws.amazon.com/iam/.

2. En Details (Detalles), elija Roles (Roles).
3. En la lista de roles, elija APIGatewayLambdaExecRole, elija Role Actions (Acciones del rol) y luego
elija Delete Role (Eliminar rol). Cuando se le pregunte, elija Yes, Delete.
4. En Details (Detalles), elija Policies (Política).
5. En la lista de políticas, elija APIGatewayLambdaExecPolicy, elija Policy Actions (Acciones de la
política) y luego elija Delete (Eliminar). Cuando se le pregunte, elija Delete (Eliminar).

Ha llegado al final de este tutorial.

Tutorial: Crear una API de REST importando un

ejemplo
Puede utilizar la consola de Amazon API Gateway para crear y probar una API REST sencilla con
integración HTTP para un sitio web PetStore. La definición de la API está preconfigurada como un archivo
de OpenAPI 2.0. Después de cargar la definición de API en API Gateway, puede utilizar la consola de API
Gateway para examinar la estructura básica de API o simplemente implementar y probar la API.

La API de ejemplo de PetStore admite los siguientes métodos para que un cliente obtenga acceso al sitio
web de backend HTTP de http://petstore-demo-endpoint.execute-api.com/petstore/pets.

• GET /: para leer el acceso del recurso raíz de la API que no se integra con ningún punto de enlace de
backend. API Gateway responde con información general del sitio web PetStore. Este es un ejemplo del
tipo de integración MOCK.
• GET /pets: para obtener acceso de lectura al recurso /pets de la API que se integra con el recurso
/pets de backend asignado. El backend devuelve una página de mascotas disponibles en PetStore.

43
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST importando un ejemplo

Este es un ejemplo del tipo de integración HTTP. La URL del punto de enlace de integración es http://
petstore-demo-endpoint.execute-api.com/petstore/pets.
• POST /pets: para obtener acceso de escritura al recurso /pets de la API que se integra con el recurso
/petstore/pets de backend. Tras recibir una solicitud correcta, el backend agrega la mascota
especificada a PetStore y devuelve el resultado al autor de la llamada. La integración también es HTTP.
• GET /pets/{petId}: para obtener acceso de lectura a una mascota identificada por un valor petId
tal como se especifica en una ruta variable de la URL de solicitud de entrada. Este método también tiene
el tipo de integración HTTP. El backend devuelve la mascota especificada que se encuentra en PetStore.
La URL del punto de enlace HTTP del backend es http://petstore-demo-endpoint.execute-
api.com/petstore/pets/n, donde n es un entero como identificador de la mascota consultada.

La API admite el acceso a CORS a través de los métodos OPTIONS del tipo de integración MOCK. API
Gateway devuelve los encabezados solicitados que admiten el acceso a CORS.

El siguiente procedimiento le guiará por los pasos para crear y probar una API a partir de un ejemplo
mediante la consola de API Gateway.

Para importar, desarrollar y probar la API de ejemplo

1. Si aún no lo ha hecho, realice los pasos de Requisitos previos (p. 13).

2. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.
3. 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).
4. En Create new API (Crear nueva API), elija Example API (API de ejemplo) y, a continuación, elija
Import (Importar) para crear la API de ejemplo. Para la primera API, la consola de API Gateway
comienza con esta opción de forma predeterminada.

Puede desplazarse por la definición de OpenAPI para obtener información detallada sobre esta API de
ejemplo antes de elegir Import (Importar).
5. La API recién creada se muestra de la siguiente forma:

44
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST importando un ejemplo

El panel Resources (Recursos) muestra la estructura de la API creada como un árbol de nodos. Los
métodos de API definidos en cada recurso son los extremos del árbol. Cuando se selecciona un
recurso, todos sus métodos se muestran en el panel Methods (Métodos) situado a la derecha. Debajo
de cada método hay un breve resumen del método, incluidos sus requisitos de URL de punto de
enlace, tipo de autorización y clave de API.
6. Para ver los detalles de un método, para modificar su configuración o para probar la invocación del
método, elija el nombre del método en la lista de métodos o en el árbol de recursos. A continuación,
elegimos el POST /pets método como ejemplo:

45
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST importando un ejemplo

El panel resultante Method Execution (Ejecución del método) presenta una vista lógica de la estructura
del método (POST /pets) elegida y los comportamientos: Method Request (Solicitud de método)
y Method Response (Respuesta de método) son la interfaz de la API con el frontend de la API
(un cliente), mientras que Integration Request (Solicitud de integración) e Integration Response
(Respuesta de integración) son la interfaz de la API con el backend (http://petstore-demo-
endpoint.execute-api.com/petstore/pets). Un cliente utiliza la API para obtener acceso
a una característica del backend a través de Method Request (Solicitud de método). API Gateway
traduce la solicitud del cliente, si fuera necesario, a un formato aceptable por el backend en Integration
Request (Solicitud de integración) antes de reenviar la solicitud entrante al backend. La solicitud
transformada se conoce como la solicitud de integración. Del mismo modo, el backend devuelve la
respuesta a API Gateway en Integration Response (Respuesta de integración). A continuación, API
Gateway la dirige a Method Response (Respuesta de método) antes de enviarla al cliente. De nuevo,
si fuera necesario, API Gateway puede asignar los datos de la respuesta del backend a un formulario
previsto por el cliente.

En el caso del método POST de recurso de API, la carga de la solicitud del método puede transmitirse
a través de la solicitud de integración sin modificación si la carga de la solicitud de método está en el
mismo formato que la carga de la solicitud de integración.

La solicitud del método GET / usa el tipo de integración MOCK y no está vinculada a ningún punto
de enlace de backend real. La Integration Response (Respuesta de integración) correspondiente
está configurada para devolver una página HTML estática. Cuando se llama al método, API Gateway
simplemente acepta la solicitud e inmediatamente devuelve la respuesta a la integración configurada
al cliente a través de Method Response (Método de respuesta). Puede utilizar la integración simulada
para probar una API sin requerir un punto de enlace del backend. También puede utilizarla para servir
una respuesta local generada partir de una plantilla de asignación de cuerpo de respuesta.

Como desarrollador de la API, puede controlar los comportamientos de las interacciones del frontend
de la API mediante la configuración de la solicitud de método y una respuesta de método. Puede
controlar los comportamientos de las interacciones del backend de la API mediante la configuración de
la solicitud de integración y la respuesta de integración. Estos comportamientos implican asignaciones
de datos entre un método y su integración correspondiente. Explicaremos cómo configurar un método
en Tutorial: Desarrollo de una API de REST con integración HTTP no de proxy (p. 56). Por el
momento, nos centraremos en probar la API para proporcionar una experiencia de usuario completa.
7. Elija Test (Probar) en Client (Cliente) (tal y como se muestra en la imagen anterior) para comenzar
la prueba. Por ejemplo, para probar el método POST /pets, escriba la siguiente carga {"type":
"dog","price": 249.99} en Request Body (Cuerpo de la solicitud) antes de elegir el botón Test
(Probar).

46
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST importando un ejemplo

47
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST importando un ejemplo

La entrada especifica los atributos de la mascota que deseamos añadir a la lista de mascotas en el
sitio web PetStore.
8. El resultado es el siguiente:

La entrada Logs (Registros) de la salida muestra los cambios de estado de la solicitud del método a la
solicitud de integración y de la respuesta de integración a la respuesta del método. Esto puede resultar
útil para la resolución de errores de asignación que impidan que la solicitud se realice correctamente.
En este ejemplo, la asignación no se aplica: la carga de la solicitud de método se transfiere a través de

48
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST importando un ejemplo

la solicitud integración al backend y, de forma parecida, la respuesta del backend se transfiere a través
de la respuesta de integración al método de respuesta.

Para probar la API con un cliente distinto de la característica test-invoke-request de API Gateway,
primero debe implementar la API en una etapa.
9. Para implementar la API de ejemplo, seleccione la API PetStore y, a continuación, elija Deploy API
(Implementar API) en el menú desplegable Actions (Acciones).

En Deploy API (Implementar API), para Deployment stage (Etapa de implementación), elija [New
Stage] (Nueva etapa) porque esta es la primera implementación de la API. Escriba un nombre (por
ejemplo, test) en Stage name (Nombre de etapa) y, si lo desea, escriba las descripciones en Stage
description (Descripción de etapa) y Deployment description (Descripción de implementación). Elija
Deploy (Implementar).

49
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST importando un ejemplo

En el panel Stage Editor (Editor de etapas) resultante, Invoke URL (URL de invocación) muestra la
dirección URL para invocar la solicitud del método GET / de la API.
10. En Stage Editor (Editor de etapas), siga el enlace Invoke URL (URL de invocación) para enviar la
solicitud del método GET / en un navegador. Una respuesta correcta devuelve el resultado, generado
a partir de la plantilla de asignación de la respuesta de integración.
11. En el panel de navegación Stages (Etapas), expanda la etapa test (prueba), seleccione GET en /
pets/{petId} y, a continuación, copie el valor Invoke URL (URL de invocación) de https://api-
id.execute-api.region.amazonaws.com/test/pets/{petId}. {petId} hace referencia a
una variable de ruta.

Pegue el valor de Invoke URL (URL de invocación) (obtenido en el paso anterior) en la barra de
direcciones de un navegador, sustituyendo {petId} por, por ejemplo, 1 y, a continuación, pulse Intro
para enviar la solicitud. Debería devolverse una respuesta 200 OK con la siguiente carga JSON:

{
"id": 1,
"type": "dog",
"price": 249.99
}

La invocación del método de la API tal como se muestra es posible porque su tipo Authorization
(Autorización) está establecido en NONE. Si se ha utilizado la autorización de AWS_IAM, firmaría la
solicitud con los protocolos Signature Version 4 (SigV4). Para ver un ejemplo de una solicitud de
este tipo, consulte the section called “Tutorial: Desarrollo de una API con integración HTTP no de
proxy” (p. 56).

50
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

Desarrollo de una API de REST de API Gateway con

integración HTTP
Para desarrollar una API con integración HTTP, puede utilizar la integración de proxy HTTP o la
integración HTTP personalizada. Le recomendamos utilizar la integración de proxy HTTP cada vez que sea
posible, para una configuración de API simplificada, al mismo tiempo que se proporcionan características
versátiles y potentes. La integración HTTP personalizada puede resultar atractiva si es necesario
transformar los datos de la solicitud el cliente para el backend o transformar los datos de respuesta del
backend para el cliente.

Temas
• Tutorial: Desarrollo de una API de REST con integración de proxy HTTP (p. 51)
• Tutorial: Desarrollo de una API de REST con integración HTTP no de proxy (p. 56)

Tutorial: Desarrollo de una API de REST con integración de proxy

HTTP
La integración de proxy HTTP es un mecanismo sencillo, potente y versátil para desarrollar una API
que permita que una aplicación web obtenga acceso a múltiples recursos o características del punto de
enlace HTTP integrado, por ejemplo, el sitio web completo, con una configuración simplificada de un único
método de API. En la integración de proxy HTTP, API Gateway transmite la solicitud de método enviada
por el cliente al backend. Los datos de la solicitud transmitida incluyen los encabezados de solicitud, los
parámetros de cadena de consulta, las variables de ruta de la URL y la carga. El punto de enlace de HTTP
del backend o del servidor web analiza los datos de la solicitud entrante para determinar la respuesta
que devuelve. La integración de proxy HTTP permite que el cliente y el backend interactúen directamente
sin intervención de API Gateway después de haber configurado el método de API, salvo cuando se
producen problemas conocidos, como caracteres no admitidos, que se indican en the section called “Notas
importantes” (p. 847).

Con el amplio recurso de proxy {proxy+} y el verbo catch-all ANY para el método HTTP, puede utilizar
una integración de proxy HTTP para crear una API de un único método de API. El método expone el
conjunto completo de recursos y operaciones HTTP de acceso público de un sitio web. Cuando el servidor
web del backend abre más recursos para acceso público, el cliente puede utilizar estos nuevos recursos
con la misma configuración de API. Para habilitar esto, el desarrollador del sitio web debe comunicar con
claridad al desarrollador del cliente cuáles son los nuevos recursos y cuáles son las operaciones aplicables
para cada uno de ellos.

Como una introducción rápida, el siguiente tutorial demuestra la integración de proxy HTTP. En el tutorial
creamos una API que utiliza la consola de API Gateway para integrarse con el sitio web PetStore mediante
un recurso de proxy genérico {proxy+} y creamos el marcador de posición del método HTTP de ANY.

Temas
• Creación de una API con integración de proxy HTTP con la consola de API Gateway (p. 51)
• Probar una API con la integración de proxy HTTP (p. 54)

Creación de una API con integración de proxy HTTP con la consola de API
Gateway
El siguiente procedimiento le guiará por los pasos para crear y probar una API con un recurso de proxy
para un backend HTTP mediante la consola de API Gateway. El backend HTTP es el PetStore sitio web

51
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

(http://petstore-demo-endpoint.execute-api.com/petstore/pets) de Tutorial: Desarrollo

de una API de REST con integración HTTP no de proxy (p. 56), en el que las capturas de pantalla se
utilizan como ayudas visuales para ilustrar los elementos de IU de API Gateway. Si es la primera vez que
utiliza la consola de API Gateway para crear una API, le recomendamos seguir esa sección en primer
lugar.

Para desarrollar una API con la integración de proxy HTTP con el sitio web PetStore a través de
un recurso de proxy

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. 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).

a. Elija New API (Nueva API).

b. Introduzca un nombre en API Name (Nombre de la API).
c. Opcionalmente, añada una descripción breve en Description (Descripción).
d. Seleccione Create API (Crear API).

Para este tutorial, utilice ProxyResourceForPetStore para el nombre de la API.

3. Para crear un recurso secundario, elija un elemento de recurso principal en el árbol Resources
(Recursos) y después elija Create Resource (Crear recurso) en el menú desplegable Actions
(Acciones). A continuación, haga lo siguiente en el panel New Child Resource (Nuevo recurso
secundario).

a. Seleccione la opción Configure as proxy resource (Configurar como recurso de proxy) para crear
un recurso de proxy. Si no va a hacerlo, déjelo sin seleccionar.
b. Escriba un nombre en el campo de texto de entrada Resource Name* (Nombre del recurso*).
c. Escriba un nombre en el campo de texto de entrada Resource Path* (Ruta del recurso*).
d. Elija Create Resource (Crear recurso).
e. Seleccione Enable API Gateway CORS (Habilitar CORS de gateway de API), si se requiere.

Para este tutorial, seleccione Configure as proxy resource (Configurar como recurso de proxy).
En Resource Name (Nombre de recurso), use el valor predeterminado, proxy. En Resource Path
(Ruta del recurso), use /{proxy+}. Seleccione Enable API Gateway CORS (Habilitar CORS de API
Gateway).

52
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

4. Para establecer el método ANY para la integración con el backend HTTP, haga lo siguiente:

a. Elija el recurso que acaba de crear y, a continuación, elija Create method (Crear método) del
menú desplegable Actions (Acciones).
b. Elija ANY de la lista desplegable de métodos HTTP y después elija el icono de marca de
verificación para guardar la selección.
c. Elija HTTP Proxy en Integration type (Tipo de integración).
d. Escriba una URL de recurso de backend HTTP en Endpoint URL (URL de punto de enlace).
e. Utilice la configuración predeterminada para el resto de los campos.
f. Elija Save (Guardar) para terminar la configuración del método ANY.

Para este tutorial, utilice http://petstore-demo-endpoint.execute-api.com/{proxy} para

Endpoint URL (URL del punto de enlace).

53
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

En la API que se acaba de crear, la ruta del recurso de proxy de la API de {proxy+} se convierte en
el marcador de posición de cualquier punto de enlace del backend bajo http://petstore-demo-
endpoint.execute-api.com/. Por ejemplo, puede ser petstore, petstore/pets y petstore/
pets/{petId}. El método ANY actúa como un marcador de posición para cualquiera de los verbos HTTP
admitidos en tiempo de ejecución.

Probar una API con la integración de proxy HTTP

El éxito de una solicitud de cliente específica dependerá de lo siguiente:

• Si el backend ha puesto a disposición el punto de enlace del backend correspondiente y, si lo ha hecho,

si ha concedido los permisos de acceso requeridos.
• Si el cliente proporciona la entrada correcta.

Por ejemplo, la API de PetStore aquí utilizada no expone el recurso /petstore. Por lo tanto, obtendrá
una respuesta 404 Resource Not Found que contiene el mensaje de error de Cannot GET /
petstore.

Además, el cliente debe tener la posibilidad de gestionar el formato de salida del backend para analizar
los resultados correctamente. API Gateway no realiza mediaciones para facilitar las interacciones entre el
cliente y el backend.

Para probar una API integrada con el sitio web PetStore utilizando la integración de proxy HTTP a
través del recurso de proxy

1. Para usar la consola de API Gateway para probar la llamada a la API, haga lo siguiente.

a. Elija ANY (Cualquiera) en el árbol Resources (Recursos).

b. Elija Test (Prueba) en el panel Method Execution (Método de ejecución).
c. En la lista desplegable Method (Método), elija un verbo HTTP que admita el backend.
d. En Path (Ruta), escriba una ruta específica para el recurso de proxy que respalde la operación
elegida.
e. Si se requiere, escriba una expresión de consulta admitida para la operación elegida en el
encabezado Query Strings (Cadenas de consulta).
f. Si se requiere, escriba una o varias expresiones de encabezado admitidas para la operación
elegida en el encabezado Headers (Encabezados).
g. Si está configurado, establezca los valores de variable de fase requeridos para la operación
elegida en el encabezado Stage Variables (Variables de fase).
h. Si se le solicita, elija un certificado de cliente generado por API Gateway en el encabezado Client
Certificate (Certificado de cliente) para que el backend autentique la operación.
i. Si se solicita, escriba un cuerpo de solicitud adecuado en el editor de texto en el encabezado
Request Body (Cuerpo de la solicitud).
j. Elija Test (Prueba) para probar la llamada al método.

Para este tutorial, utilice GET para Method (Método) en lugar de ANY, utilice petstore/pets para
Path (Ruta) en lugar de la ruta del recurso de proxy ({proxy}) y type=fish para Query Strings
(Cadenas de consulta).

54
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

55
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

Como que el sitio web del backend admite la solicitud GET /petstore/pets?type=fish, devuelve
una respuesta correcta similar a la siguiente:

[
{
"id": 1,
"type": "fish",
"price": 249.99
},
{
"id": 2,
"type": "fish",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]

Si intenta llamar a GET /petstore, obtendrá una respuesta 404 con un mensaje de error Cannot
GET /petstore. Esto se debe a que el backend no es compatible con la operación especificada. Si
llama a GET /petstore/pets/1, obtendrá una respuesta 200 OK con la siguiente carga, ya que la
solicitud admite el sitio web PetStore.

{
"id": 1,
"type": "dog",
"price": 249.99
}

2. Para usar un explorador que llame a un método GET en un recurso específico de la API, haga lo
siguiente.

a. Si aún no lo ha hecho, elija Deploy API (Implementar API) en el menú desplegable Actions
(Acciones) de la API que ha creado. Siga las instrucciones para implementar la API en un rango
específico. Anote la Invoke URL (URL de invocación) que se muestra en la página Stage Editor
(Editor de fase) resultante. Esta es la URL base de la API.
b. Para enviar una solicitud GET en un recurso específico, anexe la ruta del recurso, incluyendo
posibles expresiones de cadenas de consulta, al valor Invoke URL (URL de invocación) obtenido
en el paso anterior, copie la URL completa en la barra de direcciones de un explorador y presione
Intro.

En este tutorial, implemente la API en una etapa test y añada petstore/pets?type=fish

a la URL Invoke de la API. Esto produce la URL https://4z9giyi2c1.execute-api.us-
west-2.amazonaws.com/test/petstore/pets?type=fish.

El resultado debe ser el mismo que el que se devuelve cuando utiliza TestInvoke desde la consola
de API Gateway.

Tutorial: Desarrollo de una API de REST con integración HTTP

no de proxy
En este tutorial creará una API desde cero utilizando la consola de Amazon API Gateway. La consola se
puede considerar como un estudio de diseño de la API y se puede utilizar para definir el ámbito de las

56
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

características de API, para probar su comportamiento, para crear la API y para implementar la API en
etapas.

Temas
• Crear una API con integración de HTTP personalizada (p. 57)
• Asignación de parámetros de solicitudes para una API de API Gateway (p. 66)
• Asignar la carga de respuesta (p. 74)

Crear una API con integración de HTTP personalizada

Esta sección le guía por los pasos para crear recursos, exponer métodos en un recurso, configurar un
método para lograr los comportamientos de la API deseados y probar e implementar la API.

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. 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).

a. Elija New API (Nueva API).

b. Introduzca un nombre en API Name (Nombre de la API).
c. Opcionalmente, añada una descripción breve en Description (Descripción).
d. Seleccione Create API (Crear API).

Como resultado, se creará una API vacía. El árbol Resources (Recursos) muestra el recurso raíz (/)
sin métodos. En este ejercicio, vamos a desarrollar la API con la integración HTTP personalizada
del sitio web de PetStore (http://petstore-demo-endpoint.execute-api.com/petstore/pets). Con fines
ilustrativos, crearemos un recurso /pets como un elemento secundario de la raíz y expondremos
un método GET en este recurso para que un cliente pueda recuperar una lista de los elementos Pets
disponibles en el sitio web de PetStore.
3. Para crear el recurso /pets, seleccione la raíz, elija Actions (Acciones) y, a continuación, elija Create
Resource (Crear recurso).

Escriba Pets en Resource Name (Nombre del recurso), deje el valor que aparece en Resource Path
(Ruta de acceso del recurso), seleccione Enable API Gateway CORS (Habilitar API Gateway CORS) y
haga clic en Create Resource (Crear recurso).

57
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

4. Para exponer un método GET en el recurso /pets, elija Actions (Acciones) y después Create Method
(Crear método).

58
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

Seleccione GET en la lista situada bajo el nodo del recurso /pets y haga clic en el icono de marca de
verificación para terminar de crear el método.

59
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

Note

Otras opciones para un método de API son las siguientes:

• POST, que se utiliza principalmente para crear recursos secundarios.

• PUT, que se utiliza principalmente para actualizar los recursos existentes (y, aunque no es
recomendable, puede utilizarse para crear recursos secundarios).
• DELETE, que se utiliza para eliminar recursos.
• PATCH, que se utiliza para actualizar los recursos.
• HEAD, que se utiliza principalmente en escenarios de pruebas. Es igual que GET, pero no
devuelve la representación de los recursos.
• OPTIONS, que pueden usar los intermediarios para obtener la información sobre las
opciones de comunicación disponibles para el servicio de destino.

El método creado aún no está integrado con el backend. Lo haremos en el siguiente paso.
5. En el panel Setup (Configuración) del método, seleccione HTTP para Integration type (Tipo de
integración), seleccione GET en la lista desplegable HTTP method (Método HTTP), escriba http://
petstore-demo-endpoint.execute-api.com/petstore/pets como el valor de Endpoint URL
(URL de punto de enlace), no modifique el resto de campos y, a continuación, elija Save (Guardar).
Note

En el caso del HTTP method (Método HTTP) de la solicitud de integración, debe elegir uno de
los métodos compatibles con el backend. Para HTTP o Mock integration, es razonable
que la solicitud del método y la solicitud de integración usen el mismo verbo HTTP. Para otros
tipos de integración, la solicitud del método usará probablemente un verbo HTTP diferente del
de la solicitud de integración. Por ejemplo, para llamar a una función de Lambda, la solicitud
de integración debe utilizar POST para invocar la función, mientras que la solicitud del método
puede utilizar cualquier verbo HTTP en función de la lógica de la función de Lambda.

60
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

Cuando termine de configurar el método, aparecerá el panel Method Execution (Ejecución del
método), donde puede seguir configurando la solicitud del método para añadir parámetros de cadena
de consulta o de encabezados personalizados. También puede actualizar la solicitud de integración
para que asigne los datos de la solicitud del método en el formato requerido por el backend.

El sitio web de PetStore le permite recuperar una lista de elementos Pet por tipo de mascota (por
ejemplo, "Dog" o "Cat") en una determinada página. Utiliza los parámetros de cadena de consulta
type y page para aceptar esta entrada. Por tanto, tenemos que añadir los parámetros de cadena
de consulta a la solicitud del método y asignarlos a las cadenas de consulta correspondientes de la
solicitud de integración.
6. En el panel Method Execution (Ejecución del método) del método GET, elija Method Request
(Solicitud de método), seleccione AWS_IAM para Authorization (Autorización), expanda la sección URL
Query String Parameters (Parámetros de cadena de consulta URL) y elija Add query string (Añadir
cadena de consulta) para crear dos parámetros de cadena de consulta denominados type y page.
Seleccione el icono de marca de verificación para guardar cada uno de los parámetros de cadena de
consulta que acaba de añadir.

61
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

El cliente ahora puede proporcionar un tipo de mascota y un número de página como parámetros de
cadena de consulta cuando envíe una solicitud. Estos parámetros de entrada deben mapearse a los
parámetros de cadena de consulta de la integración para reenviar los valores de entrada a nuestro
sitio web de PetStore en el backend. Como el método utiliza AWS_IAM, debe firmar la solicitud para
invocar el método.
7. En la página Integration Request (Solicitud de integración) del método, expanda la sección URL
Query String Parameters (Parámetros de cadena de consulta URL). De forma predeterminada, los
parámetros de cadena de consulta de la solicitud del método se asignan a los parámetros de cadena
de consulta de la solicitud de integración de igual nombre. Esta asignación predeterminada funciona
para nuestra API de demostración. La dejaremos como está. Para asignar un parámetro de método
de solicitud diferente al parámetro de método de integración correspondiente, haga clic en el icono
de lápiz del parámetro para editar la expresión de asignación, mostrada en la columna Mapped from
(Asignado desde). Para asignar un parámetro de solicitud de método a un parámetro de solicitud de
integración diferente, primero seleccione el icono de eliminación para eliminar el parámetro de solicitud
de integración existente y elija Add query string (Añadir cadena de consulta) para especificar un nuevo
nombre y la expresión de asignación del parámetro de solicitud del método que desee.

62
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

Con esto finaliza la creación de esta API sencilla de demostración. Es el momento de probar la API.
8. Para probar la API con la consola de API Gateway, elija Test (Prueba) en el panel Method Execution
(Ejecución de método) del método GET /pets. En el panel Method Test (Prueba del método), escriba
Dog y 2 para las cadenas de consulta type y page, respectivamente y, a continuación, elija Test
(Probar).

El resultado es el siguiente. (Es posible que necesite desplazarse hacia abajo para ver los resultados
de la prueba).

63
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

Ahora que la prueba se ha realizado correctamente, podemos implementar la API para ponerla a
disposición del público en general.
9. Para implementar la API, seleccione la API y, a continuación, elija Deploy API (Implementar API) en el
menú desplegable Actions (Acciones).

64
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

En el cuadro de diálogo Deploy API (Implementar API), elija una etapa (o [New Stage] para la
primera implementación de la API); escriba un nombre (por ejemplo, "prueba", "prod", "dev", etc.) en el
campo de entrada Stage name (Nombre de etapa); si lo desea, proporcione una descripción en Stage
description (Descripción de etapa) y/o Deployment description (Descripción de implementación); y
después elija Deploy (Implementar).

65
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

Una vez implementada, puede obtener las URL de invocación (Invoke URL) de los puntos de enlace
de la API.

Si el método GET admitiera el acceso abierto (por ejemplo, si el tipo de autorización del método se
hubiera establecido en NONE), podría hacer doble clic en el enlace Invoke URL (URL de invocación)
para invocar el método en su navegador predeterminado. Si fuera necesario, podría también agregar
los parámetros de cadena de consulta necesarios a la URL de invocación. Con el tipo de autorización
de AWS_IAM que se describe aquí, deberá firmar la solicitud con un ID de clave de acceso y la clave
secreta correspondiente de un usuario de IAM de su cuenta de AWS. Para ello, debe utilizar un cliente
que admita los protocolos Signature Version 4 (SigV4). Un ejemplo de este tipo de cliente es una
aplicación que utilice uno de los SDK de AWS o la aplicación Postman o los comandos de cURL. Para
llamar a un método POST, PUT o PATCH que tome una carga, también necesitará un cliente de este
tipo para administrar la carga.

Para invocar este método de API en la extensión Postman, añada los parámetros de cadena de
consulta a la URL de invocación específica de la etapa (tal y como se muestra en la imagen anterior)
para crear la URL de la solicitud de método completa:

https://api-id.execute-api.region.amazonaws.com/test/pets?type=Dog&page=2

Especifique esta URL en la barra de direcciones del navegador. Elija GET como verbo HTTP.
Seleccione AWS Signature para la opción Type (Tipo) bajo la pestaña Authorization (Autorización) y, a
continuación, especifique las siguientes propiedades obligatorias antes de enviar la solicitud:

• En AccessKey, escriba la clave de acceso de AWS del intermediario, aprovisionada desde AWS
IAM.
• En SecretKey, escriba la clave secreta de AWS del intermediario que se aprovisionó desde AWS
IAM cuando se creó la clave de acceso.
• En AWS Region (Región de AWS), escriba la región de AWS donde se va a alojar la API, tal como
se especifica en la URL de invocación.
• En Service Name (Nombre de servicio), escriba execute-api para el servicio de ejecución de API
Gateway.

Si utiliza un SDK para crear un cliente, puede llamar a los métodos expuestos por el SDK para firmar
la solicitud. Para obtener más información, consulte los SDK de AWS que desee.
Note

Cuando se realicen cambios en la API, deberá volver a implementar la API para que las
características nuevas o actualizadas estén disponibles antes de volver a invocar la URL de
la solicitud.

Asignación de parámetros de solicitudes para una API de API Gateway

En este tutorial describiremos cómo asignar parámetros de solicitudes de métodos a los parámetros de
solicitudes de integración correspondientes para una API de API Gateway. Creamos una API de ejemplo
con integración HTTP personalizada y la utilizamos para demostrar cómo utilizar API Gateway para diseñar
un parámetro de solicitud de método para el parámetro de solicitud de método correspondiente. Entonces
obtenemos acceso al siguiente punto de enlace HTTP accesible públicamente:

http://petstore-demo-endpoint.execute-api.com/petstore/pets

Si copia la URL anterior, péguela en la barra de direcciones de un navegador web y pulse Enter o
Return; obtendrá el siguiente cuerpo de respuesta con formato JSON:

66
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]

El punto de enlace anterior puede aceptar dos parámetros de consulta: type y page. Por ejemplo, cambie
la URL por lo siguiente:

http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=cat&page=2

Recibirá la siguiente carga de respuesta con formato JSON, en la que se muestra la segunda página solo
con entradas "cat":

[
{
"id": 4,
"type": "cat",
"price": 999.99
},
{
"id": 5,
"type": "cat",
"price": 249.99
},
{
"id": 6,
"type": "cat",
"price": 49.97
}
]

Este punto de enlace admite también el uso de un ID de elemento, expresado mediante un parámetro de
ruta URL. Por ejemplo, busque lo siguiente:

http://petstore-demo-endpoint.execute-api.com/petstore/pets/1

Se muestra la siguiente información con formato JSON sobre el elemento con el ID 1:

{
"id": 1,
"type": "dog",
"price": 249.99
}

Además de admitir operaciones GET, este punto de enlace acepta solicitudes POST con una carga. Por
ejemplo, utilice Postman para enviar una solicitud de método POST a lo siguiente:

67
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

http://petstore-demo-endpoint.execute-api.com/petstore/pets

incluya el encabezado Content-type: application/json y el siguiente cuerpo de solicitud:

{
"type": "dog",
"price": 249.99
}

Recibirá el siguiente objeto JSON en el cuerpo de la respuesta:

{
"pet": {
"type": "dog",
"price": 249.99
},
"message": "success"
}

Estas y otras características se exponen ahora mediante el desarrollo de una API de API Gateway con la
integración HTTP personalizada de este sitio web PetStore. Las tareas son las siguientes:

• Crear una API con un recurso de https://my-api-id.execute-api.region-

id.amazonaws.com/test/petstorewalkthrough/pets que actúe como un proxy al punto de
enlace HTTP de http://petstore-demo-endpoint.execute-api.com/petstore/pets
• Habilitar la API para aceptar dos parámetros de consulta de la solicitud de método (petType y
petsPage), asignarlos a los parámetros de consulta type y page de la solicitud de integración,
respectivamente, y pasar la solicitud al punto de enlace HTTP
• Admitir un parámetro de ruta {petId} en la URL de solicitud de método de la API para especificar un
ID de elemento, asignarlo al parámetro de ruta {id} de la URL de la solicitud de integración y enviar la
solicitud al punto de enlace HTTP
• Habilitar la solicitud de método para aceptar la carga JSON del formato definido por sitio web del
backend y transmitir la carga sin modificaciones a través de la solicitud de integración al punto de enlace
HTTP del backend.

Temas
• Requisitos previos (p. 68)
• Paso 1: Crear recursos (p. 69)
• Paso 2: Crear y probar los métodos (p. 69)
• Paso 3: Implementar la API (p. 72)
• Paso 4: Probar la API (p. 73)

Note

Preste atención al uso de mayúsculas y minúsculas en los pasos de este tutorial. El uso de una
letra minúscula en lugar de una letra mayúscula (o viceversa) puede producir errores más tarde
en el tutorial.

Requisitos previos

Antes de empezar este tutorial, debe hacer lo siguiente:

68
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

1. Realice los pasos de Requisitos previos para comenzar con API Gateway (p. 13), incluida la
asignación del permiso de acceso de API Gateway al usuario de IAM.
2. Como mínimo, siga los pasos de Tutorial: Desarrollo de una API de REST con integración HTTP no de
proxy (p. 56) para crear una nueva API llamada MyDemoAPI en la consola de API Gateway.

Paso 1: Crear recursos

En este paso, creará tres recursos que permitirán a la API interactuar con el punto de enlace HTTP.

Para crear el primer recurso

1. En el panel Resources (Recursos), seleccione la raíz del recurso, representada por un signo de barra
diagonal inversa (/) y, a continuación, elija Create Resource (Crear recurso) en el menú desplegable
Actions (Acciones).
2. En Resource Name (Nombre de recurso), escriba petstorewalkthrough.
3. En Resource Path (Ruta del recurso), acepte el valor predeterminado de /petstorewalkthrough y, a
continuación, elija Create Resource (Crear recurso).

Para crear el segundo recurso

1. En el panel Resources (Recursos), elija de nuevo /petstorewalkthrough y, a continuación, elija Create

Resource (Crear recurso).
2. En Resource Name (Nombre de recurso), escriba pets.
3. En Resource Path (Ruta del recurso), acepte el valor predeterminado de /petstorewalkthrough/pets y,
a continuación, elija Create Resource (Crear recurso).

Para crear el tercer recurso

1. En el panel Resources (Recursos), elija de nuevo /petstorewalkthrough/pets y, a continuación, elija

Create Resource (Crear recurso).
2. En Resource Name (Nombre de recurso), escriba petId. Esto realiza la asignación con el ID de
elemento en el punto de enlace HTTP.
3. En Resource Path (Ruta del recurso), sobrescriba petid con {petId}. Utilice llaves ({ }) entre petId
para que se muestre /petstorewalkthrough/pets/{petId} y, a continuación, elija Create Resource (Crear
recurso).

Esto realiza la asignación con /petstore/pets/my-item-id en el punto de enlace HTTP.

Paso 2: Crear y probar los métodos

En este paso, integra los métodos con los puntos de enlace HTTP del backend, mapea el parámetro de la
solicitud de método GET a los parámetros de la solicitud de integración correspondientes y, a continuación,
prueba los métodos.

Para configurar y probar el primer método GET

Este procedimiento muestra lo siguiente:

• Crear e integrar la solicitud del método GET /petstorewalkthrough/pets con la solicitud de

integración GET http://petstore-demo-endpoint.execute-api.com/petstore/pets
• Asignar los parámetros de consulta de la solicitud del método petType y petsPage a los parámetros
de la cadena de consulta de la solicitud de integración type y page, respectivamente

69
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

1. En el panel Resources (Recursos), elija /petstorewalkthrough/pets, elija Create Method (Crear método)
en el menú Actions (Acciones) y, a continuación, elija GETen /pets en la lista desplegable de nombres
de método.
2. En el panel /petstorewalkthrough/pets - GET - Setup, elija HTTP en Integration type (Tipo de
integración) y elija GET en HTTP method (Método HTTP).
3. En Endpoint URL (URL de punto de enlace), escriba http://petstore-demo-
endpoint.execute-api.com/petstore/pets.
4. Seleccione Save.
5. En el panel Method Execution (Ejecución del método), elija Method Request (Solicitud de método) y, a
continuación, elija la flecha situada junto a URL Query String Parameters (Parámetros de consulta de
cadena URL).
6. Elija Add query string (Añadir cadena de consulta).
7. En Name (Nombre), escriba petType.

Esto especifica el parámetro de consulta petType en la solicitud del método de la API.

8. Elija el icono de marca de verificación para terminar de crear el parámetro de cadena de consulta de la
URL de solicitud del método.
9. Vuelva a elegir Add query string (Añadir cadena de consulta).
10. En Name (Nombre), escriba petsPage.

Esto especifica el parámetro de consulta petsPage en la solicitud del método de la API.

11. Elija el icono de marca de verificación para terminar de crear el parámetro de cadena de consulta de la
URL de solicitud del método.
12. Elija Method Execution (Ejecución del método), elija Integration Request (Solicitud de integración) y, a
continuación, elija la flecha situada junto a URL Query String Parameters (Parámetros de cadena de
consulta URL).
13. Elimine la entrada petType asignada desde method.request.querystring.petType y la
entrada petsPage asignada desde method.request.querystring.petsPage. Este paso se
realiza porque el punto de enlace requiere los parámetros de cadena de consulta type y page para la
URL de la solicitud, en lugar de los valores predeterminados.
14. Elija Add query string (Añadir cadena de consulta).
15. En Name (Nombre), escriba type. Esto crea los parámetros de cadena de consulta para la URL de la
solicitud de integración.
16. En Mapped from (Asignado desde), escriba method.request.querystring.petType.

Esto asigna el parámetro de consulta petType de la solicitud del método al parámetro de consulta
type de la solicitud de integración.
17. Elija el icono de marca de verificación para terminar de crear el parámetro de cadena de consulta de la
URL de solicitud de integración.
18. Vuelva a elegir Add query string (Añadir cadena de consulta).
19. En Name (Nombre), escriba page. Esto crea los parámetros de cadena de consulta para la URL de la
solicitud de integración.
20. En Mapped from (Asignado desde), escriba method.request.querystring.petsPage.

Esto asigna el parámetro de consulta petsPage de la solicitud del método al parámetro de consulta
page de la solicitud de integración.
21. Elija el icono de marca de verificación para terminar de crear el parámetro de cadena de consulta de la
URL de solicitud de integración.
22. Elija Method Execution (Ejecución del método). En el cuadro Client (Cliente), elija TEST (PROBAR).
En el área Query Strings (Consultas de cadena), para petType, escriba cat. En petsPage, escriba 2.

70
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

23. Elija Test. Si todo sale bien, Response Body (Cuerpo de la respuesta) mostrará lo siguiente:

[
{
"id": 4,
"type": "cat",
"price": 999.99
},
{
"id": 5,
"type": "cat",
"price": 249.99
},
{
"id": 6,
"type": "cat",
"price": 49.97
}
]

Para configurar y probar el segundo método GET

Este procedimiento muestra lo siguiente:

• Crear e integrar la solicitud del método GET /petstorewalkthrough/pets/{petId} con la solicitud

de integración GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/
{id}
• Asignar los parámetros de ruta de la solicitud del método de petId a los parámetros de ruta de la
solicitud de integración de id

1. En la lista Resources (Recursos), elija /petstorewalkthrough/pets/{petId}, elija Create Method (Crear

método) en el menú desplegable Actions (Acciones) y después elija GET como el verbo HTTP del
método.
2. En el panel Setup (Configuración), elija HTTP para Integration type (Tipo de integración) y elija GET
para HTTP method (Método HTTP).
3. En Endpoint URL (URL de punto de enlace), escriba http://petstore-demo-
endpoint.execute-api.com/petstore/pets/{id}.
4. Seleccione Save.
5. En el panel Method Execution (Ejecución del método), elija Integration Request (Solicitud de
integración) y, a continuación, elija la flecha situada junto a URL Path Parameters (Parámetros de ruta
URL).
6. Elija Add path (Añadir ruta).
7. En Name (Nombre), escriba id.
8. En Mapped from (Asignado desde), escriba method.request.path.petId.

Esto asigna el parámetro de ruta de la solicitud del método de petId al parámetro de ruta de la
solicitud de integración de id.
9. Elija el icono de marca de verificación para terminar de crear el parámetro de ruta URL.
10. Elija Method Execution (Ejecución del método) y, en el cuadro Client (Cliente), elija TEST (PROBAR).
En el área Path (Ruta), para petId, escriba 1.
11. Elija Test. Si todo sale bien, Response Body (Cuerpo de la respuesta) mostrará lo siguiente:

71
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

"id": 1,
"type": "dog",
"price": 249.99
}

Para configurar y probar el método POST

Este procedimiento muestra lo siguiente:

• Crear e integrar la solicitud del método POST /petstorewalkthrough/pets con la solicitud de

integración POST http://petstore-demo-endpoint.execute-api.com/petstore/pets
• Pasar la carga JSON de la solicitud del método a través de la carga de la solicitud de integración, sin
ningún tipo de modificación

1. En el panel Resources (Recursos), elija /petstorewalkthrough/pets, elija Create Method (Crear método)
en el menú desplegable Actions (Acciones) y después elija POST como el verbo HTTP del método.
2. En el panel Setup (Configuración), elija HTTP para Integration type (Tipo de integración) y elija POST
para HTTP method (Método HTTP).
3. En Endpoint URL (URL de punto de enlace), escriba http://petstore-demo-
endpoint.execute-api.com/petstore/pets.
4. Seleccione Save.
5. En el panel Method Execution (Ejecución del método), en el cuadro Client (Cliente), elija TEST
(PROBAR). Expanda Request Body (Cuerpo de la solicitud) y, a continuación, escriba lo siguiente:

{
"type": "dog",
"price": 249.99
}

6. Elija Test. Si todo sale bien, Response Body (Cuerpo de la respuesta) mostrará lo siguiente:

{
"pet": {
"type": "dog",
"price": 249.99
},
"message": "success"
}

Paso 3: Implementar la API

En este paso, implementará la API para que pueda empezar a llamarla fuera de la consola de API
Gateway.

Para implementar la API

1. En el panel Resources (Recursos), elija Deploy API (Implementar API).

2. En Deployment stage (Etapa de implementación), elija test.
Note

La entrada debe tener texto cifrado UTF-8 (es decir, no localizado).

3. En Deployment description (Descripción de la implementación), escriba Calling HTTP endpoint
walkthrough.

72
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

4. Elija Deploy (Implementar).

Paso 4: Probar la API

En este paso, saldrá de la consola de API Gateway y utilizará la API para obtener acceso al punto de
enlace HTTP.

1. En el panel Stage Editor (Editor de etapas), junto a Invoke URL (URL de invocación), copie la URL en
el portapapeles. Debe tener un aspecto similar al siguiente:

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

2. Pegue esta URL en el cuadro de direcciones de una nueva pestaña del navegador.
3. Añada /petstorewalkthrough/pets para que tenga el siguiente aspecto:

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

Desplácese hasta la dirección URL. Se debe mostrar la siguiente información:

[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]

4. Detrás de petstorewalkthrough/pets, escriba ?petType=cat&petsPage=2 para que tenga el

siguiente aspecto:

https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets?
petType=cat&petsPage=2

5. Desplácese hasta la dirección URL. Se debe mostrar la siguiente información:

[
{
"id": 4,
"type": "cat",
"price": 999.99
},
{
"id": 5,
"type": "cat",
"price": 249.99
},
{
"id": 6,
"type": "cat",
"price": 49.97

73
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

}
]

6. Detrás de petstorewalkthrough/pets, reemplace ?petType=cat&petsPage=2 por /1 para

que tenga el siguiente aspecto:

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

7. Desplácese hasta la dirección URL. Se debe mostrar la siguiente información:

{
"id": 1,
"type": "dog",
"price": 249.99
}

8. Mediante una herramienta de proxy de depuración web o la herramienta de línea de comandos

de cURL, envíe una solicitud de método POST a la URL desde el procedimiento anterior. Añada /
petstorewalkthrough/pets para que tenga el siguiente aspecto:

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

Añada el siguiente encabezado:

Content-Type: application/json

Añada el siguiente código al cuerpo de la solicitud:

{
"type": "dog",
"price": 249.99
}

Por ejemplo, si utiliza la herramienta de línea de comandos de cURL, ejecute un comando similar al
siguiente:

curl -H "Content-Type: application/json" -X POST -d "{\"type\": \"dog\",

\"price\": 249.99}" https://my-api-id.execute-api.region-id.amazonaws.com/test/
petstorewalkthrough/pets

Debe devolverse la siguiente información en el cuerpo de la respuesta:

{
"pet": {
"type": "dog",
"price": 249.99
},
"message": "success"
}

Ha llegado al final de este tutorial.

Asignar la carga de respuesta

En este tutorial mostraremos cómo utilizar modelos y plantillas de mapeo de API Gateway para transformar
la salida de una llamada de API de un esquema de datos a otro. Este tutorial se basa en las instrucciones

74
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

y conceptos de Introducción a la API de API Gateway (p. 14) y Asignación de parámetros de solicitudes
para una API de API Gateway (p. 66). Si aún no ha completado estos tutoriales, le sugerimos que los
complete antes.

Este tutorial utilizará API Gateway para obtener datos de ejemplo de un punto de enlace HTTP accesible
públicamente y de una función de AWS Lambda que creará. Tanto el punto de enlace HTTP como la
función de Lambda devuelven los mismos datos de ejemplo:

[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]

Utilizará modelos y plantillas de asignación para transformar estos datos en uno o varios formatos de
salida. En API Gateway, el modelo define el formato, también conocido como el esquema o la forma,
de algunos datos. En API Gateway se usa una plantilla de mapeo para transformar algunos datos
de un formato en otro. Para obtener más información, consulte Trabajo con modelos y plantillas de
asignación (p. 395).

El primer modelo y plantilla de asignación se utiliza para cambiar el nombre de id a number, de type a
class y de price a salesPrice, como se indica a continuación:

[
{
"number": 1,
"class": "dog",
"salesPrice": 249.99
},
{
"number": 2,
"class": "cat",
"salesPrice": 124.99
},
{
"number": 3,
"class": "fish",
"salesPrice": 0.99
}
]

El segundo modelo y plantilla de asignación se utiliza para combinar id y type en description y para
cambiar el nombre de price a askingPrice, tal y como se indica a continuación:

[
{
"description": "Item 1 is a dog.",
"askingPrice": 249.99
},

75
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

{
"description": "Item 2 is a cat.",
"askingPrice": 124.99
},
{
"description": "Item 3 is a fish.",
"askingPrice": 0.99
}
]

El tercer modelo y plantilla de asignación se utiliza para combinar id, type y price en un conjunto de
listings, como se indica a continuación:

{
"listings": [
"Item 1 is a dog. The asking price is 249.99.",
"Item 2 is a cat. The asking price is 124.99.",
"Item 3 is a fish. The asking price is 0.99."
]
}

Temas
• Paso 1: Crear modelos (p. 76)
• Paso 2: Crear recursos (p. 78)
• Paso 3: Crear métodos GET (p. 79)
• Paso 4: Crear una función de Lambda (p. 80)
• Paso 5: Configurar y probar los métodos (p. 81)
• Paso 6: Implementar la API (p. 84)
• Paso 7: Probar la API (p. 84)
• Paso 8: Eliminar (p. 86)

Paso 1: Crear modelos

En este paso, creará cuatro modelos. Los tres primeros modelos representan los formatos de salida de los
datos para su uso con el punto de enlace HTTP y la función de Lambda. El último modelo representa el
esquema de entrada de datos para su uso con la función de Lambda.

Para crear el primer modelo de salida

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Si se muestra MyDemoAPI, elija Models (Modelos).
3. Seleccione Create (Crear).
4. En Model name (Nombre del modelo), escriba PetsModelNoFlatten.
5. En Content type (Tipo de contenido), escriba application/json.
6. En Model description (Descripción del modelo), escriba Changes id to number, type to
class, and price to salesPrice.
7. En Model schema (Esquema del modelo), escriba la siguiente definición compatible con el esquema
JSON:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PetsModelNoFlatten",
"type": "array",
"items": {

76
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

"type": "object",
"properties": {
"number": { "type": "integer" },
"class": { "type": "string" },
"salesPrice": { "type": "number" }
}
}
}

8. Seleccione Create model (Crear modelo).

Para crear el segundo modelo de salida

1. Seleccione Create.
2. En Model name (Nombre del modelo), escriba PetsModelFlattenSome.
3. En Content type (Tipo de contenido), escriba application/json.
4. En Model description (Descripción del modelo), escriba Combines id and type into
description, and changes price to askingPrice.
5. En Model schema (Esquema del modelo), escriba lo siguiente:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PetsModelFlattenSome",
"type": "array",
"items": {
"type": "object",
"properties": {
"description": { "type": "string" },
"askingPrice": { "type": "number" }
}
}
}

6. Seleccione Create model (Crear modelo).

Para crear el tercer modelo de salida

1. Seleccione Create.
2. En Model name (Nombre del modelo), escriba PetsModelFlattenAll.
3. En Content type (Tipo de contenido), escriba application/json.
4. En Model description (Descripción del modelo), escriba Combines id, type, and price into
a set of listings.
5. En Model schema (Esquema del modelo), escriba lo siguiente:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PetsModelFlattenAll",
"type": "object",
"properties": {
"listings": {
"type": "array",
"items": {
"type": "string"
}
}
}
}

77
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

6. Seleccione Create model (Crear modelo).

Para crear el modelo de entrada

1. Seleccione Create.
2. En Model name (Nombre del modelo), escriba PetsLambdaModel.
3. En Content type (Tipo de contenido), escriba application/json.
4. En Model description (Descripción del modelo), escriba GetPetsInfo model.
5. En Model schema (Esquema del modelo), escriba lo siguiente:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PetsLambdaModel",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"type": { "type": "string" },
"price": { "type": "number" }
}
}
}

6. Seleccione Create model (Crear modelo).

Paso 2: Crear recursos

En este paso, creará cuatro recursos. Los tres primeros recursos le permitirán obtener los datos de
ejemplo del punto de enlace HTTP en tres formatos de salida. El último recurso le permitirá obtener
los datos de ejemplo de la función de Lambda en el esquema de salida que combina id y type en
description y cambia el nombre de price a askingPrice.

Para crear el primer recurso

1. En la lista de enlaces, elija Resources (Recursos).

2. En el panel Resources (Recursos), elija de nuevo /petstorewalkthrough y, a continuación, elija Create
Resource (Crear recurso).
3. En Resource Name (Nombre de recurso), escriba NoFlatten.
4. En Resource Path (Ruta del recurso), acepte el valor predeterminado de /petstorewalkthrough/
noflatten y, a continuación, elija Create Resource (Crear recurso).

Para crear el segundo recurso

1. En el panel Resources (Recursos), elija /petstorewalkthrough y, a continuación, elija Create Resource

(Crear recurso).
2. En Resource Name (Nombre de recurso), escriba FlattenSome.
3. En Resource Path (Ruta del recurso), acepte el valor predeterminado de /petstorewalkthrough/
flattensome y, a continuación, elija Create Resource (Crear recurso).

Para crear el tercer recurso

1. En el panel Resources (Recursos), elija /petstorewalkthrough y, a continuación, elija Create Resource

(Crear recurso).

78
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

2. En Resource Name (Nombre de recurso), escriba FlattenAll.

3. En Resource Path (Ruta del recurso), acepte el valor predeterminado de /petstorewalkthrough/
flattenall y, a continuación, elija Create Resource (Crear recurso).

Para crear el cuarto recurso

1. En el panel Resources (Recursos), elija /petstorewalkthrough y, a continuación, elija Create Resource

(Crear recurso).
2. En Resource Name (Nombre de recurso), escriba LambdaFlattenSome.
3. En Resource Path (Ruta del recurso), acepte el valor predeterminado de /petstorewalkthrough/
lambdaflattensome y, a continuación, elija Create Resource (Crear recurso).

Paso 3: Crear métodos GET

En este paso, creará un método GET para cada uno de los recursos que ha creado en el paso anterior.

Para crear el primer método GET

1. En la lista Resources (Recursos), elija /petstorewalkthrough/flattenall y, a continuación, elija Create

Resource (Crear recurso).
2. En la lista desplegable, elija GET y después haga clic en el icono de marca de verificación para
guardar la selección.
3. En el panel de configuración, elija HTTP para Integration type (Tipo de integración) y GET para HTTP
method (Método HTTP), escriba http://petstore-demo-endpoint.execute-api.com/
petstore/pets en Endpoint URL (URL de punto de enlace) y elija Save (Guardar).

Para crear el segundo método GET

1. En la lista Resources (Recursos), elija /petstorewalkthrough/lambdaflattensome y, a continuación, elija

Create Resource (Crear recurso).
2. En la lista desplegable, elija GET y después elija la marca de verificación para guardar la selección.
3. En el panel de configuración, elija Lambda Function (Función de Lambda) para Integration type (Tipo
de integración), elija la región en la que ha creado la función de Lambda GetPetsInfo (p. 80) en
la lista desplegable Lambda Region (Región de Lambda), seleccione GetPetsInfo para Lambda
Function (Función de Lambda) y elija Save (Guardar). Elija OK (Aceptar) cuando se le solicite que
agregue permiso a la función de Lambda.

Para crear el tercer método GET

1. En la lista Resources (Recursos), elija /petstorewalkthrough/flattensome y, a continuación, elija Create

Resource (Crear recurso).
2. En la lista desplegable, elija GET y después haga clic en el icono de marca de verificación para
guardar la selección.
3. En el panel de configuración, elija HTTP para Integration type (Tipo de integración) y GET para HTTP
method (Método HTTP), escriba http://petstore-demo-endpoint.execute-api.com/
petstore/pets en Endpoint URL (URL de punto de enlace) y, a continuación, elija Save (Guardar).

Para crear el cuarto método GET

1. En la lista Resources (Recursos), elija /petstorewalkthrough/noflatten y, a continuación, elija Actions

(Acciones), Create Method (Crear método).

79
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

2. En la lista desplegable, elija GET y después haga clic en el icono de marca de verificación para
guardar la selección.
3. En el panel de configuración, elija HTTP para Integration type (Tipo de integración) y GET para HTTP
method (Método HTTP), escriba http://petstore-demo-endpoint.execute-api.com/
petstore/pets en Endpoint URL (URL de punto de enlace) y, a continuación, elija Save (Guardar).

Paso 4: Crear una función de Lambda

En este paso creará una función de Lambda que devuelve los datos de ejemplo.

Para crear la función de Lambda

1. Abra la consola de AWS Lambda en https://console.aws.amazon.com/lambda/.

2. Aplique alguna de las siguientes acciones:

• Si aparece una página de bienvenida, elija Get Started Now (Empezar ahora).
• Si aparece la página de lista Lambda: Function list (Lambda: lista de funciones), elija Create a
Lambda function (Crear una función de Lambda).
3. En Name (Nombre), escriba GetPetsInfo.
4. En Description (Descripción), escriba Gets information about pets.
5. En Code template (Plantilla de código), elija None (Ninguna).
6. Escriba el código siguiente:

console.log('Loading event');

exports.handler = function(event, context, callback) {

callback(null,
[{"id": 1, "type": "dog", "price": 249.99},
{"id": 2, "type": "cat", "price": 124.99},
{"id": 3, "type": "fish", "price": 0.99}]); // SUCCESS with message
};

Tip

En el código Node.js anterior, console.log escribe información en un registro de Amazon

CloudWatch. event contiene la entrada a la función de Lambda. context contiene el
contexto de llamada. callback devuelve el resultado. Para obtener más información
sobre cómo escribir código de funciones de Lambda, consulte la sección sobre modelo de
programación del tema de introducción a AWS Lambda y los tutoriales de ejemplo de la guía
para desarrolladores de AWS Lambda.
7. En Handler name (Nombre de controlador), deje el valor predeterminado index.handler.
8. En Role (Rol), seleccione el rol de ejecución de Lambda, APIGatewayLambdaExecRole, que ha
creado en Desarrollo de una API de REST de API Gateway con integración Lambda (p. 26).
9. Seleccione Create Lambda function.
10. En la lista de funciones, elija GetPetsInfo para mostrar los detalles de la función.
11. Anote la región de AWS en la que creó esta función. Lo necesitará más adelante.
12. En la lista desplegable, elija Edit or test function (Editar o probar función).
13. En Sample event (Evento de ejemplo), sustituya el código que aparece por lo siguiente:

80
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

Tip

Las llaves vacías indican que no hay valores de entrada para esta función de Lambda. Esta
función simplemente devuelve el objeto JSON que contiene la información de mascotas, por
lo que los pares de clave-valor no son obligatorios aquí.
14. Elija Invoke (Invocar). Execution result (Resultado de ejecución)
muestra[{"id":1,"type":"dog","price":249.99},
{"id":2,"type":"cat","price":124.99},{"id":3,"type":"fish","price":0.99}],
que también se escribe en los archivos de registro de CloudWatch Logs.
15. Elija Go to function list (Ir a al lista de funciones).

Paso 5: Configurar y probar los métodos

En este paso configurará las respuestas del método, la solicitudes de integración y las solicitudes de
respuesta para especificar los esquemas (o modelos) de datos de entrada y salida para los métodos GET
asociados con el punto de enlace HTTP y la función de Lambda. También aprenderá a probar la llamada a
estos métodos con la consola de API Gateway.

Para configurar la integración para el primer método GET y después probarla

1. En el árbol Resources (Recursos) de la API, seleccione GET en el nodo /petstorewalkthrough/

flattenall.
2. En el panel Method Execution (Ejecución del método), elija Method Response (Respuesta de método)
y, a continuación, elija la flecha situada junto a 200.
3. En el área Response Models for 200 (Modelos de respuesta para 200), para application/json, haga
clic en el icono de lápiz para empezar a configurar el modelo para la salida del método. En Models
(Modelos), elija PetsModelFlattenAll y, a continuación, haga clic en el icono de marca de verificación
para guardar la configuración.
4. Elija Method Execution (Ejecución del método), Integration Response (Respuesta de integración) y, a
continuación, la flecha situada junto a 200.
5. Expanda la sección Mapping Templates (Plantillas de mapeo) y seleccioneapplication/json en Content
Type (Tipo de contenido).
6. En Generate template from model (Generar plantilla a partir de modelo), elija PetsModelFlattenAll
para mostrar una plantilla de asignación detrás del modelo PetsModelFlattenAll como punto de
partida.
7. Modifique el código de la plantilla de asignación de la siguiente manera:

#set($inputRoot = $input.path('$'))
{
"listings" : [
#foreach($elem in $inputRoot)
"Item number $elem.id is a $elem.type. The asking price is
$elem.price."#if($foreach.hasNext),#end

#end
]
}

8. Seleccione Save.
9. Elija Method Execution (Ejecución del método), en el cuadro Client (Cliente), elija TEST (PROBAR)
y, a continuación, elija Test (Probar). Si todo sale bien, Response Body (Cuerpo de la respuesta)
mostrará lo siguiente:

{
"listings" : [

81
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

"Item number 1 is a dog. The asking price is 249.99.",

"Item number 2 is a cat. The asking price is 124.99.",
"Item number 3 is a fish. The asking price is 0.99."
]
}

Para configurar la integración para el segundo método GET y después probarla

1. En el árbol Resources (Recursos) de la API, seleccione GET en el nodo /petstorewalkthrough/

lambdaflattensome.
2. En Method Execution (Ejecución del método), elija Method Response (Respuesta de método). Y, a
continuación, elija la flecha situada junto a 200 para expandir la sección.
3. En el área Response Models for 200 (Modelos de respuesta para 200), haga clic en el icono de lápiz
en la fila del tipo de contenido de application/json. Elija PetsModelFlattenSome para Models (Modelos)
y, a continuación, seleccione el icono de marca de verificación para guardar la opción.
4. Vuelva a Method Execution (Ejecución del método). Elija Integration Response (Respuesta de
integración) y, a continuación, elija la flecha situada junto a 200.
5. En la sección Mapping Templates (Plantillas de mapeo), seleccioneapplication/json en Content Type
(Tipo de contenido).
6. En Generate template (Generar plantilla), elija PetsModelFlattenSome para mostrar la plantilla de
script de mapeo para la salida de este método.
7. Modifique el código como se indica a continuación y después elija Save (Guardar):

#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end

#end
]

8. Elija Method Execution (Ejecución del método), en el cuadro Client (Cliente), elija TEST (PROBAR)
y, a continuación, elija Test (Probar). Si todo sale bien, Response Body (Cuerpo de la respuesta)
mostrará lo siguiente:

[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]

Para configurar la integración para el tercer método GET y después probarla

1. En el árbol Resources (Recursos), seleccione GET en el nodo /petstorewalkthrough/flattensome.

82
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

2. En el panel Method Execution (Ejecución del método), elija Method Response (Respuesta de método).
3. Elija la flecha situada junto a 200.
4. En el área Response Models for 200 (Modelos de respuesta para 200), para application/json, haga clic
en el icono de lápiz. Para Models (Modelos), elija PetsModelFlattenSome y, a continuación, seleccione
el icono de marca de verificación para guardar la opción.
5. Vuelva a Method Execution (Ejecución del método) y elija Integration Response (Respuesta de
integración).
6. Elija la flecha situada junto a 200 para expandir la sección.
7. Expanda el área Mapping Templates (Plantillas de mapeo). Elija application/json para Content-Type.
En Generate template (Generar plantilla), elija PetsModelFlattenSome para mostrar la plantilla de
script de mapeo para la salida de este método.
8. Modifique el código de la siguiente manera:

#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description": "Item $elem.id is a $elem.type.",
"askingPrice": $elem.price
}#if($foreach.hasNext),#end

#end
]

9. Seleccione Save.
10. Vuelva a Method Execution (Evaluación del método) y elija TEST (PROBAR) en el cuadro Client
(Cliente). Y, a continuación, elija Test (Probar). Si todo sale bien, Response Body (Cuerpo de la
respuesta) mostrará lo siguiente:

[
{
"description": "Item 1 is a dog.",
"askingPrice": 249.99
},
{
"description": "Item 2 is a cat.",
"askingPrice": 124.99
},
{
"description": "Item 3 is a fish.",
"askingPrice": 0.99
}
]

Para configurar la integración para el cuarto método GET y después probarla

1. En el árbol Resources (Recursos), seleccione GET en el nodo /petstorewalkthrough/noflatten.

2. En el panel Method Execution (Ejecución del método), elija Method Response (Respuesta de método)
y después expanda la sección 200.
3. En el área Response Models for 200 (Modelos de respuesta para 200), para application/json, haga clic
en el icono de lápiz para actualizar el modelo de respuesta de este método.
4. Elija PetsModelNoFlatten como modelo para el tipo de contenido de application/json y, a continuación,
haga clic en el icono de marca de verificación para guardar la opción.
5. Elija Method Execution (Ejecución del método), Integration Response (Respuesta de integración) y, a
continuación, la flecha situada junto a 200 para expandir la sección.

83
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

6. Expanda la sección Mapping Templates (Plantillas de asignación). Elija application/json para Content-
Type. En Generate template (Generar plantilla), elija PetsModelNoFlatten para mostrar la plantilla de
script de mapeo para la salida de este método.
7. Modifique el código de la siguiente manera:

#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"number": $elem.id,
"class": "$elem.type",
"salesPrice": $elem.price
}#if($foreach.hasNext),#end

#end
]

8. Seleccione Save.
9. Vuelva a Method Execution (Ejecución del método) y, en el cuadro Client (Cliente), elija TEST
(PROBAR) y, a continuación, elija Test (Probar). Si todo sale bien, Response Body (Cuerpo de la
respuesta) mostrará lo siguiente:

[
{
"number": 1,
"class": "dog",
"salesPrice": 249.99
},
{
"number": 2,
"class": "cat",
"salesPrice": 124.99
},
{
"number": 3,
"class": "fish",
"salesPrice": 0.99
}
]

Paso 6: Implementar la API

En este paso, implementará la API para que pueda empezar a llamarla fuera de la consola de API
Gateway.

Para implementar la API

1. En el panel Resources (Recursos), elija Deploy API (Implementar API).

2. En Deployment stage (Etapa de implementación), elija test.
3. En Deployment description (Descripción de la implementación), escriba Using models and
mapping templates walkthrough.
4. Elija Deploy (Implementar).

Paso 7: Probar la API

En este paso saldrá de la consola de API Gateway para interactuar con el punto de enlace HTTP y la
función de Lambda.

84
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

1. En el panel Stage Editor (Editor de etapas), junto a Invoke URL (URL de invocación), copie la URL en
el portapapeles. Debe tener un aspecto similar al siguiente:

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

2. Pegue esta URL en el cuadro de direcciones de una nueva pestaña del navegador.
3. Añada /petstorewalkthrough/noflatten para que tenga el siguiente aspecto:

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

Desplácese hasta la dirección URL. Se debe mostrar la siguiente información:

[
{
"number": 1,
"class": "dog",
"salesPrice": 249.99
},
{
"number": 2,
"class": "cat",
"salesPrice": 124.99
},
{
"number": 3,
"class": "fish",
"salesPrice": 0.99
}
]

4. Detrás de petstorewalkthrough/, reemplace noflatten por flattensome.

5. Desplácese hasta la dirección URL. Se debe mostrar la siguiente información:

[
{
"description": "Item 1 is a dog.",
"askingPrice": 249.99
},
{
"description": "Item 2 is a cat.",
"askingPrice": 124.99
},
{
"description": "Item 3 is a fish.",
"askingPrice": 0.99
}
]

6. Detrás de petstorewalkthrough/, reemplace flattensome por flattenall.

7. Desplácese hasta la dirección URL. Se debe mostrar la siguiente información:

{
"listings" : [
"Item number 1 is a dog. The asking price is 249.99.",
"Item number 2 is a cat. The asking price is 124.99.",
"Item number 3 is a fish. The asking price is 0.99."
]
}

85
 Amazon API Gateway Guía del desarrollador
Desarrollo de una API con integración de HTTP

8. Detrás de petstorewalkthrough/, reemplace flattenall por lambdaflattensome.

9. Desplácese hasta la dirección URL. Se debe mostrar la siguiente información:

[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]

Paso 8: Eliminar

Si ya no necesita la función de Lambda que ha creado para este tutorial, puede eliminarla ahora. También
puede eliminar los recursos de IAM asociados.
Warning

Si elimina una función de Lambda que usan sus API, esas API dejarán de funcionar. La
eliminación de una función de Lambda no se puede deshacer. Si desea utilizar la función de
Lambda de nuevo, debe volver a crearla.
Si elimina un recurso de Lambda que usa una función de Lambda, la función de Lambda y todas
las API que la utilizan dejarán de funcionar. La eliminación de un recurso de IAM no se puede
deshacer. Si desea utilizar el recurso de IAM de nuevo, debe volver a crearlo. Si tiene previsto
continuar experimentando con los recursos que ha creado para este y el resto de tutoriales, no
elimine el rol de invocación de Lambda ni el rol de ejecución de Lambda.

Para eliminar la función de Lambda

1. Inicie sesión en la consola de administración de AWS y abra la consola de AWS Lambda en https://
console.aws.amazon.com/lambda/.
2. En la página Lambda: Function list (Lambda: lista de funciones), en la lista de funciones, elija el botón
situado junto a GetPetsInfo y, a continuación, elija Actions (Acciones), Delete (Eliminar). Cuando se le
pregunte, elija Delete (Eliminar) otra vez.

Para eliminar los recursos de IAM asociados

1. Abra la consola de IAM en https://console.aws.amazon.com/iam/.

2. En el área Details (Detalles), elija Roles (Funciones).
3. Seleccione APIGatewayLambdaExecRole y, a continuación, elija Role Actions (Acciones de rol),
Delete Role (Eliminar rol). Cuando se le pregunte, elija Yes, Delete.
4. En el área Details (Detalles), elija Policies (Políticas).
5. Seleccione APIGatewayLambdaExecPolicy, y, a continuación, elija Policy Actions (Acciones de la
política) y luego Delete (Eliminar). Cuando se le pregunte, elija Delete (Eliminar).

Ha llegado al final de este tutorial.

86
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API con integración privada

Tutorial: Crear una API REST con la integración

privada de API Gateway
Puede crear una API de API Gateway con integración privada para proporcionar a sus clientes acceso a
recursos HTTP/HTTPS dentro de su Amazon Virtual Private Cloud (Amazon VPC). Estos recursos de VPC
son puntos de enlace HTTP/HTTPS de una instancia EC2 situada detrás de un balanceador de carga de
red de la VPC. El balanceador de carga de red encapsula el recurso de la VPC y direcciona las solicitudes
entrantes al recurso correspondiente.

Cuando un cliente llama a la API, API Gateway se conecta al balanceador de carga de red a través del
enlace de VPC preconfigurado. El recurso VpcLink de API Gateway encapsula un enlace de la VPC. Este
es responsable de reenviar las solicitudes del método de API a los recursos de la VPC y devuelve las
respuestas del backend al intermediario. Para los desarrolladores de API, VpcLink es funcionalmente
equivalente a un punto de enlace de integración.

Para crear una API con integración privada, debe crear un nuevo VpcLink (o elegir uno existente)
que esté conectado a un balanceador de carga de red que tenga como destino los recursos de la VPC
deseados. Debe disponer de los permisos adecuados (p. 367) para crear y administrar un VpcLink.
A continuación, deberá configurar un método de la API e integrarlo con VpcLink estableciendo HTTP o
HTTP_PROXY como tipo de integración, VPC_LINK como tipo de conexión de integración y el identificador
VpcLink en el campo connectionId de la integración.
Note

El Balanceador de carga de red y la API deben pertenecer a la misma cuenta de AWS.

Si desea empezar a crear rápidamente una API que tenga acceso a los recursos de la VPC, le guiaremos
por los pasos esenciales para crear una API con integración privada a través de la consola de API
Gateway. Antes de crear la API, haga lo siguiente:

1. Cree un recurso de la VPC, cree o elija un balanceador de carga de red en una cuenta de la misma
región y agregue la instancia EC2 que aloja el recurso como destino del balanceador de carga de
red. Para obtener más información, consulte Configuración de un balanceador de carga de red para
integraciones privadas de API Gateway (p. 366).
2. Conceda los permisos necesarios para crear los enlaces VPC para integraciones privadas. Para obtener
más información, consulte Concesión de permisos para crear un enlace VPC (p. 367).

Después de crear el recurso de VPC y el balanceador de carga de red con dicho recurso configurado en
sus grupos de destino, siga las instrucciones que se indican a continuación para crear una API e integrarla
con el recurso de la VPC a través de un VpcLink de una integración privada.

Para crear una API con integración privada a través de la consola de API Gateway

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Si aún no lo ha hecho, cree un enlace VPC:

a. En el panel de navegación principal, elija VPC Links (Enlaces de VPC) y Create (Crear).
b. Elija VPC link for REST APIs (Vínculo de VPC para API REST).
c. Escriba un nombre y, opcionalmente, una descripción para el vínculo de VPC.
d. Elija un balanceador de carga de red en la lista desplegable Target NLB (NLB de destino).

El balanceador de carga de red ya debe estar creado en la región que la API para que aparezca
en la lista.
e. Seleccione Create (Crear) para empezar a crear el enlace VPC.

87
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API con integración privada

La respuesta inicial devuelve una representación del recurso VpcLink con el ID del enlace VPC y el
estado PENDING. Esto se debe a que la operación es asíncrona y tarda alrededor de 2-4 minutos en
completarse. Una vez que finaliza correctamente, el estado pasa a ser AVAILABLE. Mientras tanto,
puede seguir creando la API.
3. Elija APIs en el panel de navegación principal y haga clic en Create API (Crear API) para crear una
nueva API optimizada para bordes o del tipo punto de enlace regional.
4. En el recurso raíz (/), seleccione Create Method (Crear método) en el menú desplegable Actions
(Acciones) y haga clic en GET.
5. En el panel / GET - Setup, inicialice la integración del método de API del modo siguiente:

a. Elija VPC Link en Integration type (Tipo de integración).

b. Seleccione Use Proxy Integration (Usar integración de proxy).
c. En la lista desplegable Method (Método), seleccione GET como método de integración.
d. En la lista desplegable VPC Link (Enlace de VPC), seleccione [Use Stage Variables] y
escriba ${stageVariables.vpcLinkId} en el cuadro de texto siguiente.

Definiremos la variable de etapa vpcLinkId después de implementar la API en una etapa y

establecer su valor en el ID del VpcLink creado en el paso 2.
e. Escriba una URL (por ejemplo, http://myApi.example.com) en Endpoint URL (URL de punto
de enlace).

Aquí, utilizaremos el nombre de host (por ejemplo, myApi.example.com) para definir el

encabezado Host de la solicitud de integración.
Note

Para el balanceador de carga de red (NLB), asegúrese de que utiliza el nombre de DNS
de NLB tal y como se describe en Introducción a Network Load Balancers.
f. Deje el valor Use Default Timeout (Usar tiempo de espera predeterminado) tal y como está, a
menos que desee personalizar los tiempos de espera de la integración.
g. Elija Save (Guardar) para completar la configuración de la integración.

Con la integración del proxy, la API está lista para implementarse. De lo contrario, debe configurar
las respuestas del método y las respuestas de integración apropiadas.
h. En el menú desplegable Actions (Acciones), seleccione Deploy API (Implementar API) y elija una
etapa nueva o existente para implementar la API.

Anote el valor resultante de Invoke URL (URL de invocación). Lo necesitará para invocar la API.
Antes de eso, debe configurar la variable de etapa vpcLinkId.
i. En Stage Editor (Editor de etapas), seleccione la pestaña Stage Variables (Variables de etapa) y
haga clic en Add Stage (Añadir etapa).

i. En la columna Name (Nombre), escriba vpcLinkId.

ii. En la columna Value (Valor), escriba el ID de VPC_LINK; por ejemplo, gix6s7.
iii. Seleccione el icono con marca de verificación para guardar esta variable de etapa.

Si utiliza la variable de etapa, podrá cambiar fácilmente entre los diferentes enlaces VPC de
la API; solo tendrá que modificar el valor de esta variable.

Aquí termina el proceso de creación de la API. Puede probar a invocarla con otras integraciones.

88
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API con integración de AWS

Tutorial: Creación de una API de REST de API

Gateway con integración de AWS
Tanto los temas Tutorial: Desarrollo de una API de REST Hello World con integración de proxy
de Lambda (p. 27) como Desarrollo de una API de REST de API Gateway con integración
Lambda (p. 26) describen cómo se debe crear una API de API Gateway para exponer la función de
Lambda integrada. Además, puede crear una API de API Gateway para exponer otros servicios de AWS,
como Amazon SNS, Amazon S3, Amazon Kinesis e incluso AWS Lambda. Esto es posible mediante la
integración de AWS. La integración de Lambda o la integración de proxy de Lambda es un caso especial,
donde la invocación de la función de Lambda se expone a través de la API de API Gateway.

Todos los servicios de AWS admiten API dedicadas para exponer sus características. Sin embargo, los
protocolos de la aplicación o las interfaces de programación probablemente difieren entre un servicio y
otro. Una API de API Gateway con la integración de AWS tiene la ventaja de proporcionar un protocolo de
aplicación coherente para que su cliente tenga acceso a diferentes servicios de AWS.

En este tutorial, vamos a crear una API para exponer Amazon SNS. Para ver más ejemplos de
integración de una API con otros servicios de AWS, consulte Tutoriales y talleres sobre Amazon API
Gateway (p. 18).

A diferencia de la integración de proxy de Lambda, no existe una integración de proxy correspondiente

para otros servicios de AWS. Por lo tanto, un método de API se integra con una única acción de AWS.
Para mayor flexibilidad, similar a la de la integración de proxy, puede configurar una integración de proxy
de Lambda. Entonces, la función de Lambda analiza y procesa solicitudes para otras acciones de AWS.

API Gateway no vuelve a intentar las operaciones cuando se agota el tiempo de espera del punto de
enlace. El intermediario de la API debe implementar una lógica de reintentos para administrar los tiempos
de espera del punto de enlace.

Este tutorial se basa en las instrucciones y conceptos de Desarrollo de una API de REST de API Gateway
con integración Lambda (p. 26). Si aún no ha completado ese tutorial, le sugerimos que lo haga
primero.

Temas
• Requisitos previos (p. 89)
• Paso 1: Crear el recurso (p. 90)
• Paso 2: Crear el método GET (p. 90)
• Paso 3: Crear el rol de ejecución del proxy de servicio de AWS (p. 90)
• Paso 4: Especificar la configuración del método y probar el método (p. 92)
• Paso 5: Implementar la API (p. 92)
• Paso 6: Probar la API (p. 93)
• Paso 7: Limpieza (p. 93)

Requisitos previos
Antes de empezar este tutorial, haga lo siguiente:

1. Realice los pasos que se indican en Requisitos previos para comenzar con API Gateway (p. 13).
2. Asegúrese de que el usuario de IAM tenga acceso para crear políticas y roles en IAM. En este tutorial
tendrá que crear una política y un rol de IAM.

89
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API con integración de AWS

3. Cree una nueva API llamada MyDemoAPI. Para obtener más información, consulte Tutorial: Desarrollo
de una API de REST con integración HTTP no de proxy (p. 56).
4. Implemente la API al menos una vez en una etapa denominada test. Para obtener más información,
consulte Implementar la API (p. 41) en Desarrollo de una API de REST de API Gateway con
integración Lambda (p. 26).
5. Realice el resto de los pasos de Desarrollo de una API de REST de API Gateway con integración
Lambda (p. 26).
6. Cree al menos un tema en Amazon Simple Notification Service (Amazon SNS). Utilizará la API
implementada para obtener una lista de temas de Amazon SNS asociados a su cuenta de AWS. Para
obtener información sobre cómo crear un tema en Amazon SNS, consulte Creación de un tema. (No
es necesario que copie el ARN del tema mencionado en el paso 5).

Paso 1: Crear el recurso

En este paso, creará un recurso que permitirá al proxy de servicio de AWS interactuar con el servicio de
AWS.

Para crear el recurso

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija MyDemoAPI.
3. En el panel Resources (Recursos), elija el recurso raíz, representado por una barra diagonal (/), y elija
Create Resource (Crear recurso).
4. En Resource Name (Nombre de recurso), escriba MyDemoAWSProxy y, a continuación, elija Create
Resource (Crear recurso).

Paso 2: Crear el método GET

En este paso, creará un método GET que permitirá al proxy de servicio de AWS interactuar con el servicio
de AWS.

Para crear el método GET

1. En el panel Resources (Recursos) elija /mydemoawsproxy y, a continuación, Create Method (Crear

método).
2. Para el método HTTP, elija GET y guarde la selección.

Paso 3: Crear el rol de ejecución del proxy de servicio de AWS

En este paso, creará un rol de IAM que utilizará el proxy de servicio de AWS para interactuar con el
servicio de AWS. A este rol de IAM lo llamamos rol de ejecución del proxy de servicio de AWS. Sin este
rol, API Gateway no puede interactuar con el servicio de AWS. Más adelante, especificará este rol en la
configuración del método GET que acaba de crear.

Para crear el rol de ejecución del proxy de servicio de AWS y su política

1. Inicie sesión en la consola de administración de AWS y abra la consola de IAM en https://

console.aws.amazon.com/iam/.
2. Elija Policies (Políticas).
3. Aplique alguna de las siguientes acciones:

90
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API con integración de AWS

• Si aparece la página Welcome to Managed Policies (Bienvenido a las políticas administradas), elija
Get Started (Empezar) y, a continuación, elija Create Policy (Crear política).
• Si aparece una lista de políticas, elija Create Policy (Crear política).
4. Elija JSON y, a continuación, escriba el texto siguiente.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Resource": [
"*"
],
"Action": [
"sns:ListTopics"
]
}
]
}

5. Elija Review policy.

6. Escriba un nombre y la descripción de la política.
7. Elija Create Policy.
8. Elija Roles.
9. Elija Create Role.
10. Elija AWS Service (Servicio de AWS) en Select type of trusted entity (Seleccionar tipo de entidad de
confianza) y, a continuación, elija API Gateway (Gateway de API).
11. Elija Next: Permissions.
12. Elija Next: Tags (Siguiente: Etiquetas).
13. Elija Next: Review.
14. En Role Name (Nombre del rol), escriba un nombre para el rol de ejecución (por ejemplo,
APIGatewayAWSProxyExecRole). También puede incluir una descripción para este rol. Por último,
elija Create role (Crear rol).
15. En la lista Roles (Roles), elija el rol que acaba de crear. Es posible que deba desplazarse por la lista.
16. Para el rol seleccionado, elija Attach policies (Asociar políticas).
17. Marque la casilla que se encuentra junto a la política que creó anteriormente (por ejemplo,
APIGatewayAWSProxyExecPolicy) y elija Attach policy (Asociar política).
18. El rol que acaba de crear tiene la siguiente relación de confianza que permite que API Gateway asuma
un rol por las acciones permitidas por las políticas adjuntas:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}

91
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API con integración de AWS

Para Role ARN (ARN de rol), anote el nombre de recurso de Amazon (ARN) del rol
de ejecución. Lo necesitará más adelante. El ARN debe tener un aspecto similar a:
arn:aws:iam::123456789012:role/APIGatewayAWSProxyExecRole, donde 123456789012
es el ID de su cuenta de AWS.

Paso 4: Especificar la configuración del método y probar el

método
En este paso, especificará la configuración para el método GET, de forma que pueda interactuar con un
servicio de AWS a través de un proxy de servicio de AWS. A continuación, probará el método.

Para especificar la configuración del método GET y después probarlo

1. En la consola de API Gateway, en el panel Recursos (Resources) de la API denominada MyDemoAPI

en /mydemoawsproxy, elija GET.
2. Elija Integration Request (Solicitud de integración) y, a continuación, AWS Service (Servicio de AWS).
3. En AWS Region (Región de AWS), elija el nombre de la región de AWS de donde desea obtener los
temas de Amazon SNS.
4. En AWS Service (Servicio de AWS), elija SNS.
5. En HTTP method (Método HTTP), elija GET.
6. En Action (Acción), escriba ListTopics.
7. En Execution Role (Rol de ejecución), escriba el ARN del rol de ejecución.
8. Deje Path Override (Invalidación de ruta) en blanco.
9. Seleccione Save.
10. En el panel Method Execution (Ejecución del método), en el cuadro Client (Cliente), elija TEST
(PROBAR) y, a continuación, elija Test (Probar). Si todo sale bien, Response Body (Cuerpo de
respuesta) mostrará una respuesta parecida a la siguiente:

{
"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"
}
}
}

Paso 5: Implementar la API

En este paso, implementará la API para que pueda llamarla desde fuera de la consola de API Gateway.

92
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API con integración de AWS

Para implementar la API

1. En el panel Resources (Recursos), elija Deploy API (Implementar API).

2. En Deployment stage (Etapa de implementación), elija test.
3. En Deployment description (Descripción de la implementación), escriba Calling AWS service
proxy walkthrough.
4. Elija Deploy (Implementar).

Paso 6: Probar la API

En este paso, saldrá de la consola de API Gateway y usará el proxy de servicio de AWS para interactuar
con el servicio de Amazon SNS.

1. En el panel Stage Editor (Editor de etapas), junto a Invoke URL (URL de invocación), copie la URL en
el portapapeles. Debería tener un aspecto similar al siguiente:

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

2. Pegue la URL en el cuadro de direcciones de una nueva pestaña del navegador.

3. Añada /mydemoawsproxy para que tenga el siguiente aspecto:

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

Desplácese hasta la dirección URL. Se debe mostrar información similar a la siguiente:

{"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}}}

Paso 7: Limpieza
Puede eliminar los recursos de IAM que el proxy de servicio de AWS necesita para funcionar.
Warning

Si elimina un recurso de IAM que utiliza un proxy de servicio de AWS, ese proxy de servicio de
AWS y todas las API que lo utilicen dejarán de funcionar. La eliminación de un recurso de IAM no
se puede deshacer. Si desea utilizar el recurso de IAM de nuevo, debe volver a crearlo.

Para eliminar los recursos de IAM asociados

1. Abra la consola de IAM en https://console.aws.amazon.com/iam/.

2. En el área Details (Detalles), elija Roles (Funciones).
3. Seleccione APIGatewayAWSProxyExecRole y, a continuación, elija Role Actions (Acciones de rol),
Delete Role (Eliminar rol). Cuando se le pregunte, elija Yes, Delete.
4. En el área Details (Detalles), elija Policies (Políticas).
5. Seleccione APIGatewayAWSProxyExecPolicy y, a continuación, elija Policy Actions (Acciones de la
política) y luego Delete (Eliminar). Cuando se le pregunte, elija Delete (Eliminar).

Ha llegado al final de este tutorial. Para obtener más detalles sobre la creación de una API con un
proxy de servicio de AWS, consulte Tutorial: Crear una API de REST como proxy de Amazon S3 en API

93
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

Gateway (p. 113), Tutorial: Crear una API REST Calc con dos integraciones de servicios de AWS y
una integración de Lambda sin proxy (p. 94) o Tutorial: Creación de una API de REST como proxy de
Amazon Kinesis en API Gateway (p. 139).

Tutorial: Crear una API REST Calc con dos

integraciones de servicios de AWS y una integración
de Lambda sin proxy
El tutorial de introducción a integraciones sin proxy (p. 34) 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:

1. Exponiendo un método GET en el recurso /calc para invocar la función de Lambda, proporcionando
la entrada como parámetros de cadena de consulta. (Integración de AWS Service)
2. Exponiendo un método 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 de AWS Service)
3. 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
de Lambda Function)

Además de probar con este tutorial, sugerimos que estudie el archivo de definición de OpenAPI (p. 109)
para la API de Calc, que puede importar a API Gateway siguiendo las instrucciones de the section called
“OpenAPI” (p. 500).

Temas
• Creación de una cuenta de AWS (p. 94)
• Crear un rol de IAM asumible (p. 95)
• Creación de una función Calc de Lambda (p. 97)
• Probar la función Calc de Lambda (p. 97)
• Cree una API de Calc (p. 99)
• Integración 1: Crear un método GET con parámetros de consulta para llamar a la función de
Lambda (p. 99)
• Integración 2: Crear un método POST con una carga JSON para llamar a la función de
Lambda (p. 101)
• Integración 3: Crear un método GET con parámetros de ruta para llamar a la función de
Lambda (p. 104)
• Definiciones de OpenAPI de una API de ejemplo integrada con una función de Lambda (p. 109)

Creación de una cuenta de AWS

Antes de comenzar este tutorial, necesitará una cuenta de AWS.

94
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

Si no dispone de una cuenta de AWS, siga estos pasos para crear una.

Para inscribirse en una cuenta de AWS

1. Abra https://portal.aws.amazon.com/billing/signup.
2. Siga las instrucciones en línea.

Parte del procedimiento de inscripción consiste en recibir una llamada telefónica e indicar un código de
verificación en el teclado del teléfono.

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

1. Inicie sesión en la consola de IAM.

2. Elija Roles.
3. Elija Create Role.
4. En Select type of trusted entity (Seleccionar tipo de entidad de confianza), elija AWS service (Servicio
de AWS).
5. En Choose the service that will use this role (Elegir el servicio que usará este rol), elija Lambda.
6. Elija Next: Permissions (Siguiente: Permisos).

95
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

7. Elija Create Policy (Crear política).

Se abrirá una nueva ventana de consola Create Policy (Crear política). En esa ventana, haga lo
siguiente:

a. En la pestaña JSON, reemplace la política existente por la siguiente:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "*"
}
]
}

b. Elija Review policy.

c. En Review Policy (Revisar política) haga lo siguiente:

i. En Nombre, escriba un nombre, como lambda_execute.

ii. Elija Create Policy.
8. En la ventana de consola Create Role (Crear rol) original, haga lo siguiente:

a. 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!)
b. Elija Next: Tags (Siguiente: Etiquetas).
c. Elija Next: Review.
d. En Role name (Nombre de rol), escriba un nombre como
lambda_invoke_function_assume_apigw_role.
e. Elija Create role.
9. Elija el rol lambda_invoke_function_assume_apigw_role de la lista de roles.
10. Seleccione la pestaña Trust Relationships (Relaciones de confianza).
11. Elija Edit trust relationship (Editar relación de confianza).
12. 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"
}
]

96
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

13. Elija Update Trust Policy.

14. 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.

1. En la consola de Lambda, elija Create function (Crear función).

2. Elija Author from Scratch (Crear desde cero).
3. En Name (Nombre), escriba Calc.
4. Establezca Runtime (Tiempo de ejecución) en un tiempo de ejecución de Node.js compatible.
5. Elija Create function.
6. Copie la siguiente función de Lambda y péguela en el editor de código en la consola de Lambda.

console.log('Loading the Calc function');

exports.handler = function(event, context, callback) {

console.log('Received event:', JSON.stringify(event, null, 2));
if (event.a === undefined || event.b === undefined || event.op === undefined) {
callback("400 Invalid Input");
}

var res = {};

res.a = Number(event.a);
res.b = Number(event.b);
res.op = event.op;

if (isNaN(event.a) || isNaN(event.b)) {
callback("400 Invalid Operand");
}

switch(event.op)
{
case "+":
case "add":
res.c = res.a + res.b;
break;
case "-":
case "sub":
res.c = res.a - res.b;
break;
case "*":
case "mul":
res.c = res.a * res.b;
break;
case "/":
case "div":
res.c = res.b===0 ? NaN : Number(event.a) / Number(event.b);
break;
default:
callback("400 Invalid Operator");
break;
}
callback(null, res);
};

7. Bajo Execution role (Rol de ejecución) elija Choose an existing role (Elegir un rol existente).

97
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

8. Escriba el ARN del rol para el rol lambda_invoke_function_assume_apigw_role que creó

anteriormente.
9. 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.

1. En el menú desplegable Saved test events (Eventos de prueba guardados), elija Configure test events
(Configurar eventos de prueba).
2. Para el nombre del evento de prueba, escriba calc2plus5.
3. Sustituya la definición del evento de prueba por lo siguiente:

{
"a": "2",
"b": "5",
"op": "+"
}

4. Seleccione Save.
5. Elija Test.
6. Expanda Execution result: succeeded (Resultado de la ejecución: correcta). Debería ver lo siguiente:

{
"a": 2,
"b": 5,
"op": "+",

98
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

"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.

Cree la API de Calc

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. 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).
3. En Create new API (Crear nueva API), elija New API (Nueva API).
4. En API name (Nombre de la API), escriba LambdaCalc.
5. Deje el campo Description (Descripción) y deje la opción Endpoint Type (Tipo de punto de enlace)
establecida en Regional.
6. 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.

Para configurar el método GET con parámetros de cadenas de consulta

1. En la consola de API Gateway, en Resources (Recursos), de la API LambdaCalc, elija /.

2. En el menú desplegable Actions (Acciones), elija Create Resource (Crear recurso).
3. En Resource Name (Nombre del recurso), escriba calc.
4. Elija Create Resource (Crear recurso).
5. Elija el recurso /calc que acaba de crear.
6. En el menú desplegable Actions (Acciones), elija Create method (Crear método).
7. En el menú desplegable que aparece, elija GET.
8. Haga clic en el icono de marca de verificación para guardar la selección.
9. En el panel Set up (Configuración) que aparece:

a. En Integration Type (Tipo de integración), elija AWS Service (Servicio de AWS).

b. En AWS Region (Región de AWS), elija la región (por ejemplo, us-west-2) donde creó la
función de Lambda.
c. En AWS service (Servicio de AWS), elija Lambda.
d. Deje AWS Subdomain (Subdominio de AWS) en blanco, ya que nuestra función de Lambda no
está alojada en ningún subdominio de AWS.

99
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

e. Para HTTP method (Método HTTP, elija POST y, a continuación, elija el icono de marca de
verificación para guardar la selección. 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.
f. Elija Use path override en Action Type (Tipo de acción). Esta opción nos permite especificar
el ARN de la acción Invoke para ejecutar nuestra función Calc.
g. Escriba /2015-03-31/functions/arn:aws:lambda:region:account-
id:function:Calc/invocations en Path override (Sustitución de ruta), donde region es
la región en la que ha creado la función de Lambda y account-id es el número de cuenta de la
cuenta de AWS.
h. En Execution Role (Rol de ejecución), escriba el ARN del rol de IAM
lambda_invoke_function_assume_apigw_role que creó anteriormente (p. 95).
i. Deje la opción Content Handling (Tratamiento de contenido) establecida en Passthrough (Acceso
directo), ya que este método no tratará con datos binarios.
j. Deje la casilla Use default timeout (Usar tiempo de espera predeterminado) desactivada.
k. Seleccione Save.
10. Elija Method Request (Solicitud de método).

Ahora, vamos a configurar los parámetros de consulta para el método GET en /calc para que pueda
recibir la entrada en nombre de la función de Lambda del backend.

a. Haga clic en el icono del lápiz que aparece junto a Request (Solicitud) y elija la opción Validate
query string parameters and headers (Validar parámetro de cadena de consulta y encabezado) en
el menú desplegable. Esta configuración provocará un mensaje de error para volver a establecer
los parámetros que faltan si el cliente no los especifica. No se le cobrará por la llamada al
backend.
b. Haga clic en el icono de marca de verificación para guardar los cambios.
c. Expanda la sección URL Query String Parameters (Parámetros de cadena de consulta URL).
d. Elija Add query string (Añadir cadena de consulta).
e. En Name (Nombre), escriba operand1.
f. Haga clic en el icono de marca de verificación para guardar el parámetro.
g. Repita los pasos anteriores para crear los parámetros denominados operand2 y operator.
h. Active la opción Required (Obligatorio) de cada parámetro para asegurarse de que se validan.
11. Elija Method Execution (Ejecución del método) y después elija Integration Request (Solicitud
de integración) para configurar la plantilla de asignación para traducir las cadenas de consulta
proporcionadas por el cliente en la carga de la solicitud de integración, de conformidad con la función
Calc.

a. Expanda la sección Mapping Templates (Plantillas de asignación).

b. Elija When no template matches the request Content-Type header (Cuando ninguna plantilla
coincida con el encabezado Content-Type de la solicitud) para Request body passthrough
(Acceso directo del cuerpo de la solicitud).
c. En Content-Type, elija Add mapping template (Añadir plantilla de asignación).
d. Escriba application/json y haga clic en el icono de marca de verificación para abrir el editor
de la plantilla.
e. Elija Yes, secure this integration (Sí, proteger esta integración) para continuar.
f. Copie el siguiente script de asignación en el editor de la plantilla de asignación:

{
"a": "$input.params('operand1')",
"b": "$input.params('operand2')",
"op": "$input.params('operator')"
100
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

Esta plantilla asigna los tres parámetros de cadena de consulta declarados en Method Request 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.
g. Seleccione Save.
12. Elija Method Execution (Ejecución del método).
13. Ahora puede probar el método GET para verificar que se ha configurado correctamente para invocar la
función de Lambda.

a. En Query Strings (Cadenas de consulta), escriba operand1=2&operand2=3&operator=+.

b. Elija Test.

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 configurar el método POST con una carga JSON para invocar una función de Lambda

1. Vaya a la consola de API Gateway.

2. Elija APIs.
3. Elija la API LambdaCalc que ha creado anteriormente.
4. Elija el recurso /calc en el panel Resources (Recursos).
5. En el menú Actions (Acciones), elija Create method (Crear método).
6. Elija POST en la lista desplegable de métodos.

101
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

7. Haga clic en el icono de marca de verificación para guardar la selección.

8. En el panel Set up (Configuración) que aparece:

a. En Integration Type (Tipo de integración), elija AWS Service (Servicio de AWS).

b. En AWS Region (Región de AWS), elija la región (por ejemplo, us-west-2) donde creó la
función de Lambda.
c. En AWS service (Servicio de AWS), elija Lambda.
d. Deje AWS Subdomain (Subdominio de AWS) en blanco, ya que nuestra función de Lambda no
está alojada en ningún subdominio de AWS.
e. En HTTP method (Método HTTP), elija POST. 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.
f. En Action (Acción), elija Use path override para Action Type (Tipo de acción). Esta opción le
permite especificar el ARN de la acción Invoke (Invocar) para ejecutar su función Calc.
g. Para Path override (Sustitución de ruta), escriba /2015-03-31/functions/
arn:aws:lambda:region:account-id:function:Calc/invocations, donde region es
la región en la que ha creado la función de Lambda y account-id es el número de cuenta de la
cuenta de AWS.
h. En Execution Role (Rol de ejecución), escriba el ARN del rol de IAM
lambda_invoke_function_assume_apigw_role que creó anteriormente (p. 95).
i. Deje la opción Content Handling (Tratamiento de contenido) establecida en Passthrough (Acceso
directo), ya que este método no tratará con datos binarios.
j. Deje la casilla Use Default Timeout (Usar tiempo de espera predeterminado) desactivada.
k. Seleccione Save.
9. Elija Models (modelos) en la API LambdaCalc en el panel de navegación principal de la consola de
API Gateway para crear modelos de datos para la entrada y la salida del método:

a. Elija Create (Crear) en el panel Models (Modelos). Escriba Input en Model name (Nombre de
modelo), escriba application/json en Content type (Tipo de contenido) y copie la siguiente
definición de esquema en el cuadro Model schema (Esquema del modelo):

{
"type":"object",
"properties":{
"a":{"type":"number"},
"b":{"type":"number"},
"op":{"type":"string"}
},
"title":"Input"
}

Este modelo describe la estructura de datos de entrada y se utilizará para validar el cuerpo de la
solicitud entrante.
b. Seleccione Create model (Crear modelo).
c. Elija Create (Crear) en el panel Models (Modelos). Escriba Output en Model name (Nombre de
modelo), escriba application/json en Content type (Tipo de contenido) y copie la siguiente
definición de esquema en el cuadro Model schema (Esquema del modelo):

{
"type":"object",
"properties":{
"c":{"type":"number"}
},
"title":"Output"
}

102
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

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.
d. Busque el ID de API de la API en la parte superior de la pantalla de la consola y anótelo.
Aparecerá entre paréntesis detrás del nombre de la API.
e. Elija Create (Crear) en el panel Models (Modelos).
f. Escriba Result en Model name (Nombre del modelo).
g. Escriba application/json en Content type (Tipo de contenido).
h. Copie la siguiente definición de esquema, donde restapi-id es el ID de la API de REST que
anotó antes, en el cuadro Model schema (Esquema del modelo):

{
"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":"Output"
}

Este modelo describe la estructura de datos de los datos de respuesta devueltos. Hace referencia
a los esquemas Input y Output definidos en la API especificada (restapi-id). Una vez más,
este modelo no se utiliza en este tutorial, ya que se utiliza el comportamiento de paso a través.
i. Seleccione Create model (Crear modelo).
10. En el panel de navegación principal, bajo la API LambdaCalc, seleccione Resources (Recursos).
11. En el panel Resources (Recursos), elija el método POST para la API.
12. Elija Method Request (Solicitud de método).
13. En la opción de configuración Method Request (Solicitud de método), realice las siguientes
operaciones para habilitar la validación de solicitudes en el cuerpo de la solicitud entrante:

a. Haga clic en el icono del lápiz que aparece junto a Request Validator (Validador de solicitudes)
para elegir Validate body. Haga clic en el icono de marca de verificación para guardar la
selección.
b. Expanda la sección Request Body (Cuerpo de solicitud) y elija Add model (Añadir modelo).
c. Escriba application/json en el campo de entrada Content-Type y elija Input en la lista
desplegable en la columna Model name (Nombre de modelo). Haga clic en el icono de marca de
verificación para guardar la selección.
14. Para probar el método POST, haga lo siguiente:

a. Elija Method Execution (Ejecución del método).

b. Elija Test.
15. Copie la siguiente carga JSON en Request Body (Cuerpo de la solicitud):

{
"a": 1,
"b": 2,
"op": "+"

103
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

16. Elija Test.

Debe ver la siguiente salida en Response Body (Cuerpo de la solicitud):

{
"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.

Esta vez utilizará el soporte de la integración de Lambda incorporado en la consola de API Gateway para
configurar la integración del método.

La estructura de recursos de la API resultante será como la siguiente:

Para configurar un método GET con parámetros de ruta URL

1. Vaya a la consola de API Gateway.

2. En APIs (API), elija la API LambdaCalc que creó anteriormente.
3. En el panel de navegación de recursos de la API, elija /calc.
4. En el menú desplegable Actions (Acciones), elija Create Resource (Crear recurso).
5. En Resource Name (Nombre de recurso), escriba {operand1}.
6. En Resource Path (Ruta del recurso), escriba {operand1}.
7. Elija Create Resource (Crear recurso).
8. Elija el recurso /calc/{operand1} que acaba de crear.

104
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

9. En el menú desplegable Actions (Acciones), elija Create Resource (Crear recurso).

10. En Resource Name (Nombre de recurso), escriba {operand2}.
11. En Resource Path (Ruta del recurso), escriba {operand2}.
12. Elija Create Resource (Crear recurso).
13. Elija el recurso /calc/{operand1}/{operand2} que acaba de crear.
14. En el menú desplegable Actions (Acciones), elija Create Resource (Crear recurso).
15. En Resource Path (Ruta del recurso), escriba {operator}.
16. En Resource Name (Nombre de recurso), escriba {operator}.
17. Elija Create Resource (Crear recurso).
18. Elija el recurso /calc/{operand1}/{operand2}/{operator} que acaba de crear.
19. En el menú desplegable Actions (Acciones), elija Create method (Crear método).
20. En el menú desplegable de métodos, elija GET.
21. En el panel Setup (Configuración), elija Lambda Function en Integration type (Tipo de integración),
para utilizar el proceso de configuración optimizado habilitado por la consola.
22. Elija una región (por ejemplo, us-west-2) para Lambda Region (Región de Lambda). Esta es la
región en la que se aloja la función de Lambda.
23. Elija su función de Lambda existente (Calc) para la Lambda Function (Función Lambda).
24. Elija Save (Guardar) y, a continuación, elija OK (Aceptar) para aceptar Add Permissions to Lambda
Function (Añadir permisos a la función de Lambda).
25. Elija Integration Request (Solicitud de integración).
26. Configure la plantilla de asignación de la siguiente manera:

a. Expanda la sección Mapping Templates (Plantillas de asignación).

b. Deje establecido en When no template matches the requested Content-Type header (Cuando
ninguna plantilla coincide con el encabezado Content-Type solicitado)
c. Elija Add mapping template (Añadir plantilla de asignación).
d. Escriba application/json para Content-Type y, a continuación, haga clic en el icono de
marca de verificación para abrir el editor de la plantilla.
e. Elija Yes, secure this integration (Sí, proteger esta integración) para continuar.
f. Copie el siguiente script de asignación en el editor de la plantilla:

{
"a": "$input.params('operand1')",
"b": "$input.params('operand2')",
"op":
#if($input.params('operator')=='%2F')"/"#{else}"$input.params('operator')"#end

Esta plantilla asigna los tres parámetros de ruta URL, declarados cuando se creó el recurso /
calc/{operand1}/{operand2}/{operator}, a 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.
g. Elija Save (Guardar).

Cuando el método está configurado correctamente, la configuración debe ser similar a la siguiente:

105
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

27. Para probar la función GET, haga lo siguiente:

a. Elija Method Execution (Ejecución del método).

b. Elija Test.
c. Escriba 1, 1 y + en los campos {operand1} ({operando1}), {operand2} ({operando1}) y {operator}
({operador}), respectivamente.
d. Elija Test.
e. El resultado debe tener el siguiente aspecto:

106
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

Este resultado de prueba muestra la salida original de la función de Lambda del backend, tal como se
ha pasado a través de la respuesta de integración sin asignación, ya que no hay ninguna plantilla de
asignación. 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.
28. 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.

a. Elija /calc/{operand1}/{operand2}/{operator}.
b. Elija GET.
c. Elija Method Execution (Ejecución del método).
d. Choose Method Response (Respuesta de método).

107
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

e. Expanda la respuesta 200,

f. En Response Body for 200 (Cuerpo de respuesta para 200), haga clic en el icono de lápiz situado
junto al modelo del tipo de contenido application/json.
g. En la lista desplegable Models (Modelos), elija Result.
h. Haga clic en el icono de marca de verificación para guardar la selección.

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.
29. Para crear la plantilla de asignación, haga lo siguiente:

a. Elija Method Execution (Ejecución del método).

b. Elija Integration Response (Respuesta de integración) y expanda la entrada de la respuesta del
método 200.
c. Expanda la sección Mapping Templates (Plantillas de asignación).
d. Elija application/json en la lista Content-Type.
e. Elija Result en la lista desplegable Generate template (Generar plantilla) para abrir el proyecto
de plantilla Result.
f. Cambie el proyecto de plantilla por el siguiente:

#set($inputRoot = $input.path('$'))
{
"input" : {
"a" : $inputRoot.a,
"b" : $inputRoot.b,
"op" : "$inputRoot.op"
},
"output" : {
"c" : $inputRoot.c
}
}

g. Seleccione Save.
30. Para probar la plantilla de asignación, haga lo siguiente:

a. Elija Method Execution (Ejecución del método).

b. Elija Test.
c. Escriba 1 2 y + en los campos de entrada operand1, operand2 y operator, respectivamente.

La respuesta de integración de la función de Lambda ahora se asigna a un objeto Result:

d. Elija Test (Prueba), y verá lo siguiente en Response Body (Cuerpo de respuesta) en la consola:

{
"input": {
"a": 1,
"b": 2,
"op": "+"
},
"output": {
"c": 3
}
}

108
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

31. En este punto la API solo se puede llamar a través de Test Invoke (Invocación de prueba) en la
consola de API Gateway. Para hacer que esté disponible para los clientes, se debe implementar tal y
como se indica a continuación:

a. Elija Deploy API (Implementar API) en el menú desplegable Actions (Acciones).

b. Elija [New Stage] ([Etapa nueva]) desde el menú desplegable Deployment Stage (Etapa de
implementación).
c. En Stage Name (Nombre de etapa), escriba test.
d. Elija Deploy (Implementar).
e. Anote la Invoke URL (URL de invocación) en la parte superior de la ventana de la consola. Puede
utilizar esto con herramientas como Postman y cURL para probar la API.

Note

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.

Definiciones de OpenAPI de una API de ejemplo integrada con

una función de Lambda
OpenAPI 2.0

{
"swagger": "2.0",
"info": {
"version": "2017-04-20T04:08:08Z",
"title": "LambdaCalc"
},
"host": "uojnr9hd57.execute-api.us-east-1.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/calc": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "operand2",
"in": "query",
"required": true,
"type": "string"
},
{
"name": "operator",
"in": "query",
"required": true,
"type": "string"
},
{

109
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

"name": "operand1",
"in": "query",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Result"
},
"headers": {
"operand_1": {
"type": "string"
},
"operand_2": {
"type": "string"
},
"operator": {
"type": "string"
}
}
}
},
"x-amazon-apigateway-request-validator": "Validate query string parameters and
headers",
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.operator": "integration.response.body.op",
"method.response.header.operand_2": "integration.response.body.b",
"method.response.header.operand_1": "integration.response.body.a"
},
"responseTemplates": {
"application/json": "#set($res = $input.path('$'))\n{\n \"result\":
\"$res.a, $res.b, $res.op => $res.c\",\n \"a\" : \"$res.a\",\n \"b\" : \"$res.b\",\n
\"op\" : \"$res.op\",\n \"c\" : \"$res.c\"\n}"
}
}
},
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/
arn:aws:lambda:us-west-2:123456789012:function:Calc/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"a\": \"$input.params('operand1')\",\n \"b
\": \"$input.params('operand2')\", \n \"op\": \"$input.params('operator')\" \n}"
},
"type": "aws"
}
},
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "Input",

110
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

"required": true,
"schema": {
"$ref": "#/definitions/Input"
}
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Result"
}
}
},
"x-amazon-apigateway-request-validator": "Validate body",
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"default": {
"statusCode": "200",
"responseTemplates": {
"application/json": "#set($inputRoot = $input.path('$'))\n{\n \"a
\" : $inputRoot.a,\n \"b\" : $inputRoot.b,\n \"op\" : $inputRoot.op,\n \"c\" :
$inputRoot.c\n}"
}
}
},
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/
arn:aws:lambda:us-west-2:123456789012:function:Calc/invocations",
"passthroughBehavior": "when_no_templates",
"httpMethod": "POST",
"type": "aws"
}
}
},
"/calc/{operand1}/{operand2}/{operator}": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "operand2",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "operator",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "operand1",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",

111
 Amazon API Gateway Guía del desarrollador
Tutorial: API Calc con tres integraciones

"schema": {
"$ref": "#/definitions/Result"
}
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"default": {
"statusCode": "200",
"responseTemplates": {
"application/json": "#set($inputRoot = $input.path('$'))\n{\n
\"input\" : {\n \"a\" : $inputRoot.a,\n \"b\" : $inputRoot.b,\n \"op\" :
\"$inputRoot.op\"\n },\n \"output\" : {\n \"c\" : $inputRoot.c\n }\n}"
}
}
},
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/
arn:aws:lambda:us-west-2:123456789012:function:Calc/invocations",
"passthroughBehavior": "when_no_templates",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"a\": \"$input.params('operand1')\",\n \"b\":
\"$input.params('operand2')\",\n \"op\": #if($input.params('operator')=='%2F')\"/
\"#{else}\"$input.params('operator')\"#end\n \n}"
},
"contentHandling": "CONVERT_TO_TEXT",
"type": "aws"
}
}
}
},
"definitions": {
"Input": {
"type": "object",
"required": [
"a",
"b",
"op"
],
"properties": {
"a": {
"type": "number"
},
"b": {
"type": "number"
},
"op": {
"type": "string",
"description": "binary op of ['+', 'add', '-', 'sub', '*', 'mul', '%2F',
'div']"
}
},
"title": "Input"
},
"Output": {
"type": "object",
"properties": {
"c": {
"type": "number"
}
},
"title": "Output"
},
"Result": {
"type": "object",

112
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

"properties": {
"input": {
"$ref": "#/definitions/Input"
},
"output": {
"$ref": "#/definitions/Output"
}
},
"title": "Result"
}
},
"x-amazon-apigateway-request-validators": {
"Validate body": {
"validateRequestParameters": false,
"validateRequestBody": true
},
"Validate query string parameters and headers": {
"validateRequestParameters": true,
"validateRequestBody": false
}
}
}

Tutorial: Crear una API de REST como proxy de

Amazon S3 en API Gateway
Para ilustrar cómo usar una API de REST en API Gateway como proxy de Amazon S3, en esta sección se
describe cómo crear y configurar una API de REST para exponer las siguientes operaciones de Amazon
S3:

• Exponer GET en el recurso raíz de la API para enumerar todos los buckets de Amazon S3 de un
intermediario.
• Exponer GET en un recurso de carpeta para ver una lista de todos los objetos de un bucket de Amazon
S3.
• Exponer PUT en un recurso de carpeta para agregar un bucket a Amazon S3.
• Exponer DELETE en un recurso de carpeta para eliminar un bucket de Amazon S3.
• Exponer GET en un recurso de carpeta o elemento para ver o descargar un objeto de un bucket de
Amazon S3.
• Exponer PUT en un recurso de carpeta o elemento para cargar un objeto en un bucket de Amazon S3.
• Exponer HEAD en un recurso de carpeta o elemento para obtener los metadatos de objeto en un bucket
de Amazon S3.
• Exponer DELETE en un recurso de carpeta o elemento para eliminar un objeto de un bucket de Amazon
S3.

Note

Para integrar su API de API Gateway con Amazon S3, debe elegir una región en la que
estén disponibles los servicios API Gateway y Amazon S3. Para obtener información sobre
la disponibilidad en función de la región, consulte Cuotas y puntos de enlace de Amazon API
Gateway.

Es posible que desee importar la API de ejemplo como proxy de Amazon S3, tal y como se muestra
en Definiciones de OpenAPI de la API de ejemplo como proxy de Amazon S3 (p. 130). Para obtener

113
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

instrucciones sobre cómo importar una API mediante la definición de OpenAPI, consulte Configuración de
una API de REST mediante OpenAPI (p. 500).

Para utilizar la consola de API Gateway para crear la API, primero debe registrarse para obtener una
cuenta de AWS.

Si no dispone de una cuenta de AWS, siga estos pasos para crear una.

Para inscribirse en una cuenta de AWS

1. Abra https://portal.aws.amazon.com/billing/signup.
2. Siga las instrucciones en línea.

Parte del procedimiento de inscripción consiste en recibir una llamada telefónica e indicar un código de
verificación en el teclado del teléfono.

Temas
• Configurar permisos de IAM para que la API invoque acciones de Amazon S3 (p. 114)
• Crear recursos de API para representar recursos de Amazon S3 (p. 115)
• Exponer un método de API para enumerar los buckets de Amazon S3 del intermediario (p. 116)
• Exponer métodos de API para tener acceso a un bucket de Amazon S3 (p. 122)
• Exponer métodos de API para tener acceso a un objeto de Amazon S3 en un bucket (p. 125)
• Llamar a la API mediante un cliente API de REST (p. 128)
• Definiciones de OpenAPI de la API de ejemplo como proxy de Amazon S3 (p. 130)

Configurar permisos de IAM para que la API invoque acciones de

Amazon S3
Para permitir que la API invoque las acciones de Amazon S3 necesarias, debe tener las políticas de IAM
adecuadas asociadas a un rol de IAM. En la siguiente sección se describe cómo verificar y crear, si es
necesario, el rol y las políticas de IAM necesarios.

Para que la API vea o muestre buckets y objetos de Amazon S3, puede utilizar la política
AmazonS3ReadOnlyAccess proporcionada por IAM en el rol de IAM. El ARN de esta política es
arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess, tal y como se muestra a continuación:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:Get*",
"s3:List*"
],
"Resource": "*"
}
]
}

Este documento de política establece que cualquiera de las acciones Get* y List* de Amazon S3 se
puede invocar en cualquiera de los recursos de Amazon S3.

Para que la API actualice los buckets y los objetos de Amazon S3, puede utilizar una política personalizada
para cualquiera de las acciones Put* de Amazon S3, tal y como se muestra a continuación:

114
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:Put*",
"Resource": "*"
}
]
}

Para que la API funcione con las acciones Get*, List* y Put* de Amazon S3, puede agregar las
políticas de solo lectura y solo inserción anteriores al rol de IAM.

Para que la API invoque las acciones Post* de Amazon S3, debe utilizar una política Allow para las
acciones s3:Post* en el rol de IAM. Para obtener una lista completa de las acciones de Amazon S3,
consulte el tema sobre especificar permisos de Amazon S3 en una política.

Para que la API cree, vea, actualice y elimine buckets y objetos en Amazon S3, puede utilizar la política
AmazonS3FullAccess proporcionada por IAM en el rol de IAM. El ARN es arn:aws:iam::aws:policy/
AmazonS3FullAccess.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "*"
}
]
}

Después de haber elegido las políticas de IAM que desea utilizar, cree un rol de IAM y asócielo a las
políticas. El rol de IAM resultante debe contener la siguiente política de confianza para que API Gateway
asuma este rol en el tiempo de ejecución.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}

Cuando utilice la consola de IAM para crear el rol, elija el tipo de rol de Amazon API Gateway para
garantizar que esta política de confianza se incluya automáticamente.

Crear recursos de API para representar recursos de Amazon S3

Utilizaremos el recurso raíz (/) de la API como contenedor de buckets de Amazon S3 de un intermediario
autenticado. También crearemos los recursos Folder y Item para representar un bucket de Amazon

115
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

S3 determinado y un objeto de Amazon S3 determinado, respectivamente. El intermediario especificará

el nombre de carpeta y la clave de objeto en forma de parámetros de ruta como parte de la URL de una
solicitud.
Note

Al acceder a los objetos cuya clave de objeto incluye / o cualquier otro carácter especial, el
carácter estar codificado en la URL. Por ejemplo, test/test.txt deben codificarse en test
%2Ftest.txt.

Para crear un recurso de API que exponga las características del servicio Amazon S3

1. En la consola de API Gateway, cree una API denominada myS3. Este recurso raíz de la API (/)
representa el servicio Amazon S3.
2. En el recurso raíz de la API, cree un recurso secundario denominado Folder (Carpeta) y establezca el
elemento Resource Path (Ruta del recurso) necesario en /{folder}.
3. Para el recurso Folder (Carpeta) de la API, cree un recurso secundario Item (Elemento). Establezca el
elemento Resource Path (Ruta del recurso) necesario en /{item}.

Exponer un método de API para enumerar los buckets de

Amazon S3 del intermediario
Obtener la lista de buckets de Amazon S3 del intermediario implica invocar la acción GET Service en
Amazon S3. En el recurso raíz de la API, (/), cree el método GET. Configure el método GET para realizar
la integración con Amazon S3, tal y como se indica a continuación.

Para crear e inicializar el método GET / de la API

1. Elija Create method (Crear método) en el nodo raíz (/) desde el menú desplegable Actions (Acciones)
en la esquina superior derecha del panel Resources (Recursos).
2. Elija GET en la lista desplegable de verbos HTTP y haga clic en el icono de marca de verificación para
empezar a crear el método.

116
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

3. En el panel / - GET - Setup, elija AWS Service (Servicio de AWS) en Integration type (Tipo de
integración).
4. Elija una región de la lista (por ejemplo, us-west-2) en AWS Region (Región de AWS).
5. En AWS Service (Servicio de AWS), elija S3.
6. Deje en blanco AWS Subdomain (Subdominio de AWS).
7. En HTTP method (Método HTTP), elija GET.
8. En Action Type (Tipo de acción), elija Use path override (Usar invalidación de ruta). Al anular la ruta,
API Gateway reenvía la solicitud del cliente a Amazon S3 como la solicitud del tipo de ruta de la API
de REST de Amazon S3 correspondiente, en la cual un recurso de Amazon S3 se expresa por la ruta
de recursos del patrón s3-host-name/bucket/key. API Gateway establece el s3-host-name y
transmite el bucket y la key especificados por el cliente a Amazon S3.
9. (Opcional) En Path override (Invalidación de ruta) escriba /.
10. Copie el ARN del rol de IAM creado anteriormente (desde la consola de IAM) y péguelo en Execution
role (Rol de ejecución).
11. Deje el resto de la configuración de forma predeterminada.
12. Elija Save (Guardar) para terminar de configurar este método.

Esta configuración integra la solicitud GET https://your-api-host/stage/ del frontend con la

solicitud GET https://your-s3-host/ del backend.
Note

Tras la configuración inicial, puede modificar estos ajustes en la página Integration Request
(Solicitud de integración) del método.

Para controlar quién puede llamar a este método de nuestra API, activamos la marca de autorización del
método y la establecemos en AWS_IAM.

Para permitir que IAM controle el acceso al método GET /

1. En Method Execution (Ejecución del método), elija Method Request (Solicitud de método).
2. Haga clic en el icono del lápiz que aparece junto a Authorization (Autorización)
3. Elija AWS_IAM en la lista desplegable.
4. Haga clic en el icono de marca de verificación para guardar la configuración.

117
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

Para que nuestra API devuelva respuestas correctas y excepciones al intermediario, vamos a declarar
las respuestas 200, 400 y 500 en Method Response (Respuesta de método). Utilizamos el mapeo
predeterminado para las respuestas 200, de forma que las respuestas del backend del código de estado
no declarado aquí se devuelvan al intermediario como respuestas 200.

Para declarar tipos de respuestas para el método GET /

1. En el panel Method Execution (Ejecución del método), elija el cuadro Method Response (Respuesta
de método). API Gateway declara la respuesta 200 de forma predeterminada.
2. Elija Add response (Añadir respuesta), escriba 400 en el cuadro de texto de entrada y elija la marca
de verificación para completar la declaración.
3. Repita el paso anterior para declarar el tipo de respuesta 500. Esta será la configuración final:

Como la respuesta de integración correcta de Amazon S3 devuelve la lista de buckets como una carga
XML y la respuesta de método predeterminada de API Gateway devuelve una carga JSON, debemos
mapear el valor del parámetro del encabezado Content-Type del backend con su homólogo en el frontend.
De lo contrario, el cliente recibirá application/json para el tipo de contenido cuando el cuerpo de

118
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

la respuesta sea en realidad una cadena XML. El siguiente procedimiento muestra cómo realizar esta
configuración. Además, también queremos mostrar al cliente otros parámetros de encabezado, como Date
y Content-Length.

Para configurar asignaciones de encabezado de respuesta para el método GET /

1. En la consola de API Gateway, elija Method Response (Respuesta del método). Añada el encabezado
Content-Type para el tipo de respuesta 200.

2. En Integration Response (Respuesta de integración), para Content-Type, escriba

integration.response.header.Content-Type para la respuesta del método.

119
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

Con los mapeos de encabezado anteriores, API Gateway traducirá el encabezado Date del backend
al encabezado Timestamp para el cliente.
3. En Integration Response (Respuesta de integración), elija Add integration response (Añadir respuesta
de integración), escriba una expresión regular adecuada en el cuadro de texto HTTP status regex
(Expresión regular de estado de HTTP) para otro estado de respuesta de método. Repita este
procedimiento hasta que se cubran todos los estados de respuesta de método.

120
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

Como práctica recomendada, vamos a probar nuestra API tal y como está configurada de momento.

Probar el método GET en el recurso raíz de la API

1. Vuelva a Method Execution (Ejecución del método), elija Test (Probar) en el cuadro Client (Cliente).
2. Elija Test (Probar) en el panel GET / - Method Test (GET / - Prueba de método). A continuación se
muestra un resultado de ejemplo.

121
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

Note
Para utilizar la consola de API Gateway para probar la API como proxy de Amazon S3, asegúrese
de que el bucket de S3 de destino procede de una región diferente de la región de la API. De lo
contrario, es posible que obtenga una respuesta 500 Internal Server Error. Esta limitación no se
aplica a las API implementadas.

Exponer métodos de API para tener acceso a un bucket de

Amazon S3
Para trabajar con un bucket de Amazon S3, exponemos los métodos GET, PUT y DELETE en el recurso /
{folder} para mostrar los objetos de un bucket, crear un nuevo bucket y eliminar un bucket existente.
Las instrucciones son similares a las que se describen en Exponer un método de API para enumerar los
buckets de Amazon S3 del intermediario (p. 116). En las siguientes explicaciones, describimos las tareas
generales y resaltamos las diferencias pertinentes.

Para exponer métodos GET, PUT y DELETE en un recurso de carpeta

1. En el nodo /{folder} del árbol Resources (Recursos), cree los métodos DELETE, GET y PUT, uno cada
vez.

122
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

2. Configure la integración inicial de cada método creado con sus puntos de enlace de Amazon S3
correspondientes. En la siguiente captura de pantalla se ilustra esta configuración para el método
PUT /{folder}. Para los métodos DELETE /{folder} y GET /{folder}, reemplace el valor de
PUT de HTTP method (Método HTTP) por DELETE y GET, respectivamente.

Observe que hemos usado el parámetro de ruta {bucket} en las direcciones URL del punto de
enlace de Amazon S3 para especificar el bucket. Necesitaremos asignar el parámetro de ruta
{folder} de las solicitudes de método al parámetro de ruta {bucket} de las solicitudes de
integración.
3. Para asignar {folder} a {bucket}:

a. Elija Method Execution (Ejecución del método) y, a continuación, Integration Request (Solicitud de
integración).
b. Expanda URL Path Parameters (Parámetros de la ruta URL) y elija Add path (Añadir ruta)
c. Escriba bucket en la columna Name (Nombre) y method.request.path.folder en la
columna Mapped from (Asignado desde). Haga clic en el icono de marca de verificación para
guardar la asignación.

123
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

4. En Method Request (Solicitud de método), añada Content-Type a la sección HTTP Request

Headers (Encabezados de solicitud HTTP).

Esto es necesario sobre todo para las pruebas, cuando se utiliza la consola de API Gateway y hay que
especificar application/xml para una carga XML.
5. En Integration Request (Solicitud de integración), configure los siguientes mapeos de encabezado, de
acuerdo con las instrucciones descritas en Exponer un método de API para enumerar los buckets de
Amazon S3 del intermediario (p. 116).

El encabezado x-amz-acl es para especificar el control de acceso en la carpeta (o el bucket de

Amazon S3 correspondiente). Para obtener más información, consulte el tema sobre la solicitud de
bucket PUT de Amazon S3.
6. Para probar el método PUT, elija Test (Probar) en el cuadro Client (Cliente) en Method Execution
(Ejecución del método) y escriba lo siguiente como entrada para las pruebas:

a. En folder (carpeta), escriba el nombre de un bucket.

b. En el encabezado Content-Type, escriba application/xml.
c. En Request Body (Cuerpo de la solicitud), proporcione la región del bucket como la restricción de
ubicación, declarada en un fragmento XML como la solicitud de carga. Por ejemplo,

<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<LocationConstraint>{region}</LocationConstraint>
</CreateBucketConfiguration>

124
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

7. Repita los pasos anteriores para crear y configurar el método GET Y DELETE en el recurso /{folder}
de la API.

Los ejemplos anteriores ilustran cómo crear un nuevo bucket en la región especificada para ver la lista
de objetos del bucket y para eliminar el bucket. Otras operaciones de bucket de Amazon S3 le permiten
trabajar con los metadatos o las propiedades del bucket. Por ejemplo, puede configurar la API para que
llame a la acción PUT /?notification de Amazon S3 para configurar notificaciones en el bucket, para que
llame a PUT /?acl para definir una lista de control de acceso en el bucket, etc. La configuración de la API
es similar, con la excepción de que debe agregar los parámetros de consulta adecuados a las direcciones
URL del punto de enlace de Amazon S3. En tiempo de ejecución, debemos proporcionar la carga XML
correspondiente a la solicitud del método. Lo mismo ocurre con las otras operaciones GET y DELETE
en un bucket de Amazon S3. Para obtener información sobre las posibles acciones de Amazon S3 en un
bucket, consulte el tema sobre operaciones de Amazon S3 en buckets.

Exponer métodos de API para tener acceso a un objeto de

Amazon S3 en un bucket
Amazon S3 admite las acciones GET, DELETE, HEAD, OPTIONS, POST y PUT para acceder a objetos de
un bucket determinado y administrarlos. Para ver la lista completa de acciones admitidas, consulte el tema
sobre operaciones de Amazon S3 en objetos.

En este tutorial, exponemos la operación PUT Object, la operación GET Object, la operación HEAD
Object y la operación DELETE Object a través de los métodos de API PUT /{folder}/{item}, GET /
{folder}/{item}, HEAD /{folder}/{item} y DELETE /{folder}/{item}, respectivamente.

Las configuraciones de API para los métodos PUT, GET y DELETE en /{folder}/{item} son similares
a las de /{folder}, como se indica en Exponer métodos de API para tener acceso a un bucket de
Amazon S3 (p. 122). Una gran diferencia es que la ruta de la solicitud relacionada con un objeto tiene un
parámetro de ruta adicional de {item} y este parámetro de ruta debe estar asignado al parámetro de ruta
de solicitud de integración de {object}.

125
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

Lo mismo sucede con los métodos GET y DELETE.

A modo de ilustración, la siguiente captura de pantalla muestra el resultado cuando se prueba el método
GET en un recurso de {folder}/{item} mediante la consola de API Gateway. La solicitud devuelve
correctamente el texto sin formato (Welcome to README.txt) como el contenido del archivo especificado
(README.txt) en el bucket de Amazon S3 indicado (apig-demo).

126
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

Para descargar o cargar archivos binarios, que en API Gateway se considera cualquier cosa que no sea
contenido JSON codificado en UTF-8, es necesaria una configuración adicional de la API. Esto se detalla
de la siguiente manera:

Descargar o cargar archivos binarios de S3

1. Registrar los tipos de archivo del archivo afectado en los tipos "binaryMediaTypes" de la API. Puede
hacer lo siguiente en la consola:

a. Elija Settings (Configuración) para la API.

b. En Binary Media Types (Tipos de medios binarios), elija Add Binary Media Type (Agregar tipo de
medios binarios).
c. Escriba el tipo de medios requerido, por ejemplo, image/png.
d. Elija Save Changes (Guardar cambios), para guardar la configuración.
2. Añada las cabeceras Content-Type (para cargar) y/o Accept (para descargar) a la solicitud del
método para exigir que el cliente especifique el tipo de medios binarios necesarios y asignarlos a la
solicitud de integración.
3. Establezca la opción Content Handling (Tratamiento de contenido) en Passthrough en la solicitud de
integración (para cargar) y en una respuesta de integración (para descargar). Asegúrese de que no se
define ninguna plantilla de mapeo para el tipo de contenido afectado. Para obtener más información,

127
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

consulte Comportamiento del acceso directo a la integración (p. 424) y Seleccionar una plantilla de
asignación VTL (p. 423).

El límite de tamaño de carga es 10 MB. Consulte Cuotas de Amazon para configurar y ejecutar una API
REST (p. 843).

Asegúrese de que los archivos en Amazon S3 incluyen los tipos de contenido correctos en los metadatos.
Para contenido multimedia que se puede transmitir, es posible que los metadatos deban incluir Content-
Disposition:inline.

Para obtener más información sobre la compatibilidad con datos binarios en API Gateway, consulte
Conversiones de tipo de contenido en API Gateway (p. 454).

Llamar a la API mediante un cliente API de REST

Para proporcionar un tutorial completo, ahora mostraremos cómo llamar a la API mediante Postman, que
admite la autorización de IAM de AWS.

Para llamar a nuestra API de proxy de Amazon S3 mediante Postman

1. Implemente o vuelva a implementar la API. Anote la URL base de la API que se muestra junto a
Invoke URL (URL de invocación) en la parte superior de Stage Editor (Editor de etapas).
2. Inicie Postman.
3. Elija Authorization (Autorización) y, a continuación, elija AWS Signature. Escriba el ID de clave
de acceso y la clave de acceso secreta del usuario de IAM en los campos de entrada AccessKey
y SecretKey, respectivamente. Especifique la región de AWS en la que va a implementar la API en
el cuadro de texto AWS Region (Región de AWS). Escriba execute-api en el campo de entrada
Service Name (Nombre del servicio).

Puede crear un par de claves desde la pestaña Security Credentials (Credenciales de seguridad) de
su cuenta de usuario de IAM en la consola de administración de IAM.
4. Para agregar un bucket denominado apig-demo-5 a su cuenta de Amazon S3 en la región
{region}:
Note
Asegúrese de que el nombre de bucket sea único de forma global.

a. Seleccione PUT en la lista desplegable de métodos y escriba la URL del método (https://api-
id.execute-api.aws-region.amazonaws.com/stage/folder-name)
b. Establezca el valor del encabezado Content-Type en application/xml. Es posible que
necesite eliminar todos los encabezados existentes antes de configurar el tipo de contenido.
c. Elija el elemento de menú Body (Cuerpo) y escriba el siguiente fragmento XML como cuerpo de la
solicitud:

<CreateBucketConfiguration>
<LocationConstraint>{region}</LocationConstraint>
</CreateBucketConfiguration>

d. Elija Send (Enviar) para enviar la solicitud. Si todo va bien, debería recibir una respuesta 200 OK
con una carga vacía.
5. Para añadir un archivo de texto a un bucket, siga las instrucciones anteriores. Si especifica el nombre
de bucket de apig-demo-5 para {folder} y el nombre de archivo Readme.txt para {item} en la
dirección URL y proporciona la cadena de texto Hello, World! como contenido de archivo (con lo
que se convierte en la carga de la solicitud), la respuesta será

PUT /S3/apig-demo-5/Readme.txt HTTP/1.1

128
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

Host: 9gn28ca086.execute-api.{region}.amazonaws.com
Content-Type: application/xml
X-Amz-Date: 20161015T062647Z
Authorization: AWS4-HMAC-SHA256 Credential=access-key-id/20161015/{region}/execute-
api/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date,
Signature=ccadb877bdb0d395ca38cc47e18a0d76bb5eaf17007d11e40bf6fb63d28c705b
Cache-Control: no-cache
Postman-Token: 6135d315-9cc4-8af8-1757-90871d00847e

Hello, World!

Si todo sale bien, debe recibir una respuesta 200 OK con una carga vacía.
6. Para obtener el contenido del archivo Readme.txt que acaba de añadir al bucket apig-demo-5,
envíe una solicitud GET como la siguiente:

GET /S3/apig-demo-5/Readme.txt HTTP/1.1

Host: 9gn28ca086.execute-api.{region}.amazonaws.com
Content-Type: application/xml
X-Amz-Date: 20161015T063759Z
Authorization: AWS4-HMAC-SHA256 Credential=access-key-id/20161015/{region}/
execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date,
Signature=ba09b72b585acf0e578e6ad02555c00e24b420b59025bc7bb8d3f7aed1471339
Cache-Control: no-cache
Postman-Token: d60fcb59-d335-52f7-0025-5bd96928098a

Si todo sale bien, debe recibir una respuesta 200 OK con la cadena de texto Hello, World! como
la carga.
7. Para mostrar los elementos del bucket apig-demo-5, envíe la siguiente solicitud:

GET /S3/apig-demo-5 HTTP/1.1

Host: 9gn28ca086.execute-api.{region}.amazonaws.com
Content-Type: application/xml
X-Amz-Date: 20161015T064324Z
Authorization: AWS4-HMAC-SHA256 Credential=access-key-id/20161015/{region}/
execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date,
Signature=4ac9bd4574a14e01568134fd16814534d9951649d3a22b3b0db9f1f5cd4dd0ac
Cache-Control: no-cache
Postman-Token: 9c43020a-966f-61e1-81af-4c49ad8d1392

Si todo sale bien, debe recibir una respuesta 200 OK con una carga XML que muestre un único
elemento en el bucket especificado, a menos que haya añadido más archivos al bucket antes de
enviar esta solicitud.

<?xml version="1.0" encoding="UTF-8"?>

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>apig-demo-5</Name>
<Prefix></Prefix>
<Marker></Marker>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>Readme.txt</Key>
<LastModified>2016-10-15T06:26:48.000Z</LastModified>
<ETag>"65a8e27d8879283831b664bd8b7f0ad4"</ETag>
<Size>13</Size>
<Owner>
<ID>06e4b09e9d...603addd12ee</ID>
<DisplayName>user-name</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>

129
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

</Contents>
</ListBucketResult>

Note

Para cargar o descargar una imagen, debe configurar el tratamiento de contenido como
CONVERT_TO_BINARY.

Definiciones de OpenAPI de la API de ejemplo como proxy de

Amazon S3
Las siguientes definiciones de OpenAPI describen la API de ejemplo, utilizada en este tutorial, como proxy
de Amazon S3.

OpenAPI 2.0

{
"swagger": "2.0",
"info": {
"version": "2016-10-13T23:04:43Z",
"title": "MyS3"
},
"host": "9gn28ca086.execute-api.{region}.amazonaws.com",
"basePath": "/S3",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Timestamp": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []

130
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type",
"method.response.header.Content-Length":
"integration.response.header.Content-Length",
"method.response.header.Timestamp": "integration.response.header.Date"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"uri": "arn:aws:apigateway:us-west-2:s3:path//",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
}
},
"/{folder}": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Date": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}

131
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type",
"method.response.header.Date": "integration.response.header.Date",
"method.response.header.Content-Length":
"integration.response.header.content-length"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.bucket": "method.request.path.folder"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "Content-Type",
"in": "header",
"required": false,
"type": "string"
},
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Content-Type": {
"type": "string"
}

132
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type",
"method.response.header.Content-Length":
"integration.response.header.Content-Length"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.header.x-amz-acl": "'authenticated-read'",
"integration.request.path.bucket": "method.request.path.folder",
"integration.request.header.Content-Type": "method.request.header.Content-
Type"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws"
}
},
"delete": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Date": {
"type": "string"

133
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type",
"method.response.header.Date": "integration.response.header.Date"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.bucket": "method.request.path.folder"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}",
"passthroughBehavior": "when_no_match",
"httpMethod": "DELETE",
"type": "aws"
}
}
},
"/{folder}/{item}": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "item",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {

134
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"content-type": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.content-type":
"integration.response.header.content-type",
"method.response.header.Content-Type":
"integration.response.header.Content-Type"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.object": "method.request.path.item",
"integration.request.path.bucket": "method.request.path.folder"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"head": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "item",
"in": "path",
"required": true,
"type": "string"
},

135
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type",
"method.response.header.Content-Length":
"integration.response.header.Content-Length"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.object": "method.request.path.item",
"integration.request.path.bucket": "method.request.path.folder"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"passthroughBehavior": "when_no_match",
"httpMethod": "HEAD",
"type": "aws"
}
},
"put": {
"produces": [
"application/json"

136
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

],
"parameters": [
{
"name": "Content-Type",
"in": "header",
"required": false,
"type": "string"
},
{
"name": "item",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type",
"method.response.header.Content-Length":
"integration.response.header.Content-Length"
}
},
"5\\d{2}": {
"statusCode": "500"
}

137
 Amazon API Gateway Guía del desarrollador
Tutorial: Crear una API de REST como
proxy de Amazon S3 en API Gateway

},
"requestParameters": {
"integration.request.path.object": "method.request.path.item",
"integration.request.header.x-amz-acl": "'authenticated-read'",
"integration.request.path.bucket": "method.request.path.folder",
"integration.request.header.Content-Type": "method.request.header.Content-
Type"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws"
}
},
"delete": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "item",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {

138
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"statusCode": "200"
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.object": "method.request.path.item",
"integration.request.path.bucket": "method.request.path.folder"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"passthroughBehavior": "when_no_match",
"httpMethod": "DELETE",
"type": "aws"
}
}
}
},
"securityDefinitions": {
"sigv4": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "awsSigv4"
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}

Tutorial: Creación de una API de REST como proxy de

Amazon Kinesis en API Gateway
Esta página describe cómo crear y configurar una API de REST con una integración del tipo AWS para
tener acceso a Kinesis.
Note

Para integrar la API de API Gateway con Kinesis, debe elegir una región en la que estén
disponibles los servicios API Gateway y Kinesis. Para conocer la disponibilidad de las regiones,
consulte Puntos de enlace y cuotas de servicio.

A modo de ejemplo, crearemos una API de ejemplo para permitir que un cliente haga lo siguiente:

1. Listado de los flujos disponibles para el usuario en Kinesis

2. Creación, descripción o eliminación de un flujo especificado
3. Leer registros de datos o escribir registros de datos en un flujo especificado

Para realizar las tareas anteriores, la API expone métodos en diferentes recursos para invocar lo siguiente,
respectivamente:

1. La acción ListStreams en Kinesis

2. La acción CreateStream, DescribeStream o DeleteStream

139
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

3. La acción GetRecords o PutRecords (incluida la acción PutRecord) en Kinesis

En concreto, crearemos la API mediante las operaciones siguientes:

• Exponer un método HTTP GET en el recurso /streams de la API e integrar el método con la acción
ListStreams de Kinesis para mostrar los flujos de la cuenta del intermediario.
• Exponer un método HTTP POST en el recurso /streams/{stream-name} de la API e integrar
el método con la acción CreateStream de Kinesis para crear un flujo con nombre en la cuenta del
intermediario.
• Exponer un método HTTP GET en el recurso /streams/{stream-name} de la API e integrar el
método con la acción DescribeStream de Kinesis para describir un flujo con nombre en la cuenta del
intermediario.
• Exponer un método HTTP DELETE en el recurso /streams/{stream-name} de la API e integrar el
método con la acción DeleteStream de Kinesis para eliminar un flujo en la cuenta del intermediario.
• Exponer un método PUT HTTP en el recurso /streams/{stream-name}/record de la API e integrar
el método con la acción PutRecord de Kinesis. Esto permite que el cliente añada un solo registro de
datos al flujo con nombre.
• Exponer un método PUT HTTP en el recurso /streams/{stream-name}/records de la API e
integrar el método con la acción PutRecords de Kinesis. Esto permite que el cliente añada una lista de
registros de datos al flujo con nombre.
• Exponer un método GET HTTP en el recurso /streams/{stream-name}/records de la API e
integrar el método con la acción GetRecords de Kinesis. Esto permite que el cliente muestre registros
de datos en el flujo con nombre, con un iterador de fragmento especificado. Un iterador de fragmento
especifica la posición del fragmento desde la que se empiezan a leer los registros de datos de forma
secuencial.
• Exponer un método GET HTTP en el recurso /streams/{stream-name}/sharditerator de
la API e integrar el método con la acción GetShardIterator de Kinesis. Este método auxiliar debe
proporcionarse en la acción ListStreams de Kinesis.

Puede aplicar las instrucciones que se presentan aquí a otras acciones de Kinesis. Para obtener la lista
completa de las acciones de Kinesis, consulte Referencia de API de Amazon Kinesis.

En lugar de utilizar la consola de API Gateway para crear la API de ejemplo, puede importar la
API de ejemplo en API Gateway mediante la API de importación de API Gateway. Para obtener
información acerca de cómo utilizar Import API, consulte Configuración de una API de REST mediante
OpenAPI (p. 500).

Si no dispone de una cuenta de AWS, siga estos pasos para crear una.

Para inscribirse en una cuenta de AWS

1. Abra https://portal.aws.amazon.com/billing/signup.
2. Siga las instrucciones en línea.

Parte del procedimiento de inscripción consiste en recibir una llamada telefónica e indicar un código de
verificación en el teclado del teléfono.

Creación de un rol y una política de IAM para que la API tenga

acceso a Kinesis
Para permitir que la API invoque las acciones de Kinesis necesarias, debe tener las políticas de IAM
adecuadas asociadas a un rol de IAM. En esta sección se explica cómo verificar y crear, si es necesario, el
rol y las políticas de IAM necesarios.

140
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

Para habilitar el acceso de solo lectura a Kinesis, puede utilizar la política AmazonKinesisReadOnlyAccess
que permite invocar las acciones Get*, List* y Describe* de Kinesis.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesis:Get*",
"kinesis:List*",
"kinesis:Describe*"
],
"Resource": "*"
}
]
}

Esta política está disponible como una política administrada aprovisionada por IAM y su ARN es
arn:aws:iam::aws:policy/AmazonKinesisReadOnlyAccess.

Para permitir acciones de lectura y escritura en Kinesis, puede utilizar la política

AmazonKinesisFullAccess.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "kinesis:*",
"Resource": "*"
}
]
}

Esta política también está disponible como una política administrada aprovisionada por IAM. Su ARN es
arn:aws:iam::aws:policy/AmazonKinesisFullAccess.

Después de decidir qué política IAM va a utilizar, asóciela a un rol de IAM nuevo o existente. Asegúrese de
que el servicio de control de API Gateway (apigateway.amazonaws.com) es una entidad de confianza
del rol y tiene permiso para asumir el rol de ejecución (sts:AssumeRole).

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}

141
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

Si crea el rol de ejecución en la consola de IAM y elige el tipo de rol Amazon API Gateway, esta política de
confianza se asocia automáticamente.

Anote el ARN del rol de ejecución. Lo necesitará cuando cree un método de API y configure su solicitud de
integración.

Inicio de la creación de una API como proxy de Kinesis

Utilice los siguientes pasos para crear la API en la consola de API Gateway.

Para crear una API como un proxy de servicio de AWS para Kinesis

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. 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).
3. Elija New API (Nueva API).
4. En API name (Nombre de la API), escriba KinesisProxy. Deje los valores predeterminados en el
resto de los campos.
5. Escriba una descripción en Description (Descripción) si lo desea.
6. Seleccione Create API (Crear API).

Una vez creada la API, la consola de API Gateway mostrará la página Resources (Recursos), que contiene
únicamente el recurso raíz de la API (/).

Lista de flujos en Kinesis

Kinesis es compatible con la acción ListStreams con la siguiente llamada a la API de REST:

POST /?Action=ListStreams HTTP/1.1

Host: kinesis.<region>.<domain>
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Authorization: <AuthParams>
X-Amz-Date: <Date>

{
...
}

En la anterior solicitud de API de REST, la acción se especifica en el parámetro de consulta Action.

También puede, en su lugar, especificar la acción en un encabezado X-Amz-Target:

POST / HTTP/1.1
Host: kinesis.<region>.<domain>
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Authorization: <AuthParams>
X-Amz-Date: <Date>
X-Amz-Target: Kinesis_20131202.ListStreams

142
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

{
...
}

En este tutorial usamos el parámetro de consulta para especificar la acción.

Para exponer una acción de Kinesis en la API, agregue un recurso /streams a la raíz de la API. A
continuación, defina un método GET en el recurso e integre el método en la acción ListStreams de
Kinesis.

En el siguiente procedimiento se describe cómo listar los flujos de Kinesis con la consola de API Gateway.

Para listar los flujos de Kinesis con la consola de API Gateway

1. Seleccione el recurso raíz de la API. En Actions (Acciones), elija Create Resource (Crear recurso).

En Resource Name (Nombre de recurso), escriba Streams, no modifique los valores predeterminados
del campo Resource Path (Ruta del recurso) o del resto y, a continuación, elija Create Resource
(Crear recurso).
2. Elija el recurso /Streams. En Actions (Acciones), elija Create Method (Crear método), elija GET en la
lista y, a continuación, haga clic en el icono de marca de verificación para terminar de crear el método.
Note

El verbo HTTP de un método invocado por un cliente puede ser diferente del verbo HTTP de
una integración requerida por el backend. Aquí elegimos GET porque mostrar los flujos es
intuitivamente una operación READ.
3. En el panel Setup (Configuración) del método, elija AWS Service (Servicio de AWS).

a. En AWS Region (Región de AWS), elija una región (por ejemplo, us-east-1).
b. En AWS Service (Servicio de AWS), elija Kinesis.
c. Deje AWS Subdomain (Subdominio de AWS) en blanco.
d. En HTTP method (Método HTTP), elija POST.
Note

Aquí elegimos POST porque Kinesis requiere que la acción ListStreams también se
invoque.
e. En Action Type, elija Use action name.
f. En Action, escriba ListStreams.
g. En Execution role (Rol de ejecución), escriba el ARN del rol de ejecución.
h. No modifique el valor predeterminado Passthrough (Acceso directo) del campo Content Handling
(Tratamiento de contenido).
i. Elija Save (Guardar) para finalizar la configuración inicial del método.

143
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

4. En el panel Integration Request (Solicitud de integración), expanda la sección HTTP Headers

(Encabezados HTTP):

a. Elija Add header (Añadir encabezado).

b. En la columna Name (Nombre), escriba Content-Type.
c. En la columna Mapped from (Asignado desde), escriba 'application/x-amz-json-1.1'.
d. Haga clic en el icono de marca de verificación para guardar la configuración.

Hemos utilizado un mapeo de parámetros de solicitud para definir el encabezado Content-Type en

el valor estático 'application/x-amz-json-1.1' para informar a Kinesis de que la entrada es
una versión específica de JSON.
5. Expanda la sección Mapping Templates (Plantillas de mapeo):

a. Elija Add mapping template (Añadir plantilla de asignación).

b. En Content-Type, escriba application/json.

144
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

c. Haga clic en el icono de marca de verificación para guardar la configuración Content-Type. Elija
Yes, secure this integration (Sí, proteger esta integración) en Change passthrough behavior
(Cambiar comportamiento de acceso directo).
d. Escriba {} en el editor de la plantilla.
e. Elija el botón Save (Guardar) para guardar la plantilla de asignación.

La solicitud ListStreams toma una carga con el siguiente formato JSON:

{
"ExclusiveStartStreamName": "string",
"Limit": number
}

Sin embargo, las propiedades son opcionales. Para utilizar los valores predeterminados, usamos aquí
una carga JSON vacía.

145
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

6. Pruebe el método GET en el recurso Streams para invocar la acción ListStreams en Kinesis:

En la consola de API Gateway, seleccione la entrada streams/GET en el panel Resources (Recursos),

elija la opción de invocación Test (Prueba) y, a continuación, elija Test (Prueba).

146
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

Si ya ha creado dos flujos llamados "myStream" y "yourStream" en Kinesis, la prueba, si se realiza

correctamente, devolverá una respuesta 200 OK con la siguiente carga:

{
"HasMoreStreams": false,
"StreamNames": [
"myStream",
"yourStream"
]
}

Creación, descripción y eliminación de un flujo en Kinesis

Crear, describir y eliminar un flujo en Kinesis implica realizar las siguientes solicitudes a la API de REST de
Kinesis, respectivamente:

POST /?Action=CreateStream HTTP/1.1

Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
"ShardCount": number,
"StreamName": "string"
}

POST /?Action=DescribeStream HTTP/1.1

Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
"ExclusiveStartShardId": "string",
"Limit": number,
"StreamName": "string"
}

POST /?Action=DeleteStream HTTP/1.1

Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
"StreamName":"string"
}

147
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

Podemos crear la API para que acepte la entrada necesaria como una carga JSON de una solicitud de
método y transmita la carga a la solicitud de integración. Sin embargo, para proporcionar más ejemplos
de mapeo de datos entre solicitudes de método e integración y respuestas de método e integración,
crearemos nuestra API de una forma ligeramente distinta.

Exponemos los métodos HTTP GET, POST y Delete HTTP en un recurso Stream al que se asignará
un nombre. Utilizamos la variable de ruta {stream-name} como marcador de posición del recurso
de flujo e integramos estos métodos de la API con las acciones DescribeStream, CreateStream y
DeleteStream de Kinesis respectivamente. Exigimos que el cliente pase otros datos de entrada como
encabezados, parámetros de consulta o la carga de una solicitud de método. Proporcionamos plantillas de
asignación para transformar los datos en la carga de solicitud de integración necesaria.

Para configurar y probar el método GET en un recurso de flujo

1. Cree un recurso secundario con la variable de ruta {stream-name} bajo el recurso /streams
creado con anterioridad.

2. Agregue los verbos HTTP POST, GET y DELETE a este recurso.

Después de crear los métodos en el recurso, la estructura de la API debe ser similar a la siguiente:

148
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

3. Configure el método GET /streams/{stream-name} para que llame a la acción POST /?

Action=DescribeStream en Kinesis, tal y como se muestra a continuación.

149
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

4. Añada el mapeo de encabezado Content-Type a la solicitud de integración:

Content-Type: 'x-amz-json-1.1'

La tarea sigue el mismo procedimiento para configurar el mapeo del parámetro de solicitud que el
método GET /streams.
5. Añada la siguiente plantilla de mapeo de cuerpo para mapear los datos de la solicitud del método
GET /streams/{stream-name} a la solicitud de integración POST /?Action=DescribeStream:

{
"StreamName": "$input.params('stream-name')"
}

Esta plantilla de mapeo genera la carga de la solicitud de integración necesaria para la acción
DescribeStream de Kinesis a partir del valor del parámetro de ruta stream-name de la solicitud de
método.
6. Pruebe el método GET /stream/{stream-name} para invocar la acción DescribeStream en
Kinesis:

150
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

En la consola de API Gateway, seleccione /streams/{stream-name}/GET en el panel Resources

(Recursos), elija Test (Prueba) para comenzar la prueba, escriba el nombre de un flujo de Kinesis
existente en el campo Path (Ruta) para stream-name y elija Test (Prueba). Si la prueba tiene éxito,
se devuelve la respuesta 200 OK con una carga similar a la siguiente:

{
"StreamDescription": {
"HasMoreShards": false,
"RetentionPeriodHours": 24,
"Shards": [
{
"HashKeyRange": {
"EndingHashKey": "68056473384187692692674921486353642290",
"StartingHashKey": "0"
},
"SequenceNumberRange": {
"StartingSequenceNumber":
"49559266461454070523309915164834022007924120923395850242"
},
"ShardId": "shardId-000000000000"
},
...
{
"HashKeyRange": {
"EndingHashKey": "340282366920938463463374607431768211455",
"StartingHashKey": "272225893536750770770699685945414569164"
},
"SequenceNumberRange": {
"StartingSequenceNumber":
"49559266461543273504104037657400164881014714369419771970"
},
"ShardId": "shardId-000000000004"
}
],
"StreamARN": "arn:aws:kinesis:us-east-1:12345678901:stream/myStream",
"StreamName": "myStream",
"StreamStatus": "ACTIVE"
}
}

Después de implementar la API, puede realizar una solicitud REST a este método de la API:

GET https://your-api-id.execute-api.region.amazonaws.com/stage/streams/myStream
HTTP/1.1
Host: your-api-id.execute-api.region.amazonaws.com
Content-Type: application/json
Authorization: ...
X-Amz-Date: 20160323T194451Z

Para configurar y probar el método POST en un recurso de flujo

1. Configure el método POST /streams/{stream-name} para llamar a la acción POST /?

Action=CreateStream en Kinesis. La tarea sigue el mismo procedimiento para configurar el
método GET /streams/{stream-name} siempre y cuando reemplace la acción DescribeStream
por CreateStream.
2. Añada el mapeo de encabezado Content-Type a la solicitud de integración:

151
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

Content-Type: 'x-amz-json-1.1'

La tarea sigue el mismo procedimiento para configurar el mapeo del parámetro de solicitud que el
método GET /streams.
3. Añada la siguiente plantilla de mapeo de cuerpo para mapear los datos de la solicitud del método
POST /streams/{stream-name} a la solicitud de integración POST /?Action=CreateStream:

{
"ShardCount": #if($input.path('$.ShardCount') == '') 5 #else
$input.path('$.ShardCount') #end,
"StreamName": "$input.params('stream-name')"
}

En la plantilla de mapeo anterior, definimos ShardCount en un valor fijo de 5 si el cliente no

especifica un valor en la carga de la solicitud de método.
4. Pruebe el método POST /streams/{stream-name} para crear un flujo con nombre en Kinesis:

En la consola de API Gateway, seleccione /streams/{stream-name}/GET en el panel Resources

(Recursos), elija Test (Prueba) para comenzar la prueba, ingrese el nombre de un flujo de Kinesis
nuevo en Path (Ruta) para stream-name y elija Test (Prueba). Si la prueba tiene éxito, se devuelve
una respuesta 200 OK sin datos.

Después de implementar la API, también puede realizar una solicitud de API de REST al método
POST en un recurso Stream para invocar la acción CreateStream en Kinesis:

POST https://your-api-id.execute-api.region.amazonaws.com/stage/streams/yourStream
HTTP/1.1
Host: your-api-id.execute-api.region.amazonaws.com
Content-Type: application/json
Authorization: ...
X-Amz-Date: 20160323T194451Z

{
"ShardCount": 5
}

Configurar y probar el método DELETE en un recurso de flujo

1. Configure el método DELETE /streams/{stream-name} para integrar la acción POST /?

Action=DeleteStream en Kinesis. La tarea sigue el mismo procedimiento para configurar el
método GET /streams/{stream-name} siempre y cuando reemplace la acción DescribeStream
por DeleteStream.
2. Añada el mapeo de encabezado Content-Type a la solicitud de integración:

Content-Type: 'x-amz-json-1.1'

La tarea sigue el mismo procedimiento para configurar el mapeo del parámetro de solicitud que el
método GET /streams.
3. Añada la siguiente plantilla de mapeo de cuerpo para mapear los datos de la solicitud de
método DELETE /streams/{stream-name} a la solicitud de integración de POST /?
Action=DeleteStream correspondiente:

152
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

{
"StreamName": "$input.params('stream-name')"
}

Esta plantilla de mapeo genera la entrada necesaria de la DELETE /streams/{stream-name}

acción desde el nombre de ruta URL proporcionada por el cliente: stream-name.
4. Pruebe el método DELETE para eliminar un flujo con nombre en Kinesis:

En la consola de API Gateway, seleccione el nodo de método /streams/{stream-name}/DELETE en el

panel Resources (Recursos), elija Test (Prueba) para comenzar la prueba, escriba el nombre de un
flujo de Kinesis existente en Path (Ruta) para stream-name y elija Test (Prueba). Si la prueba tiene
éxito, se devuelve una respuesta 200 OK sin datos.

Después de implementar la API, también puede realizar la siguiente solicitud API de REST al método
DELETE en el recurso Stream para llamar a la acción DeleteStream en Kinesis:

DELETE https://your-api-id.execute-api.region.amazonaws.com/stage/streams/yourStream
HTTP/1.1
Host: your-api-id.execute-api.region.amazonaws.com
Content-Type: application/json
Authorization: ...
X-Amz-Date: 20160323T194451Z

{}

Obtención de registros y adición de registros a un flujo de Kinesis

Después de crear un flujo en Kinesis, puede agregar registros de datos al flujo y leer los datos del flujo.
Agregar registros de datos implica llamar a la acción PutRecords o PutRecord de Kinesis. La primera
acción añade varios registros, mientras que la última añade un solo registro al flujo.

POST /?Action=PutRecords HTTP/1.1

Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
"Records": [
{
"Data": blob,
"ExplicitHashKey": "string",
"PartitionKey": "string"
}
],
"StreamName": "string"
}

o bien

POST /?Action=PutRecord HTTP/1.1

153
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
"Data": blob,
"ExplicitHashKey": "string",
"PartitionKey": "string",
"SequenceNumberForOrdering": "string",
"StreamName": "string"
}

Aquí, StreamName identifica el flujo de destino para añadir registros. StreamName, Data y
PartitionKey son datos de entrada necesarios. En nuestro ejemplo, usamos los valores
predeterminados para todos los datos de entrada opcionales y no especificaremos de forma explícita los
valores para ellos en la entrada de la solicitud del método.

Leer datos en Kinesis equivale a llamar a la acción GetRecords:

POST /?Action=GetRecords HTTP/1.1

Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
"ShardIterator": "string",
"Limit": number
}

Aquí, el flujo de origen del que se obtienen los registros se especifica en el valor de ShardIterator
necesario, tal y como se muestra en la siguiente acción de Kinesis para obtener un iterador de fragmento:

POST /?Action=GetShardIterator HTTP/1.1

Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
"ShardId": "string",
"ShardIteratorType": "string",
"StartingSequenceNumber": "string",
"StreamName": "string"
}

Para las acciones GetRecords y PutRecords, exponemos los métodos GET y PUT, respectivamente,
en un recurso /records que se añade a un recurso de flujo con nombre (/{stream-name}). Del mismo
modo, exponemos la acción PutRecord como un método PUT en un recurso /record.

Como la acción GetRecords toma como entrada un valor de ShardIterator, que se obtiene
llamando a la acción auxiliar GetShardIterator, exponemos un método auxiliar GET en un recurso
ShardIterator (/sharditerator).

154
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

En la siguiente ilustración se muestra la estructura de API de los recursos después de crear los métodos:

Los siguientes cuatro procedimientos describen cómo configurar cada uno de los métodos, cómo asignar
datos desde las solicitudes de método a las solicitudes de integración y cómo probar los métodos.

Para configurar y probar el método PUT /streams/{stream-name}/record para invocar a

PutRecord en Kinesis

1. Configure el método PUT, como se muestra a continuación:

155
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

2. Agregue el siguiente mapeo de parámetro de solicitud para configurar el encabezado Content-Type

de una versión de JSON compatible con AWS en la solicitud de integración:

Content-Type: 'x-amz-json-1.1'

La tarea sigue el mismo procedimiento para configurar el mapeo del parámetro de solicitud que el
método GET /streams.
3. Añada la siguiente plantilla de mapeo de cuerpo para mapear los datos de la solicitud de
método PUT /streams/{stream-name}/record a la solicitud de integración de POST /?
Action=PutRecord correspondiente:

{
"StreamName": "$input.params('stream-name')",
"Data": "$util.base64Encode($input.json('$.Data'))",
"PartitionKey": "$input.path('$.PartitionKey')"
}

En esta plantilla de asignación se asume que la carga del método de solicitud tiene el siguiente
formato:

{
"Data": "some data",
"PartitionKey": "some key"

156
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

Estos datos se pueden modelar mediante el siguiente esquema JSON:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PutRecord proxy single-record payload",
"type": "object",
"properties": {
"Data": { "type": "string" },
"PartitionKey": { "type": "string" }
}
}

Puede crear un modelo para incluir este esquema y utilizar el modelo para facilitar la generación de
la plantilla de asignación. Sin embargo, puede generar una plantilla de asignación sin usar ningún
modelo.
4. Para probar el método PUT /streams/{stream-name}/record, establezca la variable de ruta
stream-name en el nombre de un flujo existente, introduzca la carga del formato necesario y, a
continuación, envíe la solicitud de método. El resultado correcto es una respuesta 200 OK con una
carga con el formato siguiente:

{
"SequenceNumber": "49559409944537880850133345460169886593573102115167928386",
"ShardId": "shardId-000000000004"
}

Para configurar y probar el método PUT /streams/{stream-name}/records para invocar a

PutRecords en Kinesis

1. Configure el método PUT /streams/{stream-name}/records tal y como se muestra a

continuación:

157
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

2. Agregue el siguiente mapeo de parámetro de solicitud para configurar el encabezado Content-Type

de una versión de JSON compatible con AWS en la solicitud de integración:

Content-Type: 'x-amz-json-1.1'

La tarea sigue el mismo procedimiento para configurar el mapeo del parámetro de solicitud que el
método GET /streams.
3. Añada la siguiente plantilla de mapeo de cuerpo para mapear los datos de la solicitud de
método PUT /streams/{stream-name}/records a la solicitud de integración de POST /?
Action=PutRecords correspondiente:

{
"StreamName": "$input.params('stream-name')",
"Records": [
#foreach($elem in $input.path('$.records'))
{
"Data": "$util.base64Encode($elem.data)",
"PartitionKey": "$elem.partition-key"
}#if($foreach.hasNext),#end
#end
]
}

158
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

Esta plantilla de mapeo asume que el siguiente esquema JSON puede modelar la carga de la solicitud
de método:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PutRecords proxy payload data",
"type": "object",
"properties": {
"records": {
"type": "array",
"items": {
"type": "object",
"properties": {
"data": { "type": "string" },
"partition-key": { "type": "string" }
}
}
}
}
}

Puede crear un modelo para incluir este esquema y utilizar el modelo para facilitar la generación de
la plantilla de asignación. Sin embargo, puede generar una plantilla de asignación sin usar ningún
modelo.

En este tutorial, hemos usado dos formatos de carga ligeramente diferentes para ilustrar que un
desarrollador de API puede optar por exponer el formato de datos de backend al cliente u ocultárselo.
Un formato es para el método PUT /streams/{stream-name}/records (anterior). Otro formato
se utiliza en el método PUT /streams/{stream-name}/record (en el procedimiento anterior). En
un entorno de producción, debe mantener la coherencia de ambos formatos.
4.
Para probar el método PUT /streams/{stream-name}/records, establezca la variable de ruta
stream-name en un flujo existente, introduzca la siguiente carga y envíe la solicitud del método.

{
"records": [
{
"data": "some data",
"partition-key": "some key"
},
{
"data": "some other data",
"partition-key": "some key"
}
]
}

El resultado correcto es una respuesta 200 OK con una carga similar a la siguiente:

{
"FailedRecordCount": 0,
"Records": [
{
"SequenceNumber": "49559409944537880850133345460167468741933742152373764162",
"ShardId": "shardId-000000000004"
},
{
"SequenceNumber": "49559409944537880850133345460168677667753356781548470338",

159
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"ShardId": "shardId-000000000004"
}
]
}

Para configurar y probar el método GET /streams/{stream-name}/sharditerator para

invocar a GetShardIterator en Kinesis

GET /streams/{stream-name}/sharditerator es un método auxiliar para adquirir un iterador de

fragmento necesario antes de llamar al método GET /streams/{stream-name}/records.

1. Configure la integración del método GET /streams/{stream-name}/sharditerator tal y como

se muestra a continuación:

2.
La acción GetShardIterator requiere una entrada de un valor de ShardId. Para pasar un valor de
ShardId proporcionado por el cliente, añadimos un parámetro de consulta shard-id a la solicitud
del método, tal y como se muestra a continuación:

160
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

En la siguiente plantilla de mapeo de cuerpo, definimos el valor del parámetro de consulta

shard-id en el valor de la propiedad ShardId de la carga JSON como entrada de la acción
GetShardIterator en Kinesis.
3. Configure la plantilla de mapeo de cuerpo para generar la entrada adecuada (ShardId y
StreamName) de la GetShardIterator acción a partir de los parámetros shard-id y
stream-name de la solicitud de método. Además, la plantilla de mapeo también establece
ShardIteratorType en TRIM_HORIZON como valor predeterminada.

{
"ShardId": "$input.params('shard-id')",
"ShardIteratorType": "TRIM_HORIZON",
"StreamName": "$input.params('stream-name')"
}

4. Con la opción Test (Prueba) de la consola de API Gateway, escriba un nombre de flujo existente
como el valor de la variable stream-name de Path (Ruta), establezca shard-id para Query string
(Cadena de consulta) en un valor ShardId existente (por ejemplo, shard-000000000004) y elija
Test (Prueba).

161
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

La carga de la respuesta correcta es similar al siguiente resultado:

{
"ShardIterator": "AAAAAAAAAAFYVN3VlFy..."
}

Anote el valor de ShardIterator. Lo necesita para obtener los registros de un flujo.

Para configurar y probar el método GET /streams/{stream-name}/records para invocar la

acción GetRecords en Kinesis

1. Configure el método GET /streams/{stream-name}/records tal y como se muestra a

continuación:

2.
La acción GetRecords requiere una entrada de un valor de ShardIterator. Para pasar un valor
de ShardIterator proporcionado por el cliente, añadimos un parámetro de encabezado Shard-
Iterator a la solicitud del método, tal y como se muestra a continuación:

162
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

3. Configure la siguiente plantilla de mapeo para asignar el valor del parámetro de encabezado Shard-
Iterator al valor de la propiedad ShardIterator de la carga JSON de la GetRecords acción en
Kinesis.

{
"ShardIterator": "$input.params('Shard-Iterator')"
}

4. Con la opción Test (Prueba) de la consola de API Gateway, escriba un nombre de flujo existente
como el valor de la variable stream-name de Path (Ruta), establezca Shard-Iteratorpara Header
(Encabezado) en el valor ShardIterator obtenido de la serie de pruebas del método GET /
streams/{stream-name}/sharditerator (arriba) y elija Test (Prueba).

La carga de la respuesta correcta es similar al siguiente resultado:

{
"MillisBehindLatest": 0,
"NextShardIterator": "AAAAAAAAAAF...",
"Records": [ ... ]
}

163
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

Definiciones de OpenAPI de la API de ejemplo como un proxy de

Kinesis
A continuación se muestran las definiciones de OpenAPI de la API de ejemplo, utilizada en este tutorial,
como un proxy de Kinesis.

OpenAPI 3.0

{
"openapi": "3.0.0",
"info": {
"title": "KinesisProxy",
"version": "2016-03-31T18:25:32Z"
},
"paths": {
"/streams/{stream-name}/sharditerator": {
"get": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "shard-id",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/GetShardIterator",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardId\": \"$input.params('shard-
id')\",\n \"ShardIteratorType\": \"TRIM_HORIZON\",\n \"StreamName\":
\"$input.params('stream-name')\"\n}"
},

164
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}/records": {
"get": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Shard-Iterator",
"in": "header",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/GetRecords",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardIterator\": \"$input.params('Shard-
Iterator')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"put": {
"parameters": [
{
"name": "Content-Type",
"in": "header",
"schema": {
"type": "string"
}
},
{

165
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PutRecordsMethodRequestPayload"
}
},
"application/x-amz-json-1.1": {
"schema": {
"$ref": "#/components/schemas/PutRecordsMethodRequestPayload"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/PutRecords",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-
name')\",\n \"Records\": [\n {\n \"Data\":
\"$util.base64Encode($elem.data)\",\n \"PartitionKey\": \"$elem.partition-
key\"\n }#if($foreach.hasNext),#end\n ]\n}",
"application/x-amz-json-1.1": "{\n \"StreamName\":
\"$input.params('stream-name')\",\n \"records\" : [\n {\n \"Data
\" : \"$elem.data\",\n \"PartitionKey\" : \"$elem.partition-key\"\n
}#if($foreach.hasNext),#end\n ]\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}": {
"get": {
"parameters": [
{

166
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/DescribeStream",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-
name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"post": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/CreateStream",
"responses": {
"default": {

167
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardCount\": 5,\n \"StreamName\":
\"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"delete": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Content-Type": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"400": {
"description": "400 response",
"headers": {
"Content-Type": {
"schema": {
"type": "string"
}
}
},
"content": {}
},
"500": {
"description": "500 response",
"headers": {
"Content-Type": {
"schema": {
"type": "string"
}
}
},
"content": {}
}
},

168
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/DeleteStream",
"responses": {
"4\\d{2}": {
"statusCode": "400",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type"
}
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type"
}
},
"5\\d{2}": {
"statusCode": "500",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type"
}
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-
name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}/record": {
"put": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",

169
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"uri": "arn:aws:apigateway:us-east-1:kinesis:action/PutRecord",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-
name')\",\n \"Data\": \"$util.base64Encode($input.json('$.Data'))\",\n
\"PartitionKey\": \"$input.path('$.PartitionKey')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams": {
"get": {
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/ListStreams",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
}
},
"components": {
"schemas": {
"Empty": {
"type": "object"
},
"PutRecordsMethodRequestPayload": {
"type": "object",
"properties": {
"records": {
"type": "array",
"items": {
"type": "object",

170
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"properties": {
"data": {
"type": "string"
},
"partition-key": {
"type": "string"
}
}
}
}
}
}
}
}
}

OpenAPI 2.0

{
"swagger": "2.0",
"info": {
"version": "2016-03-31T18:25:32Z",
"title": "KinesisProxy"
},
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/streams": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/ListStreams",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},

171
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"/streams/{stream-name}": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/DescribeStream",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-
name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",

172
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/CreateStream",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardCount\": 5,\n \"StreamName\":
\"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"delete": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
},
"500": {
"description": "500 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/DeleteStream",

173
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"responses": {
"4\\d{2}": {
"statusCode": "400",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type"
}
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type"
}
},
"5\\d{2}": {
"statusCode": "500",
"responseParameters": {
"method.response.header.Content-Type":
"integration.response.header.Content-Type"
}
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-
name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}/record": {
"put": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/PutRecord",
"responses": {
"default": {
"statusCode": "200"

174
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-
name')\",\n \"Data\": \"$util.base64Encode($input.json('$.Data'))\",\n
\"PartitionKey\": \"$input.path('$.PartitionKey')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}/records": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "Shard-Iterator",
"in": "header",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/GetRecords",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardIterator\": \"$input.params('Shard-
Iterator')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"put": {

175
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"consumes": [
"application/json",
"application/x-amz-json-1.1"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "Content-Type",
"in": "header",
"required": false,
"type": "string"
},
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "PutRecordsMethodRequestPayload",
"required": true,
"schema": {
"$ref": "#/definitions/PutRecordsMethodRequestPayload"
}
},
{
"in": "body",
"name": "PutRecordsMethodRequestPayload",
"required": true,
"schema": {
"$ref": "#/definitions/PutRecordsMethodRequestPayload"
}
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/PutRecords",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-
name')\",\n \"Records\": [\n {\n \"Data\":
\"$util.base64Encode($elem.data)\",\n \"PartitionKey\": \"$elem.partition-
key\"\n }#if($foreach.hasNext),#end\n ]\n}",
"application/x-amz-json-1.1": "{\n \"StreamName\":
\"$input.params('stream-name')\",\n \"records\" : [\n {\n \"Data
\" : \"$elem.data\",\n \"PartitionKey\" : \"$elem.partition-key\"\n
}#if($foreach.hasNext),#end\n ]\n}"

176
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}/sharditerator": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "shard-id",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/GetShardIterator",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardId\": \"$input.params('shard-
id')\",\n \"ShardIteratorType\": \"TRIM_HORIZON\",\n \"StreamName\":
\"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
}
},
"definitions": {
"Empty": {
"type": "object"
},
"PutRecordsMethodRequestPayload": {
"type": "object",
"properties": {

177
 Amazon API Gateway Guía del desarrollador
Tutorial: Creación de una API de
REST como proxy de Amazon Kinesis

"records": {
"type": "array",
"items": {
"type": "object",
"properties": {
"data": {
"type": "string"
},
"partition-key": {
"type": "string"
}
}
}
}
}
}
}
}

178
 Amazon API Gateway Guía del desarrollador
Desarrollo

Uso de API HTTP

Las API HTTP le permiten crear API de RESTful con menor latencia y menor costo que las API de REST.

Puede utilizar las API HTTP para enviar solicitudes a las funciones de AWS Lambda o a cualquier punto de
enlace de HTTP enrutable.

Por ejemplo, puede crear una API HTTP que se integre con una función de Lambda en el backend.
Cuando un cliente llama a la API, API Gateway envía la solicitud a la función de Lambda y devuelve la
respuesta de la función al cliente.

Las API HTTP son compatibles con la autorización de OpenID Connect y OAuth 2.0. Vienen con soporte
integrado para el uso compartido de recursos entre orígenes (CORS) y las implementaciones automáticas.

Puede crear API HTTP mediante la consola de administración de AWS, la CLI de AWS, las API, AWS
CloudFormation o los SDK. Las API HTTP utilizan API versión 2 de API Gateway, que anteriormente solo
admitían las API de WebSocket.

Temas
• Desarrollo de una API HTTP en API Gateway (p. 179)
• Publicación de una API HTTP para que los clientes la invoquen (p. 215)
• Protección de la API HTTP (p. 219)
• Monitoreo de la API HTTP (p. 224)
• Solución de problemas con las API HTTP (p. 232)

Desarrollo de una API HTTP en API Gateway

En esta sección se proporciona información detallada acerca de las capacidades de API Gateway que
necesitará para desarrollar las API de API Gateway.

A medida que se desarrolla la API de API Gateway, se decide sobre una serie de características de la API.
Estas características dependen del uso de la API. Por ejemplo, es posible que quiera permitir solo a ciertos
clientes llamar a la API o puede que quiera que esté disponible para todos. Puede querer que una llamada
a la API ejecute una función de Lambda, haga una consulta a la base de datos o llame a una aplicación.

Temas
• Creación de una API HTTP (p. 179)
• Uso de rutas para API HTTP (p. 180)
• Control y administración del acceso a una API HTTP en API Gateway (p. 182)
• Configuración de integraciones para API HTTP (p. 190)
• Configuración de CORS para una API HTTP (p. 203)
• Transformación de solicitudes y respuestas de API (p. 204)
• Uso de definiciones de OpenAPI para API HTTP (p. 209)

Creación de una API HTTP

Para crear una API funcional, debe contar al menos con una ruta, una integración, una etapa y una
implementación.

179
 Amazon API Gateway Guía del desarrollador
Rutas

En los siguientes ejemplos se muestra cómo crear una API con una integración de AWS Lambda o HTTP,
una ruta y una etapa predeterminada configurada para implementar automáticamente los cambios.

Temas
• Crear una API HTTP mediante la consola de administración de AWS (p. 180)
• Crear una API HTTP mediante la CLI de AWS (p. 180)

Crear una API HTTP mediante la consola de administración de

AWS
1. Abra la consola de API Gateway.
2. Seleccione Create API (Crear API).
3. En HTTP API (API HTTP), elija Build (Compilación).
4. Elija Add integration (Agregar integración) y, a continuación, una función de AWS Lambda o escriba un
punto de enlace HTTP.
5. En Name (Nombre), escriba un nombre para la API.
6. Elija Review and create (Revisar y crear).
7. Seleccione Create (Crear).

La API ya está lista para su invocación. Puede probar la API escribiendo su URL de invocación en un
navegador o con Curl.

curl https://api-id.execute-api.us-east-2.amazonaws.com

Crear una API HTTP mediante la CLI de AWS

Puede utilizar la creación rápida (p. 9) para crear una API con una integración de Lambda o HTTP, una
ruta de método catch-all predeterminada y una etapa predeterminada configurada para implementar
automáticamente los cambios. El siguiente comando utiliza la creación rápida para crear una API que se
integra con una función de Lambda en el backend.
Note
Para invocar una integración de Lambda, la API Gateway debe tener los permisos necesarios.
Puede utilizar una política basada en recursos o un rol de IAM para conceder a la API Gateway
permisos para invocar una función Lambda. Para obtener más información, consulte Permisos de
AWS Lambda en la guía para desarrolladores de AWS Lambda.

Example

aws apigatewayv2 create-api --name my-api --protocol-type HTTP --target arn:aws:lambda:us-

east-2:123456789012:function:function-name

La API ya está lista para su invocación. Puede probar la API escribiendo su URL de invocación en un
navegador o con Curl.

curl https://api-id.execute-api.us-east-2.amazonaws.com

Uso de rutas para API HTTP

Las rutas dirigen las solicitudes entrantes de la API a los recursos de backend. Las rutas constan de dos
partes: un método HTTP y una ruta de recurso, por ejemplo, GET /pets. Puede definir métodos HTTP

180
 Amazon API Gateway Guía del desarrollador
Rutas

específicos para su ruta. O bien, puede utilizar el método ANY para que coincida con todos los métodos
que no haya definido para un recurso. Puede crear una ruta $default que actúe como método catch-all
para las solicitudes que no coincidan con ninguna otra ruta.

Trabajar con variables de ruta

Puede utilizar variables de ruta en rutas de API HTTP.

Por ejemplo, la ruta GET /pets/{petID} captura una solicitud GET que un cliente envía a
https://api-id.execute-api.us-east-2.amazonaws.com/pets/6.

Una variable de ruta ambiciosa captura todos los recursos secundarios de una ruta. Para crear una
variable de ruta ambiciosa, agregue + al nombre de la variable, por ejemplo, {proxy+}. La variable de
ruta expansiva debe estar al final de la ruta del recurso.

Trabajar con parámetros de cadena de consulta

De forma predeterminada, API Gateway envía parámetros de cadena de consulta a su integración de
backend si se incluyen en una solicitud a una API HTTP.

Por ejemplo, cuando un cliente envía una solicitud a https://api-id.execute-api.us-

east-2.amazonaws.com/pets?id=4&type=dog, los parámetros de cadena de consulta ?
id=4&type=dog se envían a su integración.

Trabajar con la ruta $default

La ruta $default captura solicitudes que no coinciden explícitamente con otras rutas en su API.

Cuando la ruta $default recibe una solicitud, API Gateway envía la ruta de solicitud completa a la
integración. Por ejemplo, puede crear una API con solo una ruta $default e integrarla en el método ANY
con el punto de enlace HTTP https://petstore-demo-endpoint.execute-api.com. Cuando envía
una solicitud a https://api-id.execute-api.us-east-2.amazonaws.com/store/checkout,
API Gateway envía una solicitud a https://petstore-demo-endpoint.execute-api.com/store/
checkout.

Para obtener más información acerca de las integraciones de HTTP, consulte Uso de integraciones de
proxy de HTTP para API HTTP (p. 195).

Enrutamiento de solicitudes de la API

Cuando un cliente envía una solicitud de la API, API Gateway primero determina hacia qué etapa dirigir
la solicitud. Si la solicitud coincide explícitamente con una etapa, API Gateway envía la solicitud a esa
etapa. Si ninguna etapa coincide completamente con la solicitud, API Gateway envía la solicitud a la etapa
$default. Si no hay ninguna etapa $default, entonces la API vuelve a {"message":"Not Found"}.

Después de seleccionar una etapa, API Gateway selecciona una ruta. API Gateway selecciona la ruta con
la coincidencia más específica y aplica las siguientes prioridades:

1. Coincidencia completa para una ruta y método.

2. Haga coincidir una ruta y un método con una variable de ruta ambiciosa ({proxy+}).
3. La ruta $default.

Si ninguna ruta coincide con una solicitud, API Gateway devuelve {"message":"Not Found"} al cliente.

Por ejemplo, piense en una API con una etapa $default y las siguientes rutas de ejemplo:

1. GET /pets/dog/1

181
 Amazon API Gateway Guía del desarrollador
Control de acceso

2. GET /pets/dog/{id}
3. GET /pets/{proxy+}
4. ANY /{proxy+}
5. $default

En la siguiente tabla se resume la forma en que API Gateway enruta las solicitudes a las rutas de
ejemplo.

Solicitud Ruta seleccionada Explicación

GET https://api- GET /pets/dog/1 La solicitud coincide

id.execute- completamente con esta ruta
api.region.amazonaws.com/ estática.
pets/dog/1

GET https://api- GET /pets/dog/{id} La solicitud coincide

id.execute- completamente con esta ruta.
api.region.amazonaws.com/
pets/dog/2

GET https://api- GET /pets/{proxy+} La solicitud no coincide

id.execute- completamente con una ruta.
api.region.amazonaws.com/ La ruta con un método GET y
pets/cat/1 una variable de ruta ambiciosa
captura esta solicitud.

POST https://api- ANY /{proxy+} El método ANY coincide con

id.execute- todos los métodos que no ha
api.region.amazonaws.com/ definido para una ruta. Las rutas
test/5 con variables de ruta ambiciosas
tienen mayor prioridad que la ruta
$default.

Control y administración del acceso a una API HTTP

en API Gateway
API Gateway admite varios mecanismos para controlar y administrar el acceso a la API HTTP:

• Los autorizadores de Lambda utilizan las funciones de Lambda para controlar el acceso a las API. Para
obtener más información, consulte Uso de autorizadores de AWS Lambda para API HTTP (p. 182).
• Los autorizadores de JWT utilizan tokens web JSON para controlar el acceso a las API. Para obtener
más información, consulte Control del acceso a las API HTTP con autorizadores de JWT (p. 189).
• Los roles y políticas estándar de AWS IAM ofrecen controles de acceso flexibles y sólidos. Puede usar
roles y políticas de IAM para controlar quién puede crear y administrar sus API, así como quién puede
invocarlas. Para obtener más información, consulte Uso de la autorización de IAM (p. 190).

Uso de autorizadores de AWS Lambda para API HTTP

El autorizador de Lambda se utiliza para emplear una función de Lambda para controlar el acceso a una
API HTTP. Después, cuando un cliente llama a dicha API, API Gateway invoca la función de Lambda. API
Gateway utiliza la respuesta de su función de Lambda para determinar si el cliente puede acceder a la API.

182
 Amazon API Gateway Guía del desarrollador
Control de acceso

Versión de formato de carga

La versión del formato de carga del autorizador especifica el formato de los datos que API Gateway envía
a un autorizador de Lambda y cómo API Gateway interpreta la respuesta de Lambda. Si no especifica una
versión de formato de carga, la consola de administración de AWS utiliza la versión más reciente de forma
predeterminada. Si crea un autorizador de Lambda mediante la CLI de AWS, AWS CloudFormation o un
SDK, debe especificar una authorizerPayloadFormatVersion. Los valores admitidos son 1.0 y 2.0.

Si necesita compatibilidad con las API de REST, utilice la versión 1.0.

Los siguientes ejemplos muestran la estructura de cada versión de formato de carga.

2.0

{
"version": "2.0",
"type": "REQUEST",
"routeArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": ["user1", "123"],
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
"cookies": ["cookie1", "cookie2"],
"headers": {
"Header1": "value1",
"Header2": "value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "IP",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"pathParameters": { "parameter1": "value1" },
"stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" }
}

183
 Amazon API Gateway Guía del desarrollador
Control de acceso

1.0

{
"version": "1.0",
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": "user1,123",
"authorizationToken": "user1,123",
"resource": "/request",
"path": "/request",
"httpMethod": "GET",
"headers": {
"X-AMZ-Date": "20170718T062915Z",
"Accept": "*/*",
"HeaderAuth1": "headerValue1",
"CloudFront-Viewer-Country": "US",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Is-Mobile-Viewer": "false",
"User-Agent": "..."
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"pathParameters": {},
"stageVariables": {
"StageVar1": "stageValue1"
},
"requestContext": {
"path": "/request",
"accountId": "123456789012",
"resourceId": "05c7jb",
"stage": "test",
"requestId": "...",
"identity": {
"apiKey": "...",
"sourceIp": "...",
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"resourcePath": "/request",
"httpMethod": "GET",
"apiId": "abcdef123"
}
}

Formato de respuesta del autorizador de Lambda

La versión del formato de carga también determina la estructura de la respuesta que debe devolver de su
función de Lambda.

Respuesta de función de Lambda para el formato 1.0

Si elige la versión de formato 1.0, los autorizadores de Lambda deben devolver una política de IAM que
permita o deniegue el acceso a su ruta de la API. Puede utilizar la sintaxis de política de IAM estándar en

184
 Amazon API Gateway Guía del desarrollador
Control de acceso

la política. Para obtener algunos ejemplos de políticas de IAM, consulte the section called “ Controlar el
acceso para invocar una API” (p. 294). El objeto context es opcional. Puede transmitir propiedades de
contexto a integraciones o registros de acceso de Lambda mediante $context.authorizer.property.
Para obtener más información, consulte the section called “Variables de registro” (p. 228).

Example

{
"principalId": "abcdef", // The principal user identification associated with the token
sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/
[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}

Respuesta de función de Lambda para el formato 2.0

Si elige la versión de formato 2.0, puede devolver un valor booleano o una política de IAM que utilice
la sintaxis de la política de IAM estándar de la función de Lambda. Para devolver un valor booleano,
habilite respuestas simples para el autorizador. Los siguientes ejemplos muestran el formato que
debe utilizar para codificar la devolución de la función de Lambda. El objeto context es opcional.
Puede transmitir propiedades de contexto a integraciones o registros de acceso de Lambda mediante
$context.authorizer.property. Para obtener más información, consulte the section called
“Variables de registro” (p. 228).

Simple response

{
"isAuthorized": true/false,
"context": {
"exampleKey": "exampleValue"
}
}

IAM policy

{
"principalId": "abcdef", // The principal user identification associated with the
token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/
{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},

185
 Amazon API Gateway Guía del desarrollador
Control de acceso

"context": {
"exampleKey": "exampleValue"
}
}

Ejemplo de funciones de autorizador de Lambda

El siguiente ejemplo de funciones de Lambda Node.js muestran los formatos de respuesta necesarios que
debe devolver desde la función de Lambda para la versión del formato de carga 2.0.

Simple response

exports.handler = async(event) => {

let response = {
"isAuthorized": false,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};

if (event.headers.authorization === "secretToken") {

response = {
"isAuthorized": true,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
}

return response;

};

IAM policy

exports.handler = async(event) => {

if (event.headers.authorization == "secretToken") {
console.log("allowed");
return {
"principalId": "abcdef", // The principal user identification associated with the
token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],

186
 Amazon API Gateway Guía del desarrollador
Control de acceso

"mapKey": { "value1": "value2" }

}
};
}
else {
console.log("denied");
return {
"principalId": "abcdef", // The principal user identification associated with the
token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
};

Fuentes de identidad
Opcionalmente, puede especificar orígenes de identidad para un autorizador de Lambda. Los orígenes de
identidad especifican la ubicación de los datos necesarios para autorizar una solicitud. Por ejemplo, puede
especificar valores de cabecera o cadena de consulta como orígenes de identidad. Si especifica orígenes
de identidad, los clientes deben incluirlos en la solicitud. Si la solicitud del cliente no incluye los orígenes
de identidad, API Gateway no invoca el autorizador de Lambda y el cliente recibe un error 401. Se admiten
los siguientes orígenes de identidad:

Expresiones de selección

Tipo Ejemplo Notas

Valor del encabezado $request.header.name Los nombres del encabezado no

distinguen entre mayúsculas y
minúsculas.

Valor de la cadena de consulta $request.querystring.name Los nombres de las cadenas de

consulta distinguen mayúsculas y
minúsculas.

Variable de contexto $contexto.variableName El valor de una variable de

contexto (p. 228) compatible.

Variable de etapa $stageVariables.variableName El valor de una variable de

etapa (p. 216).

Almacenamiento en caché de las respuestas de los autorizadores

Para habilitar el almacenamiento en caché de un autorizador de Lambda debe especificar un
authorizerResultTtlInSeconds. Cuando el almacenamiento en caché está habilitado para un autorizador,

187
 Amazon API Gateway Guía del desarrollador
Control de acceso

API Gateway utiliza los orígenes de identidad del autorizador como clave de caché. Si un cliente especifica
los mismos parámetros en orígenes de identidad dentro del TTL configurado, API Gateway utiliza el
resultado del autorizador almacenado en caché, en lugar de invocar su función de Lambda.

Para habilitar el almacenamiento en caché, el autorizador debe tener al menos un origen de identidad.

Si habilita respuestas simples para un autorizador, la respuesta del autorizador permite o deniega
completamente todas las solicitudes de la API que coincidan con los valores de origen de identidad
almacenados en caché. Para obtener permisos pormenorizados, desactive las respuestas simples y
devuelva una política de IAM.

De forma predeterminada, API Gateway utiliza la respuesta del autorizador almacenada en caché para
todas las rutas de una API que utiliza el autorizador. Para almacenar en caché las respuestas por ruta,
agregue $context.routeKey a las fuentes de identidad del autorizador.

Crear un autorizador de Lambda

Al crear un autorizador de Lambda, se especifica la función de Lambda que utilizará API Gateway. Debe
conceder permiso de API Gateway para invocar la función de Lambda mediante la política de recursos de
la función o un rol de IAM. En este ejemplo, actualizamos la política de recursos de la función para que
otorgue a API Gateway permiso para invocar la función de Lambda.

aws apigatewayv2 create-authorizer \

--api-id abcdef123 \
--authorizer-type REQUEST \
--identity-source '$request.header.Authorization' \
--name lambda-authorizer \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/
functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations' \
--authorizer-payload-format-version '2.0' \
--enable-simple-responses

El siguiente comando otorga permiso a API Gateway para invocar la función de Lambda. Si API Gateway
no tiene permiso para invocar la función, los clientes reciben un 500 Internal Server Error.

aws lambda add-permission \

--function-name my-authorizer-function \
--statement-id apigateway-invoke-permissions-abc123 \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/authorizers/authorizer-
id"

Una vez se haya creado un autorizador y concedido permiso a API Gateway para invocarlo, actualice la
ruta para poder utilizarlo.

aws apigatewayv2 update-route \

--api-id abcdef123 \
--route-id acd123 \
--authorization-type CUSTOM \
--authorizer-id def123

Resolución de problemas de los autorizadores de Lambda

Si API Gateway no puede invocar su autorizador de Lambda, o su autorizador de Lambda devuelve una
respuesta en un formato no válido, los clientes recibirán un 500 Internal Server Error.

Para solucionar errores, habilite el registro de acceso (p. 226) en la etapa de la API. Incluya la variable
de registro $context.authorizer.error en su formato de registro.

188
 Amazon API Gateway Guía del desarrollador
Control de acceso

Si los registros indican que API Gateway no tiene permiso para invocar la función, actualice la política de
recursos de la función o proporcione un rol de IAM para conceder permiso a API Gateway para invocar el
autorizador.

Si los registros indican que la función de Lambda devuelve una respuesta no válida, compruebe que la
función de Lambda devuelve una respuesta en el formato requerido (p. 184).

Control del acceso a las API HTTP con autorizadores de JWT

Puede utilizar JSON Web Tokens (JWT) como parte de los marcos OpenID Connect (OIDC) y OAuth 2.0
para restringir el acceso del cliente a las API.

Si configura un autorizador de JWT para una ruta de la API, API Gateway valida los JWT que los clientes
envían con solicitudes de la API. API Gateway permite o deniega las solicitudes en función de la validación
del token y, opcionalmente, de los ámbitos del token. Si configura ámbitos para una ruta, el token debe
incluir al menos uno de los ámbitos de la ruta.

Puede configurar distintos autorizadores para cada ruta de una API o utilizar el mismo autorizador para
varias rutas.
Note

No existe ningún mecanismo estándar para diferenciar los tokens de acceso de JWT de otros
tipos de JWT, como los tokens de ID de OpenID Connect. A menos que necesite tokens de ID
para la autorización de la API, le recomendamos que configure las rutas para que soliciten los
ámbitos de la autorización. También puede configurar los autorizadores de JWT para que soliciten
los emisores o los destinatarios que el proveedor de identidades utiliza solo al emitir tokens de
acceso de JWT.

Autorización de solicitudes de la API

API Gateway utiliza el siguiente flujo de trabajo general para autorizar solicitudes a rutas configuradas para
que utilicen un autorizador de JWT.

1. Comprueba si identitySource contiene un token. identitySource puede incluir solo el token o el

token con el prefijo Bearer .
2. Descodifique el token.
3. Compruebe el algoritmo y la firma del token tilizando la clave pública obtenida del jwks_uri del emisor.
Actualmente, solo se admiten algoritmos basados en RSA.
4. Validar las reclamaciones. API Gateway evalúa las siguientes reclamaciones de token:
• kid: el token debe tener una reclamación de encabezado que coincida con la clave de jwks_uri
que firmó el token.
• iss: debe coincidir con el issuer configurado para el autorizador.
• aud o client_id: deben coincidir con una de las entradas de audience configuradas para el
autorizador.
• exp: debe ser posterior a la hora actual en UTC.
• nbf: debe ser anterior a la hora actual en UTC.
• iat: debe ser anterior a la hora actual en UTC.
• scope o scp: el token debe incluir al menos uno de los ámbitos de los authorizationScopes de la
ruta.

Si falla alguno de estos pasos, API Gateway deniega la solicitud de la API.

Después de validar el JWT, API Gateway transfiere las reclamaciones del token a la integración de la ruta
de la API. Los recursos de backend, como las funciones de Lambda, pueden acceder a las reclamaciones

189
 Amazon API Gateway Guía del desarrollador
Integraciones

de JWT en $context.authorizer.claims. Por ejemplo, si el JWT incluía una reclamación de

identidad emailID, esta está disponible en $context.authorizer.claims.emailID.

Crear un autorizador de JWT a través de la CLI de AWS

Antes de crear un autorizador de JWT, debe registrar una aplicación cliente con un proveedor de
identidad. También debe haber creado una API HTTP. Para obtener ejemplos de creación de una API
HTTP, consulte Creación de una API HTTP (p. 179). Para obtener un ejemplo de plantilla de AWS
CloudFormation que crea una API HTTP con un autorizador de JWT que utiliza Amazon Cognito como
proveedor de identidades, consulte http-with-jwt-auth.yaml.

El siguiente comando crea un autorizador de JWT que utiliza Amazon Cognito como proveedor de
identidad. Para Audience, especifique el ID de un cliente asociado al grupo de usuarios que especifique
para Issuer.

aws apigatewayv2 create-authorizer \

--name authorizer-name \
--api-id api-id \
--authorizer-type JWT \
--identity-source '$request.header.Authorization' \
--jwt-configuration Audience=audience,Issuer=https://cognito-idp.us-
east-2.amazonaws.com/userPoolID

Actualizar una ruta para utilizar un autorizador de JWT a través de la CLI de AWS
El siguiente comando actualiza una ruta para utilizar un autorizador de JWT.

aws apigatewayv2 update-route \

--api-id api-id \
--route-id route-id \
--authorization-type JWT \
--authorizer-id authorizer-id \
--authorization-scopes user.id user.email

Uso de la autorización de IAM

Puede habilitar la autorización de IAM para rutas HTTP API. Si la autorización de IAM está habilitada,
los clientes deben utilizar la versión 4 de firma para firmar sus solicitudes con credenciales de AWS. API
Gateway invoca su ruta API solo si el cliente tiene el permiso execute-api para la ruta.

La autorización de IAM para las API HTTP es similar a la de las API de REST (p. 294).

Para obtener ejemplos de políticas de IAM que otorgan a los clientes el permiso para invocar las API,
consulte the section called “ Controlar el acceso para invocar una API” (p. 294).

Habilitar la autorización de IAM para una ruta

El siguiente comando de AWS CLI habilita la autorización de IAM para una ruta de API HTTP.

aws apigatewayv2 update-route \

--api-id abc123 \
--route-id abcdef \
--authorization-type AWS_IAM

Configuración de integraciones para API HTTP

Las integraciones conectan una ruta a los recursos de backend. Las API HTTP admiten integraciones de
proxy de Lambda, de servicio de AWS y de proxy de HTTP. Por ejemplo, puede configurar una solicitud

190
 Amazon API Gateway Guía del desarrollador
Integraciones

POST para la ruta /signup de la API para que se integre con una función de Lambda que se encarga del
registro de clientes.

Temas
• Uso de integraciones de proxy de AWS Lambda para las API HTTP (p. 191)
• Uso de integraciones de proxy de HTTP para API HTTP (p. 195)
• Uso de integraciones de servicios de AWS para API HTTP (p. 195)
• Uso de integraciones privadas para API HTTP (p. 201)

Uso de integraciones de proxy de AWS Lambda para las API

HTTP
Una integración de proxy de Lambda le permite integrar una ruta de API con una función de Lambda.
Cuando un cliente llama a la API, API Gateway envía la solicitud a la función de Lambda y devuelve la
respuesta de la función al cliente. Para obtener ejemplos de creación de una API HTTP, consulte Creación
de una API HTTP (p. 179).

Versión de formato de carga

La versión del formato de carga especifica el formato de los datos que API Gateway envía a una
integración de Lambda y cómo API Gateway interpreta la respuesta de Lambda. Si no especifica una
versión de formato de carga, la consola de administración de AWS utiliza la versión más reciente de forma
predeterminada. Si crea una integración de Lambda mediante la CLI de AWS, AWS CloudFormation o un
SDK, debe especificar una payloadFormatVersion. Los valores admitidos son 1.0 y 2.0.

Los siguientes ejemplos muestran la estructura de cada versión de formato de carga.

Note

El formato 2.0 no tiene campos multiValueHeaders o

multiValueQueryStringParameters. Los encabezados duplicados se combinan con comas
y se incluyen en el campo headers. Las cadenas de consulta duplicadas se combinan con comas
y se incluyen en el campo queryStringParameters.
El formato 2.0 incluye un nuevo campo cookies. Todos los encabezados de cookies en la
solicitud se combinan con comas y se agregan al campo cookies. En la respuesta al cliente,
cada cookie se convierte en un encabezado set-cookie.

2.0

{
"version": "2.0",
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
"cookies": [
"cookie1",
"cookie2"
],
"headers": {
"Header1": "value1",
"Header2": "value1,value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",

191
 Amazon API Gateway Guía del desarrollador
Integraciones

"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"authorizer": {
"jwt": {
"claims": {
"claim1": "value1",
"claim2": "value2"
},
"scopes": [
"scope1",
"scope2"
]
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "IP",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"body": "Hello from Lambda",
"pathParameters": {
"parameter1": "value1"
},
"isBase64Encoded": false,
"stageVariables": {
"stageVariable1": "value1",
"stageVariable2": "value2"
}
}

1.0

{
"version": "1.0",
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"Header1": "value1",
"Header2": "value2"
},
"multiValueHeaders": {
"Header1": [
"value1"

192
 Amazon API Gateway Guía del desarrollador
Integraciones

],
"Header2": [
"value1",
"value2"
]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value"
},
"multiValueQueryStringParameters": {
"parameter1": [
"value1",
"value2"
],
"parameter2": [
"value"
]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "IP",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",

193
 Amazon API Gateway Guía del desarrollador
Integraciones

"isBase64Encoded": false
}

Formato de respuesta de función de Lambda

La versión del formato de carga determina la estructura de la respuesta que debe devolver su función de
Lambda.

Respuesta de función de Lambda para el formato 1.0

Con la versión de formato 1.0, las integraciones de Lambda deben devolver una respuesta con el
siguiente formato.

Example

{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headerName": "headerValue", ... },
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"body": "..."
}

Respuesta de función de Lambda para el formato 2.0

Con la versión de formato 2.0, API Gateway puede inferir el formato de respuesta por usted. API Gateway
hace las siguientes suposiciones si su función de Lambda devuelve JSON válido y no devuelve un
statusCode:

• isBase64Encoded es false.
• statusCode es 200.
• content-type es application/json.
• body es la respuesta de la función.

Los siguientes ejemplos muestran el resultado de una función de Lambda y la interpretación de API
Gateway.

Salida de función de Lambda Interpretación de API Gateway

"Hello from Lambda!" {

"isBase64Encoded": false,
"statusCode": 200,
"body": "Hello from Lambda!",
"headers": {
"Content-Type": "application/json"
}
}

{ "message": "Hello from Lambda!" } {

"isBase64Encoded": false,
"statusCode": 200,
"body": "{ \"message\": \"Hello from
Lambda!\" }",
"headers": {
"Content-Type": "application/json"

194
 Amazon API Gateway Guía del desarrollador
Integraciones

Salida de función de Lambda Interpretación de API Gateway

}
}

Para personalizar la respuesta, su función de Lambda debe devolver una respuesta con el siguiente
formato.

{
"cookies" : ["cookie1", "cookie2"],
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headerName": "headerValue", ... },
"body": "Hello from Lambda!"
}

Uso de integraciones de proxy de HTTP para API HTTP

Una integración de proxy HTTP le permite conectar una ruta de API a un punto de enlace HTTP enrutable
públicamente. Con este tipo de integración, API Gateway pasa toda la solicitud y respuesta entre el
frontend y el backend.

Para crear una integración de proxy HTTP, proporcione la dirección URL de un punto de enlace HTTP
direccionable públicamente.

Integración de proxy HTTP con variables de ruta

Puede utilizar variables de ruta en rutas de API HTTP.

Por ejemplo, la ruta /pets/{petID} captura solicitudes a /pets/6. Puede hacer referencia a variables
de ruta en el URI de integración para enviar el contenido de la variable a una integración. Un ejemplo es: /
pets/extentendedpath/{petID}.

Puede usar variables de ruta ambiciosas para capturar todos los recursos secundarios de una ruta. Para
crear una variable de ruta ambiciosa, agregue + al nombre de la variable, por ejemplo, {proxy+}.

Para configurar una ruta con una integración de proxy HTTP que capte todas las solicitudes, cree una ruta
API con una variable de ruta ambiciosa (por ejemplo, /parent/{proxy+}). Integre la ruta con un punto
de enlace HTTP (por ejemplo, https://petstore-demo-endpoint.execute-api.com/petstore/
{proxy}) en el método ANY. La variable de ruta expansiva debe estar al final de la ruta del recurso.

Uso de integraciones de servicios de AWS para API HTTP

Puede integrar su API HTTP con los servicios de AWS mediante integraciones de primera clase. Una
integración de primera clase conecta una ruta de API HTTP a una API de servicio de AWS. Cuando un
cliente invoca una ruta respaldada por una integración de primera clase, API Gateway invoca una API
de servicio de AWS para usted. Por ejemplo, puede utilizar integraciones de primera clase para enviar
un mensaje a una cola de Amazon Simple Queue Service o para iniciar una máquina de estado de AWS
Step Functions. Para ver las acciones de servicio compatibles, consulte the section called “Referencia de
integraciones de servicios de AWS” (p. 197).

Asignar parámetros de solicitud

Las integraciones de primera clase tienen parámetros obligatorios y opcionales. Debe configurar todos los
parámetros que son obligatorios para crear una integración. Puede utilizar valores estáticos o parámetros
de asignación que se evalúan dinámicamente en el tiempo de ejecución. Para obtener una lista completa
de las integraciones y parámetros admitidos, consulte the section called “Referencia de integraciones de
servicios de AWS” (p. 197).

195
 Amazon API Gateway Guía del desarrollador
Integraciones

Asignación de parámetros

Tipo Ejemplo Notas

Valor del encabezado $request.header.name Los nombres del encabezado

no distinguen entre mayúsculas
y minúsculas. API Gateway
combina varios valores de
encabezado con comas,
por ejemplo, "header1":
"value1,value2".

Valor de la cadena de consulta $request.querystring.name Los nombres de las cadenas

de consulta distinguen
mayúsculas y minúsculas.
API Gateway combina varios
valores con comas, por
ejemplo, "querystring1":
"Value1,Value2".

Parámetro de ruta $request.path.name El valor de un parámetro de ruta

en la solicitud. Por ejemplo, si
la ruta es /pets/{petId},
puede asignar el parámetro
petId de la solicitud con
$request.path.petId.

Solicitar acceso directo del $request.body API Gateway transfiere todo

cuerpo el cuerpo de la solicitud
directamente.

Cuerpo de la solicitud $request.body.name Una expresión de ruta de acceso

JSON. El descenso recursivo
($request.body..name)
y las expresiones de filtro
(?(expression)) no son
compatibles.
Note

Cuando se especifica
una ruta JSON, API
Gateway trunca
el cuerpo de la
solicitud en 100 KB
y, a continuación,
aplica la expresión
de selección. Para
enviar cargas de más
de 100 KB, especifique
$request.body.

Variable de contexto $contexto.variableName El valor de una variable de

contexto (p. 228) compatible.

Variable de etapa $stageVariables.variableName El valor de una variable de

etapa (p. 216).

Valor estático string Un valor constante.

196
 Amazon API Gateway Guía del desarrollador
Integraciones

Crear una integración de primera clase

Antes de crear una integración de primera clase, debe crear un rol de IAM que otorgue a API Gateway
permisos para invocar la acción de servicio de AWS con la que se está integrando. Para obtener más
información, consulte Crear un rol para un servicio de AWS.

Para crear una integración de primera clase, elija una acción de servicio de AWS compatible, como SQS-
SendMessage, configure los parámetros de la solicitud y proporcione un rol que otorgue a API Gateway
permisos para invocar la API de servicio de AWS integrada. Dependiendo del subtipo de integración, se
requieren diferentes parámetros de solicitud. Para obtener más información, consulte the section called
“Referencia de integraciones de servicios de AWS” (p. 197).

El siguiente comando de la CLI de AWS crea una integración que envía un mensaje de Amazon SQS.

aws apigatewayv2 create-integration \

--api-id abcdef123 \
--integration-subtype SQS-SendMessage \
--integration-type AWS_PROXY \
--payload-format-version 1.0 \
--credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \
--request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody":
"$request.body.message"}'

Referencia del subtipo de integración

Los siguientes subtipos de integración son compatibles con las API HTTP.

Subtipos de integración
• EventBridge-PutEvents (p. 197)
• SQS-SendMessage (p. 198)
• SQS-ReceiveMessage (p. 198)
• SQS-DeleteMessage (p. 199)
• SQS-PurgeQueue (p. 199)
• AppConfig-GetConfiguration (p. 199)
• Kinesis-PutRecord (p. 199)
• StepFunctions-StartExecution (p. 200)
• StepFunctions: StartSyncExecution (p. 200)
• StepFunctions-StopExecution (p. 201)

EventBridge-PutEvents

Envía eventos personalizados a Amazon EventBridge para que puedan ajustarse a las reglas.

EventBridge-PutEvents 1.0

Parámetro Obligatorio

Detalle True

DetailType True

Fuente True

Tiempo Falso

EventBusName Falso

197
 Amazon API Gateway Guía del desarrollador
Integraciones

Parámetro Obligatorio

Recursos Falso

Región Falso

TraceHeader Falso

Para obtener más información, consulte PutEvents en la Referencia de la API de Amazon EventBridge.

SQS-SendMessage
Entrega un mensaje a la cola especificada.

SQS-SendMessage 1.0

Parámetro Obligatorio

QueueUrl True

MessageBody True

DelaySeconds Falso

MessageAttributes Falso

MessageDeduplicationId Falso

MessageGroupId Falso

MessageSystemAttributes Falso

Región Falso

Para obtener más información, consulte SendMessage en la Referencia de la API de Amazon Simple
Queue Service.

SQS-ReceiveMessage
Recupera uno o varios mensajes (hasta 10) de la cola especificada.

SQS-ReceiveMessage 1.0

Parámetro Obligatorio

QueueUrl True

AttributeNames Falso

MaxNumberOfMessages Falso

MessageAttributeNames Falso

ReceiveRequestAttemptId Falso

VisibilityTimeout Falso

WaitTimeSeconds Falso

Región Falso

198
 Amazon API Gateway Guía del desarrollador
Integraciones

Para obtener más información, consulte ReceiveMessage en la Referencia de la API de Amazon Simple
Queue Service.

SQS-DeleteMessage
Elimina el mensaje especificado de la cola especificada.

SQS-DeleteMessage 1.0
Parámetro Obligatorio

ReceiptHandle True

QueueUrl True

Región Falso

Para obtener más información, consulte DeleteMessage en la Referencia de la API de Amazon Simple
Queue Service.

SQS-PurgeQueue
Elimina todos los mensajes de la cola especificada.

SQS-PurgeQueue 1.0
Parámetro Obligatorio

QueueUrl True

Región Falso

Para obtener más información, consulte PurgeQueue en la Referencia de la API de Amazon Simple Queue
Service.

AppConfig-GetConfiguration
Recibe información acerca de una configuración.

AppConfig-GetConfiguration 1.0
Parámetro Obligatorio

Aplicación True

Entorno True

Configuración True

ClientId True

ClientConfigurationVersion Falso

Región Falso

Para obtener más información, consulte GetConfiguration en la Referencia de la API de AWS AppConfig.

Kinesis-PutRecord
Escribe un único registro de datos en un flujo de datos de Amazon Kinesis.

199
 Amazon API Gateway Guía del desarrollador
Integraciones

Kinesis-PutRecord 1.0

Parámetro Obligatorio

StreamName True

Datos True

PartitionKey True

SequenceNumberForOrdering Falso

ExplicitHashKey Falso

Región Falso

Para obtener más información, consulte PutRecord en la Referencia de la API de Amazon Kinesis Data
Streams.

StepFunctions-StartExecution

Comienza la ejecución de la máquina de estado.

StepFunctions-StartExecution 1.0

Parámetro Obligatorio

StateMachineArn True

Nombre Falso

Input Falso

Región Falso

Para obtener más información, consulte StartExecution en la Referencia de la API de AWS Step Functions.

StepFunctions: StartSyncExecution

Comienza la ejecución de la máquina de estado sincrónico.

StepFunctions: StartSyncExecution 1.0

Parámetro Obligatorio

StateMachineArn True

Nombre Falso

Input Falso

Región Falso

TraceHeader Falso

Para obtener más información, consulte StartSyncExecution en la Referencia de la API de AWS Step
Functions.

200
 Amazon API Gateway Guía del desarrollador
Integraciones

StepFunctions-StopExecution

Detiene una ejecución.

StepFunctions-StopExecution 1.0

Parámetro Obligatorio

ExecutionArn True

Causa Falso

Error Falso

Región Falso

Para obtener más información, consulte StopExecution en la Referencia de la API de AWS Step Functions.

Uso de integraciones privadas para API HTTP

Las integraciones privadas le permiten crear integraciones de API con recursos privados en una VPC,
como balanceadores de carga de aplicaciones o aplicaciones basadas en contenedores de Amazon ECS.

Puede exponer sus recursos en una VPC para que los clientes fuera de la VPC tengan acceso mediante
integraciones privadas. Puede controlar el acceso a la API mediante cualquiera de los métodos de
autorización (p. 182) admitidos por API Gateway.

Para crear una integración privada, primero debe crear un enlace de la VPC. Para obtener más
información acerca de los enlaces de la VPC, consulte Uso de enlaces de la VPC para API
HTTP (p. 202).

Después de crear un vínculo de VPC, puede configurar integraciones privadas que se conecten a un
balanceador de carga de aplicaciones, a un balanceador de carga de red o a recursos registrados con un
servicio de AWS Cloud Map.

Para crear una integración privada, todos los recursos deben ser propiedad de la misma cuenta de AWS
(incluido el balanceador de carga o el servicio de AWS Cloud Map, el enlace de VPC y la API HTTP).

De forma predeterminada, el tráfico de integración privada utiliza el protocolo HTTP. Puede especificar
tlsConfig si necesita tráfico de integración privada para utilizar HTTPS.
Note

Para integraciones privadas, API Gateway incluye la parte de etapa (p. 215) del punto de enlace
de la API en la solicitud a sus recursos backend. Por ejemplo, una solicitud a la etapa test de
una API incluye test/route-path en la solicitud a su integración privada.

Crear una integración privada mediante un balanceador de carga de aplicaciones

o un balanceador de carga de red
Antes de crear una integración privada, debe crear un enlace de la VPC. Para obtener más información
acerca de los enlaces de la VPC, consulte Uso de enlaces de la VPC para API HTTP (p. 202).

Para crear una integración privada con un balanceador de carga de aplicaciones o un balanceador de
carga de red, cree una integración de proxy HTTP, especifique el enlace de la VPC que se va a utilizar y
proporcione el ARN del agente de escucha del balanceador de carga.

Utilice el siguiente comando para crear una integración privada que se conecte a un equilibrador de carga
mediante un enlace de la VPC.

201
 Amazon API Gateway Guía del desarrollador
Integraciones

aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \

--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:elasticloadbalancing:us-east-2:123456789012:listener/app/my-
load-balancer/50dc6c495c0c9188/0467ef3c8400ae65
--payload-format-version 1.0

Crear una integración privada mediante la detección de servicios de AWS Cloud

Map
Antes de crear una integración privada, debe crear un enlace de la VPC. Para obtener más información
acerca de los enlaces de la VPC, consulte Uso de enlaces de la VPC para API HTTP (p. 202).

Para las integraciones con AWS Cloud Map, API Gateway utiliza DiscoverInstances para identificar
recursos. Puede utilizar parámetros de consulta para orientar recursos específicos. Los atributos de los
recursos registrados deben incluir direcciones IP y puertos. API Gateway distribuye las solicitudes entre los
recursos en buen estado que se devuelven desde DiscoverInstances. Para obtener más información,
consulte DiscoverInstances en la Referencia de la API de AWS Cloud Map.
Note

Si utiliza Amazon ECS para rellenar entradas en AWS Cloud Map, debe configurar su tarea de
Amazon ECS para utilizar registros SRV. Los registros "A" no son compatibles. Para obtener más
información, consulte Configuración del servicio para utilizar la detección de servicios en la guía
para desarrolladores de Amazon Elastic Container Service.

Para crear una integración privada con AWS Cloud Map, cree una integración de proxy de HTTP,
especifique el enlace de la VPC que desea utilizar y proporcione el ARN del servicio de AWS Cloud Map.

Utilice el siguiente comando para crear una integración privada que utilice la detección de servicios de
AWS Cloud Map para identificar recursos.

aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \

--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:servicediscovery:us-east-2:123456789012:service/srv-id?
stage=prod&deployment=green_deployment
--payload-format-version 1.0

Uso de enlaces de la VPC para API HTTP

Los enlaces de la VPC le permiten crear integraciones privadas que conectan las rutas de la API HTTP a
los recursos privados de una VPC, como balanceadores de carga de aplicaciones o aplicaciones basadas
en contenedores de Amazon ECS. Para obtener más información sobre la creación de integraciones
privadas, consulte Uso de integraciones privadas para API HTTP (p. 201).

Una integración privada utiliza el enlace de la VPC para encapsular las conexiones entre API Gateway y
los recursos de la VPC de destino. Puede reutilizar enlaces de la VPC a través de diferentes rutas y API.

Cuando crea un enlace de la VPC, API Gateway crea y administra interfaces de red elástica para el enlace
de la VPC en su cuenta. Este proceso puede tardar unos minutos. Cuando un enlace de VPC está listo
para usar, su estado cambia de PENDING a AVAILABLE.
Note

Si no se envía tráfico a través del enlace de la VPC durante 60 días, se convierte en INACTIVE.
Cuando un enlace de la VPC tiene el estado INACTIVE, API Gateway elimina todas las interfaces
de red del enlace de la VPC. Esto hace que las solicitudes de API que dependen del enlace de
la VPC fallen. Si las solicitudes de la API se reanudan, API Gateway reaprovisiona las interfaces

202
 Amazon API Gateway Guía del desarrollador
CORS

de red. Puede tardar unos minutos en crear las interfaces de red y reactivar el enlace de la VPC.
Puede utilizar el estado del enlace de la VPC para supervisar el estado del enlace de la VPC.

Crear un enlace de la VPC mediante la CLI de AWS

Utilice el siguiente comando para crear un enlace de la VPC. Para crear un enlace de la VPC, todos los
recursos involucrados deben ser propiedad de la misma cuenta de AWS.

aws apigatewayv2 create-vpc-link --name MyVpcLink \

--subnet-ids subnet-aaaa subnet-bbbb \
--security-group-ids sg1234 sg5678

Note
Los enlaces de la VPC son inmutables. Después de crear un enlace de la VPC, no puede cambiar
sus subredes o grupos de seguridad.

Eliminar un enlace de la VPC mediante la CLI de AWS

Utilice el siguiente comando para eliminar un enlace de la VPC.

aws apigatewayv2 delete-vpc-link --vpc-link-id abcd123

Configuración de CORS para una API HTTP

El uso compartido de recursos entre orígenes (CORS) es una característica de seguridad del navegador
que restringe las solicitudes HTTP que se inician desde secuencias de comandos que se ejecutan en el
navegador.

Por lo general, se necesita CORS para crear aplicaciones web que acceden a las API alojadas en
un dominio u origen distinto. Puede habilitar CORS para permitir las solicitudes a la API desde una
aplicación web alojada en un dominio distinto. Por ejemplo, si la API está alojada en https://
{api_id}.execute-api.{region}.amazonaws.com/ y desea llamar a la API desde una aplicación
web alojada en example.com, la API debe ser compatible con CORS.

Si configura CORS para una API, API Gateway envía automáticamente una respuesta a las solicitudes
OPTIONS preliminares, incluso si no hay ninguna ruta OPTIONS configurada para la API. En una
solicitud de CORS, API Gateway agrega los encabezados de CORS configurados a la respuesta de una
integración.
Note
Si configura CORS para una API, API Gateway ignora los encabezados de CORS devueltos por
su integración de backend.

Puede especificar los siguientes parámetros en una configuración de CORS.

Encabezados de CORS Propiedad de configuración de Valores de ejemplo

CORS

Access-Control-Allow-Origin allowOrigins • https://www.example.com

• * (permitir todos los orígenes)
• https://* (permitir cualquier
origen que comience por
https://)
• http://* (permitir cualquier
origen que comience por
http://)

203
 Amazon API Gateway Guía del desarrollador
Asignación de parámetros

Encabezados de CORS Propiedad de configuración de Valores de ejemplo

CORS

Access-Control-Allow-Credentials allowCredentials true

Access-Control-Expose-Headers exposeHeaders Fecha, x-api-id

Access-Control-Max-Age maxAge 300

Access-Control-Allow-Methods allowMethods GET, POST, DELETE, *

Access-Control-Allow-Headers allowHeaders Autorización, *

Configurar CORS para una API HTTP con una ruta $default y
un autorizador de JWT
Puede habilitar CORS y configurar la autorización para cualquier ruta de una API HTTP. Cuando habilita
CORS y la autorización para la ruta $default, hay que tener en cuenta algunas consideraciones
especiales. La ruta $default captura las solicitudes de todos los métodos y rutas que no haya definido
explícitamente, incluidas las solicitudes OPTIONS. Para admitir las solicitudes OPTIONS no autorizadas,
agregue una ruta OPTIONS /{proxy+} a su API que no requiera autorización. La ruta OPTIONS /
{proxy+} tiene mayor prioridad que la ruta $default. Como resultado, permite a los clientes enviar
solicitudes OPTIONS a su API sin autorización. Para obtener más información acerca de las prioridades de
enrutamiento, consulte Enrutamiento de solicitudes de la API (p. 181).

Configurar CORS para una API HTTP mediante la CLI de AWS

Puede utilizar el siguiente comando para habilitar las solicitudes de CORS de https://
www.example.com.

Example

aws apigatewayv2 update-api --api-id api-id --cors-configuration AllowOrigins="https://

www.example.com"

Para obtener más información, consulte CORS en la Referencia de la API de Amazon API Gateway
Versión 2.

Transformación de solicitudes y respuestas de API

Puede modificar las solicitudes API de los clientes antes de que lleguen a sus integraciones de backend.
También puede cambiar la respuesta de las integraciones antes de que API Gateway devuelva la
respuesta a los clientes. Utilice el mapeo de parámetros para modificar las solicitudes y respuestas de API
para API HTTP. Para utilizar el mapeo de parámetros, especifique los parámetros de solicitud o respuesta
de API que se van a modificar e indique cómo modificarlos.

Transformación de solicitudes de API

Los parámetros de solicitud se utilizan para cambiar las solicitudes antes de que lleguen a sus
integraciones de backend. Puede modificar encabezados, cadenas de consulta, la ruta de la solicitud o su
cuerpo.

Los parámetros de solicitud son un mapa de valor-clave. La clave identifica la ubicación del parámetro de
solicitud que se va a cambiar y cómo cambiarlo. El valor especifica los datos nuevos para el parámetro.

204
 Amazon API Gateway Guía del desarrollador
Asignación de parámetros

En la siguiente tabla se muestran las claves admitidas.

Claves del mapeo de parámetros

Tipo Sintaxis

Header append|overwrite|
remove:header.headername

Cadena de consulta append|overwrite|

remove:querystring.querystring-name

Ruta overwrite:path

En la siguiente tabla se muestran los valores admitidos que se pueden mapear a los parámetros.

Valores del mapeo de parámetros de solicitud

Tipo Sintaxis Notas

Valor del encabezado $request.header.name Los nombres del encabezado

no distinguen entre mayúsculas
y minúsculas. API Gateway
combina varios valores de
encabezado con comas,
por ejemplo "header1":
"value1,value2".
Algunos encabezados están
reservados. Para obtener
más información, consulte the
section called “Encabezados
reservados” (p. 207).

Valor de la cadena de consulta $request.querystring.name Los nombres de las cadenas

de consulta distinguen
mayúsculas y minúsculas.
API Gateway combina varios
valores con comas, por
ejemplo "querystring1"
"Value1,Value2".

Cuerpo de la solicitud $request.body.name Una expresión de ruta

JSON. El descenso recursivo
($request.body..name)
y las expresiones de filtro
(?(expression)) no son
compatibles.
Note

Cuando se especifica
una ruta JSON, API
Gateway trunca
el cuerpo de la
solicitud en 100 KB
y, a continuación,
aplica la expresión
de selección. Para

205
 Amazon API Gateway Guía del desarrollador
Asignación de parámetros

Tipo Sintaxis Notas

enviar cargas de más
de 100 KB, especifique
$request.body.

Ruta de solicitud $request.path La ruta de la solicitud, sin el

nombre de la etapa.

Parámetro de ruta $request.path.name El valor de un parámetro de ruta

en la solicitud. Por ejemplo, si
la ruta es /pets/{petId},
puede mapear el parámetro
petId de la solicitud con
$request.path.petId.

Variable de contexto $contexto.variableName El valor de una variable de

contexto (p. 228).

Variable de etapa $stageVariables.variableName El valor de una variable de

etapa (p. 216).

Valor estático string Un valor constante.

Transformación de respuestas de API

Los parámetros de respuesta se utilizan para transformar la respuesta HTTP de una integración de
backend antes de devolver la respuesta a los clientes. Puede modificar los encabezados o el código de
estado de una respuesta antes de que API Gateway devuelva la respuesta a los clientes.

Los parámetros de respuesta se configuran para cada código de estado que devuelve la integración. Los
parámetros de respuesta son un mapa de valor-clave. La clave identifica la ubicación del parámetro de
solicitud que se va a cambiar y cómo cambiarlo. El valor especifica los datos nuevos para el parámetro.

En la siguiente tabla se muestran las claves admitidas.

Claves del mapeo de parámetros de respuesta

Tipo Sintaxis

Header append|overwrite|
remove:header.headername

Código de estado overwrite:statuscode

En la siguiente tabla se muestran los valores admitidos que se pueden mapear a los parámetros.

Valores del mapeo de parámetros de respuesta

Tipo Sintaxis Notas

Valor del encabezado $request.header.name Los nombres del encabezado

no distinguen entre mayúsculas
y minúsculas. API Gateway
combina varios valores de
encabezado con comas,
por ejemplo "header1":

206
 Amazon API Gateway Guía del desarrollador
Asignación de parámetros

Tipo Sintaxis Notas

"value1,value2".
Algunos encabezados están
reservados. Para obtener
más información, consulte the
section called “Encabezados
reservados” (p. 207).

Cuerpo de respuesta $response.body.name Una expresión de ruta

JSON. El descenso recursivo
($response.body..name)
y las expresiones de filtro
(?(expression)) no son
compatibles.
Note

Cuando se especifica
una ruta JSON, API
Gateway trunca
el cuerpo de la
solicitud en 100 KB
y, a continuación,
aplica la expresión
de selección. Para
enviar cargas de más
de 100 KB, especifique
$response.body.

Variable de contexto $contexto.variableName El valor de una variable de

contexto (p. 228) compatible.

Variable de etapa $stageVariables.variableName El valor de una variable de

etapa (p. 216).

Valor estático string Un valor constante.

Encabezados reservados
Los siguientes encabezados están reservados. No puede configurar mapeos de solicitud o respuesta para
estos encabezados.

• access-control-*
• apigw-*
• Autorización
• Conexión
• Content-Encoding
• Longitud del contenido
• Content-Location
• Forwarded
• Keep-Alive
• Origen
• Proxy-Authenticate
• Proxy-Authorization

207
 Amazon API Gateway Guía del desarrollador
Asignación de parámetros

• TE
• Trailers
• Transfer-Encoding
• Upgrade
• x-amz-*
• x-amzn-*
• X-Forwarded-For
• X-Forwarded-Host
• X-Forwarded-Proto
• Via

Ejemplos
En los siguientes ejemplos de la CLI de AWS se configuran mapeos de parámetros. Por ejemplo, plantillas
de AWS CloudFormation, consulte GitHub.

Agregar un encabezado a una solicitud de API

En el siguiente ejemplo se agrega un encabezado denominado header1 a una solicitud de API antes de
que llegue a su integración de backend. API Gateway rellena el encabezado con el ID de solicitud.

aws apigatewayv2 create-integration \

--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header1": "$context.requestId" }'

Cambiar el nombre de un encabezado de solicitud

En el ejemplo siguiente se cambia el nombre de un encabezado de solicitud de header1 a header2.

aws apigatewayv2 create-integration \

--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header2": "$request.header.header1",
"remove:header.header1": "''"}' }

Cambiar la respuesta de una integración

En el siguiente ejemplo se configuran los parámetros de respuesta para una integración. Cuando las
integraciones devuelven un código de estado 500, API Gateway cambia el código de estado a 403 y
agrega header11 a la respuesta. Cuando la integración devuelve un código de estado 404, API Gateway
agrega un error encabezado a la respuesta.

aws apigatewayv2 create-integration \

--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \

208
 Amazon API Gateway Guía del desarrollador
OpenAPI

--integration-uri 'https://api.example.com' \
--integration-method ANY \
--response-parameters '{"500" : {"append:header.header1": "$context.requestId",
"overwrite:statuscode" : "403"}, "404" : {"append:header.error" :
"$stageVariables.environmentId"} }

Eliminar mapeos de parámetros configurados

El siguiente comando de ejemplo elimina los parámetros de solicitud configurados previamente para
append:header.header1. También elimina los parámetros de respuesta configurados previamente para
un código de estado 200.

aws apigatewayv2 update-integration \

--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters {"append:header.header1" : ""} \
--response-parameters {"200" : {}}

Uso de definiciones de OpenAPI para API HTTP

Para definir su API HTTP puede utilizar un archivo de definición de OpenAPI 3.0. A continuación, puede
importar la definición a API Gateway para crear una API. Para obtener más información sobre las
extensiones de API Gateway para OpenAPI, consulte Extensiones de OpenAPI (p. 771).

Importación de una API HTTP

Para crear una API HTTP puede importar un archivo de definición de OpenAPI 3.0.

Para migrar desde una API de REST a una API HTTP, puede exportar la API de REST como un archivo
de definición de OpenAPI 3.0. A continuación, importe la definición de la API como una API HTTP. Para
obtener más información acerca de cómo exportar una API de REST, consulte Exportación de una API
REST desde API Gateway (p. 507).
Note

Las API HTTP admiten las mismas variables de AWS que las API de REST. Para obtener más
información, consulte Variables de AWS para la importación de OpenAPI (p. 506).

Importar información de validación

Al importar una API, API Gateway proporciona tres categorías de información de validación.

Información

Una propiedad es válida de acuerdo con la especificación de OpenAPI, pero dicha propiedad no es
compatible con las API HTTP.

Por ejemplo, el siguiente fragmento de OpenAPI 3.0 genera información en la importación porque
las API HTTP no son compatibles con la validación de solicitudes. API Gateway ignora los campos
requestBody y schema.

"paths": {
"/": {
"get": {

209
 Amazon API Gateway Guía del desarrollador
OpenAPI

"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Body"
}
}
}
}
}
}
...
},
"components": {
"schemas": {
"Body": {
"type": "object",
"properties": {
"key": {
"type": "string"
}
}
}
...
}
...
}

Advertencia

Una propiedad o estructura no es válida de acuerdo con la especificación de OpenAPI, pero no

bloquea la creación de API. Puede especificar si API Gateway debe hacer caso omiso de estas
advertencias y seguir creando la API o dejar de crear la API según las advertencias.

El siguiente documento de OpenAPI 3.0 genera advertencias en la importación porque las API HTTP
solo son compatibles con integraciones de proxy de Lambda y proxy de HTTP.

"x-amazon-apigateway-integration": {
"type": "AWS",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
}

Error

La especificación OpenAPI no es válida o es incorrecta. API Gateway no puede crear ningún recurso a
partir del documento con formato incorrecto. Debe corregir los errores y, a continuación, intentarlo de
nuevo.

La siguiente definición de API genera errores en la importación porque las API HTTP solo son
compatibles con la especificación de OpenAPI 3.0.

{
"swagger": "2.0.0",
"info": {

210
 Amazon API Gateway Guía del desarrollador
OpenAPI

"title": "My API",

"description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
"version": "1.0"
}
...
}

Como otro ejemplo, mientras que OpenAPI permite a los usuarios definir una API con varios requisitos
de seguridad asociados a una operación en particular, API Gateway no admite esto. Cada operación
solo puede tener una autorización de IAM, un autorizador de Lambda o un autorizador JWT. Cuando
se intenta modelar varios requisitos de seguridad, se produce un error.

Importar una API con la CLI de AWS

El siguiente comando importa el archivo de definición de OpenAPI 3.0 api-definition.json como una
API HTTP.

Example

aws apigatewayv2 import-api --body file://api-definition.json

Example

Puede importar el siguiente ejemplo de definición de OpenAPI 3.0 para crear una API HTTP.

{
"openapi": "3.0.1",
"info": {
"title": "Example Pet Store",
"description": "A Pet Store API.",
"version": "1.0"
},
"paths": {
"/pets": {
"get": {
"operationId": "GET HTTP",
"parameters": [
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}

211
 Amazon API Gateway Guía del desarrollador
OpenAPI

},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pets"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
},
"post": {
"operationId": "Create Pet",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPet"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPetResponse"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "POST",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
}
},
"/pets/{petId}": {
"get": {
"operationId": "Get Pet",
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"schema": {
"type": "string"

212
 Amazon API Gateway Guía del desarrollador
OpenAPI

}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/
{petId}",
"payloadFormatVersion": 1.0
}
}
}
},
"x-amazon-apigateway-cors": {
"allowOrigins": [
"*"
],
"allowMethods": [
"GET",
"OPTIONS",
"POST"
],
"allowHeaders": [
"x-amzm-header",
"x-apigateway-header",
"x-api-key",
"authorization",
"x-amz-date",
"content-type"
]
},
"components": {
"schemas": {
"Pets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pet"
}
},
"Empty": {
"type": "object"
},
"NewPetResponse": {
"type": "object",
"properties": {
"pet": {
"$ref": "#/components/schemas/Pet"

213
 Amazon API Gateway Guía del desarrollador
OpenAPI

},
"message": {
"type": "string"
}
}
},
"Pet": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"price": {
"type": "number"
}
}
},
"NewPet": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/PetType"
},
"price": {
"type": "number"
}
}
},
"PetType": {
"type": "string",
"enum": [
"dog",
"cat",
"fish",
"bird",
"gecko"
]
}
}
}
}

Exportación de una API HTTP desde API Gateway

Después de crear una API HTTP, puede exportar una definición de OpenAPI 3.0 de su API desde API
Gateway. Puede elegir una etapa que exportar o exportar la configuración más reciente de su API.
También puede importar una definición de API exportada a API Gateway para crear otra API idéntica. Para
obtener más información sobre la importación de definiciones de API, consulte Importación de una API
HTTP (p. 209).

Exportar una definición de OpenAPI 3.0 de una etapa mediante la CLI de AWS
El siguiente comando exporta una definición de OpenAPI de una etapa de API denominada prod a
un archivo YAML denominado stage-definition.yaml. El archivo de definición exportado incluye
extensiones de API Gateway (p. 771) de forma predeterminada.

aws apigatewayv2 export-api \

--api-id api-id \
--output-type YAML \

214
 Amazon API Gateway Guía del desarrollador
Publicación

--specification OAS30 \
--stage-name prod \
stage-definition.yaml

Exportar una definición de OpenAPI 3.0 de los últimos cambios de la API

mediante la CLI de AWS
El siguiente comando exporta una definición de OpenAPI de una API HTTP a un archivo JSON
denominado latest-api-definition.json. Dado que el comando no especifica una etapa,
API Gateway exporta la configuración más reciente de la API, con independencia de que se haya
implementado en una etapa o no. El archivo de definición exportado no incluye extensiones de API
Gateway (p. 771).

aws apigatewayv2 export-api \

--api-id api-id \
--output-type JSON \
--specification OAS30 \
--no-include-extensions \
latest-api-definition.json

Para obtener más información, consulte ExportAPI en la Referencia de la API de Amazon API Gateway
Versión 2.

Publicación de una API HTTP para que los clientes

la invoquen
Puede utilizar etapas y nombres de dominio personalizados para publicar su API para que los clientes la
invoquen.

Una referencia lógica a un estado del ciclo de vida de la API (por ejemplo, dev, prod, beta o v2). Cada
etapa es una referencia con nombre a una implementación de la API y está disponible para que las
aplicaciones cliente realicen las llamadas. Puede configurar diferentes integraciones y configuraciones
para cada etapa de una API.

Puede usar nombres de dominio personalizados para proporcionar una URL más simple e intuitiva para
que los clientes invoquen su API en vez de la URL predeterminada https://api-id.execute-
api.region.amazonaws.com/stage.

Temas
• Trabajar con etapas para API HTTP (p. 215)
• Configuración de nombres de dominio personalizados para API HTTP (p. 217)

Trabajar con etapas para API HTTP

Una referencia lógica a un estado del ciclo de vida de la API (por ejemplo, dev, prod, beta o v2). Las
etapas de API se identifican por su ID de API y su nombre de etapa, y se incluyen en la URL que utiliza
para invocar la API. Cada etapa es una referencia con nombre a una implementación de la API y está
disponible para que las aplicaciones cliente realicen las llamadas.

Puede crear una etapa $default que se ofrezca desde la base de la URL de su API, por ejemplo,
https://{api_id}.execute-api.{region}.amazonaws.com/. Utilice esta URL para invocar una
etapa de la API.

215
 Amazon API Gateway Guía del desarrollador
Etapas

Una implementación es una instantánea de la configuración de la API. Después de implementar una API
en una etapa, esta está disponible para que los clientes la invoquen. Debe implementar una API para que
los cambios surtan efecto. Si habilita implementaciones automáticas, los cambios realizados en una API se
liberarán automáticamente.

Variables de etapa
Las variables de etapa son pares clave-valor que se pueden definir para una etapa de una API HTTP.
Actúan como variables de entorno y se pueden usar en la configuración de la API.

Por ejemplo, puede definir una variable de etapa y, a continuación, establecer su valor como extremo
HTTP para una integración de proxy HTTP. Posteriormente, puede hacer referencia al punto de enlace
mediante el nombre de variable de etapa asociada. Al hacer esto, puede usar la misma configuración de
API con un punto de enlace diferente en cada etapa. Del mismo modo, puede utilizar variables de etapa
para especificar una integración de funciones de AWS Lambda diferente para cada etapa de su API.
Note

Las variables de etapa no están pensadas a fin de ser utilizadas para datos confidenciales,
como credenciales. Para transferir datos confidenciales a integraciones, utilice un autorizador de
AWS Lambda. Puede pasar datos confidenciales a integraciones en la salida del autorizador de
Lambda. Para obtener más información, consulte the section called “Formato de respuesta del
autorizador de Lambda” (p. 184).

Ejemplos
Para utilizar una variable de etapa para personalizar el punto de enlace de integración HTTP, primero
debe establecer el nombre y el valor de la variable de etapa (por ejemplo, url) con un valor de
example.com. A continuación, configure una integración de proxy HTTP. En lugar de escribir la URL
del punto de enlace, puede indicar a API Gateway que use el valor de la variable de etapa, http://
${stageVariables.url}. Este valor indica a API Gateway que sustituya la variable de etapa ${} en el
tiempo de ejecución en función de la etapa de la API.

Puede hacer referencia a variables de etapa de una manera similar para especificar un nombre de función
de Lambda o un ARN de rol de AWS.

Cuando especifica el nombre de una función de Lambda como un valor de variable de etapa, debe
configurar manualmente los permisos en la función de Lambda. Para ello puede utilizar la interfaz de línea
de comandos de AWS (CLI de AWS).

aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-

name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/
resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action
lambda:InvokeFunction

Referencia de variables de etapa de API Gateway

URI de integración HTTP
Puede utilizar una variable de etapa como parte de una URI de integración HTTP, tal y como se muestra
en los siguientes ejemplos.

• Una URI completa sin protocolo: http://${stageVariables.<variable_name>}

• Un dominio completo: http://${stageVariables.<variable_name>}/resource/operation
• Un subdominio: http://${stageVariables.<variable_name>}.example.com/resource/
operation
• Una ruta: http://example.com/${stageVariables.<variable_name>}/bar

216
 Amazon API Gateway Guía del desarrollador
Nombres de dominio personalizados

• Una cadena de consulta: http://example.com/foo?q=${stageVariables.<variable_name>}

Funciones de Lambda
Puede utilizar una variable de etapa en lugar de un nombre de función de Lambda o alias, como se
muestra en los ejemplos siguientes.

• arn:aws:apigateway:<region>:lambda:path/2015-03-31/
functions/arn:aws:lambda:<region>:<account_id>:function:
${stageVariables.<function_variable_name>}/invocations
• arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/
arn:aws:lambda:<region>:<account_id>:function:<function_name>:
${stageVariables.<version_variable_name>}/invocations

Note
Para utilizar una variable de etapa para una función de Lambda, la función debe estar en la misma
cuenta que la API. Las variables de etapa no admiten funciones de Lambda entre cuentas.

Credenciales de integración con AWS

Puede utilizar una variable de etapa como parte de un ARN de credenciales de usuario o rol de AWS,
como se muestra en el siguiente ejemplo.

• arn:aws:iam::<account_id>:${stageVariables.<variable_name>}

Configuración de nombres de dominio personalizados

para API HTTP
Losnombres de dominio personalizados son direcciones URL más sencillas e intuitivas que puede
proporcionar a los usuarios de la API.

Después de implementar la API, usted (y sus clientes) puede invocar la API utilizando la URL base
predeterminada con el siguiente formato:

https://api-id.execute-api.region.amazonaws.com/stage

donde api-id lo genera API Gateway, region (región de AWS) lo especifica usted al crear la API y
stage lo especifica usted al implementar la API.

La parte del nombre de host de la URL (es decir, api-id.execute-api.region.amazonaws.com)

hace referencia a un punto de enlace de la API. El punto de enlace de la API predeterminado puede ser
difícil de recordar y no es muy descriptivo.

Con los nombres de dominio personalizados, puede configurar el nombre de host de la API y elegir una
ruta base (por ejemplo, myservice) para asignarle una URL alternativa. Por ejemplo, una URL base de la
API más simple puede ser:

https://api.example.com/myservice

Si no establece ningún mapeo de ruta base bajo un nombre de dominio personalizado, la URL
base de la API resultante será la misma que la del dominio personalizado (por ejemplo, https://
api.example.com). En este caso, el nombre de dominio personalizado no puede admitir más de una
API.

217
 Amazon API Gateway Guía del desarrollador
Nombres de dominio personalizados

Note
Los dominios personalizados se pueden asociar con API de REST y API HTTP. Puede utilizar
las API de API Gateway versión 2 para crear y administrar nombres de dominio regionales
personalizados para API de REST y API HTTP.
Para las API HTTP, TLS 1.2 es la única versión de TLS admitida.

Registrar un nombre de dominio

Debe disponer de un nombre de dominio de Internet registrado para poder crear nombres de dominio
personalizados para sus API. Si es necesario, puede registrar un dominio de Internet con Amazon Route
53 o un registrador de dominios de un tercero de su elección. Un nombre de dominio personalizado de la
API puede ser el nombre de un subdominio o el dominio raíz (lo que recibe el nombre de "ápex de zona")
de un dominio de Internet registrado.

Después de crear un nombre de dominio personalizado en API Gateway, debe crear o actualizar el registro
de recursos del proveedor de DNS para asignarlo al punto de enlace de la API. Si no se realiza este
mapeo, las solicitudes de API vinculadas al nombre de dominio personalizado no pueden llegar a API
Gateway.

Nombres de dominio personalizados regionales

Cuando se crea un nombre de dominio personalizado para una API de región, API Gateway crea un
nombre de dominio de región para la API. Debe establecer un registro DNS para asignar el nombre de
dominio personalizado al nombre de dominio regional. También debe proporcionar un certificado para el
nombre de dominio personalizado.

Nombres de dominio personalizados comodín

Con los nombres de dominio personalizados comodín, puede admitir un número casi infinito de nombres
de dominio sin exceder el límite predeterminado (p. 840). Por ejemplo, puede dar a cada uno de los
clientes su propio nombre de dominio, customername.api.example.com.

Para crear un nombre de dominio personalizado comodín, especifique un comodín (*) como primer
subdominio de un dominio personalizado que represente todos los subdominios posibles de un dominio
raíz.

Por ejemplo, el nombre de dominio personalizado comodín *.example.com produce subdominios como
a.example.com, b.example.com y c.example.com, que enrutan al mismo dominio.

Los nombres de dominio personalizados comodín admiten configuraciones distintas de los nombres de
dominio personalizados estándar de API Gateway. Por ejemplo, en una sola cuenta de AWS, puede
configurar *.example.com y a.example.com para que se comporten de manera diferente.

Para crear un nombre de dominio personalizado comodín, debe proporcionar un certificado emitido por
ACM que se haya validado utilizando el método DNS o de validación de correo electrónico.
Note
No se puede crear un nombre de dominio personalizado comodín si una cuenta de AWS diferente
ha creado un nombre de dominio personalizado que entra en conflicto con el nombre de dominio
personalizado comodín. Por ejemplo, si la cuenta A ha creado a.example.com, la cuenta B no
puede crear el nombre de dominio personalizado comodín *.example.com.
Si la cuenta A y la cuenta B comparten un propietario, puede ponerse en contacto con el Centro
de soporte de AWS para solicitar una excepción.

Certificados para nombres de dominio personalizados

Para proporcionar un certificado para un nombre de dominio personalizado en una región donde se admita
ACM, debe solicitar a ACM un certificado. Para proporcionar un certificado para un nombre de dominio

218
 Amazon API Gateway Guía del desarrollador
Proteger

personalizado de región en una región donde no se admita ACM, debe importar un certificado en API
Gateway en esa región.

Para importar un certificado SSL/TLS, debe proporcionar el cuerpo del certificado SSL/TLS con formato
PEM, su clave privada y la cadena de certificados para el nombre de dominio personalizado. Los
certificados almacenados en ACM se identifican mediante su ARN. Para utilizar un certificado administrado
por AWS para un nombre de dominio, solo tiene que hacer referencia a su ARN.

ACM facilita la configuración y el uso de un nombre de dominio personalizado para una API. El usuario
crea un certificado para el nombre de dominio dado (o importa un certificado), configura el nombre de
dominio en API Gateway con el ARN del certificado proporcionado por ACM y asigna una ruta base bajo
el nombre de dominio personalizado a una etapa implementada de la API. Con los certificados emitidos
por ACM no tiene que preocuparse de si se exponen datos del certificado confidenciales, como la clave
privada.

Para obtener información detallada sobre la configuración de un nombre de dominio personalizado,

consulte Obtención de certificados listos en AWS Certificate Manager (p. 545) y Configuración de un
nombre de dominio regional personalizado en API Gateway (p. 558).

Desactivación del punto de enlace predeterminado para una API

HTTP
De forma predeterminada, los clientes pueden invocar su API mediante el punto de enlace execute-api
que API Gateway genera para su API. Para asegurarse de que los clientes solo puedan acceder a su API
mediante un nombre de dominio personalizado, deshabilite el punto de enlace predeterminado execute-
api.
Note

Cuando deshabilita el punto de enlace predeterminado, esto afecta a todas las etapas de una API.

El siguiente comando de la CLI de AWS desactiva el punto de enlace predeterminado para una API HTTP.

aws apigatewayv2 update-api \

--api-id abcdef123 \
--disable-execute-api-endpoint

Después de desactivar el punto de enlace predeterminado, debe implementar la API para que el cambio
surta efecto, salvo que se hayan habilitado las implementaciones automáticas.

El siguiente comando de la CLI de AWS crea una implementación.

aws apigatewayv2 create-deployment \

--api-id abcdef123 \
--stage-name dev

Protección de la API HTTP

API Gateway proporciona una serie de formas de proteger su API de ciertas amenazas, como usuarios
malintencionados o picos de tráfico. Puede proteger su API mediante estrategias como establecer límites
de limitación y habilitar TLS mutuas. En esta sección puede aprender cómo habilitar estas capacidades
mediante API Gateway.

Temas
• Solicitudes de limitación controlada a su API HTTP (p. 220)
• Configuración de la autenticación TLS mutua para una API HTTP (p. 221)

219
 Amazon API Gateway Guía del desarrollador
Limitación controlada

Solicitudes de limitación controlada a su API HTTP

Para evitar que la API resulte colapsada por un enorme número de solicitudes, Amazon API Gateway
limita las solicitudes a la API utilizando el algoritmo de bucket de tokens, donde un token da cuenta de una
solicitud. En concreto, API Gateway establece un ratio de solicitudes en estado estable y una ráfaga de
envíos de solicitudes para todas las API de su cuenta, por región. En el algoritmo del bucket de tokens,
una ráfaga es el tamaño máximo del bucket.

Cuando los envíos de solicitudes superan los límites de ratio de solicitudes en estado estable y de
ráfaga, API Gateway no acepta las solicitudes que exceden el límite y devuelve respuestas de error 429
Too Many Requests al cliente. Cuando un cliente recibe estas respuestas de error, el cliente puede
reenviar las solicitudes que han producido un error de forma que limita el ratio y los límites de solicitudes
controladas de API Gateway.

Limitaciones de nivel de cuenta por región

De forma predeterminada, API Gateway limita la tasa de solicitudes de estado estacionario por segundo
(rps) en todas las API de una cuenta de AWS, por región. También limita la ráfaga (es decir, el tamaño
máximo del bucket) en todas las API dentro de una cuenta de AWS, por región. En API Gateway, el
límite de ráfaga se corresponde con el número máximo de envíos de solicitudes simultáneas que API
Gateway; puede abordar en un momento determinado sin devolver respuestas de error 429 Too
Many Requests. Para obtener más información sobre la limitación de cuotas, consulte Cuotas y notas
importantes (p. 840).

Para ayudarle a entender estas restricciones de la limitación controlada, aquí se presenta un límite de
ráfaga de 5000 y un límite de la tasa de nivel de cuenta de 10 000 solicitudes por segundo en la región:

• Si un intermediario envía 10 000 solicitudes en un período de un segundo de manera uniforme (por

ejemplo, 10 solicitudes cada milisegundo), API Gateway procesa todas las solicitudes sin cancelar
ninguna.
• Si el intermediario envía 10 000 solicitudes en el primer milisegundo, API Gateway sirve 5000 de estas
solicitudes y limita el resto al periodo de un segundo.
• Si el intermediario envía 5 000 solicitudes en el primer milisegundo y, a continuación, distribuye de
manera uniforme otras 5 000 solicitudes en los 999 milisegundos restantes (por ejemplo, unas 5
solicitudes cada milisegundo), API Gateway procesa las 10 000 solicitudes en el periodo de un segundo
sin devolver respuestas de error 429 Too Many Requests.
• Si el intermediario envía 5 000 solicitudes en el primer milisegundo y espera hasta el milisegundo
101 para enviar otras 5 000, API Gateway procesa 6 000 solicitudes y limita el resto al periodo de un
segundo. Esto ocurre porque, a una velocidad de 10 000 rps, API Gateway ha servido 1000 solicitudes
después de los primeros 100 milisegundos y, por lo tanto, ha vaciado el bucket por la misma cantidad.
Del próximo pico de 5000 solicitudes, 1000 llenan el bucket y están en cola para ser procesadas. Las
otras 4000 superan la capacidad de bucket y se descartan.
• Si el intermediario envía 5000 solicitudes en el primer milisegundo, envía 1000 solicitudes en
milisegundo 101 y, a continuación, distribuye de manera uniforme otras 4000 solicitudes a través de los
899 milisegundos restantes, API Gateway procesa las 10 000 solicitudes en el periodo de un segundo
sin limitación controlada.

De forma más general, en un momento dado, cuando un bucket contiene b y su capacidad máxima es B, el
número máximo de tokens adicionales que se pueden añadir al bucket es #=B-b. Este número máximo de
tokens adicionales se corresponde con el número máximo de solicitudes simultáneas adicionales que un
cliente puede enviar sin recibir respuestas de error 429.

En general, # varía con el tiempo. El valor oscila entre cero cuando el bucket está lleno (es decir, b=B) y B
cuando el bucket está vacío (es decir, b=0). El intervalo depende de la velocidad de procesamiento de las
solicitudes (la velocidad a la que los tokens se eliminan del bucket) y de la velocidad del límite de ratio (la
velocidad a la que los tokens se añaden al bucket).

220
 Amazon API Gateway Guía del desarrollador
TLS mutua

A continuación, se muestra un diagrama de los comportamientos generales de #, el número máximo de

solicitudes simultáneas adicionales, como una función de tiempo. El diagrama asume que los tokens de
bucket disminuyen a una tasa combinada de r a partir de un bucket vacío.

El límite de tasa de nivel de cuenta por región se puede aumentar previa solicitud. Para solicitar un
aumento de los límites de nivel de cuenta, póngase en contacto con el Centro de soporte de AWS. Para
obtener más información, consulte Cuotas de Amazon API Gateway y notas importantes (p. 840).

Limitación controlada de nivel de ruta

Puede definir la limitación controlada del nivel de ruta para invalidar los límites de limitación controlada
de las solicitudes de nivel de cuenta de una determinada etapa o de las rutas individuales de la API. Los
límites de la limitación controlada de ruta predeterminada se rigen por los límites de frecuencia de nivel
de cuenta, aunque defina los límites de la limitación controlada de ruta predeterminada por encima de los
límites de nivel de cuenta.

Puede configurar la limitación controlada de nivel de ruta mediante la CLI de AWS. El siguiente comando
configura la limitación controlada de nivel de ruta para la etapa y la ruta especificadas de una API.

aws apigatewayv2 update-stage \

--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"GET /pets":
{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'

Configuración de la autenticación TLS mutua para una

API HTTP
La autenticación TLS mutua requiere la autenticación bidireccional entre el cliente y el servidor. Con la TLS
mutua, los clientes deben presentar certificados X.509 para verificar su identidad y acceder a su API. La
TLS mutua es un requisito frecuente para el Internet de las cosas (IOT) y las aplicaciones entre empresas.

Para habilitar la TLS mutua para una API HTTP, debe configurar un nombre de dominio personalizado
para su API. Puede habilitar la TLS mutua para un nombre de dominio personalizado y, a continuación,
proporcionar el nombre de dominio personalizado a los clientes. Para acceder a una API mediante un
nombre de dominio personalizado que tenga habilitada la TLS mutua, los clientes deben presentar
certificados en los que confíe en las solicitudes de API.

221
 Amazon API Gateway Guía del desarrollador
TLS mutua

Puede utilizar TLS mutuo junto con otros métodos de autorización y autenticación (p. 182) compatibles
con API Gateway. API Gateway reenvía los certificados que los clientes proporcionan a los autorizadores
de Lambda y a las integraciones de Lambda backend.
Important
De forma predeterminada, los clientes pueden invocar su API mediante el punto de enlace
execute-api que API Gateway genera para su API. Para asegurarse de que los clientes solo
puedan acceder a su API mediante un nombre de dominio personalizado con la TLS mutua,
deshabilite el punto de enlace execute-api predeterminado. Para obtener más información,
consulte the section called “Deshabilitación del punto de enlace predeterminado” (p. 219).

Configuración de la TLS mutua para un nombre de dominio

personalizado
Para utilizar la TLS mutua, cree un almacén de confianza de certificados X.509 en los que confíe para
acceder a su API. Los certificados pueden ser de autoridades de certificación públicas o privadas. Los
certificados pueden tener una longitud máxima de cadena de cuatro. También puede proporcionar
certificados autofirmados. Se admiten los siguientes:

• SHA-256 o más seguro

• RSA-2048 o más seguro
• ECDSA-256 o más seguro

API Gateway valida una serie de propiedades de certificado. Puede utilizar autorizadores de Lambda para
realizar comprobaciones adicionales cuando un cliente invoque una API, incluida la comprobación de si un
certificado se ha revocado. API Gateway valida las siguientes propiedades de certificado:

Validación Descripción

Sintaxis X.509 El certificado debe cumplir los requisitos de sintaxis

X.509.

Integridad El contenido del certificado no debe haberse

alterado con respecto al firmado por la entidad de
certificación del almacén de confianza.

Validez El período de validez del certificado debe ser

actual.

Encadenamiento de nombres/encadenamiento de Los nombres y asuntos de los certificados deben

claves formar una cadena ininterrumpida. Los certificados
pueden tener una longitud máxima de cadena de
cuatro.

Cargue el almacén de confianza a un bucket de Amazon S3 en un solo archivo.

Example certificates.pem

-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>

222
 Amazon API Gateway Guía del desarrollador
TLS mutua

-----END CERTIFICATE-----
...

El siguiente comando de la CLI de AWS carga certificates.pem en Amazon S3.

aws s3 cp certificates.pem s3://bucket-name

Después de cargar su almacén de confianza en Amazon S3, puede configurar su nombre de dominio
personalizado para que utilice TLS mutua.

Cuando crea un nombre de dominio personalizado que tiene la TLS mutua habilitada o actualiza un
dominio personalizado para utilizar un nuevo almacén de confianza, API Gateway devuelve advertencias
si los certificados del almacén de confianza no son válidos. La TLS mutua aún está habilitada, pero es
posible que algunos clientes no puedan acceder a la API. Para resolver advertencias, cargue un nuevo
almacén de confianza en S3 y, a continuación, actualice el nombre de dominio para utilizar la nueva
versión. Para obtener más información, consulte the section called “Solución de problemas de advertencias
de certificados” (p. 224).
Note
Para habilitar TLS mutuo, el nombre de dominio debe utilizar un certificado de servidor de
confianza pública emitido por AWS Certificate Manager.

aws apigatewayv2 create-domain-name \

--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-
west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name

Después de crear el nombre de dominio, debe configurar los registros DNS y las asignaciones de ruta base
para las API. Para obtener más información, consulte Configuración de un nombre de dominio regional
personalizado en API Gateway (p. 558).

Invocar una API mediante un nombre de dominio personalizado

que requiere la TLS mutua
Para invocar una API con la TLS mutua habilitada, los clientes deben presentar un certificado de confianza
en la solicitud de la API. El siguiente ejemplo de comando curl envía una solicitud a api.example.com,
que incluye my-cert.pem en la solicitud. my-key.key es la clave privada del certificado.

curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com

Su API solo se invoca si su almacén de confianza confía en el certificado. Si el certificado no es de

confianza, caducó o no utiliza un algoritmo compatible, API Gateway no desaprueba el protocolo de enlace
TLS y niega la solicitud con un código de estado 403.
Note
API Gateway no comprueba si se ha revocado un certificado.

Actualización de su almacén de confianza

Para actualizar los certificados de su almacén de confianza, cargue un nuevo paquete de certificados en
Amazon S3 y, a continuación, actualice el nombre de dominio personalizado para utilizar la nueva versión.

Utilice el control de versiones de Amazon S3 para mantener varias versiones de su almacén de confianza.
Cuando actualiza el nombre de dominio personalizado para utilizar una nueva versión del almacén de
confianza, API Gateway devuelve advertencias si los certificados no son válidos.

223
 Amazon API Gateway Guía del desarrollador
Monitoreo

Note

API Gateway produce advertencias de certificado solo cuando actualiza el nombre de dominio
para utilizar un nuevo almacén de confianza. API Gateway no le notifica si caduca un certificado
cargado anteriormente.

El siguiente comando de la CLI de AWS actualiza un nombre de dominio personalizado para utilizar una
nueva versión del almacén de confianza.

aws apigatewayv2 update-domain-name \

--domain-name api.example.com \
--mutual-tls-authentication truststoreVersion='abcdef123'

Deshabilitar la TLS mutua

Para deshabilitar la TLS mutua para un nombre de dominio personalizado, elimine el almacén de confianza
del nombre de dominio personalizado, como se muestra en el siguiente comando.

aws apigatewayv2 update-domain-name \

--domain-name api.example.com \
--mutual-tls-authentication truststoreUri=''

Solución de problemas de advertencias de certificados

Cuando crea un nombre de dominio personalizado que tiene la TLS mutua habilitada o actualiza su
nombre de dominio personalizado para utilizar un nuevo almacén de confianza, API Gateway devuelve
advertencias si los certificados no son válidos. Las advertencias indican el problema con el certificado y el
asunto del certificado que produjo la advertencia.

Para identificar el certificado que produjo la advertencia, descodifique los certificados en su almacén de
confianza. Puede utilizar herramientas como openssl para descodificar los certificados e identificar sus
asuntos.

El siguiente comando muestra el contenido de un certificado, incluido su asunto.

openssl x509 -in certificate.crt -text -noout

Actualice o elimine los certificados que produjeron advertencias y, a continuación, cargue una nueva
versión del almacén de confianza en Amazon S3. Después de cargar un nuevo almacén de confianza en
Amazon S3, actualice su nombre de dominio personalizado para utilizar el nuevo almacén de confianza.

Monitoreo de la API HTTP

Puede utilizar las métricas de CloudWatch y CloudWatch Logs para monitorear las API HTTP. Al combinar
registros y métricas, puede registrar errores y monitorear el rendimiento de su API.
Note

API Gateway podría no generar registros y métricas en los siguientes casos:

• Errores 413: Entidad de solicitud demasiado grande

• Errores 429: Demasiadas Solicitudes
• Errores de la serie 400 de solicitudes enviadas a un dominio personalizado que no tiene
asignación de API
• Errores de la serie 500 causados por errores internos

224
 Amazon API Gateway Guía del desarrollador
Métricas

Temas
• Trabajar con métricas para API HTTP (p. 225)
• Configuración de registro para una API HTTP (p. 226)

Trabajar con métricas para API HTTP

Puede monitorear la ejecución de la API mediante CloudWatch, que recopila y procesa datos sin formato
de API Gateway en métricas legibles casi en tiempo real. Estas estadísticas se registran durante un
periodo de 15 meses, para que pueda obtener acceso a información de historial y obtener una mejor
perspectiva acerca del desempeño de su aplicación web o servicio. De forma predeterminada, los datos
de las métricas de API Gateway se envían automáticamente a CloudWatch en períodos de un minuto.
Para obtener más información, consulte ¿Qué es Amazon CloudWatch? en la guía del usuario de Amazon
Cloudwatch.

Las siguientes métricas son compatibles con las API HTTP. También puede habilitar métricas detalladas
para escribir métricas en el nivel de ruta en Amazon CloudWatch.

Métrica Descripción

4xx El número de errores del cliente

capturados en un periodo
determinado.

5xx El número de errores del servidor

capturados en un periodo
determinado.

Recuento El número total de solicitudes

de API en un periodo de tiempo
determinado.

IntegrationLatency Es el tiempo entre que API

Gateway transmite una solicitud
al backend y se recibe una
respuesta del backend.

Latencia El tiempo entre que API Gateway

recibe una solicitud de un cliente
y devuelve una respuesta al
cliente. La latencia incluye la
latencia de la integración y otra
carga de API Gateway.

Datos procesados La cantidad de datos procesados

en bytes.

Puede usar las dimensiones de la tabla siguiente para filtrar las métricas de API Gateway.

Dimensión Descripción

ApiId Filtra las métricas de API

Gateway para una API con el ID
de API especificado.

225
 Amazon API Gateway Guía del desarrollador
Registro de

Dimensión Descripción

ApiId, Stage Filtra las métricas de API

Gateway para una etapa de API
cuyos ID de API y de etapa se
hayan especificado.

ApiId, Stage, Route Filtra las métricas de API

Gateway para un método de
API cuyos ID de API, de etapa
y de enrutamiento se hayan
especificado.

API Gateway no enviará estas

métricas a menos que haya
habilitado explícitamente
las métricas detalladas de
CloudWatch. Puede hacerlo
mediante una llamada a la
acción UpdateStage de la API
de REST de API Gateway V2
para establecer la propiedad
metricsEnabled en true. Si
activa estas métricas, se le
cobrarán cargos adicionales
en su cuenta. Para obtener
más información sobre precios,
consulte Precios de Amazon
CloudWatch.

Configuración de registro para una API HTTP

Puede habilitar el registro para escribir registros en CloudWatch Logs. Puede utilizar variables de
registro (p. 228) para personalizar el contenido de los registros.

Para habilitar el registro para una API HTTP, tendrá que hacer lo siguiente.

1. Asegúrese de que el usuario de IAM tenga los permisos necesarios para habilitar el registro.
2. Cree un grupo de registros de CloudWatch Logs.
3. Proporcione el ARN del grupo de registros de CloudWatch Logs para una etapa de la API.

Permisos para habilitar el registro

Para habilitar el registro para una API, el usuario de IAM debe tener los siguientes permisos.

Example

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:GetLogEvents",

226
 Amazon API Gateway Guía del desarrollador
Registro de

"logs:FilterLogEvents"
],
"Resource": "arn:aws:logs:us-east-2:123456789012:log-group:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogDelivery",
"logs:PutResourcePolicy",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:CreateLogGroup",
"logs:DescribeResourcePolicies",
"logs:GetLogDelivery",
"logs:ListLogDeliveries"
],
"Resource": "*"
}
]
}

Creación de un grupo de registros

El siguiente comando de la CLI de AWS crea un grupo de registros.

aws logs create-log-group --log-group-name my-log-group

Necesita el nombre de recurso de Amazon (ARN) para su grupo de registros para habilitar el registro. El
formato ARN es arn:aws:logs:region:account-id:log-group:log-group-name.

Habilitación del registro para una etapa

El siguiente comando de la CLI de AWS habilita el registro para la etapa $default de una API HTTP.

aws apigatewayv2 update-stage --api-id abcdef \

--stage-name '$default' \
--access-log-settings '{"DestinationArn": "arn:aws:logs:region:account-id:log-
group:log-group-name", "Format": "$context.identity.sourceIp - - [$context.requestTime]
\"$context.httpMethod $context.routeKey $context.protocol\" $context.status
$context.responseLength $context.requestId"}'

Ejemplos de formatos de registro

La consola de API Gateway incluye algunos ejemplos de los formatos de registro de acceso habituales, los
cuales se detallan a continuación.

• CLF (Common Log Format):

$context.identity.sourceIp - - [$context.requestTime] "$context.httpMethod

$context.routeKey $context.protocol" $context.status $context.responseLength
$context.requestId

• JSON:

{ "requestId":"$context.requestId", "ip": "$context.identity.sourceIp",

"requestTime":"$context.requestTime",
"httpMethod":"$context.httpMethod","routeKey":"$context.routeKey",

227
 Amazon API Gateway Guía del desarrollador
Registro de

"status":"$context.status","protocol":"$context.protocol",
"responseLength":"$context.responseLength" }

• XML:

<request id="$context.requestId"> <ip>$context.identity.sourceIp</ip> <requestTime>

$context.requestTime</requestTime> <httpMethod>$context.httpMethod</httpMethod>
<routeKey>$context.routeKey</routeKey> <status>$context.status</status> <protocol>
$context.protocol</protocol> <responseLength>$context.responseLength</responseLength> </
request>

• CSV (valores separados por comas):

$context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,
$context.protocol,$context.status,$context.responseLength,$context.requestId

Personalización de registros de acceso de las API HTTP

Puede utilizar las siguientes variables para personalizar los registros de acceso de las API HTTP. Para
obtener más información acerca de los registros de acceso para las API HTTP, consulte Configuración de
registro para una API HTTP (p. 226).

Parámetro Descripción

$context.accountId El ID de cuenta de AWS del propietario de la API.

$context.apiId El identificador que API Gateway asigna a su API.

$context.authorizer.claims.property Una propiedad de las reclamaciones devueltas

por el JSON Web Token (JWT) una vez que se
ha autenticado correctamente al intermediario
del método. Para obtener más información,
consulte Control del acceso a las API HTTP con
autorizadores de JWT (p. 189).
Note

La llamada a
$context.authorizer.claims
devuelve null.

$context.authorizer.error El mensaje de error devuelto por un autorizador.

$context.authorizer.principalId Identificación de usuario principal que devuelve un

autorizador de Lambda.

$context.authorizer.property El valor del par clave-valor especificado de la

asignación context devuelto de una función de
autorizador de Lambda para API Gateway. Por
ejemplo, si el autorizador devuelve la siguiente
asignación de context:

"context" : {
"key": "value",
"numKey": 1,
"boolKey": true
}

228
 Amazon API Gateway Guía del desarrollador
Registro de

Parámetro Descripción
la llamada a $context.authorizer.key
devuelve la cadena "value", la llamada a
$context.authorizer.numKey devuelve 1 y
la llamada a $context.authorizer.boolKey
devuelve true.

$context.awsEndpointRequestId El ID de solicitud del punto de enlace de AWS

desde el encabezado x-amz-request-id o x-
amzn-requestId.

$context.awsEndpointRequestId2 El ID de solicitud del punto de enlace de AWS

desde el encabezado x-amz-id-2.

$context.dataProcessed La cantidad de datos procesados en bytes.

$context.domainName El nombre de dominio completo que se utiliza

para invocar la API. Este debe ser el mismo que el
encabezado Host entrante.

$context.domainPrefix La primera etiqueta del $context.domainName.

Se utiliza a menudo como un intermediario/
identificador de cliente.

$context.error.message Una cadena que contiene un mensaje de error de

API Gateway.

$context.error.messageString El valor entrecomillado de

$context.error.message, es decir,
"$context.error.message".

$context.error.responseType Un tipo de GatewayResponse. Para obtener

más información, consulte the section called
“Métricas” (p. 760) y the section called
“Configuración de respuestas de gateway para
personalizar respuestas de errores” (p. 438).

$context.extendedRequestId El ID ampliado que API Gateway asigna a la

solicitud de la API, que contiene más información
útil para la depuración/resolución de problemas.

$context.httpMethod El método HTTP utilizado. Los valores válidos son:

DELETE, GET, HEAD, OPTIONS, PATCH, POST y
PUT.

$context.identity.accountId El ID de la cuenta de AWS asociado con la

solicitud. Compatible con rutas que utilizan la
autorización de IAM.

$context.identity.caller El identificador principal del intermediario que

realiza la solicitud. Compatible con rutas que
utilizan la autorización de IAM.

229
 Amazon API Gateway Guía del desarrollador
Registro de

Parámetro Descripción

Una lista separada por comas de los proveedores

$context.identity.cognitoAuthenticationProvider
de autenticación de Amazon Cognito utilizados
por el intermediario que realiza la solicitud. Solo
está disponible si la solicitud se firmó con las
credenciales de Amazon Cognito.

Por ejemplo, para una identidad de un grupo de

usuarios de Amazon Cognito, cognito-idp.
region.amazonaws.com/
user_pool_id,cognito-
idp.region.amazonaws.com/
user_pool_id:CognitoSignIn:token
subject claim

Consulte Uso de las identidades federadas en la

guía para desarrolladores de Amazon Cognito para
obtener más información.

El tipo de autenticación de Amazon Cognito

$context.identity.cognitoAuthenticationType
del intermediario que realiza la solicitud. Solo
está disponible si la solicitud se firmó con las
credenciales de Amazon Cognito. Los valores
posibles incluyen authenticated para
identidades autenticadas y unauthenticated
para identidades no autenticadas.

$context.identity.cognitoIdentityId El ID de identidad de Amazon Cognito del

intermediario que realiza la solicitud. Solo
está disponible si la solicitud se firmó con las
credenciales de Amazon Cognito.

$context.identity.cognitoIdentityPoolId El ID del grupo de identidades de Amazon Cognito

del intermediario que realiza la solicitud. Solo
está disponible si la solicitud se firmó con las
credenciales de Amazon Cognito.

$context.identity.principalOrgId El ID de organización de AWS. Compatible con

rutas que utilizan la autorización de IAM.

El certificado de cliente codificado en PEM que

$context.identity.clientCert.clientCertPem
el cliente presentó durante la autenticación TLS
mutua. Presente cuando un cliente accede a una
API mediante un nombre de dominio personalizado
que tiene una TLS mutua habilitada.

$context.identity.clientCert.subjectDN Nombre distintivo del asunto del certificado que

presenta un cliente. Presente cuando un cliente
accede a una API mediante un nombre de dominio
personalizado que tiene una TLS mutua habilitada.

$context.identity.clientCert.issuerDN Nombre distintivo del emisor del certificado que

presenta un cliente. Presente cuando un cliente
accede a una API mediante un nombre de dominio
personalizado que tiene una TLS mutua habilitada.

230
 Amazon API Gateway Guía del desarrollador
Registro de

Parámetro Descripción

Número de serie del certificado. Presente cuando

$context.identity.clientCert.serialNumber
un cliente accede a una API mediante un nombre
de dominio personalizado que tiene una TLS
mutua habilitada.

Fecha antes de la cual el certificado no es válido.

$context.identity.clientCert.validity.notBefore
Presente cuando un cliente accede a una API
mediante un nombre de dominio personalizado que
tiene una TLS mutua habilitada.

Fecha después de la cual el certificado no es

$context.identity.clientCert.validity.notAfter
válido. Presente cuando un cliente accede a una
API mediante un nombre de dominio personalizado
que tiene una TLS mutua habilitada.

$context.identity.sourceIp La dirección IP de origen de la conexión TCP

inmediata que realiza la solicitud al punto de
enlace de API Gateway.

$context.identity.user El identificador principal del usuario que realiza

la solicitud. Compatible con rutas que utilizan la
autorización de IAM.

$context.identity.userAgent El encabezado User-Agent del intermediario de

la API.

$context.identity.userArn El Nombre de recurso de Amazon (ARN) del

usuario identificado después de la autenticación.
Compatible con rutas que utilizan la autorización
de IAM. Para obtener más información, consulte
https://docs.aws.amazon.com/IAM/latest/
UserGuide/id_users.html.

$context.integration.error El mensaje de error devuelto por

una integración. Es igual que
$context.integrationErrorMessage.

$context.integration.integrationStatus Para la integración de proxy de Lambda, el código

de estado que devuelve AWS Lambda, en lugar del
código de función de Lambda del backend.

$context.integration.latency La latencia de integración en ms. Es igual que

$context.integrationLatency.

$context.integration.requestId El ID de solicitud del punto de enlace de AWS. Es

igual que $context.awsEndpointRequestId.

$context.integration.status El código de estado devuelto por una integración.

Para integraciones de proxy de Lambda,
este es el código de estado que devuelve su
código de la función de Lambda. Es igual que
$context.integrationStatus.

$context.integrationErrorMessage Una cadena que contiene un mensaje de error de

integración.

$context.integrationLatency La latencia de integración en ms.

231
 Amazon API Gateway Guía del desarrollador
Solución de problemas

Parámetro Descripción

$context.integrationStatus Para la integración de proxy de Lambda, este

parámetro representa el código de estado que
devuelve AWS Lambda, en lugar del código de
función de Lambda del backend.

$context.path Ruta de acceso de la solicitud. Por ejemplo, /

{stage}/root/child.

$context.protocol Protocolo de la solicitud; por ejemplo, HTTP/1.1.

$context.requestId El ID que API Gateway asigna a la solicitud de API.

$context.requestTime Hora de la solicitud en formato CLF-(dd/MMM/

yyyy:HH:mm:ss +-hhmm).

$context.requestTimeEpoch Hora de la solicitud en formato Epoch.

$context.responseLatency La latencia de respuesta en ms.

$context.responseLength La duración de la carga de respuesta.

$context.routeKey La clave de ruta de la solicitud de la API, por

ejemplo, /pets.

$context.stage La etapa de implementación de la solicitud de la

API (por ejemplo, beta o prod).

$context.status El estado de respuesta de método.

Solución de problemas con las API HTTP

Los siguientes temas le proporcionan consejos para solucionar errores y problemas que puedan surgir al
utilizar API HTTP.

Temas
• Solución de problemas con las integraciones de HTTP API Lambda (p. 232)
• Solución de problemas con los autorizadores JWT de la API HTTP (p. 234)

Solución de problemas con las integraciones de HTTP

API Lambda
A continuación se le proporcionan consejos para solucionar errores y problemas que puedan surgir al
utilizar Integraciones de AWS Lambda (p. 191) con API HTTP.

Problema: mi API con una integración de Lambda devuelve

{"message":"Internal Server Error"}
Para solucionar el error interno del servidor, agregue la variable de registro (p. 228)
$context.integrationErrorMessage al formato de registro y vea sus registros de API HTTP. Para
ello, haga lo siguiente:

232
 Amazon API Gateway Guía del desarrollador
Integraciones de Lambda

Para crear un grupo de registros mediante consola de administración de AWS

1. Abra la consola de CloudWatch en https://console.aws.amazon.com/cloudwatch/.

2. Elija Log groups (Grupos de registros).
3. Elija Create log group (Crear grupo de registros).
4. Escriba un nombre de grupo de registros y, a continuación, elija Create (Crear).
5. Anote el nombre de recurso de Amazon (ARN) de su grupo de registros. El formato ARN es
arn:aws:logs: region: account-id:log-group:log-group-name. Necesita el ARN del grupo de
registros para habilitar el registro de acceso a su API HTTP.

Para agregar la variable de registro $context.integrationErrorMessage

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija su API HTTP.
3. En Metrics (Métricas), elija Logging (Registro).
4. Seleccione una etapa de su API.
5. Elija Edit (Editar) y, a continuación, habilite el registro de acceso.
6. En Log format (Formato de registro), elija CLF.
7. Agregue $context.integrationErrorMessage al final del formato de registro.
8. Elija Save (Guardar).

Para ver los registros de la API

1. Generación de registros. Utilice un navegador o curl para invocar su API.

$curl https://api-id.execute-api.us-west-2.amazonaws.com/route

2. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

3. Elija su API HTTP.
4. En Metrics (Métricas), elija Logging (Registro).
5. Seleccione la etapa de su API para la que habilitó el registro.
6. Elija View logs in CloudWatch (Ver registros en CloudWatch).
7. Elija la última secuencia de registro para ver sus registros de API HTTP.
8. Su entrada de registro debe tener un aspecto similar a este:

233
 Amazon API Gateway Guía del desarrollador
Autorizadores de JWT

Dado que agregamos $context.integrationErrorMessage al formato de registro, vemos un

mensaje de error en nuestros registros que resume el problema.

Los registros pueden incluir un mensaje de error diferente que indica que hay un problema con el código
de función de Lambda. En ese caso, verifique su código de función de Lambda y compruebe que su
función de Lambda devuelva una respuesta en el formato necesario (p. 194).

En este caso, los registros muestran que API Gateway no tenía los permisos necesarios para invocar la
función de Lambda.

Cuando crea una integración de Lambda en la consola de API Gateway, API Gateway configura
automáticamente los permisos para invocar la función de Lambda. Al crear una integración de Lambda
mediante la CLI de AWS, AWS CloudFormation o un SDK, debe conceder permisos a API Gateway para
invocar la función. El siguiente comando de la CLI de AWS concede permisos para la etapa $default y la
ruta $default de una API HTTP para invocar una función de Lambda.

aws lambda add-permission \

--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/\$default/\$default"

Confirme la política de la función en la pestaña Permissions (Permisos) de la consola de Lambda.

Intente volver a invocar su API. Debería ver la respuesta de su función de Lambda.

Solución de problemas con los autorizadores JWT de

la API HTTP
A continuación se le proporcionan consejos para solucionar errores y problemas que puedan surgir al
utilizar los autorizadores de JSON Web Token (JWT) con API HTTP.

234
 Amazon API Gateway Guía del desarrollador
Autorizadores de JWT

Problema: mi API devuelve 401

{"message":"Unauthorized"}
Compruebe el encabezado www-authenticate en la respuesta de la API.

El siguiente comando utiliza curl para enviar una solicitud a una API con un autorizador de JWT que
utiliza $request.header.Authorization como su origen de identidad.

$curl -v -H "Authorization: token" https://api-id.execute-api.us-west-2.amazonaws.com/route

La respuesta de la API incluye un encabezado www-authenticate.

...
< HTTP/1.1 401 Unauthorized
< Date: Wed, 13 May 2020 04:07:30 GMT
< Content-Length: 26
< Connection: keep-alive
< www-authenticate: Bearer scope="" error="invalid_token" error_description="the token does
not have a valid audience"
< apigw-requestid: Mc7UVioPPHcEKPA=
<
* Connection #0 to host api-id.execute-api.us-west-2.amazonaws.com left intact
{"message":"Unauthorized"}}

En este caso, el encabezado www-authenticate muestra que el token no se emitió para un destinatario
válido. Para que API Gateway autorice una solicitud, la reclamación aud o client_id de JWT debe
coincidir con una de las entradas de destinatario configuradas para el autorizador.

También puede decodificar un JWT y comprobar que coincida con el emisor, el destinatario y los ámbitos
que requiere su API. El sitio web jwt.io puede depurar JWT en el navegador. OpenID Foundation mantiene
una lista de bibliotecas para trabajar con JWT.

Para obtener más información acerca de los autorizadores de JWT, consulte Control del acceso a las API
HTTP con autorizadores de JWT (p. 189).

235
 Amazon API Gateway Guía del desarrollador
Desarrollo

Uso de API de REST

Una API de REST en API Gateway es una colección de recursos y métodos que se integran con
puntos de enlace de HTTP del backend, funciones de Lambda u otros servicios de AWS. Puede utilizar
características de API Gateway para ayudarle con todos los aspectos del ciclo de vida de la API, desde la
creación hasta el monitoreo de sus API de producción.

Las API de REST de API Gateway utilizan un modelo de solicitud/respuesta en el que un cliente envía una
solicitud a un servicio y el servicio responde de forma sincrónica. Este tipo de modelo es adecuado para
muchos tipos diferentes de aplicaciones que dependen de la comunicación sincrónica.

Temas
• Desarrollo de una API REST en API Gateway (p. 236)
• Publicación de una API de REST para que los clientes la invoquen (p. 510)
• Optimización del rendimiento de las API REST (p. 564)
• Distribución de la API de REST a los clientes (p. 574)
• Protección de la API REST (p. 660)
• Monitoreo de las API de REST (p. 695)

Desarrollo de una API REST en API Gateway

En esta sección se proporciona información detallada acerca de las capacidades de API Gateway que
necesitará para desarrollar las API de API Gateway.

A medida que se desarrolla la API de API Gateway, se decide sobre una serie de características de la API.
Estas características dependen del uso de la API. Por ejemplo, es posible que quiera permitir solo a ciertos
clientes llamar a la API o puede que quiera que esté disponible para todos. Puede querer que una llamada
a la API ejecute una función de Lambda, haga una consulta a la base de datos o llame a una aplicación.

Temas
• Creación de una API REST en Amazon API Gateway (p. 236)
• Control y administración del acceso a una API REST en API Gateway (p. 269)
• Configuración de integraciones de la API REST (p. 331)
• Habilitar la validación de solicitudes en API Gateway (p. 376)
• Configuración de transformaciones de datos para API REST (p. 389)
• Respuestas de gateway en API Gateway (p. 438)
• Habilitación de CORS para un recurso de la API de REST (p. 445)
• Trabajar con tipos de medios binarios para API REST (p. 453)
• Invocación de una API REST en Amazon API Gateway (p. 477)
• Configuración de una API de REST mediante OpenAPI (p. 500)

Creación de una API REST en Amazon API Gateway

En Amazon API Gateway, las API REST se crean como una colección de entidades programables
conocidas como recursos de API Gateway. Por ejemplo, se utiliza un recurso RestApi para representar
una API que puede contener una colección de entidades Resource. Cada entidad Resource a su vez
puede tener uno o más recursos Method. Expresado en los parámetros de solicitud y en el cuerpo, un
Method define la interfaz de programación de aplicaciones del cliente para obtener acceso al Resource
expuesto y representa una solicitud entrante enviada por el cliente. A continuación, se crea un recurso

236
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Integration para integrar el Method con un punto de enlace de backend, también conocido como punto
de enlace de integración, reenviando la solicitud entrante a un URI de punto de enlace de integración
especificado. Si es necesario, puede transformar los parámetros de solicitud o el cuerpo para que
cumplan los requisitos del backend. Para las respuestas, puede crear un recurso MethodResponse para
representar una respuesta de solicitud recibida por el cliente y crear un recurso IntegrationResponse
para representar la respuesta de solicitud que devuelve el backend. Puede configurar la respuesta de
integración para transformar los datos de respuesta del backend antes de devolver los datos al cliente o
transferir la respuesta del backend tal y como está al cliente.

Para ayudar a sus clientes a comprender su API, también puede proporcionar documentación para la
API, como parte de la creación de la API o una vez que se ha creado. Para ello, agregue un recurso
DocumentationPart para una entidad de API compatible.

Para controlar el modo en que los clientes llaman a la API, utilice permisos de IAM (p. 287), un
autorizador de Lambda (p. 305) o un grupo de usuarios de Amazon Cognito (p. 322). Para medir el
uso de la API, configure planes de uso (p. 574) para limitar las solicitudes a la API. Puede habilitar estos
elementos al crear o al actualizar la API.

Puede realizar estas y otras tareas a través de la consola de API Gateway, la API REST de API Gateway,
la CLI de AWS o uno de los SDK de AWS. A continuación, trataremos cómo realizar estas tareas.

Temas
• Elección de un tipo de punto de enlace para configurarlo para una API de API Gateway (p. 237)
• Inicialización de la configuración de una API REST en API Gateway (p. 239)
• Configurar métodos de API REST en API Gateway (p. 256)

Elección de un tipo de punto de enlace para configurarlo para

una API de API Gateway

Los tipos de punto de enlace de API (p. 6) hacen referencia al nombre de host de la API. El punto de
enlace de la API puede ser de tres tipos, optimizado para sistemas perimetrales, regional o privado, en
función de dónde se origine la mayoría del tráfico de la API.

Punto de enlace de API optimizado para bordes

Un punto de enlace de API optimizado para sistemas perimetrales (p. 7) es la mejor opción cuando los
clientes están distribuidos geográficamente. Las solicitudes de API se dirigen al punto de presencia (POP)
de CloudFront más cercano. Este es el tipo de punto de enlace predeterminado para las API REST de API
Gateway.

Las API optimizadas para sistemas perimetrales utilizan mayúsculas en la inicial de los nombres de los
encabezados HTTP (por ejemplo, Cookie).

CloudFront ordena las cookies HTTP según su nombre antes de reenviar la solicitud al origen. Para
obtener más información sobre el modo en que CloudFront procesa las cookies, consulte Almacenamiento
en caché de contenido en función de cookies.

Cualquier nombre de dominio personalizado que se utilice con una API optimizada para sistemas
perimetrales se aplicará a todas las regiones.

Puntos de enlace de API regionales

Los puntos de enlace de API regionales (p. 9) están destinados a los clientes que se encuentran en la
misma región. Cuando un cliente que se ejecuta en una instancia EC2 llama a una API en la misma región,
o cuando una API tiene por objeto servir a una cantidad reducida de clientes con altas demandas, una API
regional reduce la sobrecarga de conexión.

237
 Amazon API Gateway Guía del desarrollador
Crear y configurar

En una API regional, el nombre de dominio personalizado es específico de la región en la que está
implementada la API. Si implementa una API regional en varias regiones, esta puede tener el mismo
nombre de dominio personalizado en todas las regiones. Puede utilizar dominios personalizados
junto con Amazon Route 53 para realizar tareas como el direccionamiento basado en latencia. Para
obtener más información, consulte the section called “Configuración de un nombre de dominio regional
personalizado” (p. 558) y the section called “Creación de un nombre de dominio personalizado
optimizado para bordes” (p. 551).

Los puntos de enlace de API regionales ransfieren todos los nombres de encabezado tal y como están.

Puntos de enlace de API privados

Un punto de enlace de API privado (p. 8) es un punto de enlace de la API al que solo se pueda obtener
acceso desde una Amazon Virtual Private Cloud (VPC) mediante un punto de enlace de la VPC de tipo
interfaz, que es una interfaz de red de punto de enlace (ENI) que se crea en la VPC. Para obtener más
información, consulte the section called “API privadas” (p. 688).

Los puntos de enlace de API privados transfieren todos los nombres de encabezado tal y como están.

Cambiar el tipo de punto de enlace de una API pública o privada en API Gateway
Para cambiar el tipo de un punto de enlace de la API, es preciso actualizar la configuración de la API.
Puede cambiar un tipo de API existente mediante la consola de API Gateway, la CLI de AWS o un SDK de
AWS para API Gateway. La operación de actualización puede tardar hasta 60 segundos en completarse.
Durante este tiempo, la API estará disponible, pero su tipo de punto de enlace no se puede cambiar de
nuevo hasta que se complete el cambio actual.

Se admiten los siguientes cambios de tipo de puntos de enlace:

• De "optimizado para sistemas perimetrales" a "regional" o "privado"

• De "regional" a "optimizado para sistemas perimetrales" o "privado"
• De "privado" a "regional"

No puede transformar una API privada en una API optimizada para límites.

Si va a cambiar una API pública optimizada para límites a regional o viceversa, tenga en cuenta que las
API optimizadas para sistemas perimetrales pueden comportarse de forma distinta que las API regionales.
Por ejemplo, una API optimizada para límites elimina el encabezado Content-MD5. Cualquier valor
de hash MD5 transmitido al backend se puede expresar en un parámetro de cadena de solicitud o una
propiedad del cuerpo. Sin embargo, la API regional transmite este encabezado, aunque puede reasignar
el nombre de encabezado a otro nombre. Comprender estas diferencias le ayuda a decidir cómo actualizar
una API optimizada para límites a una regional o bien de una API regional a una optimizada para límites.

Temas
• Uso de la consola de API Gateway para cambiar el tipo de punto de enlace de la API (p. 238)
• Uso de la CLI de AWS para cambiar el tipo de punto de enlace de una API (p. 239)

Uso de la consola de API Gateway para cambiar el tipo de punto de enlace de la API
Para cambiar el tipo de punto de enlace de la API, siga uno de estos procedimientos:

Para convertir un punto de enlace público de regional u optimizado para sistemas perimetrales, y
viceversa

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija una API de REST.
3. Elija Settings.

238
 Amazon API Gateway Guía del desarrollador
Crear y configurar

4. Cambie la opción Endpoint Type (Tipo de punto de enlace) en Endpoint Configuration (Configuración
de punto de enlace) de Edge Optimized a Regional o bien de Regional a Edge Optimized.
5. Elija Save Changes (Guardar cambios) para iniciar la actualización.

Para convertir un punto de enlace privado en un punto de enlace regional

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija una API de REST.
3. Modifique la política de recursos de la API para eliminar cualquier mención a las VPC o los puntos de
enlace de la VPC, de modo que tanto las llamadas a la API que se realicen desde fuera de la VPC
como las que se realicen desde dentro se ejecuten correctamente.
4. Elija Settings.
5. Cambie Endpoint Type (Tipo de punto de enlace) a Regional.
6. Elija Save Changes (Guardar cambios) para iniciar la actualización.
7. Quite la política de recursos de la API.
8. Vuelva a implementar la API para que los cambios surtan efecto.

Uso de la CLI de AWS para cambiar el tipo de punto de enlace de una API
Si desea utilizar la CLI de AWS para actualizar una API optimizada para bordes cuyo ID es {api-id},
llame a update-rest-api tal y como se indica a continuación:

aws apigateway update-rest-api \

--rest-api-id {api-id}
--patch-operations op=replace,path=/endpointConfiguration/types/EDGE,value=REGIONAL

La respuesta correcta tiene un código de estado 200 OK y una carga similar a la siguiente:

"createdDate": "2017-10-16T04:09:31Z",
"description": "Your first API with Amazon API Gateway. This is a sample API that
integrates via HTTP with our demo Pet Store endpoints",
"endpointConfiguration": {
"types": "REGIONAL"
},
"id": "0gsnjtjck8",
"name": "PetStore imported as edge-optimized"
}

De igual forma, actualice una API regional a una API optimizada para límites del modo siguiente:

aws apigateway update-rest-api \

--rest-api-id {api-id}
--patch-operations op=replace,path=/endpointConfiguration/types/REGIONAL,value=EDGE

Dado que put-rest-api se utiliza para actualizar definiciones de API, no puede utilizarse para actualizar un
tipo de punto de enlace de API.

Inicialización de la configuración de una API REST en API

Gateway
Para este ejemplo, utilizamos una API PetStore simplificada, con la integración HTTP, que expone los
métodos GET /pets y GET /pets/{petId}. Los métodos se integran con los dos puntos de enlace

239
 Amazon API Gateway Guía del desarrollador
Crear y configurar

HTTP, respectivamente, de http://petstore-demo-endpoint.execute-api.com/petstore/

pets y http://petstore-demo-endpoint.execute-api.com/petstore/pets/{petId}. La API
gestiona las respuestas 200 OK. Los ejemplos se centran en las tareas de programación esenciales para
crear una API en API Gateway, aprovechando los ajustes predeterminados cuando sea posible.

Debido a los ajustes predeterminados, la API resultante está optimizada para límites. Una alternativa es
configurar una API regional (p. 253). Para configurar una API regional, debe establecer explícitamente
el tipo de punto de enlace de la API como REGIONAL. Para configurar una API optimizada para límites
explícitamente, puede establecer EDGE como tipo de endpointConfiguration.

Al configurar una API, debe elegir una región. Cuando se implementa, la API es específica de una
región. En el caso de una API optimizada para bordes, la URL base tiene el formato http[s]://
{restapi-id}.execute-api.amazonaws.com/stage, donde {restapi-id} es el valor de id de
la API generado por API Gateway. Puede asignar un nombre de dominio personalizado (por ejemplo,
apis.example.com) como nombre de host de la API y llamar a la API con una URL base con el formato
https://apis.example.com/myApi.

Temas
• Configuración de una API con la consola de API Gateway (p. 240)
• Configurar una API optimizada para bordes mediante comandos de la CLI de AWS (p. 240)
• Configurar una API optimizada para bordes con el SDK de AWS para Node.js (p. 245)
• Configurar una API optimizada para bordes importando definiciones de OpenAPI (p. 252)
• Configuración de una API regional en API Gateway (p. 253)

Configuración de una API con la consola de API Gateway

Para configurar una API de API Gateway mediante la consola de API Gateway, consulte Tutorial:
Desarrollo de una API de REST con integración HTTP no de proxy (p. 56).

Puede obtener información sobre cómo configurar una API siguiendo un ejemplo. Para obtener más
información, consulte Tutorial: Crear una API de REST importando un ejemplo (p. 43).

Como alternativa, puede crear una API a través de la función Importar API (p. 500) de API Gateway para
cargar una definición de API externa, como la expresada en OpenAPI 2.0 con Trabajar con extensiones de
API Gateway para OpenAPI (p. 771). En el ejemplo proporcionado en Tutorial: Crear una API de REST
importando un ejemplo (p. 43) se utiliza la característica Import API.

Configurar una API optimizada para bordes mediante comandos de la CLI de

AWS
Para configurar una API mediante la CLI de AWS, es necesario trabajar con los comandos create-
rest-api, create-resource o get-resources, put-method, put-method-response, put-
integration y put-integration-response. Los siguientes procedimientos muestran cómo trabajar
con estos comandos de la CLI de AWS para crear la API de PetStore del tipo de integración HTTP.

Para crear una API PetStore sencilla mediante la CLI de AWS

1. Llame al comando create-rest-api para configurar la RestApi en una región concreta (us-
west-2).

aws apigateway create-rest-api --name 'Simple PetStore (AWS CLI)' --region us-west-2

A continuación se muestra la salida de este comando:

240
 Amazon API Gateway Guía del desarrollador
Crear y configurar

"name": "Simple PetStore (AWS CLI)",

"id": "vaz7da96z6",
"createdDate": 1494572809
}

Anote el id devuelto de la RestApi recién creada. Lo necesitará para configurar otras partes de la
API.
2. Llame al comando get-resources para recuperar el identificador del recurso raíz de la RestApi.

aws apigateway get-resources --rest-api-id vaz7da96z6 --region us-west-2

A continuación se muestra la salida de este comando:

{
"items": [
{
"path": "/",
"id": "begaltmsm8"
}
]
}

Anote el Id del recurso raíz. Lo necesitará para comenzar a establecer el árbol de recursos de la API
y para configurar métodos e integraciones.
3. Llame al comando create-resource para asociar un recurso secundario (pets) bajo el recurso raíz
(begaltmsm8):

aws apigateway create-resource --rest-api-id vaz7da96z6 \

--region us-west-2 \
--parent-id begaltmsm8 \
--path-part pets

A continuación se muestra la salida de este comando:

{
"path": "/pets",
"pathPart": "pets",
"id": "6sxz2j",
"parentId": "begaltmsm8"
}

Para asociar un recurso secundario bajo la raíz, se especifica el Id del recurso raíz como valor de la
propiedad parentId. Del forma similar, para asociar un recurso secundario bajo el recurso pets, se
repite el paso anterior y se sustituye el valor parent-id por el pets id del recurso de 6sxz2j:

aws apigateway create-resource --rest-api-id vaz7da96z6 \

--region us-west-2 \
--parent-id 6sxz2j \
--path-part '{petId}'

Para hacer de una parte de la ruta un parámetro de ruta, sitúela entre llaves. Si se ejecuta
correctamente, este comando devuelve la siguiente respuesta:

{
"path": "/pets/{petId}",
"pathPart": "{petId}",
241
 Amazon API Gateway Guía del desarrollador
Crear y configurar

"id": "rjkmth",
"parentId": "6sxz2j"
}

Ahora que ha creado dos recursos, /pets (6sxz2j) y /pets/{petId} (rjkmth), puede continuar
configurando métodos sobre ellos.
4. Llame al comando put-method para añadir el método HTTP GET en el recurso /pets. Esto crea un
Method de API de GET /pets con acceso abierto, haciendo referencia al recurso /pets mediante su
valor de ID de 6sxz2j.

aws apigateway put-method --rest-api-id vaz7da96z6 \

--resource-id 6sxz2j \
--http-method GET \
--authorization-type "NONE" \
--region us-west-2

Si se ejecuta correctamente, el resultado de este comando sería el siguiente:

{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE"
}

El método es de acceso abierto porque authorization-type está ajustado en NONE. Para permitir
que solo puedan llamar al método los usuarios autenticados, puede utilizar políticas y roles de IAM, un
autorizador de Lambda (que anteriormente se denominaba autorizador personalizado) o un grupo de
usuarios de Amazon Cognito. Para obtener más información, consulte the section called “Control de
acceso” (p. 269).

Para habilitar el acceso de lectura al recurso /pets/{petId} (rjkmth), añada el método HTTP GET
para crear un Method de API de GET /pets/{petId} del siguiente modo.

aws apigateway put-method --rest-api-id vaz7da96z6 \

--resource-id rjkmth --http-method GET \
--authorization-type "NONE" \
--region us-west-2 \
--request-parameters method.request.path.petId=true

Si se ejecuta correctamente, el resultado de este comando sería el siguiente:

{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.path.petId": true
}
}

Tenga en cuenta que el parámetro de ruta de solicitud de método de petId debe especificarse como
un parámetro de solicitud necesario para que su valor establecido dinámicamente se asigne a un
parámetro de solicitud de integración correspondiente y se transfiera al backend.
5. Llame al comando put-method-response para configurar la respuesta 200 OK del método GET /
pets, especificando el recurso /pets mediante su valor de ID de 6sxz2j.

242
 Amazon API Gateway Guía del desarrollador
Crear y configurar

aws apigateway put-method-response --rest-api-id vaz7da96z6 \

--resource-id 6sxz2j --http-method GET \
--status-code 200 --region us-west-2

A continuación se muestra la salida de este comando:

{
"statusCode": "200"
}

De forma similar, para establecer la respuesta 200 OK del método GET /pets/{petId}, realice lo
siguiente, especificando el recurso /pets/{petId} mediante su valor de ID de recurso de rjkmth:

aws apigateway put-method-response --rest-api-id vaz7da96z6 \

--resource-id rjkmth --http-method GET \
--status-code 200 --region us-west-2

Tras configurar una interfaz de cliente sencilla para la API, puede continuar y configurar la integración
de los métodos de la API con el backend.
6. Llame al comando put-integration para configurar una Integration con un punto de enlace
HTTP especificado para el método GET /pets. El recurso /pets se identifica mediante su id de
recurso 6sxz2j:

aws apigateway put-integration --rest-api-id vaz7da96z6 \

--resource-id 6sxz2j --http-method GET --type HTTP \
--integration-http-method GET \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets' \
--region us-west-2

A continuación se muestra la salida de este comando:

{
"httpMethod": "GET",
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"type": "HTTP",
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"cacheNamespace": "6sxz2j"
}

Tenga en cuenta que el uri de integración de http://petstore-demo-endpoint.execute-

api.com/petstore/pets especifica el punto de enlace de integración del método GET /pets.

De forma similar, se crea una solicitud de integración para el método GET /pets/{petId} del
siguiente modo:

aws apigateway put-integration \

--rest-api-id vaz7da96z6 \
--resource-id rjkmth \
--http-method GET \
--type HTTP \
--integration-http-method GET \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}' \
--request-parameters
'{"integration.request.path.id":"method.request.path.petId"}' \

243
 Amazon API Gateway Guía del desarrollador
Crear y configurar

--region us-west-2

Aquí, el punto de enlace de integración, uri de http://petstore-demo-endpoint.execute-

api.com/petstore/pets/{id}, también utiliza un parámetro de ruta (id). Su valor se asigna a
partir del parámetro de ruta de solicitud de método correspondiente de {petId}. La asignación se
define como parte de request-parameters. Si esta asignación no se define aquí, el cliente recibe
una respuesta de error al intentar llamar al método.

A continuación se muestra la salida de este comando:

{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}",
"httpMethod": "GET",
"cacheNamespace": "rjkmth",
"type": "HTTP",
"requestParameters": {
"integration.request.path.id": "method.request.path.petId"
}
}

7. Llame al comando put-integration-response para crear una entidad IntegrationResponse

del método GET /pets integrada con un backend HTTP.

aws apigateway put-integration-response --rest-api-id vaz7da96z6 \

--resource-id 6sxz2j --http-method GET \
--status-code 200 --selection-pattern "" \
--region us-west-2

A continuación se muestra la salida de este comando:

{
"selectionPattern": "",
"statusCode": "200"
}

Del forma similar, llame al siguiente comando put-integration-response para crear una
IntegrationResponse del método GET /pets/{petId}:

aws apigateway put-integration-response --rest-api-id vaz7da96z6 \

--resource-id rjkmth --http-method GET
--status-code 200 --selection-pattern ""
--region us-west-2

Con los pasos anteriores, ha terminado la configuración de una API sencilla que permite a sus clientes
consultar las mascotas disponibles en el sitio web de PetStore y ver una mascota concreta con un
identificador especificado. Para que el cliente pueda llamar a la API, debe implementarla.
8. Implemente la API en una etapa stage llamando, por ejemplo, a create-deployment:

aws apigateway create-deployment --rest-api-id vaz7da96z6 \

--region us-west-2 \
--stage-name test \
--stage-description 'Test stage' \
--description 'First deployment'

244
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Puede probar esta API escribiendo la URL https://vaz7da96z6.execute-api.us-

west-2.amazonaws.com/test/pets en un navegador y sustituyendo vaz7da96z6 por el identificador
de la API. La salida esperada debe ser la siguiente:

[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]

Para probar el método GET /pets/{petId}, escriba https://vaz7da96z6.execute-api.us-

west-2.amazonaws.com/test/pets/3 en el navegador. Debería recibir la siguiente respuesta:

{
"id": 3,
"type": "fish",
"price": 0.99
}

Configurar una API optimizada para bordes con el SDK de AWS para Node.js
Como ejemplo, utilizamos el SDK de AWS para Node.js para describir cómo se puede utilizar un SDK de
AWS para crear una API de API Gateway. Para obtener más información sobre el uso de un SDK de AWS,
incluida la configuración del entorno de desarrollo, consulte SDK de AWS.

La configuración de una API mediante el SDK de AWS para Node.js implica la llamada a las funciones
createRestApi, createResource o getResources, putMethod, putMethodResponse,
putIntegration y putIntegrationResponse.

Los siguientes procedimientos le guiarán por los pasos necesarios para utilizar estos comandos del SDK
con el fin de configurar una sencilla API de PetStore que admita los métodos GET /pets y GET /pets/
{petId}.

Para configurar una API sencilla de PetStore con el SDK de AWS para Node.js

1. Inicie el SDK:

var AWS = require('aws-sdk');

AWS.config.region = 'us-west-2';
var apig = new AWS.APIGateway({apiVersion: '2015/07/09'});

2. Llame a la función createRestApi para configurar la entidad RestApi.

apig.createRestApi({
name: "Simple PetStore (node.js SDK)",
binaryMediaTypes: [
'*'

245
 Amazon API Gateway Guía del desarrollador
Crear y configurar

],
description: "Demo API created using the AWS SDK for node.js",
version: "0.00.001"
}, function(err, data){
if (!err) {
console.log(data);
} else {
console.log('Create API failed:\n', err);
}
});

La función devuelve un resultado similar al siguiente:

{
id: 'iuo308uaq7',
name: 'PetStore (node.js SDK)',
description: 'Demo API created using the AWS SDK for node.js',
createdDate: 2017-09-05T19:32:35.000Z,
version: '0.00.001',
binaryMediaTypes: [ '*' ]
}

El identificador de API resultante es iuo308uaq7. Debe facilitarlo para continuar la configuración de

la API.
3. Llame a la función getResources para recuperar el identificador de recurso raíz de la RestApi.

apig.getResources({
restApiId: 'iuo308uaq7'
}, function(err, data){
if (!err) {
console.log(data);
} else {
console.log('Get the root resource failed:\n', err);
}
})

Esta función devuelve un resultado similar al siguiente:

{
"items": [
{
"path": "/",
"id": "s4fb0trnk0"
}
]
}

El identificador de recurso raíz es s4fb0trnk0. Este es el punto de partida para la crear el árbol de
recursos de la API, que es el siguiente paso.
4. Llame a la función createResource para configurar el recurso /pets para la API, especificando el
identificador de recurso raíz (s4fb0trnk0) en la propiedad parentId.

apig.createResource({
restApiId: 'iuo308uaq7',
parentId: 's4fb0trnk0',
pathPart: 'pets'
}, function(err, data){
if (!err) {
console.log(data);

246
 Amazon API Gateway Guía del desarrollador
Crear y configurar

} else {
console.log("The '/pets' resource setup failed:\n", err);
}
})

El resultado correcto es el siguiente:

{
"path": "/pets",
"pathPart": "pets",
"id": "8sxa2j",
"parentId": "s4fb0trnk0'"
}

Para configurar el recurso /pets/{petId}, llame a la siguiente función createResource,

especificando el recurso /pets recién creado (8sxa2j) en la propiedad parentId.

apig.createResource({
restApiId: 'iuo308uaq7',
parentId: '8sxa2j',
pathPart: '{petId}'
}, function(err, data){
if (!err) {
console.log(data);
} else {
console.log("The '/pets/{petId}' resource setup failed:\n", err);
}
})

El resultado correcto devuelve el valor id del recurso recién creado:

{
"path": "/pets/{petId}",
"pathPart": "{petId}",
"id": "au5df2",
"parentId": "8sxa2j"
}

A lo largo de este procedimiento, se hace referencia al recurso /pets especificando su ID de recurso

de 8sxa2j y al recurso /pets/{petId} especificando su ID de recurso de au5df2.
5. Llame a la función putMethod para añadir el método HTTP GET en el recurso /pets (8sxa2j). Esto
configura el GET /pets Method con acceso abierto.

apig.putMethod({
restApiId: 'iuo308uaq7',
resourceId: '8sxa2j,
httpMethod: 'GET',
authorizationType: 'NONE'
}, function(err, data){
if (!err) {
console.log(data);
} else {
console.log("The 'GET /pets' method setup failed:\n", err);
}
})

Esta función devuelve un resultado similar al siguiente:

247
 Amazon API Gateway Guía del desarrollador
Crear y configurar

{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE"
}

Para añadir el método HTTP GET en el recurso /pets/{petId} (au5df2), que configura el método
de API de GET /pets/{petId} con acceso abierto, llame a la función putMethod del siguiente
modo.

apig.putMethod({
restApiId: 'iuo308uaq7',
resourceId: 'au5df2',
httpMethod: 'GET',
authorizationType: 'NONE',
requestParameters: {
"method.request.path.petId" : true
}
}, function(err, data){
if (!err) {
console.log(data);
} else {
console.log("The 'GET /pets/{petId}' method setup failed:\n", err);
}
})

Esta función devuelve un resultado similar al siguiente:

{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.path.petId": true
}
}

Debe establecer la propiedad requestParameters tal y como se muestra en el ejemplo anterior

para asignar y transferir el valor petId suministrado por el cliente al backend.
6. Llame a la función putMethodResponse para configurar una respuesta de método para el método
GET /pets.

apig.putMethodResponse({
restApiId: 'iuo308uaq7',
resourceId: "8sxa2j",
httpMethod: 'GET',
statusCode: '200'
}, function(err, data){
if (!err) {
console.log(data);
} else {
console.log("Set up the 200 OK response for the 'GET /pets' method failed:\n", err);
}

})

Esta función devuelve un resultado similar al siguiente:

248
 Amazon API Gateway Guía del desarrollador
Crear y configurar

{
"statusCode": "200"
}

Para establecer la respuesta 200 OK del método GET /pets/{petId}, llame a la función
putMethodResponse, especificando el identificador de recurso /pets/{petId} (au5df2) en la
propiedad resourceId.

apig.putMethodResponse({
restApiId: 'iuo308uaq7',
resourceId: "au5df2",
httpMethod: 'GET',
statusCode: '200'
}, function(err, data){
if (!err) {
console.log(data);
} else {
console.log("Set up the 200 OK response for the 'GET /pets/{petId}' method failed:
\n", err);
}

})

7. Llame a la función putIntegration para configurar la Integration con un punto de enlace HTTP
especificado para el método GET /pets, facilitando el identificador del recurso /pets (8sxa2j) en la
propiedad parentId.

apig.putIntegration({
restApiId: 'iuo308uaq7',
resourceId: '8sxa2j',
httpMethod: 'GET',
type: 'HTTP',
integrationHttpMethod: 'GET',
uri: 'http://perstore-demo-endpoint.execute-api.com/pets'
}, function(err, data){
if (!err) {
console.log(data);
} else {
console.log("Set up the integration of the 'GET /' method of the API failed:\n",
err);
}

})

Esta función devuelve un resultado similar al siguiente:

{
"httpMethod": "GET",
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"type": "HTTP",
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"cacheNamespace": "8sxa2j"
}

Para configurar la integración del método GET /pets/{petId} con el punto de enlace HTTP de
http://perstore-demo-endpoint.execute-api.com/pets/{id} del backend, llame a la
siguiente función putIntegration, facilitando el identificador de recurso /pets/{petId} de la API
(au5df2) en la propiedad parentId.

249
 Amazon API Gateway Guía del desarrollador
Crear y configurar

apig.putIntegration({
restApiId: 'iuo308uaq7',
resourceId: 'au5df2',
httpMethod: 'GET',
type: 'HTTP',
integrationHttpMethod: 'GET',
uri: 'http://perstore-demo-endpoint.execute-api.com/pets/{id}',
requestParameters: {
"integration.request.path.id": "method.request.path.petId"
}
}, function(err, data){
if (!err) {
console.log(data);
} else {
console.log("The 'GET /pets/{petId}' method integration setup failed:\n", err);
}

})

Esta función devuelve un resultado correcto similar al siguiente:

{
"httpMethod": "GET",
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"type": "HTTP",
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}",
"cacheNamespace": "au5df2",
"requestParameters": {
"integration.request.path.id": "method.request.path.petId"
}
}

8. Llame a la función putIntegrationResponse para configurar la respuesta de integración 200 OK

para el método GET /pets, especificando el identificador de recurso /pets de la API (8sxa2j) en la
propiedad resourceId.

apig.putIntegrationResponse({
restApiId: 'iuo308uaq7',
resourceId: '8sxa2j',
httpMethod: 'GET',
statusCode: '200',
selectionPattern: ''
}, function(err, data){
if (!err) {
console.log(data);
} else
console.log("The 'GET /pets' method integration response setup failed:\n", err);

})

Esta función devolverá un resultado similar al siguiente:

{
"selectionPattern": "",
"statusCode": "200"
}

250
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Para configurar la respuesta de integración 200 OK del método GET /pets/{petId}, llame a la
función putIntegrationResponse, especificando el identificador del recurso /pets/{petId} de
la API (au5df2) en la propiedad resourceId.

apig.putIntegrationResponse({
restApiId: 'iuo308uaq7',
resourceId: 'au5df2',
httpMethod: 'GET',
statusCode: '200',
selectionPattern: ''
}, function(err, data){
if (!err) {
console.log(data);
} else
console.log("The 'GET /pets/{petId}' method integration response setup failed:\n",
err);

})

9. Como buena práctica, pruebe a invocar la API antes de implementarla. Para probar la invocación del
método GET /pets, llame al testInvokeMethod, especificando el identificador de recurso /pets
(8sxa2j) en la propiedad resourceId:

apig.testInvokeMethod({
restApiId: 'iuo308uaq7',
resourceId: '8sxa2j',
httpMethod: "GET",
pathWithQueryString: '/'
}, function(err, data){
if (!err) {
console.log(data)
} else {
console.log('Test-invoke-method on 'GET /pets' failed:\n', err);
}
})

Para probar la invocación del método GET /pets/{petId}, llame al testInvokeMethod,

especificando el identificador de recurso /pets/{petId} (au5df2) en la propiedad resourceId:

apig.testInvokeMethod({
restApiId: 'iuo308uaq7',
resourceId: 'au5df2',
httpMethod: "GET",
pathWithQueryString: '/'
}, function(err, data){
if (!err) {
console.log(data)
} else {
console.log('Test-invoke-method on 'GET /pets/{petId}' failed:\n', err);
}
})

10. Por último, puede implementar la API para que la llamen sus clientes.

apig.createDeployment({
restApiId: 'iuo308uaq7',
stageName: 'test',
stageDescription: 'test deployment',
description: 'API deployment'
}, function(err, data){

251
 Amazon API Gateway Guía del desarrollador
Crear y configurar

if (err) {
console.log('Deploying API failed:\n', err);
} else {
console.log("Deploying API succeeded\n", data);
}
})

Configurar una API optimizada para bordes importando definiciones de OpenAPI

Puede configurar una API en API Gateway especificando definiciones de OpenAPI de las entidades API de
API Gateway correspondientes e importando las definiciones de OpenAPI en API Gateway.

Las siguientes definiciones de OpenAPI describen la API sencilla, que expone solo el método GET /
integrado con un punto de enlace HTTP del sitio web PetStore en el backend y devuelve una respuesta
200 OK.

OpenAPI 2.0

{
"swagger": "2.0",
"info": {
"title": "Simple PetStore (OpenAPI)"
},
"schemes": [
"https"
],
"paths": {
"/pets": {
"get": {
"responses": {
"200": {
"description": "200 response"
}
},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "http"
}
}
},
"/pets/{petId}": {
"get": {
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response"
}
},
"x-amazon-apigateway-integration": {

252
 Amazon API Gateway Guía del desarrollador
Crear y configurar

"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.id": "method.request.path.petId"
},
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "http"
}
}
}
}
}

El siguiente procedimiento describe cómo importar estas definiciones de OpenAPI en API Gateway
mediante la consola de API Gateway.

Para importar las definiciones de OpenAPI de la API sencilla utilizando la consola de API Gateway

1. Inicie sesión en la consola de API Gateway.

2. Seleccione Create API (Crear API).
3. Elija Import from OpenAPI (Importar de OpenAPI).
4. Si guardó las definiciones de OpenAPI anteriores en un archivo, elija Select OpenAPI File (Seleccionar
archivo de OpenAPI). También puede copiar las definiciones de OpenAPI y pegarlas en el editor de
texto de importación.
5. Seleccione Import (Importar) para completar la importación de las definiciones de OpenAPI.

Para importar las definiciones de OpenAPI utilizando la CLI de AWS, guarde las definiciones de
OpenAPI en un archivo y, a continuación, ejecute el siguiente comando, en el que se supone que
la región es us-west-2 y que la ruta absoluta del archivo de OpenAPI es file:///path/to/
API_OpenAPI_template.json:

aws apigateway import-rest-api --body 'file:///path/to/API_OpenAPI_template.json' --region

us-west-2

Configuración de una API regional en API Gateway

Cuando las solicitudes de API se originan predominantemente desde una instancia EC2 o servicios dentro
de la misma región donde se ha implementado la API, normalmente un punto de enlace de API regional
reducirá la latencia de las conexiones, lo que se recomienda para este tipo de situaciones.
Note

En los casos en que los clientes de la API están dispersos geográficamente, sigue teniendo
sentido utilizar un punto de enlace de API regional, junto con su propia distribución de Amazon
CloudFront para garantizar que API Gateway no asocia la API con distribuciones de CloudFront
controladas por servicios. Para obtener más información acerca de este caso de uso, consulte la
sección sobre cómo configurar API Gateway con mi propia distribución de CloudFront.

Para crear una API regional, siga los pasos que se indican en la sección de creación de una API
optimizada para bordes (p. 239), pero debe definir de forma explícita el tipo REGIONAL como única
opción de endpointConfiguration en la API.

253
 Amazon API Gateway Guía del desarrollador
Crear y configurar

A continuación, mostramos cómo crear una API regional utilizando la consola de API Gateway, la CLI de
AWS, el SDK de AWS para JavaScript en Node.js.

Temas
• Crear una API regional mediante la consola de API Gateway (p. 254)
• Creación de una API regional con la CLI de AWS (p. 254)
• Creación de una API regional con el SDK de AWS para JavaScript (p. 254)
• Prueba de una API regional (p. 255)

Crear una API regional mediante la consola de API Gateway

Para crear una API regional mediante la consola de API Gateway

1. Inicie sesión en la consola de API Gateway y elija + Create API (Crear API).
2. En Create new API (Crear nueva API), elija la opción New API (Nueva API).
3. Escriba un nombre (por ejemplo, Simple PetStore (Console, Regional)) para API name
(Nombre de la API).
4. Elija Regional para Endpoint Type (Tipo de punto de enlace).
5. Seleccione Create API (Crear API).

A partir de aquí, puede pasar a configurar los métodos de la API y sus integraciones asociadas tal y como
se describe en la sección de creación de una API optimizada para sistemas perimetrales (p. 240).

Creación de una API regional con la CLI de AWS

Para crear una API regional con la CLI de AWS, llame al comando create-rest-api:

aws apigateway create-rest-api \

--name 'Simple PetStore (AWS CLI, Regional)' \
--description 'Simple regional PetStore API' \
--region us-west-2 \
--endpoint-configuration '{ "types": ["REGIONAL"] }'

Una respuesta correcta devuelve una carga similar a la siguiente:

{
"createdDate": "2017-10-13T18:41:39Z",
"description": "Simple regional PetStore API",
"endpointConfiguration": {
"types": "REGIONAL"
},
"id": "0qzs2sy7bh",
"name": "Simple PetStore (AWS CLI, Regional)"
}

A partir de aquí, puede seguir las mismas instrucciones dadas en the section called “Configurar una API
optimizada para bordes mediante comandos de la CLI de AWS” (p. 240) para configurar métodos e
integraciones para esta API.

Creación de una API regional con el SDK de AWS para JavaScript

Para crear una API regional con el SDK de AWS para JavaScript:

apig.createRestApi({
name: "Simple PetStore (node.js SDK, regional)",

254
 Amazon API Gateway Guía del desarrollador
Crear y configurar

endpointConfiguration: {
types: ['REGIONAL']
},
description: "Demo regional API created using the AWS SDK for node.js",
version: "0.00.001"
}, function(err, data){
if (!err) {
console.log('Create API succeeded:\n', data);
restApiId = data.id;
} else {
console.log('Create API failed:\n', err);
}
});

Una respuesta correcta devuelve una carga similar a la siguiente:

{
"createdDate": "2017-10-13T18:41:39Z",
"description": "Demo regional API created using the AWS SDK for node.js",
"endpointConfiguration": {
"types": "REGIONAL"
},
"id": "0qzs2sy7bh",
"name": "Simple PetStore (node.js SDK, regional)"
}

Una vez realizados los pasos anteriores, puede seguir las instrucciones de the section called “Configurar
una API optimizada para bordes con el SDK de AWS para Node.js” (p. 245) para configurar métodos e
integraciones para esta API.

Prueba de una API regional

Una vez implementada, el nombre de host de la URL predeterminada de la API regional tiene el siguiente
formato:

{restapi-id}.execute-api.{region}.amazonaws.com

La URL base para invocar la API es como la siguiente:

https://{restapi-id}.execute-api.{region}.amazonaws.com/{stage}

Suponiendo que configura los métodos GET /pets y GET /pets/{petId} en este ejemplo, puede
probar la API escribiendo las siguientes URL en un navegador:

https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets

https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets/1

También puede utilizar los comandos de cURL:

curl -X GET https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets

curl -X GET https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets/2

255
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Configurar métodos de API REST en API Gateway

En API Gateway, un método de API incluye una solicitud de método y una respuesta de método. Se
configura un método de API para definir lo que un cliente debería o debe hacer para enviar una solicitud
de acceso al servicio en el backend y para definir las respuestas que recibe a cambio el cliente. Para la
entrada, puede elegir los parámetros de solicitud de método, o bien una carga aplicable, para que el cliente
proporcione los datos necesarios u opcionales en el tiempo de ejecución. Para la salida, se determina
el código de estado de respuesta del método, los encabezados y el cuerpo aplicable como destinos a
los que asignar los datos de respuesta del backend, antes de que se devuelvan al cliente. Para ayudar
al desarrollador cliente a comprender los comportamientos y los formatos de entrada y salida de su API,
puede documentar la API (p. 589) y ofrecer mensajes de error adecuados (p. 438) para solicitudes no
válidas (p. 376).

Una solicitud de método de API es una solicitud HTTP. Para configurar la solicitud de método, debe
configurar un método (o verbo) HTTP, la ruta a un recurso de API, los encabezados y los parámetros
de cadenas de consulta aplicables. También configura una carga cuando el método HTTP es POST,
PUTo PATCH. Por ejemplo, para recuperar una mascota con la API de muestra PetStore (p. 43), define la
solicitud de método de API de GET /pets/{petId}, donde {petId} es un parámetro de ruta que puede
tomar un número en tiempo de ejecución.

GET /pets/1
Host: apigateway.us-east-1.amazonaws.com
...

Si el cliente especifica una ruta incorrecta, por ejemplo, /pet/1 o /pets/one en lugar de /pets/1, se
lanza una excepción.

Una respuesta de método de API es una respuesta HTTP con un código de estado determinado. Para
una integración que no sea de proxy, debe configurar respuestas de método para especificar los destinos
necesarios u opcionales de las asignaciones. Estos transforman los encabezados o el cuerpo de respuesta
de la integración en encabezados o en cuerpo de respuesta de método. El mapeo puede ser tan sencillo
como una transformación de identidad que pasa los encabezados o el cuerpo a través de la integración tal
y como están. Por ejemplo, la siguiente respuesta de método 200 muestra un ejemplo de transferencia de
una respuesta de integración correcta tal y como está.

200 OK
Content-Type: application/json
...

{
"id": "1",
"type": "dog",
"price": "$249.99"
}

En principio, puede definir una respuesta de método correspondiente a una respuesta específica desde
el backend. Normalmente, esto implica cualquier respuesta 2XX, 4XX y 5XX. Sin embargo, puede que no
sea práctico, porque a menudo es posible que no sepa con antelación todas las respuestas que puede
devolver un backend. En la práctica, puede designar una respuesta de método como predeterminada para
gestionar las respuestas desconocidas o no asignadas desde el backend. Es una buena práctica designar
la respuesta 500 como predeterminada. En cualquier caso, debe configurar al menos una respuesta de
método para integraciones que no sean de proxy. De lo contrario, API Gateway devuelve una respuesta de
error 500 al cliente incluso cuando la solicitud se completa correctamente en el backend.

Para admitir un SDK con establecimiento inflexible de tipos para la API, como un SDK de Java, debe
definir el modelo de datos de entrada para la solicitud de método y definir el modelo de datos de salida de
la respuesta de método.

256
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Temas
• Configurar una solicitud de método en API Gateway (p. 257)
• Configurar respuestas de método en API Gateway (p. 264)
• Configuración de un método con la consola de API Gateway (p. 266)

Configurar una solicitud de método en API Gateway

Configurar una solicitud de método implica realizar las siguientes tareas, después de la creación de un
recurso RestApi:

1. Creación de una nueva API o elección de una entidad Resource de API existente.
2. Creación de un recurso Method de API que sea un verbo HTTP específico en el Resource nuevo o
elegido de la API. Esta tarea se puede dividir aún más en las siguientes subtareas:
• Añadido de un método HTTP a la solicitud de métodos
• Configuración de parámetros de solicitudes
• Definición de un modelo para el cuerpo de la solicitud
• Aplicación de un esquema de autorización
• Habilitación de la validación de la solicitud

Puede realizar estas tareas con los siguientes métodos:

• Consola de API Gateway (p. 266)

• Comandos de la CLI de AWS (create-resource y put-method)
• Funciones del SDK de AWS (por ejemplo, en Node.js, createResource y putMethod)
• API REST de API Gateway (resource:create y method:put).

Para ver ejemplos del uso de estas herramientas, consulte Inicialización de la configuración de una API
REST en API Gateway (p. 239).

Temas
• Configurar recursos de API (p. 257)
• Configurar un método HTTP (p. 260)
• Configurar parámetros de solicitud de método (p. 260)
• Configurar un modelo de solicitud de método (p. 261)
• Configurar la autorización de solicitud de método (p. 262)
• Configurar la validación de solicitud de método (p. 263)

Configurar recursos de API

En una API de API Gateway, los recursos que se pueden dirigir se exponen como un árbol de entidades
Resources de API, con el recurso de raíz (/) en la parte superior de la jerarquía. El recurso de raíz
depende de la URL base de la API, que se compone del punto de enlace de la API y un nombre de etapa.
En la consola de API Gateway, este URI base se denomina Invoke URI y se muestra en el editor de etapas
de la API una vez que se implementa la API.

El punto de enlace de la API puede ser un nombre de host predeterminado o un nombre de dominio
personalizado. El nombre de host predeterminado tiene el siguiente formato:

{api-id}.execute-api.{region}.amazonaws.com

257
 Amazon API Gateway Guía del desarrollador
Crear y configurar

En este formato, la {api-id} representa el identificador de la API que genera API Gateway. La variable
{region} representa la región de AWS (por ejemplo, us-east-1) que eligió al crear la API. Un nombre
de dominio personalizado es cualquier nombre fácil de recordar en un dominio de Internet válido. Por
ejemplo, si ha registrado un dominio de Internet de example.com, *.example.com es un nombre de
dominio personalizado válido. Para obtener más información, consulte configurar nombres de dominio
personalizados (p. 542).

Para la API de ejemplo de PetStore (p. 43), el recurso de raíz (/) expone la tienda de mascotas. El recurso
/pets representa la variedad de mascotas disponibles en la tienda. El /pets/{petId} expone una
mascota individual de un identificador concreto (petId). El parámetro de la ruta de {petId} forma parte
de los parámetros de solicitudes.

Para configurar un recurso de API, se elige un recurso existente como principal y, a continuación, se crea
el recurso secundario bajo el recurso principal. Se empieza con el recurso raíz como principal, se añade un
recurso a este principal, se añade otro recurso a este recurso secundario como nuevo principal, etc., a su
identificador principal. A continuación, se añade el recurso designado al principal.

Con CLI de AWS, puede llamar al comando get-resources para averiguar qué recursos de una API
están disponibles:

aws apigateway get-resources --rest-api-id <apiId> \

--region <region>

El resultado es una lista de los recursos disponibles de la API actualmente. En la API de nuestro ejemplo
de PetStore, esta lista sería similar a la siguiente:

{
"items": [
{
"path": "/pets",
"resourceMethods": {
"GET": {}
},
"id": "6sxz2j",
"pathPart": "pets",
"parentId": "svzr2028x8"
},
{
"path": "/pets/{petId}",
"resourceMethods": {
"GET": {}
},
"id": "rjkmth",
"pathPart": "{petId}",
"parentId": "6sxz2j"
},
{
"path": "/",
"id": "svzr2028x8"
}
]
}

Cada elemento enumera los identificadores del recurso (id) y, excepto el recurso raíz, su recurso principal
inmediato (parentId), así como el nombre del recurso (pathPart). El recurso raíz es especial, ya que
no tiene ninguno principal. Después de elegir un recurso como principal, llame al siguiente comando para
añadir un recurso secundario.

aws apigateway create-resource --rest-api-id <apiId> \

--region <region> \

258
 Amazon API Gateway Guía del desarrollador
Crear y configurar

--parent-id <parentId> \
--path-part <resourceName>

Por ejemplo, para añadir alimentos de mascotas para la venta en el sitio web de PetStore, añada un
recurso food a la raíz (/), estableciendo path-part para food y parent-id para svzr2028x8. El
resultado es similar al siguiente:

{
"path": "/food",
"pathPart": "food",
"id": "xdsvhp",
"parentId": "svzr2028x8"
}

Utilizar un recurso proxy para simplificar la configuración de API

A medida que crece el negocio, el propietario de PetStore puede que decida añadir a la venta alimentos,
juguetes y otros artículos relacionados con mascotas. Para sustentarlo, puede añadir /food, /toys
y otros recursos debajo del recurso raíz. Debajo de cada categoría de venta, es posible que también
desee añadir más recursos, como por ejemplo /food/{type}/{item}, /toys/{type}/{item},
etc. Esto puede ser una tarea tediosa. Si decide añadir una capa intermedia {subtype} a las rutas de
recursos para cambiar la jerarquía de rutas a /food/{type}/{subtype}/{item}, /toys/{type}/
{subtype}/{item}, etc., los cambios afectarán a la configuración existente de la API. Para evitarlo,
puede utilizar un recurso de proxy (p. 336) de API Gateway para exponer un conjunto de recursos de la
API a la vez.

API Gateway define un recurso de proxy como un marcador de posición para que un recurso se
especifique cuando se envíe la solicitud. Un recurso de proxy se expresa mediante un parámetro de ruta
especial de {proxy+}, a menudo denominado parámetro de ruta expansiva. El signo + indica los recursos
secundarios que lleva asociados. El marcador de posición /parent/{proxy+} equivale a cualquier
recurso que coincida con el patrón de ruta de /parent/*. El nombre de parámetro de ruta expansiva,
proxy, se puede sustituir con otra cadena, del mismo modo que se trata un nombre de parámetro de ruta
normal.

Con la CLI de AWS, llama al siguiente comando para configurar un recurso de proxy bajo la raíz (/{proxy
+}):

aws apigateway create-resource --rest-api-id <apiId> \

--region <region> \
--parent-id <rootResourceId> \
--path-part {proxy+}

El resultado es similar al siguiente:

{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "234jdr",
"parentId": "svzr2028x8"
}

Para el ejemplo de API de PetStore, puede utilizar /{proxy+} para representar tanto /pets como /
pets/{petId}. Este recurso de proxy también puede hacer referencia a cualquier otro recurso (existente
o que se vaya a añadir), como por ejemplo /food/{type}/{item}, /toys/{type}/{item}, etc., o
/food/{type}/{subtype}/{item}, /toys/{type}/{subtype}/{item}, etc. El desarrollador del
backend determina la jerarquía de recursos y el desarrollador cliente es responsable de comprenderlo. API
Gateway simplemente transfiere lo que envíe el cliente al backend.

259
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Una API puede tener más de un recurso de proxy. Por ejemplo, los siguientes recursos de proxy están
permitidos dentro de una API.

/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}

Cuando un recurso de proxy tiene elementos secundarios que no son de proxy, los recursos secundarios
se excluyen de la representación del recurso de proxy. En los ejemplos anteriores, /{proxy+} hace
referencia a cualquier recurso bajo el recurso raíz, excepto los recursos /parent[/*]. En otras palabras,
una solicitud de método realizada para un recurso específico prevalece sobre una solicitud de método
realizada para un recurso genérico en el mismo nivel de la jerarquía de recursos.

Un recurso de proxy no puede tener cualquier recurso secundario. Un recurso de API después de {proxy
+} es redundante y ambiguo. Los siguientes recursos de proxy no se permiten dentro de una API.

/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}

Configurar un método HTTP

Una solicitud de métodos de API se encapsula mediante el recurso Method de API Gateway. Para
configurar la solicitud de método, primero debe iniciar el recurso Method, configurando al menos un
método HTTP y un tipo de autorización en el método.

API Gateway, estrechamente asociado con el recurso de proxy, admite un método HTTP de ANY. Este
método ANY representa cualquier método HTTP que se suministre en el tiempo de ejecución. Le permite
utilizar una sola configuración de método de API para todos los métodos HTTP admitidos de DELETE, GET,
HEAD, OPTIONS, PATCH, POST y PUT.

También puede configurar el método ANY en un recurso que no sea de proxy. Al combinar el método
ANY con un recurso de proxy, obtiene una configuración de método de API único para todos los métodos
compatibles con HTTP frente a cualquier recurso de una API. Además, el backend puede evolucionar sin
que afecte a la configuración de API existente.

Antes de configurar un método de API, tenga en cuenta quién puede llamar al método. Establezca el tipo
de autorización según su plan. Para un acceso abierto, establézcalo en NONE. Para utilizar permisos de
IAM, establezca el tipo de autorización en AWS_IAM. Para utilizar una función de autorizador de Lambda,
establezca esta propiedad en CUSTOM. Para utilizar un grupo de usuarios de Amazon Cognito, establezca
el tipo de autorización en COGNITO_USER_POOLS.

El siguiente comando de CLI de AWS muestra cómo crear una solicitud de método del verbo ANY frente a
un recurso especificado (6sxz2j), mediante los permisos de IAM para controlar su acceso.

aws apigateway put-method --rest-api-id vaz7da96z6 \

--resource-id 6sxz2j \
--http-method ANY \
--authorization-type AWS_IAM \
--region us-west-2

Para crear una solicitud de método de API con un tipo de autorización distinta, consulte the section called
“Configurar la autorización de solicitud de método” (p. 262).

Configurar parámetros de solicitud de método

Los parámetros de solicitud de método son una forma para que un cliente proporcione los datos de entrada
o el contexto de ejecución necesarios para completar la solicitud de métodos. Un parámetro de método
puede ser un método de ruta, un encabezado o un parámetro de cadena de consulta. Como parte de la

260
 Amazon API Gateway Guía del desarrollador
Crear y configurar

configuración de solicitud de método, debe declarar los parámetros de solicitud necesarios para que estén
disponibles para el cliente. Para la integración que no sea de proxy, puede traducir estos parámetros de
solicitud en un formato que sea compatible con el requisito del backend.

Por ejemplo, para la solicitud de métodos GET /pets/{petId}, la variable de ruta {petId} es un
parámetro de solicitud necesario. Puede declarar este parámetro de ruta al llamar al comando put-
method de la CLI de AWS. Esto se detalla de la siguiente manera:

aws apigateway put-method --rest-api-id vaz7da96z6 \

--resource-id rjkmth \
--http-method GET \
--authorization-type "NONE" \
--region us-west-2 \
--request-parameters method.request.path.petId=true

Si un parámetro no es necesario, puede establecerlo en false en request-parameters. Por ejemplo,

si el método GET /pets utiliza un parámetro de cadena de consulta opcional de type y un parámetro de
encabezado opcional de breed, puede declararlos usando el siguiente comando de la CLI, suponiendo
que el recurso /pets sea id 6sxz2j:

aws apigateway put-method --rest-api-id vaz7da96z6 \

--resource-id 6sxz2j \
--http-method GET \
--authorization-type "NONE" \
--region us-west-2 \
--request-parameters
method.request.querystring.type=false,method.request.header.breed=false

En lugar de esta forma abreviada, puede utilizar una cadena de JSON para establecer el valor request-
parameters:

'{"method.request.querystring.type":false,"method.request-header.breed":false}'

Con esta configuración, el cliente puede consultar las mascotas por tipo:

GET /pets?type=dog

Además, el cliente puede consultar los perros de raza caniche de la siguiente manera:

GET /pets?type=dog
breed:poodle

Para obtener información sobre cómo asignar parámetros de solicitud de método a parámetros de solicitud
de integración, consulte the section called “Integraciones” (p. 331).

Configurar un modelo de solicitud de método

Para un método de API que pueda tomar datos de entrada en una carga, puede utilizar un modelo.
Un modelo se expresa en un esquema JSON, borrador 4 y describe la estructura de datos del cuerpo
de la solicitud. Con un modelo, un cliente puede determinar cómo construir una carga de solicitud de
métodos como entrada. Y lo que es más importante, API Gateway utiliza el modelo para validar una
solicitud (p. 376), generar un SDK (p. 633) e inicializar una plantilla de mapeo para configurar la
integración en la consola de API Gateway. Para obtener información sobre cómo crear un modelo, consulte
Crear modelos y plantillas de mapeo (p. 395).

En función de los tipos de contenido, una carga de método puede tener diferentes formatos. Un modelo
se indexa frente al tipo de medio de la carga aplicada. API Gateway utiliza el encabezado de la solicitud

261
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Content-Type para determinar el tipo de contenido. Para configurar modelos de solicitud de método,
agregue pares de clave-valor de formato "<media-type>":"<model-name>" al mapa requestModels
al llamar al comando put-method de la CLI de AWS.

Para utilizar el mismo modelo independientemente del tipo de contenido, especifique $default como
clave.

Por ejemplo, para establecer un modelo en la carga de JSON de la solicitud de método POST /pets de la
API de ejemplo de PetStore, puede llamar al siguiente comando de CLI de AWS:

aws apigateway put-method \

--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method POST \
--authorization-type "NONE" \
--region us-west-2 \
--request-models '{"application/json":"petModel"}'

Aquí, petModel es el valor de propiedad name de un recurso Model que describe una mascota. La
definición del esquema real se expresa como un valor de cadena JSON de la propiedad schema del
recurso Model.

En un SDK Java de la API, u otro tipo de SDK con establecimiento inflexible de tipos, los datos de entrada
se forman como la clase petModel derivada de la definición del esquema. Con el modelo de solicitud,
los datos de entrada en el SDK generado se forman en la clase Empty, que se deriva del modelo Empty
predeterminado. En este caso, el cliente no puede crear una instancia de la clase de datos correcta para
proporcionar la entrada necesaria.

Configurar la autorización de solicitud de método

Para controlar quién puede llamar al método de la API, puede configurar el tipo de autorización en el
método. Puede utilizar este tipo para aplicar uno de los autorizadores admitidos, incluidos roles y políticas
de IAM (AWS_IAM), un grupo de usuarios de Amazon Cognito (COGNITO_USER_POOLS), o un autorizador
de Lambda basado en funciones de Lambda (CUSTOM).

Para utilizar permisos de IAM para autorizar el acceso al método de la API, establezca la propiedad de
entrada authorization-type en AWS_IAM. Cuando esta opción está establecida, API Gateway verifica
la firma del intermediario en la solicitud, basándose en el identificador de clave de acceso de usuario de
IAM del intermediario y la clave secreta. Si el usuario verificado tiene permiso para llamar al método, se
acepta la solicitud. De lo contrario, se rechaza la solicitud y el intermediario recibe una respuesta de error
no autorizado. La llamada al método no da un resultado correcto, a menos que se haya concedido permiso
al intermediario para invocar el método de la API o que se le permita al intermediario que asuma un rol
para el que se le ha concedido permiso. El intermediario tiene permisos para llamar a este y a cualquier
otro método de la API creado por cualquier usuario de la misma cuenta de AWS si el intermediario tiene la
siguiente política de IAM asociada a su usuario de IAM:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": "arn:aws:execute-api:*:*:*"
}
]

262
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Para obtener más información, consulte the section called “Usar permisos de IAM” (p. 287).

En la actualidad, esta política se puede conceder solo a los usuarios de IAM de la cuenta del propietario
de la API. Los usuarios de una cuenta de AWS diferente pueden llamar a los métodos de la API si se les
permite asumir un rol de la cuenta del propietario de la API y el rol asumido tiene los permisos adecuados
para la acción execute-api:Invoke. Para obtener más información sobre los permisos entre cuentas,
consulte Uso de roles de IAM.

Puede utilizar CLI de AWS, un SDK de AWS o un cliente de API REST, como Postman, que implementa el
Proceso de firma Signature Version 4.

Para utilizar un autorizador de Lambda para autorizar el acceso al método de la API, establezca
la propiedad de entrada authorization-type en CUSTOM y establezca la propiedad de entrada
authorizer-id en el valor de propiedad id de un autorizador de Lambda que ya exista. El autorizador
de Lambda al que se hace referencia puede ser del tipo TOKEN o REQUEST. Para obtener información
acerca de cómo crear un autorizador de Lambda, consulte the section called “Uso de autorizadores
Lambda” (p. 305).

Para utilizar un grupo de usuarios de Amazon Cognito para autorizar el acceso al método de la
API, establezca la propiedad de entrada authorization-type en COGNITO_USER_POOLS y
establezca la propiedad de entrada authorizer-id en el valor de propiedad id del autorizador
COGNITO_USER_POOLS que ya se ha creado. Para obtener información sobre la creación de un
autorizador de grupo de usuarios de Amazon Cognito, consulte the section called “Uso de grupos de
usuarios de Amazon Cognito como autorizador para una API REST” (p. 322).

Configurar la validación de solicitud de método

Puede habilitar la validación de solicitud al configurar una solicitud de método de API. Primero tiene que
crear un validador de solicitudes:

aws apigateway create-request-validator \

--rest-api-id 7zw9uyk9kl \
--name bodyOnlyValidator \
--validate-request-body \
--no-validate-request-parameters

Este comando de la CLI crea un validador de solicitud de solo cuerpo. A continuación, se muestra un
ejemplo de resultado:

{
"validateRequestParameters": true,
"validateRequestBody": true,
"id": "jgpyy6",
"name": "bodyOnlyValidator"
}

Con este validador de solicitud, puede habilitar la validación de solicitud como parte de la configuración de
solicitud de método:

aws apigateway put-method \

--rest-api-id 7zw9uyk9kl
--region us-west-2
--resource-id xdsvhp
--http-method PUT
--authorization-type "NONE"
--request-parameters '{"method.request.querystring.type": false,
"method.request.querystring.page":false}'

263
 Amazon API Gateway Guía del desarrollador
Crear y configurar

--request-models '{"application/json":"petModel"}'
--request-validator-id jgpyy6

Para que se incluya en la validación de solicitud, debe declararse un parámetro de

solicitud como sea necesario. Si el parámetro de cadena de consulta de la página se utiliza
en la validación de solicitud, el mapa de request-parameters del ejemplo anterior
debe especificarse como '{"method.request.querystring.type": false,
"method.request.querystring.page":true}'.

Configurar respuestas de método en API Gateway

Una respuesta de método de API encapsula el resultado de una solicitud de método de API que el cliente
recibirá. Los datos de salida incluyen un código de estado HTTP, algunos encabezados y posiblemente un
cuerpo.

Con las integraciones que no sean de proxy, los parámetros de respuesta especificados y el cuerpo
se pueden asignar desde los datos de respuesta de integración asociados o se les pueden asignar
determinados valores estáticos según las asignaciones. Estas asignaciones se especifican en la respuesta
de integración. La asignación puede ser una transformación idéntica que transfiere la respuesta de
integración tal y como es.

Con una integración de proxy, API Gateway transfiere la respuesta del backend a la respuesta del método
automáticamente. No es necesario configurar la respuesta del método de API. Sin embargo, con la
integración proxy de Lambda, la función de Lambda debe devolver un resultado de este formato de
salida (p. 351) para que API Gateway asigne correctamente la respuesta de integración a una respuesta
de método.

Mediante programación, la configuración de la respuesta de método equivale a crear un recurso

MethodResponse de API Gateway y a establecer las propiedades de statusCode, responseParameters y
responseModels.

Al establecer códigos de estado para un método de API, debe elegir uno como predeterminado para
gestionar cualquier respuesta de integración de un código de estado no previsto. Es razonable establecer
500 como predeterminado, ya que esto equivale a emitir respuestas que de otro modo no estarían
asignadas como un error del servidor. Por motivos de instrucción, la consola de API Gateway establece la
respuesta 200 como la opción predeterminada. Pero puede restablecerla en la respuesta 500.

Para configurar una respuesta de método, debe haber creado la solicitud de método.

Configurar el código de estado de la respuesta de método

El código de estado de una respuesta de método define un tipo de respuesta. Por ejemplo, las respuestas
de 200, 400 y 500 indican respuestas de éxito, de error del lado del cliente y de error del lado del servidor,
respectivamente.

Para configurar un código de estado de respuesta de método, establezca la propiedad statusCode en un

código de estado HTTP. El siguiente comando de CLI de AWS crea una respuesta de método de 200.

aws apigateway put-method-response \

--region us-west-2 \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200

Configurar parámetros de respuesta de métodos

Los parámetros de respuesta de método definen qué encabezados recibe el cliente en respuesta a la
solicitud de método asociado. Los parámetros de respuesta también especifican un objetivo al que API

264
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Gateway asigna un parámetro de respuesta de integración, según los mapeos prescritos en la respuesta
de integración del método de la API.

Para configurar los parámetros de respuesta de método, agregue al mapa responseParameters de

MethodResponse pares de clave-valor con el formato "{parameter-name}":"{boolean}". El
siguiente comando de CLI muestra un ejemplo de configuración del encabezado my-header, la variable
de rutas petId y el parámetro de consulta query como objetivos de la asignación:

aws apigateway put-method-response \

--region us-west-2 \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200 \
--response-parameters method.request.header.my-
header=false,method.request.path.petId=true,method.request.querystring.query=false

Configurar modelos de respuesta de método

Un modelo de respuesta de método define un formato del cuerpo de la respuesta del método. Antes de
configurar el modelo de respuesta, primero debe crear el modelo en API Gateway. Para ello, puede llamar
al comando create-model. El siguiente ejemplo muestra cómo crear un modelo PetStorePet para
describir el cuerpo de la respuesta para la solicitud de método GET /pets/{petId}.

aws apigateway create-model \

--region us-west-2 \
--rest-api-id vaz7da96z6 \
--content-type application/json \
--name PetStorePet \
--schema '{ \
"$schema": "http://json-schema.org/draft-04/schema#", \
"title": "PetStorePet", \
"type": "object", \
"properties": { \
"id": { "type": "number" }, \
"type": { "type": "string" }, \
"price": { "type": "number" } \
} \
}'

El resultado se crea como un recurso Model de API Gateway.

Para configurar los modelos de respuesta de método para definir el formato de la carga, agregue el par de
clave-valor "application/json":"PetStorePet" al mapa requestModels del recurso MethodResponse. El
siguiente comando de CLI de AWS de put-method-response muestra cómo se realiza:

aws apigateway put-method-response \

--region us-west-2 \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200 \
--response-parameters method.request.header.my-
header=false,method.request.path.petId=true,method.request.querystring.query=false \
--response-models '{"application/json":"PetStorePet"}'

Es necesario configurar un modelo de respuesta de método al generar un SDK con establecimiento

inflexible de tipos para la API. Garantiza que el resultado se traduzca en una clase apropiada en Java u
Objective-C. En otros casos, la configuración de un modelo es opcional.

265
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Configuración de un método con la consola de API Gateway

Antes de configurar un método de API, verifique lo siguiente:

• El método debe estar disponible en API Gateway. Siga las instrucciones en Tutorial: Desarrollo de una
API de REST con integración HTTP no de proxy (p. 56).
• Si desea que el método se comunique con una función de Lambda, debe haber creado ya el rol de
invocación de Lambda y el rol de ejecución de Lambda en IAM. También debe haber creado la función
de Lambda con la que el método se comunicará en AWS Lambda. Para crear los roles y la función,
utilice las instrucciones de Creación de una función de Lambda para la integración de Lambda no de
proxy (p. 34) de Desarrollo de una API de REST de API Gateway con integración Lambda (p. 26).
• Si desea que el método se comunique con una integración HTTP o de proxy HTTP, debe haber creado y
tener acceso a la URL del punto de enlace HTTP con la que se comunicará el método.
• Compruebe que API Gateway admite los certificados de los puntos de enlace HTTP y proxy de HTTP.
Para obtener más información, consulte Entidades de certificación compatibles con API Gateway para
las integraciones HTTP y Proxy HTTP (p. 667).

Temas
• Configurar una solicitud de método de API Gateway en la consola de API Gateway (p. 266)
• Configurar una respuesta de método de API Gateway en la consola de API Gateway (p. 268)

Configurar una solicitud de método de API Gateway en la consola de API Gateway

Para utilizar la consola de API Gateway para especificar una solicitud o respuesta del método de una API y
para configurar la forma en que el método autorizará las solicitudes, siga estas instrucciones.
Note

Estas instrucciones presuponen que ya ha completado los pasos que se detallan en Configuración
de una solicitud de integración de la API mediante la consola de API Gateway (p. 337). El mejor
modo de utilizarlas es para complementar las conversaciones que se indican en Desarrollo de una
API de REST de API Gateway con integración Lambda (p. 26).

1. Con el método seleccionado en el panel Resources (Recursos), elija Method Request (Solicitud de
método) en el panel Method Execution (Ejecución del método).
2. En Settings (Configuración), seleccione el icono de lápiz para abrir el menú desplegable Authorization
(Autorización) y elija uno de los autorizadores disponibles.

a. Para habilitar el acceso abierto al método a cualquier usuario, elija NONE. Este paso se puede
omitir si el ajuste predeterminado no se ha cambiado.
b. Para utilizar permisos de IAM para controlar el acceso de clientes al método, elija AWS_IAM. Con
esta opción, solo los usuarios de los roles de IAM con la política correcta de IAM asociada pueden
llamar a este método.

Para crear el rol de IAM, especifique una política de acceso con un formato como el siguiente:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"resource-statement"

266
 Amazon API Gateway Guía del desarrollador
Crear y configurar

]
}
]
}

En esta política de acceso, resource-statement es el valor del campo ARN en la sección

Authorization Settings (Configuración de autorización). Para obtener más información acerca de
cómo establecer los permisos de IAM, consulte Control del acceso a una API con permisos de
IAM (p. 287).

Para crear el rol de IAM, puede adaptar las instrucciones de "Para crear el rol de invocación de
Lambda y su política" y "Para crear el rol de ejecución de Lambda y su política" de la sección
Crear funciones de Lambda (p. 34) de Desarrollo de una API de REST de API Gateway con
integración Lambda (p. 26).

Para guardar la selección, elija Update (Actualizar). De lo contrario, seleccione Cancel (Cancelar).
c. Para utilizar un autorizador de Lambda, elija uno en Token authorizer (Autorizador de tokens).
Debe haber creado un autorizador de Lambda para que esta opción se muestre en el menú
desplegable. Para obtener más información sobre cómo crear un autorizador de Lambda,
consulte Uso de autorizadores Lambda de API Gateway (p. 305).
d. Para utilizar un grupo de usuarios de Amazon Cognito, elija un grupo de usuarios disponible en
Cognito user pool authorizers (Autorizadores de grupos de usuarios de Cognito). Debe haber
creado un grupo de usuarios en Amazon Cognito y un autorizador de grupo de usuarios de
Amazon Cognito en API Gateway para que esta opción se muestre en el menú desplegable. Para
obtener información sobre cómo crear un autorizador de grupo de usuarios de Amazon Cognito,
consulte Control del acceso a una API de REST con grupos de usuarios de Amazon Cognito
como autorizador (p. 322).
3. Para habilitar o deshabilitar la validación de solicitud, haga clic en el icono de lápiz del menú
desplegable en Request Validator (Validador de solicitudes) y elija una de las opciones que se
muestran. Para obtener más información acerca de cada opción, consulte Habilitar la validación de
solicitudes en API Gateway (p. 376).
4. Para solicitar una clave de API, haga clic en el icono de lápiz para abrir el menú desplegable API Key
Required (Clave de API obligatoria) y elija true o false según los requisitos de la API. Cuando se
habilita, las claves de API se utilizan en planes de uso (p. 574) para limitar el tráfico del cliente.
5. Para añadir un parámetro de cadena de consulta al método, haga lo siguiente:

a. Elija la flecha situada junto a URL Query String Parameters (Parámetros de cadena de consulta
URL) y, a continuación, elija Add query string (Añadir cadena de consulta).
b. En Name (Nombre), escriba el nombre del parámetro de cadena de consulta.
c. Haga clic en el icono de marca de verificación para guardar el nuevo nombre de parámetro de
cadena de consulta.
d. Si el parámetro de cadena de consulta recién creado debe utilizarse para la validación de
solicitud, elija la opción Required (Obligatorio). Para obtener más información sobre la validación
de solicitud, consulte Habilitar la validación de solicitudes en API Gateway (p. 376).
e. Si el parámetro de cadena de consulta recién creado debe utilizarse como parte de una clave
de almacenamiento en caché, marque la opción Caching (Almacenamiento en caché). Esto solo
puede aplicarse cuando se habilita el almacenamiento en caché. Para obtener más información
acerca del almacenamiento en caché, consulte Usar parámetros de método o integración como
claves de caché para indexar las respuestas almacenadas en caché (p. 566).

Tip

Para eliminar el parámetro de cadena de consulta, haga clic en el icono x asociado al mismo
y, a continuación, elija Remove this parameter and any dependent parameters (Eliminar este
parámetro y todos los parámetros dependientes) para confirmar la eliminación.

267
 Amazon API Gateway Guía del desarrollador
Crear y configurar

Para cambiar el nombre del parámetro de cadena de consulta, elimínelo y cree uno nuevo.
6. Para añadir un parámetro de encabezado al método, haga lo siguiente:

a. Elija la flecha situada junto a HTTP Request Headers (Encabezados de solicitud HTTP) y, a
continuación, elija Add header (Añadir encabezado).
b. Para Name (Nombre), escriba el nombre del parámetro de encabezado y, a continuación, haga
clic en el icono de marca de verificación para guardar la configuración.
c. Si el parámetro de encabezado recién creado debe utilizarse para la validación de solicitud, elija
la opción Required (Obligatorio). Para obtener más información sobre la validación de solicitud,
consulte Habilitar la validación de solicitudes en API Gateway (p. 376).
d. Si el parámetro de encabezado recién creado debe utilizarse como parte de una clave de
almacenamiento en caché, elija la opción Caching (Almacenamiento en caché). Esto solo puede
aplicarse cuando se habilita el almacenamiento en caché. Para obtener más información acerca
del almacenamiento en caché, consulte Usar parámetros de método o integración como claves de
caché para indexar las respuestas almacenadas en caché (p. 566).

Tip

Para eliminar el parámetro de encabezado, haga clic en el icono x asociado al mismo y, a

continuación, elija Remove this parameter and any dependent parameters (Eliminar este
parámetro y todos los parámetros dependientes) para confirmar la eliminación.
Para cambiar el nombre del parámetro de encabezado, elimínelo y cree uno nuevo.
7. Para declarar el formato de carga de una solicitud de método con el verbo HTTP POST, PUTo PATCH,
expanda Request Body (Cuerpo de la solicitud) y realice lo siguiente:

a. Elija Add model (Añadir modelo).

b. Escriba un tipo de MIME (por ejemplo, application/json) para Content type (Tipo de
contenido).
c. Abra el menú desplegable Model name (Nombre de modelo) para elegir un modelo disponible
para la carga y haga clic en el icono de marca de verificación para guardar la configuración.

Los modelos disponibles actualmente para la API incluyen los modelos predeterminados Empty
y Error, así como cualquier modelo que haya creado y agregado a la colección Models de
la API. Para obtener más información acerca de la creación de un modelo, consulte Crear un
modelo (p. 395).
Note

El modelo es útil para informar al cliente del formato de datos esperado de una carga.
Resulta útil para generar una plantilla de asignación de esqueleto. Es importante para
generar un SDK con establecimiento inflexible de tipos de la API en idiomas como Java,
C #, Objective-C y Swift. Solo es necesario si se habilita la validación de solicitudes
frente a la carga.
8. Para asignar un nombre de operación en un SDK de Java de esta API, generado por API Gateway,
expanda SDK Settings (Configuración del SDK) y escriba un nombre en Operation name (Nombre
de operación). Por ejemplo, para la solicitud de método de GET /pets/{petId}, el nombre de
operación de SDK de Java correspondiente es por defecto GetPetsPetId. Este nombre se crea a
partir del verbo HTTP del método (GET) y los nombres de variables de la ruta de recursos (Pets y
PetId). Si establece el nombre de operación como getPetById, el nombre de operación de SDK
pasa a ser GetPetById.

Configurar una respuesta de método de API Gateway en la consola de API Gateway

Un método de API puede tener una o más respuestas. Cada respuesta se indexa mediante su código
de estado HTTP. De forma predeterminada, la consola de API Gateway agrega la respuesta 200 a las

268
 Amazon API Gateway Guía del desarrollador
Control de acceso

respuestas de método. Puede modificarla, por ejemplo, para que el método devuelva 201 en su lugar.
Puede añadir otras respuestas, por ejemplo, 409 para la denegación de acceso y 500 para las variables
de etapa sin inicializar utilizadas.

Para utilizar la consola de API Gateway para modificar, eliminar o agregar una respuesta a un método de
API, siga estas instrucciones.

1. Elija Method Response (Respuesta de método) en Method Execution (Ejecución del método) para un
método concreto de un recurso de API.
2. Para añadir una respuesta nueva, elija Add Response (Añadir respuesta).

a. Escriba un código de estado HTTP; por ejemplo, 200, 400, o 500, para HTTP Status (Estado de
HTTP) y, a continuación, haga clic en el icono de marca de verificación para guardar la selección.

Si una respuesta devuelta del backend no tiene una respuesta de método correspondiente
definida, API Gateway no puede devolver la respuesta al cliente. En su lugar, devuelve una
respuesta de error 500 Internal server error.
b. Amplíe la respuesta del código de estado dado.
c. Elija Add Header (Añadir encabezado).
d. Escriba un nombre para Name (Nombre) en Response Headers for {status} (Encabezados de
respuesta para {estado}) y, a continuación, haga clic en el icono de marca de verificación para
guardar la selección.

Si necesita traducir cualquier encabezado devuelto por el backend a uno definido en una
respuesta de método, primero debe añadir el encabezado de la respuesta de método tal y como
se describe en este paso.
e. Elija Add Response Model (Añadir modelo de respuesta) en Response Body for {status}
(Cuerpo de respuesta para {estado}).
f. Escriba el tipo de medio de la carga de respuesta de Content type (Tipo de contenido) y elija un
modelo en el menú desplegable Models (Modelos).
g. Haga clic en el icono de marca de verificación para guardar la configuración.
3. Para modificar una respuesta existente, expanda la respuesta y siga el Paso 2 anterior.
4. Para eliminar una respuesta, haga clic en el icono x para la respuesta y confirme que desea eliminar la
respuesta.

Para cada respuesta que devuelve el backend, debe tener una respuesta compatible configurada como
respuesta de método. Sin embargo, los encabezados de respuesta de método de configuración y el
modelo de carga son opcionales, a menos que asigne el resultado del backend a la respuesta de método
antes de volver al cliente. Además, un modelo de carga de respuesta de método es importante si está
generando un SDK con establecimiento inflexible de tipos para su API.

Control y administración del acceso a una API REST

en API Gateway
API Gateway admite varios mecanismos para controlar y administrar el acceso a la API.

Puede utilizar os siguientes mecanismos para realizar la autenticación y autorización:

• Gracias a las políticas de recursos, puede crear políticas basadas en recursos para permitir o denegar
el acceso a sus API y métodos desde determinadas direcciones IP de origen o determinados puntos
de enlace de la VPC. Para obtener más información, consulte the section called “Uso de políticas de
recursos de API Gateway” (p. 270).
• Los roles y políticas de AWS IAM estándar ofrecen controles de acceso flexibles y robustos que se
pueden aplicar a toda una API o a métodos individuales. Puede usar roles y políticas de IAM para

269
 Amazon API Gateway Guía del desarrollador
Control de acceso

controlar quién puede crear y administrar sus API, así como quién puede invocarlas. Para obtener más
información, consulte the section called “Usar permisos de IAM” (p. 287).
• Las etiquetas de IAM se pueden utilizar con políticas de IAM para controlar el acceso. Para obtener más
información, consulte the section called “Control de acceso basado en etiquetas” (p. 834).
• Las políticas de punto de enlace para los puntos de enlace de la VPC de interfaz le permiten asociar las
políticas de recursos de IAM a puntos de enlace de interfaz de la VPC para mejorar la seguridad de sus
API privadas. Para obtener más información, consulte the section called “Utilizar políticas de punto de
enlace de la VPC para API privadas” (p. 303).
• Los autorizadores Lambda son funciones de Lambda que controlan el acceso a los métodos de
la API REST utilizando la autenticación de token al portador, así como la información descrita por
los encabezados, rutas, cadenas de consulta, variables de etapa o parámetros de solicitud de
variables contextuales. Los autorizadores Lambda se utilizan para controlar quién puede invocar los
métodos REST API. Para obtener más información, consulte the section called “Uso de autorizadores
Lambda” (p. 305).
• Los grupos de usuarios de Amazon Cognito permiten crear soluciones personalizables de autenticación
y autorización para las API REST. Los grupos de usuarios de Amazon Cognito se utilizan para controlar
quién puede invocar los métodos de la API REST. Para obtener más información, consulte the section
called “Uso de grupos de usuarios de Amazon Cognito como autorizador para una API REST” (p. 322).

Puede utilizar los siguientes mecanismos para realizar otras tareas relacionadas con el control de acceso:

• El uso compartido de recursos entre orígenes (CORS) permite controlar la forma en que la API REST
responde a las solicitudes de recursos entre dominios. Para obtener más información, consulte the
section called “CORS” (p. 445).
• Los certificados SSL del lado del cliente pueden utilizarse para verificar que las solicitudes HTTP
dirigidas a su sistema backend proceden de API Gateway. Para obtener más información, consulte the
section called “Certificados de cliente” (p. 664).
• AWS WAF se puede utilizar para proteger la API de API Gateway frente a ataques web comunes. Para
obtener más información, consulte the section called “AWS WAF” (p. 683).

Puede utilizar los siguientes mecanismos para rastrear y limitar el acceso concedido a los clientes
autorizados:

• Los planes de uso permiten proporcionar claves de API a sus clientes y, después, realizar un
seguimiento y limitar el uso de etapas y métodos de API para cada clave de API. Para obtener más
información, consulte the section called “Planes de uso” (p. 574).

Control del acceso a una API con políticas de recursos de API

Gateway
Las políticas de recursos de Amazon API Gateway son documentos de política JSON que se asocian a
una API para controlar si una entidad principal especificada (por lo general, un usuario o un rol de IAM)
puede invocar la API. Puede utilizar las políticas de recursos de API Gateway para permitir la invocación
segura de la API por parte de:

• Los usuarios de una cuenta de AWS especificada.

• Los intervalos de direcciones IP o bloques de CIDR especificados.
• Las nubes privadas virtuales (VPC) o los puntos de enlace de la VPC (de cualquier cuenta)
especificados.

Puede utilizar las políticas de recursos con todos los tipos de enlace de la API de API Gateway: privados,
optimizados para bordes y regionales.

270
 Amazon API Gateway Guía del desarrollador
Control de acceso

Para API privadas, puede utilizar las políticas de recursos junto con las políticas de punto de enlace de
la VPC para controlar qué entidades principales tienen acceso a qué recursos y acciones. Para obtener
más información, consulte the section called “Utilizar políticas de punto de enlace de la VPC para API
privadas” (p. 303).

Puede asociar una política de recursos a una API utilizando la consola de administración de AWS, la CLI
de AWS o los SDK de AWS.

Las políticas de recursos de API Gateway son diferentes de las políticas basadas en entidades de IAM.
Las políticas basadas en identidades de IAM se asocian a usuarios, grupos o roles de IAM y definen qué
acciones pueden realizar esas identidades y en qué recursos. Las políticas de recursos de API Gateway
están asociadas a recursos. Para obtener un análisis más detallado de las diferencias entre las políticas
basadas en identidades y las políticas de recursos, consulte Políticas basadas en identidades y políticas
basadas en recursos.

Puede utilizar las políticas de recursos de API Gateway junto con las políticas de IAM.

Temas
• Información general del lenguaje de políticas de acceso para Amazon API Gateway (p. 271)
• Cómo afectan las políticas de recursos de API Gateway al flujo de trabajo de autorización (p. 272)
• Ejemplos de políticas de recursos de API Gateway (p. 281)
• Creación y asociación de una política de recursos de API Gateway a una API (p. 284)
• Claves de condición de AWS que se pueden utilizar en las políticas de recursos de API
Gateway (p. 285)

Información general del lenguaje de políticas de acceso para Amazon API

Gateway
Esta página describe los elementos básicos utilizados en las políticas de recursos de Amazon API
Gateway.

Las políticas de recursos se especifican utilizando la misma sintaxis que para las políticas de IAM. Para
obtener información completa acerca del lenguaje de políticas, consulte Información general sobre las
políticas de IAM y Referencia de políticas de AWS Identity and Access Management en la guía del usuario
de IAM.

Para obtener información sobre cómo decide un servicio de AWS si se permite o se deniega una solicitud
determinada, consulte Determinar si se permite o deniega una solicitud.

Elementos comunes en una política de acceso

Una política de recursos contiene los siguientes elementos básicos:

• Recursos: las API son los recursos de Amazon API Gateway para los que puede conceder o denegar
permisos. En una política, se usa el nombre de recurso de Amazon (ARN) para identificar el recurso.
También puede utilizar sintaxis abreviada, que API Gateway expande automáticamente al ARN completo
al guardar una política de recursos. Para obtener más información, consulte Ejemplos de políticas de
recursos de API Gateway (p. 281).

Para conocer el formato del elemento Resource completo, consulte Formato de Resource de permisos
para ejecutar la API en API Gateway (p. 296).
• Acciones: para cada recurso, Amazon API Gateway admite un conjunto de operaciones. Con las
palabras clave de acción puede identificar las operaciones del recurso que desea permitir o denegar.

Por ejemplo, el permiso execute-api:Invoke autorizará al usuario a invocar una API previa solicitud
del cliente.

271
 Amazon API Gateway Guía del desarrollador
Control de acceso

Para conocer el formato del elemento Action, consulte Formato de Action de permisos para ejecutar la
API en API Gateway (p. 296).
• Efecto: el efecto que se obtendrá cuando el usuario solicite la acción específica. Puede ser Allow o
Deny. También puede denegar de forma explícita el acceso a un recurso para asegurarse de que un
usuario no obtenga acceso a él, aunque otra política se lo conceda.
Note

"Denegar de forma implícita" es lo mismo que "denegar de forma predeterminada".

Una "negación implícita" es diferente de una "negación explícita". Para obtener más
información, consulte Diferencia entre denegar de forma predeterminada y la denegación
explícita.
• Entidad principal: la cuenta o el usuario con permiso de acceso a las acciones y los recursos en la
instrucción. En una política de recursos, la entidad principal es el usuario o la cuenta de IAM que recibe
este permiso.

La política de recursos del ejemplo siguiente ilustra los elementos comunes de política mencionados
anteriormente. La política concede acceso a la API bajo el account-id especificado en la región
especificada a cualquier usuario cuya dirección IP de origen está en el bloque de direcciones
123.4.5.6/24. La política deniega todo el acceso a la API si la IP de origen del usuario no está dentro
del rango.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:region:account-id:*"
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:region:account-id:*",
"Condition": {
"NotIpAddress": {
"aws:SourceIp": "123.4.5.6/24"
}
}
}
]
}

Cómo afectan las políticas de recursos de API Gateway al flujo de trabajo de

autorización
Cuando API Gateway evalúa la política de recursos asociada a la API, el resultado depende del tipo de
autenticación que se haya definido para la API, tal y como se muestra en los diagramas de flujo de las
siguientes secciones.

Temas
• Solo política de recursos de API Gateway (p. 273)
• Autorizador de Lambda y política de recursos (p. 274)
• Autenticación de IAM y política de recursos (p. 276)

272
 Amazon API Gateway Guía del desarrollador
Control de acceso

• Política de recursos y autenticación de Amazon Cognito (p. 278)

• Tablas de resultados de evaluación de políticas (p. 280)

Solo política de recursos de API Gateway

En este flujo de trabajo, una política de recursos de API Gateway está asociada a la API, pero no se
ha definido ningún tipo de autenticación para la API. Para evaluar la política ay que buscar un permiso
explícito en función de los criterios de entrada del intermediario. Una denegación implícita o cualquier
denegación explícita provoca la denegación del intermediario.

El siguiente ejemplo muestra dicha política.

{
"Version": "2012-10-17",
"Statement": [
{

273
 Amazon API Gateway Guía del desarrollador
Control de acceso

"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:region:account-id:api-id/",
"Condition": {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}

Autorizador de Lambda y política de recursos

En este flujo de trabajo, un autorizador de Lambda está configurado para la API, además de una política
de recursos. La política de recursos se evalúan en dos fases. Antes de llamar al autorizador de Lambda,
API Gateway primero evalúa la política y comprueba si hay denegaciones explícitas. Si se encuentran, se
deniega inmediatamente el acceso al intermediario. De lo contrario, se llamada al autorizador de Lambda,
que devuelve un documento de política (p. 316), que se evalúa junto con la política de recursos. El
resultado se determina en función de la Tabla A (p. 280) (cerca del final de este tema).

La siguiente política de recursos de ejemplo solo permite llamadas desde el punto de enlace de la
VPC cuyo ID de punto de enlace de la VPC sea vpce-1a2b3c4d. Durante la evaluación "previa a la
autenticación"·, solo se permiten las llamadas procedentes del punto de enlace de la VPC que se indican
l el ejemplo para seguir adelante y evaluar el autorizador de Lambda. Todas las llamadas restantes se
bloquean.

274
Amazon API Gateway Guía del desarrollador
Control de acceso

275
 Amazon API Gateway Guía del desarrollador
Control de acceso

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:region:account-id:api-id/"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpce": "vpce-1a2b3c4d"
}
}
}
]
}

Autenticación de IAM y política de recursos

En este flujo de trabajo, se ha configurado la autenticación de IAM para la API, además de una política de
recursos. Después de autenticar al usuario con el servicio de IAM, se evalúan las políticas asociadas al
usuario de IAM y a la política de recursos. El resultado varía en función de si el intermediario se encuentra
en la misma cuenta, o en una cuenta de AWS diferente, del propietario de la API.

Si el intermediario y el propietario de la API proceden de cuentas distintas, tanto las políticas de

usuario de IAM y la política de recursos permiten explícitamente al intermediario continuar. (Consulte
la Tabla B (p. 280) al final de este tema.) Por el contrario, si el intermediario y el propietario de la API
se encuentran en la misma cuenta, las políticas del usuario o la política de recursos deben permitir
explícitamente al intermediario continuar. (Véase la Tabla A (p. 280) incluida a continuación).

276
Amazon API Gateway Guía del desarrollador
Control de acceso

277
 Amazon API Gateway Guía del desarrollador
Control de acceso

El siguiente ejemplo muestra una política de recursos entre cuentas. Si presuponemos que la política de
usuario de IAM contiene un permiso Allow, esta política de recursos solo permite llamadas desde la VPC
cuyo ID de VPC sea vpc-2f09a348. (Consulte la Tabla B (p. 280) al final de este tema.)

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "",
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:region:account-id:api-id/"
],
"Condition" : {
"StringEquals": {
"aws:SourceVpc": "vpc-2f09a348"
}
}
}
]
}

Política de recursos y autenticación de Amazon Cognito

En este flujo de trabajo, se configura un grupo de usuarios de Amazon Cognito (p. 322) para la API,
además de una política de recursos. API Gateway intenta primero autenticar a la persona que llama a
través de Amazon Cognito. Esto se realiza normalmente a través de un token JWT proporcionado por la
persona que llama. Si la autenticación se realiza correctamente, la política de recursos se evalúa de forma
independiente, y se requiere un permiso explícito. Una denegación o "ni permitir ni denegar" da como
resultado una denegación. El siguiente ejemplo muestra una política de recursos que podrían utilizarse
junto con grupos de usuarios de Amazon Cognito.

278
Amazon API Gateway Guía del desarrollador
Control de acceso

279
 Amazon API Gateway Guía del desarrollador
Control de acceso

El siguiente ejemplo muestra una política de recursos que solo permite llamadas desde direcciones IP de
origen específicas, suponiendo que el token de autenticación de Amazon Cognito contiene un permiso.
(Consulte la Tabla A (p. 280) cerca del final de este tema.)

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:region:account-id:api-id/",
"Condition": {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}

Tablas de resultados de evaluación de políticas

La tabla A muestra el comportamiento resultante cuando el acceso a una API de API Gateway está
controlado por una política de IAM (o un autorizador de grupos de usuarios de Lambda o Amazon Cognito)
y una política de recursos de API Gateway, que se encuentran en la misma cuenta de AWS.

Tabla A: La cuenta A llama a una API que pertenece a la cuenta A

Política de usuario de IAM Política de recursos de API Comportamiento resultante

(o autorizador de grupos de Gateway
usuarios de Lambda o Amazon
Cognito)

Allow Allow Allow

Allow Ni permitir ni denegar Allow

Allow Denegar Denegación explícita

Ni permitir ni denegar Allow Allow

Ni permitir ni denegar Ni permitir ni denegar Denegar de forma implícita

Ni permitir ni denegar Denegar Denegación explícita

Denegar Allow Denegación explícita

Denegar Ni permitir ni denegar Denegación explícita

Denegar Denegar Denegación explícita

La tabla B muestra el comportamiento resultante cuando el acceso a una API de API Gateway está
controlado por una política de IAM (o un autorizador de grupos de usuarios de Lambda o Amazon Cognito)
y una política de recursos de API Gateway, que se encuentran en diferentes cuentas de AWS. Si no existe
un permiso ni una denegación, el acceso entre cuentas se deniega. Esto se debe a que el acceso entre
cuentas requiere que la política de recursos y la política de IAM (o un autorizador de Lambda o grupos de
usuarios de Amazon Cognito) concedan acceso de forma explícita.

280
 Amazon API Gateway Guía del desarrollador
Control de acceso

Tabla B: La cuenta B llama a una API que pertenece a la cuenta A

Política de usuario de IAM Política de recursos de API Comportamiento resultante

(o autorizador de grupos de Gateway
usuarios de Lambda o Amazon
Cognito)

Allow Allow Allow

Allow Ni permitir ni denegar Denegar de forma implícita

Allow Denegar Denegación explícita

Ni permitir ni denegar Allow Denegar de forma implícita

Ni permitir ni denegar Ni permitir ni denegar Denegar de forma implícita

Ni permitir ni denegar Denegar Denegación explícita

Denegar Allow Denegación explícita

Denegar Ni permitir ni denegar Denegación explícita

Denegar Denegar Denegación explícita

Ejemplos de políticas de recursos de API Gateway

En esta página se presentan algunos ejemplos de casos de uso típicos de políticas de recursos de API
Gateway.

Las políticas de ejemplo siguientes utilizan una sintaxis simplificada para especificar el recurso de API.
Esta sintaxis simplificada es una forma abreviada de hacer referencia a un recurso de API, en lugar
de especificar el nombre de recursos de Amazon (ARN) completo. API Gateway convierte la sintaxis
abreviada en el ARN completo al guardar la política. Por ejemplo, puede especificar el recurso execute-
api:/stage-name/GET/pets en una política de recursos. API Gateway convierte el recurso en
arn:aws:execute-api:us-east-2:123456789012:aabbccddee/stage-name/GET/pets cuando
se guarda la política de recursos. API Gateway crea el ARN completo utilizando la región actual, el ID de
su cuenta de AWS y el ID de la API REST con la que está asociada la política de recursos. Puede utilizar
execute-api:/* para representar todas las etapas, métodos y rutas de la API actual. Para obtener
información acerca del lenguaje de la política de acceso, consulte Información general del lenguaje de
políticas de acceso para Amazon API Gateway (p. 271).

Temas
• Ejemplo: Permitir que los usuarios de otra cuenta de AWS utilicen una API (p. 281)
• Ejemplo: Cómo denegar el tráfico a una API para una dirección o un rango de direcciones IP de
origen (p. 282)
• Ejemplo: Denegar el tráfico de API basado en la dirección IP de origen o rango cuando se utiliza una
API privada (p. 282)
• Ejemplo: Permitir el tráfico de una API privada en función del punto de enlace de la VPC o la VPC de
origen (p. 283)

Ejemplo: Permitir que los usuarios de otra cuenta de AWS utilicen una API

En el siguiente ejemplo de política de recursos, se concede a la API acceso en una cuenta de AWS a
dos usuarios de una cuenta de AWS diferente a través de los protocolos Signature Version 4 (SigV4). En
concreto, se concede a Alice y al usuario raíz para la cuenta de AWS identificado por account-id-2 la
acción execute-api:Invoke para ejecutar la acción GET en el recurso pets (API) en la cuenta de AWS.

281
 Amazon API Gateway Guía del desarrollador
Control de acceso

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::account-id-2:user/Alice",
"account-id-2"
]
},
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/stage/GET/pets"
]
}
]
}

Ejemplo: Cómo denegar el tráfico a una API para una dirección o un rango de direcciones IP de
origen
El siguiente ejemplo de política de recursos deniega (bloquea) el tráfico entrante a una API privada
procedente de dos bloques de direcciones IP de origen especificadas.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}

Ejemplo: Denegar el tráfico de API basado en la dirección IP de origen o rango cuando se utiliza
una API privada
El siguiente ejemplo de política de recursos deniega (bloquea) el tráfico entrante a una API privada
procedente de dos bloques de direcciones IP de origen especificadas. Cuando se utilizan API privadas,
el punto de enlace final de VPC para execute-api vuelve a escribir la dirección IP de origen original. La
condición aws:VpcSourceIp filtra la solicitud contra la dirección IP del solicitante original.

{
"Version": "2012-10-17",

282
 Amazon API Gateway Guía del desarrollador
Control de acceso

"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:VpcSourceIp": ["192.0.2.0/24", "198.51.100.0/24"]
}
}
}
]
}

Ejemplo: Permitir el tráfico de una API privada en función del punto de enlace de la VPC o la VPC
de origen
En el ejemplo siguiente, las políticas de recursos permiten el tráfico entrante en una API privada solo
desde una nube virtual privada (VPC) o un punto de enlace de la VPC especificados.

Esta política de recursos de ejemplo especifica una VPC de origen:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpc": "vpc-1a2b3c4d"
}
}
}
]
}

Esta política de recursos de ejemplo especifica un punto de enlace de la VPC de origen:

283
 Amazon API Gateway Guía del desarrollador
Control de acceso

"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpce": "vpce-1a2b3c4d"
}
}
}
]
}

Creación y asociación de una política de recursos de API Gateway a una API

Para permitir a un usuario obtener acceso a una API llamando al servicio de ejecución de la API, debe
crear una política de recursos de API Gateway, que controle el acceso a los recursos de API Gateway y
asociar la política a la API.
Important
Para actualizar una política de recursos de API Gateway, tendrá que tener permiso
apigateway:UpdateRestApiPolicy además de permiso apigateway:PATCH.

La política de recursos se puede asociar a la API en el momento en que se crea la API o más tarde. En el
caso de las API privadas, tenga en cuenta que hasta que la política de recursos se asocie a la API privada,
se producirá un error en todas las llamadas a la API.
Important
Si actualiza la política de recursos después de crear la API, tendrá que implementar la API para
propagar los cambios después de asociar la política actualizada. Si únicamente se actualiza o
se guarda la política, no se modifica el comportamiento en tiempo de ejecución de la API. Para
obtener más información acerca cómo implementar una API, consulte Implementación de una API
de REST en Amazon API Gateway (p. 510).

El acceso se puede controlar mediante elementos de condición de IAM; por ejemplo, condiciones de la
cuenta de AWS, de la VPC de origen, del punto de enlace de la VPC o del intervalo de direcciones IP. Si
la entidad Principal de la política se establece en "*", se pueden utilizar otros tipos de autorización
junto con la política de recursos. Si la entidad Principal se establece en "AWS", se producirá un error de
autorización para todos los recursos no protegidos con la autorización AWS_IAM, incluidos los recursos no
seguros.

En las secciones siguientes se describe cómo crear su propia política de recursos de API Gateway y
asociarla a una API. Al asociar una política, se aplican los permisos de la política a los métodos de la API.
Important
Si usa la consola de API Gateway para asociar una política de recursos a una API implementada
o actualiza una política de recursos existente, tendrá que volver a implementar la API para que los
cambios surtan efecto.

284
 Amazon API Gateway Guía del desarrollador
Control de acceso

Temas
• Asociación de políticas de recursos de API Gateway (consola) (p. 285)
• Asociación de políticas de recursos de API Gateway (CLI de AWS) (p. 285)

Asociación de políticas de recursos de API Gateway (consola)

Puede utilizar la consola de administración de AWS para asociar una política de recursos a una API de API
Gateway.

Para asociar una política de recursos a una API de API Gateway

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija una API de REST.
3. En el panel de navegación izquierdo, elija Resource Policy (Política de recursos).
4. Si lo desea, elija uno de los Examples (Ejemplos). En las políticas de ejemplo, los marcadores de
posición se indican mediante llaves ("{{placeholder}}"). Sustituya cada uno de los marcadores
de posición (incluidas las llaves) por la información necesaria.

Si no utiliza uno de los Examples (Ejemplos), introduzca su política de recursos.

5. Elija Save (Guardar).

Si la API se ha implementado anteriormente en la consola de API Gateway, tendrá que volver a

implementarla para que la política de recursos surta efecto.

Asociación de políticas de recursos de API Gateway (CLI de AWS)

Para utilizar la CLI de AWS para crear una API nueva y asociarla una política de recursos, llame al
comando create-rest-api tal y como se indica a continuación:

aws apigateway create-rest-api \

--name "api-name" \
--policy "{\"jsonEscapedPolicyDocument\"}"

Para utilizar la CLI de AWS para asociar una política de recursos a una API existente, llame al comando
update-rest-api tal y como se indica a continuación:

aws apigateway update-rest-api \

--rest-api-id api-id \
--patch-operations op=replace,path=/policy,value='{\"jsonEscapedPolicyDocument\"}'

Claves de condición de AWS que se pueden utilizar en las políticas de recursos

de API Gateway
La siguiente tabla contiene las claves de condición de AWS que se pueden utilizar en las políticas de
recursos de las API de API Gateway con cada tipo de autorización.

Para obtener más información sobre las claves de condición de AWS, consulte Claves de contexto de
condición globales de AWS.

Tabla de claves de condición

Claves de condición Criterios ¿Necesita AuthN? Tipo de autorización

aws:CurrentTime Ninguno No Todos

aws:EpochTime Ninguno No Todos

285
 Amazon API Gateway Guía del desarrollador
Control de acceso

Claves de condición Criterios ¿Necesita AuthN? Tipo de autorización

aws:TokenIssueTime La clave solo está Sí IAM

en las solicitudes
que se firman con
credenciales de
seguridad temporales.

La clave solo está

aws:MultiFactorAuthPresent Sí IAM
en las solicitudes
que se firman con
credenciales de
seguridad temporales.

La clave solo está si

aws:MultiFactorAuthAge Sí IAM
se utiliza la MFA en las
solicitudes.

aws:PrincipalAccountNone (Ninguno) Sí IAM

aws:PrincipalArn None (Ninguno) Sí IAM

aws:PrincipalOrgID Esta clave solamente se Sí IAM

incluye en el contexto
de la solicitud si la
entidad principal
es miembro de una
organización.

Esta clave solamente se

aws:PrincipalOrgPaths Sí IAM
incluye en el contexto
de la solicitud si la
entidad principal
es miembro de una
organización.

aws:PrincipalTag Esta clave solamente se Sí IAM

incluye en el contexto
de la solicitud si la
entidad principal está
usando un usuario
de IAM con etiquetas
asociadas. Se incluye
para una entidad
principal que utiliza un
rol de IAM con etiquetas
o etiquetas de sesión
asociadas.

aws:PrincipalType None (Ninguno) Sí IAM

aws:Referer La clave solo está si No Todos

el valor lo proporciona
el intermediario en el
encabezado HTTP.

aws:SecureTransport Ninguno No Todos

aws:SourceArn Ninguno No Todos

286
 Amazon API Gateway Guía del desarrollador
Control de acceso

Claves de condición Criterios ¿Necesita AuthN? Tipo de autorización

aws:SourceIp Ninguno No Todos

aws:SourceVpc Esta clave solo se No Todos

puede utilizar con las
API privadas.

aws:SourceVpce Esta clave solo se No Todos

puede utilizar con las
API privadas.

aws:UserAgent La clave solo está si No Todos

el valor lo proporciona
el intermediario en el
encabezado HTTP.

aws:userid None (Ninguno) Sí IAM

aws:username None (Ninguno) Sí IAM

Control del acceso a una API con permisos de IAM

Puede controlar el acceso a su API de Amazon API Gateway con permisos de IAM controlando el acceso a
los dos procesos de componentes de API Gateway siguientes:

• Para crear, implementar y administrar una API en API Gateway, debe conceder al desarrollador de la
API permisos para realizar las acciones necesarias admitidas por el componente de administración de la
API de API Gateway.
• Para llamar a una API implementada o para actualizar el almacenamiento en caché de la API, debe
conceder al intermediario de la API permisos para realizar las acciones de IAM necesarias admitidas por
el componente de ejecución de la API de API Gateway.

El control de acceso para los dos procesos implica diferentes modelos de permisos, que se explican a
continuación.

Modelo de permisos de API Gateway para crear y administrar una API

Para permitir a un desarrollador de API crear y administrar una API en API Gateway debe crear políticas
de permisos de IAM que permitan a un desarrollador de la API especificado crear, actualizar, implementar,
ver o eliminar las entidades de API necesarias. Asocia la política de permisos a un usuario de IAM que
representa al desarrollador, a un grupo de IAM que contiene al usuario o a un rol de IAM asumido por el
usuario.

En este documento de política de IAM, el elemento Resource contiene una lista de entidades API de
API Gateway, incluidos los recursos de API Gateway y las relaciones de enlace de API Gateway. El
elemento Action de IAM contiene las acciones de administración de API de API Gateway necesarias.
Estas acciones se declaran con el formato apigateway:HTTP_VERB, donde apigateway designa el
componente de administración de la API subyacente de API Gateway y HTTP_VERB representa los verbos
HTTP admitidos por API Gateway.

Para obtener más información sobre cómo usar este modelo de permisos, consulte Controlar el acceso
para administrar una API (p. 289).

287
 Amazon API Gateway Guía del desarrollador
Control de acceso

Modelo de permisos de API Gateway para invocar una API

Para permitir a un intermediario de la API invocar la API o actualizar su caché, debe crear políticas de
IAM que permitan a un intermediario de la API especificado invocar el método de API para el que se
ha habilitado la autenticación de usuarios de IAM. El desarrollador de la API establece la propiedad
authorizationType del método en AWS_IAM para exigir que el intermediario envíe las clave de acceso
del usuario de IAM que se va a autenticar. A continuación, asocia la política de permisos a un usuario de
IAM que representa al intermediario de la API, a un grupo de IAM, que contiene al usuario o a un rol de
IAM asumido por el usuario.

En esta instrucción de política de permisos de IAM, el elemento Resource de IAM contiene una lista de
métodos de la API implementada identificados por verbos HTTP y rutas de recursos de API Gateway. El
elemento Action de IAM contiene las acciones de ejecución de API de API Gateway necesarias. Estas
acciones incluyen execute-api:Invoke o execute-api:InvalidateCache, donde execute-api
designa el componente de ejecución de la API subyacente de API Gateway.

Para obtener más información sobre cómo usar este modelo de permisos, consulte Controlar el acceso
para invocar una API (p. 294).

Cuando una API está integrada con un servicio de AWS (por ejemplo, AWS Lambda) en el backend,
API Gateway también debe tener permisos para obtener acceso a los recursos de AWS integrados (por
ejemplo, invocar una función de Lambda) en nombre del intermediario de la API. Para conceder estos
permisos, cree un rol de IAM del tipo AWS service for API Gateway. Cuando crea este rol en la consola de
administración de IAM, este rol resultante contiene la siguiente política de confianza de IAM que designa a
API Gateway como la entidad de confianza capaz de asumir el rol:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}

Si crea el rol de IAM llamando al comando create-role de la CLI o a un método del SDK correspondiente,
debe proporcionar la política de confianza anterior como el parámetro de entrada de assume-role-
policy-document. No intente crear esta política directamente en la consola de administración de IAM o
llamando al comando create-policy de la CLI de AWS o un método del SDK correspondiente.

Para que API Gateway llame al servicio de AWS integrado, también debe asociar a este rol las políticas de
permisos de IAM correspondientes para llamar a los servicios de AWS integrados. Por ejemplo, para llamar
a una función de Lambda, debe incluir la siguiente política de permisos de IAM en el rol de IAM:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "*"
}
]
}

288
 Amazon API Gateway Guía del desarrollador
Control de acceso

Tenga en cuenta que Lambda admite la política de acceso basada en recursos, que combina políticas de
confianza y de permisos. Cuando integre una API con una función de Lambda mediante la consola de API
Gateway, no se le pedirá que establezca este rol de IAM explícitamente, porque la consola establece los
permisos basados en recursos en la función de Lambda por usted, con su consentimiento.
Note

Para establecer el control del acceso a un servicio de AWS, puede utilizar el modelo de permisos
basado en el intermediario, donde una política de permisos se asocia directamente al usuario o
grupo de IAM del intermediario, o el modelo de permisos basado en rol, donde una política de
permisos se asocia a un rol de IAM que API Gateway puede asumir. Los permisos de políticas
pueden ser diferentes en los dos modelos. Por ejemplo, la política basada en el intermediario
bloquea el acceso, mientras que la política basada en roles lo permite. Puede aprovechar esto
para exigir que un usuario de IAM tenga acceso a un servicio de AWS únicamente a través de la
API de API Gateway.

Controlar el acceso para administrar una API

En esta sección, aprenderá a crear instrucciones de política de IAM para controlar quién puede o no crear,
implementar y actualizar una API en API Gateway. También encontrará la referencia de instrucciones
de política, incluidos los formatos de los campos Action y Resource relacionados con el servicio de
administración de la API.

Controlar quién puede crear y administrar una API de API Gateway con políticas de IAM

Para controlar quién puede o no puede crear, implementar y actualizar la API con el servicio de
administración de la API de API Gateway, cree un documento de política de IAM con los permisos
necesarios, tal y como se muestra en la siguiente plantilla de política:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Permission",
"Action": [
"apigateway:HTTP_VERB"
],
"Resource": [
"arn:aws:apigateway:region::resource1-path",
"arn:aws:apigateway:region::resource2-path",
...
]
}
]
}

Aquí Permission puede ser Allow o Deny para conceder o revocar, respectivamente, los derechos de
acceso estipulados por la instrucción de política. Para obtener más información, consulte Permisos de IAM
en AWS.

HTTP_VERB pueden ser cualquiera de los verbos HTTP admitidos por API Gateway (p. 290). * se puede
utilizar para designar cualquiera de los verbos HTTP.

Resource contiene una lista de los ARN de las entidades de API afectadas, incluidas RestApi,
Resource, Method, Integration, DocumentationPart, Model, Authorizer, UsagePlan, etc. Para obtener más
información, consulte Formato de Resource de permisos para administrar API en API Gateway (p. 291).

Combinando diferentes instrucciones de políticas, puede personalizar los permisos de acceso para
usuarios individuales, grupos o roles para tener acceso a las entidades de API seleccionadas y para
realizar acciones específicas en esas entidades. Por ejemplo, puede incluir la siguiente instrucción en

289
 Amazon API Gateway Guía del desarrollador
Control de acceso

la política de IAM para conceder al equipo de documentación permiso para crear, publicar, actualizar y
eliminar las partes de documentación de una API determinada, así como para ver las entidades de la API.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:GET"
],
"Resource": [
"arn:aws:apigateway:region::/restapis/api-id/*"
]
},
{
"Effect": "Allow",
"Action": [
"apigateway:POST",
"apigateway:PATCH",
"apigateway:DELETE"
],
"Resource": [
"arn:aws:apigateway:region::/restapis/api-id/documentation/*"
]
}
]
}

Para el equipo de desarrollo de la API, que es el responsable de todas las operaciones, puede incluir la
siguiente instrucción en la política de IAM para concederle permisos de acceso mucho más amplios.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:*"
],
"Resource": [
"arn:aws:apigateway:*::/*"
]
}
]
}

Referencia de instrucciones de políticas de IAM para administrar la API en API Gateway

La siguiente información describe el formato de los elementos Action y Resource usados en una
instrucción de política de IAM para conceder o revocar los permisos para administrar entidades de API de
API Gateway.

Formato de Action de permisos para administrar API en API Gateway

La expresión Action de administración de API tiene el siguiente formato general:

apigateway:action

donde action es una de las siguientes acciones de API Gateway:

290
 Amazon API Gateway Guía del desarrollador
Control de acceso

• *, que representa todas las acciones siguientes.

• GET, que se utiliza para obtener información acerca de los recursos.
• POST, que se utiliza principalmente para crear recursos secundarios.
• PUT, que se utiliza principalmente para actualizar los recursos (y, aunque no es recomendable, puede
utilizarse para crear recursos secundarios).
• DELETE, que se utiliza para eliminar recursos.
• PATCH, que se puede utilizar para actualizar los recursos.

Algunos ejemplos de la expresión Action incluyen:

• apigateway:* para todas las acciones de API Gateway.

• apigateway:GET solo para la acción GET en API Gateway.

Formato de Resource de permisos para administrar API en API Gateway

La expresión Resource de administración de API tiene el siguiente formato general:

arn:aws:apigateway:region::resource-path-specifier

donde region es una región de AWS de destino (como us-east-1 o * para todas las regiones de AWS
admitidas) y resource-path-specifier es la ruta de acceso a los recursos de destino.

Algunos ejemplos de expresiones de recursos incluyen:

• arn:aws:apigateway:region::/restapis/* para todos los recursos, métodos, modelos y etapas

de la región de AWS especificada en region.
• arn:aws:apigateway:region::/restapis/api-id/* para todos los recursos, modelos y etapas
de la API con el identificador api-id de la región de AWS especificada en region.
• arn:aws:apigateway:region::/restapis/api-id/resources/resource-id/* para todos
los recursos y métodos del recurso con el identificador resource-id, que se encuentra en la API con el
identificador api-id en la región de AWS especificada en region.
• arn:aws:apigateway:region::/restapis/api-id/resources/resource-id/methods/*
para todos los métodos del recurso con el identificador resource-id, que se encuentra en la API con
el identificador api-id en la región de AWS especificada en region.
• arn:aws:apigateway:region::/restapis/api-id/resources/resource-id/methods/GET
solo para el método GET del recurso con el identificador resource-id, que se encuentra en la API con
el identificador api-id en la región de AWS especificada en region.
• arn:aws:apigateway:region::/restapis/api-id/models/* para todos los modelos de la API
con el identificador api-id de la región de AWS especificada en region.
• arn:aws:apigateway:region::/restapis/api-id/models/model-name para el modelo con
el nombre model-name, que se encuentra en la API con el identificador api-id en la región de AWS
especificada en region.
• arn:aws:apigateway:region::/restapis/api-id/stages/* para todas las etapas de la API
con el identificador api-id de la región de AWS especificada en region.
• arn:aws:apigateway:region::/restapis/api-id/stages/stage-name solo para la etapa
con el nombre stage-name, que se encuentra en la API con el identificador api-id en la región de
AWS especificada en region.

Para obtener más información, consulte Referencia del nombre de recurso de Amazon (ARN) de API
Gateway (p. 766).

291
 Amazon API Gateway Guía del desarrollador
Control de acceso

Control del acceso entre cuentas a una API

Puede administrar el acceso a sus API mediante la creación de políticas de permisos de IAM para controlar
quién puede o no crear, actualizar, implementar, ver o eliminar entidades de API. Una política se asocia a
un usuario de IAM que representa al usuario, a un grupo de IAM, que contiene al usuario o a un rol de IAM
asumido por el usuario.

En las políticas de IAM que cree para las API, puede utilizar elementos Condition para permitir el acceso
únicamente a determinados autorizadores o integraciones de Lambda.

El bloque Condition utiliza operadores de condición booleanos para emparejar la condición de la política
con los valores de la solicitud. El operador de condición StringXxx funcionará tanto para la integración
de AWS (en la que el valor debe ser un ARN de función de Lambda) como para la integración de HTTP (en
la que el valor debe ser un URI HTTP). Se admiten los siguientes operadores de condición StringXxx:
StringEquals, StringNotEquals, StringEqualsIgnoreCase, StringNotEqualsIgnoreCase,
StringLike, StringNotLike. Para obtener más información, consulte Operadores de condición de
cadena en la guía del usuario de IAM.

Política de IAM para un autorizador de Lambda entre cuentas

A continuación se muestra un ejemplo de política de IAM para controlar una función de autorizador de
Lambda entre cuentas:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:POST"
],
"Resource": [
"arn:aws:apigateway:[region]::/restapis/restapi_id/authorizers"
],
//Create Authorizer operation is allowed only with the following Lambda
function
"Condition": {
"StringEquals": {
"apigateway:AuthorizerUri":
"arn:aws:apigateway:region:lambda:path/2015-03-31/functions/
arn:aws:lambda:region:123456789012:function:example/invocations"
}
}
}
]
}

Política de IAM para la integración de Lambda entre cuentas

Con la integración entre cuentas, si se desea restringir las operaciones con algunos recursos específicos
(por ejemplo, put-integration para una función de Lambda concreta), se puede agregar un elemento
Condition a la política para especificar el recurso (función de Lambda) que se ve afectado.

A continuación se muestra un ejemplo de política de IAM para controlar una función de integración de
Lambda entre cuentas:

Para conceder a otra cuenta de AWS permiso para que pueda llamar a integration:put o a put-
integration con el fin de configurar una integración de Lambda en una API, puede incluir la siguiente
instrucción en la política de IAM.

292
 Amazon API Gateway Guía del desarrollador
Control de acceso

"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:PUT"
],
"Resource": [
"arn:aws:apigateway:api-region::/restApis/api-id/resources/resource-id/
methods/GET/integration"
],
//PutIntegration is only valid with the following Lambda function
"Condition": {
"StringEquals": {
"apigateway:IntegrationUri": "arn:aws:lambda:region:account-
id:function:lambda-function-name"
}
}
}
]
}

Como permitir a otra cuenta administrar la función de Lambda que se utiliza para importar un
archivo de OpenAPI
Para conceder a otra cuenta de AWS permiso para que pueda llamar a restapi:import o a import-
rest-api con el fin de importar un archivo de OpenAPI, puede incluir la siguiente instrucción en la política
de IAM.

En la instrucción Condition siguiente, la cadena "lambda:path/2015-03-31/functions/

arn:aws:lambda:us-east-1:account-id:function:lambda-function-name" es el ARN
completo de la función de Lambda.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:POST"
],
"Resource": "arn:aws:apigateway:*::/restapis",
"Condition": {
"StringLike": {
"apigateway:IntegrationUri": [
"arn:aws:apigateway:apigateway-region:lambda:path/2015-03-31/
functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/
invocations"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"apigateway:POST"
],
"Resource": "arn:aws:apigateway:*::/restapis",
"Condition": {
"StringLike": {
"apigateway:AuthorizerUri": [
"arn:aws:apigateway:apigateway-region:lambda:path/2015-03-31/
functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/
invocations"

293
 Amazon API Gateway Guía del desarrollador
Control de acceso

]
}
}
}
]
}

Controlar el acceso para invocar una API

En esta sección aprenderá a crear instrucciones de política de IAM para controlar quién puede o no puede
llamar a una API implementada en API Gateway. Aquí, encontrará también la referencia de instrucciones
de política, incluidos los formatos de los campos Action y Resource relacionados con el servicio de
ejecución de la API. También debe estudiar la sección IAM en the section called “Cómo afectan las
políticas de recursos al flujo de trabajo de autorización” (p. 272).

Para API privadas, debe utilizar una combinación de una política de recursos de API Gateway y una
política de punto de enlace de la VPC. Para obtener más información, consulte los siguientes temas:

• the section called “Uso de políticas de recursos de API Gateway” (p. 270)
• the section called “Utilizar políticas de punto de enlace de la VPC para API privadas” (p. 303)

Controlar quién puede llamar a una API de API Gateway con políticas de IAM

Para controlar quién puede o no puede llamar a una API implementada con permisos de IAM, cree un
documento de política de IAM con los permisos necesarios. A continuación, se muestra una plantilla para
un documento de política como este.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Permission",
"Action": [
"execute-api:Execution-operation"
],
"Resource": [
"arn:aws:execute-api:region:account-id:api-id/stage/METHOD_HTTP_VERB/Resource-path"
]
}
]
}

Aquí, Permission se sustituirá por Allow o Deny dependiendo de si desea conceder o revocar los
permisos incluidos. Execution-operation se sustituirá por las operaciones compatibles con el servicio
de ejecución de la API. METHOD_HTTP_VERB hace referencia a un verbo HTTP compatible con los
recursos especificados. Resource-path es el marcador de posición de la ruta URL de una instancia
de Resource de la API implementada que admite el METHOD_HTTP-VERB mencionado. Para obtener
más información, consulte Referencia de instrucciones de políticas de IAM para ejecutar la API en API
Gateway (p. 296).
Note

Para que las políticas de IAM sean eficaces, debe haber habilitado la autenticación de IAM en los
métodos de API configurando AWS_IAM para la propiedad authorizationType de los métodos.
En caso contrario, estos métodos de API serán accesibles públicamente.

Por ejemplo, para conceder a un usuario permiso para ver una lista de mascotas expuesta por una API
determinada, pero denegarle permiso para agregar una mascota a la lista, se podría incluir la siguiente
instrucción en la política de IAM:

294
 Amazon API Gateway Guía del desarrollador
Control de acceso

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/pets"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:account-id:api-id/*/POST/pets"
]
}
]
}

Para conceder a un usuario permiso para ver una mascota específica expuesta por una API que se
configura como GET /pets/{petId}, podría incluir la siguiente declaración en la política de IAM:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/pets/a1b2"
]
}
]
}

Para el equipo de desarrolladores que prueba las API, puede incluir la siguiente instrucción en la política
de IAM para permitir a cualquier desarrollador del equipo llamar a cualquier método de cualquier recurso
de cualquier API en la etapa test.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke",
"execute-api:InvalidateCache"
],
"Resource": [
"arn:aws:execute-api:*:*:*/test/*"
]
}
]
}

295
 Amazon API Gateway Guía del desarrollador
Control de acceso

Referencia de instrucciones de políticas de IAM para ejecutar la API en API Gateway

La siguiente información describe el formato de Action y Resource de las instrucciones de política de IAM
de permisos de acceso para ejecutar una API.

Formato de Action de permisos para ejecutar la API en API Gateway

La expresión Action de ejecución de API tiene el siguiente formato general:

execute-api:action

donde action es una acción de ejecución de API disponible:

• *, que representa todas las acciones siguientes.

• Invoke, que se utiliza para invocar una API previa solicitud del cliente.
• InvalidateCache, que se utiliza para invalidar la caché de API previa solicitud del cliente.

Formato de Resource de permisos para ejecutar la API en API Gateway

La expresión Resource de ejecución de API tiene el siguiente formato general:

arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier

donde:

• region es la región de AWS (como us-east-1 o * para todas las regiones de AWS) que se
corresponde con la API implementada para el método.
• account-id es el ID de cuenta de 12 dígitos de AWS del propietario de la API REST.
• api-id es el identificador que API Gateway ha asignado a la API para el método (se puede usar * para
todas las API, independientemente del identificador de la API).
• stage-name es el nombre de la etapa asociada con el método (se puede utilizar * para todas las
etapas, independientemente del nombre de la etapa).
• HTTP-VERB es el verbo HTTP del método. Puede ser uno de los siguientes: GET, POST, PUT, DELETE,
PATCH. (* se puede utilizar para todos los verbos HTTP).
• resource-path-specifier es la ruta al método deseado (se puede usar * para todas las rutas).

Algunos ejemplos de expresiones de recursos incluyen:

• arn:aws:execute-api:*:*:* para cualquier ruta de recurso en cualquier etapa, para cualquier API
de cualquier región de AWS. (Equivale a *).
• arn:aws:execute-api:us-east-1:*:* para cualquier ruta de recurso en cualquier etapa, para
cualquier API en la región de AWS de us-east-1.
• arn:aws:execute-api:us-east-1:*:api-id/* para cualquier ruta de recurso en cualquier etapa,
para la API con el identificador api-id de la región de AWS us-east-1.
• arn:aws:execute-api:us-east-1:*:api-id/test/* para la ruta del recurso en la etapa test,
para la API con el identificador api-id en la región de AWS us-east-1.
• arn:aws:execute-api:us-east-1:*:api-id/test/*/mydemoresource/* para cualquier ruta
del recurso junto la ruta mydemoresource, para cualquier método HTTP en la etapa test, para la API
con el identificador api-id en la región de AWS us-east-1.
• arn:aws:execute-api:us-east-1:*:api-id/test/GET/mydemoresource/* para los métodos
GET en cualquier ruta de recurso junto con la ruta mydemoresource, en la etapa test, para la API con
el identificador api-id en la región de AWS us-east-1.

296
 Amazon API Gateway Guía del desarrollador
Control de acceso

Para obtener más información, consulte Referencia del nombre de recurso de Amazon (ARN) de API
Gateway (p. 766).

Ejemplos de políticas de IAM para administrar las API de API Gateway

Los siguientes documentos de política de ejemplo muestran varios casos de uso para establecer permisos
de acceso para administrar recursos de API en API Gateway. Para ver el modelo de permisos y otra
información de referencia, consulte Controlar quién puede crear y administrar una API de API Gateway
con políticas de IAM (p. 289).

Temas
• Permisos sencillos de lectura (p. 297)
• Permisos de solo lectura en cualquier API (p. 298)
• Permisos de acceso completo a cualquier recurso de API Gateway (p. 299)
• Permisos de acceso completo para administrar las etapas de API (p. 299)
• Impedir a usuarios especificados eliminar recursos de la API (p. 300)

Permisos sencillos de lectura

La siguiente instrucción de política concede al usuario permiso para obtener información acerca de todos
los recursos, métodos, modelos y etapas de la API con el identificador a123456789 en la región de AWS
us-east-1:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:GET"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/restapis/a123456789/*"
]
}
]
}

La siguiente instrucción de política de ejemplo concede al usuario de IAM permiso para mostrar
información para todos los recursos, métodos, modelos y etapas en cualquier región. El usuario también
tiene permiso para realizar todas las acciones de API Gateway disponibles para la API con el identificador
a123456789 en la región de AWS us-east-1:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:GET"
],
"Resource": [
"arn:aws:apigateway:*::/restapis/*"
]
},
{
"Effect": "Allow",
"Action": [

297
 Amazon API Gateway Guía del desarrollador
Control de acceso

"apigateway:*"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/restapis/a123456789/*"
]
}
]
}

Permisos de solo lectura en cualquier API

El siguiente documento de política permitirá a las entidades asociadas (usuarios, grupos o roles) recuperar
cualquiera de las API de la cuenta de AWS del intermediario. Esto incluye todos los recursos secundarios
de una API, como el método, la integración, etc.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1467321237000",
"Effect": "Deny",
"Action": [
"apigateway:POST",
"apigateway:PUT",
"apigateway:PATCH",
"apigateway:DELETE"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/*"
]
},
{
"Sid": "Stmt1467321341000",
"Effect": "Deny",
"Action": [
"apigateway:GET"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/",
"arn:aws:apigateway:us-east-1::/account",
"arn:aws:apigateway:us-east-1::/clientcertificates",
"arn:aws:apigateway:us-east-1::/domainnames",
"arn:aws:apigateway:us-east-1::/apikeys"
]
},
{
"Sid": "Stmt1467321344000",
"Effect": "Allow",
"Action": [
"apigateway:GET"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/restapis/*"
]
}
]
}

La primera instrucción Deny prohíbe explícitamente las llamadas de POST, PUT, PATCH, DELETE en
cualquier recurso en API Gateway. De este modo, se garantiza que otros documentos de política,
asociados también al intermediario, no invaliden dichos permisos. La segunda instrucción Deny impide
al intermediario consultar el recurso raíz (/), la información de la cuenta (/account), los certificados del
cliente (/clientcertificates), los nombres de dominios personalizados (/domainnames) y las claves

298
 Amazon API Gateway Guía del desarrollador
Control de acceso

de API (/apikeys). Juntas, las tres instrucciones garantizan que el intermediario solo pueda consultar los
recursos relacionados con la API. Esto puede resultar útil en las pruebas de la API cuando no desee que el
evaluador modifique el código.

Para restringir el acceso de solo lectura anterior a las API especificadas, sustituya la propiedad Resource
de la instrucción Allow por lo siguiente:

"Resource": ["arn:aws:apigateway:us-east-1::/restapis/restapi_id1/*",
"arn:aws:apigateway:us-east-1::/restapis/restapi_id2/*"]

Permisos de acceso completo a cualquier recurso de API Gateway

El siguiente documento de política de ejemplo concede acceso completo a cualquiera de los recursos de
API Gateway de la cuenta de AWS.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1467321765000",
"Effect": "Allow",
"Action": [
"apigateway:*"
],
"Resource": [
"*"
]
}
]
}

En general, debe abstenerse de utilizar una política de acceso tan amplia y abierta. Puede ser necesaria
para que su equipo de desarrollo de la API pueda crear, implementar, actualizar y eliminar cualquier
recurso de API Gateway.

Permisos de acceso completo para administrar las etapas de API

El siguiente documento de política de ejemplo concede permisos de acceso completo a los recursos
relacionados con la etapa de cualquier API en la cuenta de AWS del intermediario.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:*"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/restapis/*/stages",
"arn:aws:apigateway:us-east-1::/restapis/*/stages/*"
]
}
]
}

El documento de política anterior concede permisos de acceso completo solo a la colección stages y a
cualquiera de los recursos stage incluidos, siempre que no se asocie ninguna otra política que conceda
más acceso al intermediario. De lo contrario, debe denegar explícitamente todos los accesos.

299
 Amazon API Gateway Guía del desarrollador
Control de acceso

Con esta política, el intermediario debe conocer el identificador de la API de REST de antemano, ya
que el usuario no puede llamar a GET /restapis para consultar las API disponibles. Además, si no
se especifica arn:aws:apigateway:us-east-1::/restapis/*/stages en la lista Resource, el
recurso Stages no estará accesible. En este caso, el intermediario no podrá crear una etapa ni obtener
las etapas existentes, aunque puede consultar, actualizar o eliminar una etapa, siempre que conozca el
nombre de la etapa.

Para conceder permisos para etapas de la API específicas, solo tiene que sustituir la propiedad
restapis/* de las especificaciones Resource por restapis/restapi_id, donde restapi_id es el
identificador de la API específica.

Impedir a usuarios especificados eliminar recursos de la API

El siguiente documento de política de ejemplo de IAM impide a un usuario especificado eliminar cualquier
recurso en API Gateway.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1467331998000",
"Effect": "Allow",
"Action": [
"apigateway:GET",
"apigateway:PATCH",
"apigateway:POST",
"apigateway:PUT"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/restapis/*"
]
},
{
"Sid": "Stmt1467332141000",
"Effect": "Allow",
"Action": [
"apigateway:DELETE"
],
"Condition": {
"StringNotLike": {
"aws:username": "johndoe"
}
},
"Resource": [
"arn:aws:apigateway:us-east-1::/restapis/*"
]
}
]
}

Esta política de IAM concede permiso de acceso completo para crear, implementar, actualizar y eliminar
API a los usuarios, grupos o roles asociados, excepto al usuario especificado (johndoe), que no puede
eliminar ningún recurso de la API. Se asume que ningún otro documento de política que conceda permisos
Allow en la raíz, las claves de API, los certificados del cliente o los nombres de dominio personalizados se
ha asociado al intermediario.

Para impedir que el usuario especificado elimine recursos de API Gateway específicos, por ejemplo, una
API concreta o los recursos de una API, sustituya la especificación Resource anterior por esta:

"Resource": ["arn:aws:apigateway:us-east-1::/restapis/restapi_id_1",
"arn:aws:apigateway:us-east-1::/restapis/restapi_id_2/resources"]

300
 Amazon API Gateway Guía del desarrollador
Control de acceso

Ejemplos de política de IAM para permisos de ejecución de la API

Para ver el modelo de permisos y otra información de referencia, consulte Controlar el acceso para
invocar una API (p. 294).

La siguiente instrucción de política concede al usuario permiso para llamar a cualquier método POST
en la ruta mydemoresource, en la etapa test, para la API con el identificador de API a123456789,
suponiendo que la API correspondiente se ha implementado en la región de AWS us-east-1:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:*:a123456789/test/POST/mydemoresource/*"
]
}
]
}

La siguiente instrucción de política de ejemplo concede al usuario permiso para llamar a cualquier método
en la ruta del recurso petstorewalkthrough/pets, en cualquier etapa, para la API con el identificador
a123456789, en cualquier región de AWS en la que se haya implementado la API correspondiente:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:*:*:a123456789/*/*/petstorewalkthrough/pets"
]
}
]
}

Crear y asociar una política a un usuario de IAM

Para que un usuario pueda llamar al servicio de administración de la API o al servicio de ejecución de la
API, debe crear una política de IAM para un usuario de IAM, que controle el acceso a las entidades de API
Gateway y después asociar la política al usuario de IAM. Los siguientes pasos describen cómo crear la
política de IAM.

Para crear su propia política de IAM

1. Inicie sesión en la consola de administración de AWS y abra la consola de IAM en https://

console.aws.amazon.com/iam/.
2. Elija Policies y después, Create Policy. Si aparece el botón Get Started (Empezar), elíjalo y, a
continuación, elija Create Policy (Crear política).
3. Junto a Create Your Own Policy, seleccione Select.
4. En Policy Name (Nombre de política), escriba cualquier valor que sea fácil de consultar más tarde. Si
lo desea, escriba un texto descriptivo en Description (Descripción).

301
 Amazon API Gateway Guía del desarrollador
Control de acceso

5. En Policy Document (Documento de política), escriba una instrucción de política con el formato
siguiente y, a continuación, elija Create Policy (Crear política):

{
"Version": "2012-10-17",
"Statement" : [
{
"Effect" : "Allow",
"Action" : [
"action-statement"
],
"Resource" : [
"resource-statement"
]
},
{
"Effect" : "Allow",
"Action" : [
"action-statement"
],
"Resource" : [
"resource-statement"
]
}
]
}

En esta instrucción, sustituya action-statement y resource-statement según sea necesario,

y agregue otras instrucciones para especificar las entidades de API Gateway que desea que el
usuario de IAM pueda administrar, los métodos de API a los que puede llamar el usuario de IAM o
ambas cosas. De forma predeterminada, el usuario de IAM no tiene permisos a menos que exista la
instrucción Allow explícita correspondiente.
6. Para habilitar la política para un usuario, elija Users (Usuarios).
7. Elija el usuario de IAM a quien desea asociar la política.

Acaba de crear una política de IAM. No tendrá ningún efecto hasta que la asocie a un usuario de IAM, a un
grupo de IAM que contenga al usuario o a un rol de IAM asumido por el usuario.

Para asociar una política de IAM a un usuario de IAM

1. Para el usuario elegido, elija la pestaña Permissions (Permisos) y, a continuación, elija Attach Policy
(Asociar política).
2. En Grant permissions (Conceder permisos), elija Attach existing policies directly (Asociar las políticas
existentes directamente).
3. Elija el documento de política que acaba de crear en la lista mostrada y, a continuación, elija Next:
Review (Siguiente: Revisar).
4. En Permissions summary (Resumen de permisos), elija Add permissions (Añadir permisos).

Del mismo modo, si lo desea, puede agregar el usuario a un grupo de IAM, si el usuario aún no es
miembro, y asociar el documento de política al grupo para que las políticas asociadas se apliquen a todos
los miembros del grupo. Esto es útil para administrar y actualizar configuraciones de políticas en un grupo
de usuarios de IAM. A continuación, explicaremos cómo asociar la política a un grupo de IAM, suponiendo
que ya haya creado el grupo y haya agregado al usuario al grupo.

Para asociar un documento de política de IAM a un grupo de IAM

1. Elija Groups (Grupos) en el panel de navegación principal.

302
 Amazon API Gateway Guía del desarrollador
Control de acceso

2. Seleccione la pestaña Permissions (Permisos) en el grupo seleccionado.

3. Elija Attach policy.
4. Elija el documento de política que ha creado anteriormente y, a continuación, elija Attach policy
(Asociar política).

Para que API Gateway llame a otros servicios de AWS en su nombre, cree un rol de IAM del tipo Amazon
API Gateway.

Para crear un tipo de rol de Amazon API Gateway

1. Elija Roles en el panel de navegación principal.

2. Elija Create New Role.
3. Escriba un nombre para Role name (Nombre de rol) y, a continuación, elija Next Step (Paso siguiente).
4. En Select Role Type (Seleccionar tipo de rol), en AWS Service Roles (Roles de servicio de AWS), elija
Select (Seleccionar) junto a Amazon API Gateway.
5. Elija una política de permisos de IAM administrada disponible (por ejemplo,
AmazonAPIGatewayPushToCloudWatchLog) si desea que API Gateway registre las métricas en
CloudWatch en Attach Policy (Asociar política) y, a continuación, elija Next Step (Siguiente paso).
6. En Trusted Entities (Entidades de confianza), compruebe que apigateway.amazonaws.com aparece
como una entrada y, a continuación, elija Create Role (Crear rol).
7. En el rol recién creado, elija la pestaña Permissions (Permisos) y, a continuación, elija Attach Policy
(Asociar política).
8. Elija el documento de política de IAM personalizado creado anteriormente y, a continuación, elija
Attach Policy (Asociar política).

Utilizar políticas de punto de enlace de la VPC para API privadas

en API Gateway
Puede mejorar la seguridad de sus API privadas configurando API Gateway para utilizar un punto de
enlace de la VPC de interfaz. Los puntos de enlace de la interfaz tienen tecnología AWS PrivateLink, que
le permite obtener acceso de forma privada a los servicios de AWS mediante direcciones IP privadas. Para
obtener más información acerca de la creación de puntos de enlace de la VPC, consulte Creación de un
punto de enlace de interfaz.

Una política de punto de enlace de la VPC es una política de recursos de IAM que se puede asociar a
un punto de enlace de la VPC de interfaz para controlar el acceso al punto de enlace. Para obtener más
información, consulte Control del acceso a los servicios con Puntos de conexión de la VPC. Puede utilizar
una política de punto de enlace para restringir el tráfico procedente de su red interna para obtener acceso
a API privada. Tiene la opción de permitir o no el acceso a API privada específicas a las que se puede
acceder mediante el punto de enlace de la VPC.

Las políticas de punto de enlace de la VPC se pueden utilizar junto con las políticas de recursos de API
Gateway. La política de recursos se utiliza para especificar las entidades principales que pueden tener
acceso a la API. La política de puntos de enlace especifica qué API privadas se pueden llamar a través
del punto de enlace de la VPC. Para obtener más información sobre las políticas de recursos, consulte the
section called “Uso de políticas de recursos de API Gateway” (p. 270).

Ejemplos de políticas de puntos de enlace de la VPC

Puede crear políticas para los puntos de enlace de Amazon Virtual Private Cloud para Amazon API
Gateway en las que puede especificar:

• La entidad principal que puede realizar acciones.

• Las acciones que se pueden realizar.

303
 Amazon API Gateway Guía del desarrollador
Control de acceso

• Los recursos en los que se pueden realizar acciones.

Para asociar la política al punto de enlace de la VPC, tendrá que utilizar la consola de VPC. Para obtener
más información, consulte Control del acceso a los servicios con Puntos de conexión de la VPC.

Ejemplo 1: Concesión de acceso a la política de punto de enlace de la VPC a dos

API
El siguiente ejemplo de política concede acceso solo a dos API específicas a través del punto de enlace de
la VPC al que está asociado la política.

{
"Statement": [
{
"Principal": "*",
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*",
"arn:aws:execute-api:us-east-1:123412341234:aaaaa11111/*"
]
}
]
}

Ejemplo 2: Política de punto de enlace de la VPC que concede acceso a métodos

GET
El siguiente ejemplo de política concede acceso a los usuarios a los métodos GET para una API específica
a través del punto de enlace de la VPC a la que la política está asociada.

{
"Statement": [
{
"Principal": "*",
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/stageName/GET/*"
]
}
]
}

Ejemplo 3: Concesión de acceso al usuario de una política de punto de enlace de

la VPC a una API específica
El siguiente ejemplo de política concede acceso a un usuario específico a una API específica a través del
punto de enlace de la VPC a la que la política está asociada.

{
"Statement": [
{
"Principal": {
"AWS": [

304
 Amazon API Gateway Guía del desarrollador
Control de acceso

"arn:aws:iam::123412341234:user/MyUser"
]
},
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*"
]
}
]
}

Uso de etiquetas para controlar el acceso a una API REST en

API Gateway
El permiso para obtener acceso a las API REST se puede ajustar mediante el control de acceso basado en
etiquetas en las políticas de IAM.

Para obtener más información, consulte the section called “Control de acceso basado en
etiquetas” (p. 834).

Uso de autorizadores Lambda de API Gateway

Un autorizador de Lambda (que anteriormente se denominaba autorizador personalizado) es una
característica de API Gateway que utiliza una función de Lambda para controlar el acceso a su API.

Un autorizador de Lambda resulta útil si desea implementar un esquema de autorización personalizado

que utiliza una estrategia de autenticación de token al portador como OAuth o SAML, o que utiliza los
parámetros de la solicitud para determinar la identidad del intermediario.

Cuando un cliente realiza una solicitud a uno de los métodos de la API, API Gateway llama a su
autorizador de Lambda, que toma la identidad del intermediario como entrada y devuelve una política de
IAM como salida.

Hay dos tipos de autorizadores Lambda:

• Un autorizador de Lambda basado en token (también llamado autorizador TOKEN) recibe la identidad
del intermediario en un token al portador, como, por ejemplo, un JSON Web Token (JWT) o un token de
OAuth.
• Un autorizador de Lambda basado en parámetros de solicitud (también denominado autorizador
REQUEST) recibe la identidad del autor de la llamada en una combinación de encabezados, parámetros
de cadena de consulta, stageVariables (p. 436) y variables $context (p. 425).

Para las API de WebSocket, solo se admiten los autorizadores basados en parámetros de la solicitud.

Se puede utilizar una función AWS Lambda de otra cuenta de AWS distinta de la cuenta en la que
creó la función de autorizador de Lambda. Para obtener más información, consulte the section called
“Configuración de un autorizador de Lambda entre cuentas” (p. 320).

Para ver ejemplos de funciones Lambda, consulte aws-apigateway-lambda-authorizer-blueprints en

GitHub.

Temas
• Flujo de trabajo de autorización para autorizadores de Lambda (p. 306)
• Pasos para crear un autorizador de Lambda de API Gateway (p. 307)
• Crear una función del autorizador de Lambda de API Gateway en la consola de Lambda. (p. 307)

305
 Amazon API Gateway Guía del desarrollador
Control de acceso

• Configuración de un autorizador de Lambda mediante la consola de API Gateway (p. 312)

• Entrada a un autorizador de Lambda de Amazon API Gateway (p. 314)
• Salida de un autorizador de Lambda de Amazon API Gateway (p. 316)
• Llamada a una API con autorizadores de Lambda de API Gateway (p. 318)
• Configuración de un autorizador de Lambda entre cuentas (p. 320)

Flujo de trabajo de autorización para autorizadores de Lambda

El siguiente diagrama ilustra el flujo de trabajo de autorización para autorizadores de Lambda.

Flujo de trabajo de autorización de Lambda en API Gateway

1. El cliente llama a un método en un método de la API de API Gateway, pasando un token al portador o
parámetros de solicitud.
2. API Gateway comprueba si hay configurado un autorizador de Lambda para el método. Si es así, API
Gateway llama a la función de Lambda.
3. La función de Lambda autentica al intermediario mediante métodos como los siguientes:

• Llamando a un proveedor de OAuth para obtener un token de acceso OAuth.

• Llamando a un proveedor de SAML para obtener una aserción SAML.
• Generando una política de IAM basada en los valores de los parámetros de la solicitud.
• Recuperando credenciales de una base de datos.
4. Si la llamada se realiza correctamente, la función de Lambda concede acceso devolviendo un objeto
de salida que contiene al menos una política de IAM y un identificador principal.
5. API Gateway evalúa la política.

• Si se deniega el acceso, API Gateway devuelve un código de estado HTTP apropiado, como por
ejemplo 403 ACCESS_DENIED.
• Si se permite el acceso, API Gateway ejecuta el método. Si el almacenamiento en caché está
habilitado en la configuración de autorizador, API Gateway también almacena en caché la política
de modo que no es necesario volver a invocar la función del autorizador de Lambda.

306
 Amazon API Gateway Guía del desarrollador
Control de acceso

Pasos para crear un autorizador de Lambda de API Gateway

Para crear un autorizador de Lambda, debe realizar las siguientes tareas:

1. Cree la función del autorizador de Lambda en la consola de Lambda tal y como se describe en the
section called “Crear una función del autorizador de Lambda en la consola de Lambda.” (p. 307).
Puede utilizar uno de los ejemplos de proyecto como punto de partida y personalizar la
entrada (p. 314) y salida (p. 316) como desee.
2. Configure la función de Lambda como un autorizador de API Gateway y configurar un método de API
para exigirlo tal y como se describe en the section called “Configuración de un autorizador de Lambda
mediante la consola” (p. 312). Por otro lado, si necesita un autorizador de Lambda entre cuentas,
consulte the section called “Configuración de un autorizador de Lambda entre cuentas” (p. 320).
Note

También puede configurar un autorizador mediante la CLI de AWS o un SDK de AWS.

3. Pruebe el autorizador mediante Postman, tal y como se describe en the section called “Llamada a una
API con autorizadores de Lambda” (p. 318).

Crear una función del autorizador de Lambda de API Gateway en la consola de

Lambda.
Antes de configurar un autorizador de Lambda, en primer lugar debe crear la función de Lambda que
implemente la lógica para autorizar y, si es necesario, autenticar al intermediario. La consola de Lambda
ofrece un proyecto de Python, que se puede utilizar eligiendo Use a blueprint (Utilizar un proyecto) y
eligiendo el proyecto api-gateway-authorizer-python. De lo contrario, deberá utilizar uno de los proyectos
en el repositorio de GitHub awslabs como punto de partida.

Para las funciones del autorizador de Lambda de ejemplo en esta sección, que no llaman a otros servicios,
puede utilizar el AWSLambdaBasicExecutionRole integrado. Al crear la función de Lambda para el
autorizador de Lambda de API Gateway, tendrá que asignar un rol de ejecución de IAM para la función
de Lambda si esta llama a otros servicios de AWS. Para crear el rol, siga las instrucciones de Rol de
ejecución de AWS Lambda.

Para ver más ejemplos de funciones de Lambda, consulte aws-apigateway-lambda-authorizer-blueprints

en GitHub.

EJEMPLO: Crear una función de autorizador de Lambda basada en tokens

Para crear una función de autorizador de Lambda basada en tokens, escriba el siguiente código Node.js
en la consola de Lambda y pruébelo en la consola de API Gateway, tal y como se indica a continuación.

1. En la consola de Lambda, elija Create function (Crear función).

2. Elija Author from scratch.
3. Escriba el nombre de la función.
4. Seleccione Create function (Crear función).
5. Copie y pegue el siguiente código en el editor de códigos.

// A simple token-based authorizer example to demonstrate how to use an authorization

token
// to allow or deny a request. In this example, the caller named 'user' is allowed to
invoke
// a request if the client-supplied token value is 'allow'. The caller is not allowed
to invoke
// the request if the token value is 'deny'. If the token value is 'unauthorized' or an
empty

307
 Amazon API Gateway Guía del desarrollador
Control de acceso

// string, the authorizer function returns an HTTP 401 status code. For any other token
value,
// the authorizer returns an HTTP 500 status code.
// Note that token values are case-sensitive.

exports.handler = function(event, context, callback) {

var token = event.authorizationToken;
switch (token) {
case 'allow':
callback(null, generatePolicy('user', 'Allow', event.methodArn));
break;
case 'deny':
callback(null, generatePolicy('user', 'Deny', event.methodArn));
break;
case 'unauthorized':
callback("Unauthorized"); // Return a 401 Unauthorized response
break;
default:
callback("Error: Invalid token"); // Return a 500 Invalid token response
}
};

// Help function to generate an IAM policy

var generatePolicy = function(principalId, effect, resource) {
var authResponse = {};

authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17';
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke';
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}

// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}

6. Elija Deploy (Implementar).

7. En la consola de API Gateway, cree una API sencilla (p. 43) si todavía no tiene una.
8. Elija la API de la lista de API.
9. Elija Authorizers (Autorizadores).
10. Elija Create New Authorizer (Crear nuevo autorizador).
11. Escriba un nombre para el autorizador.
12. En Type (Tipo), seleccione Lambda.
13. Para Lambda Function (Función de Lambda), elija la región donde ha creado la función de autorizador
de Lambda y elija el nombre de la función en el menú desplegable.
14. Deje Lambda Invoque Role (Rol de invocación de Lambda) en blanco.
15. Para Lambda Event Payload (Carga de evento de Lambda), elija Token.
16. Para Token Source (Origen de token), escriba authorizationToken.

308
 Amazon API Gateway Guía del desarrollador
Control de acceso

17. Elija Create (Crear), y, a continuación, elija Grant & Create (Conceder y crear).
18. Elija Test.
19. Para el valor authorizationToken escriba allow.
20. Elija Test.

En este ejemplo, cuando la API recibe una solicitud de método, API Gateway pasa el token de origen
a esta función de autorizador de Lambda en el atributo event.authorizationToken. La función del
autorizador de Lambda lee el token y actúa como se indica a continuación:

• Si el valor del token es 'allow', la función del autorizador devuelve una respuesta HTTP 200 OK y
una política de IAM que tiene un aspecto similar al siguiente, y la solicitud del método se lleva a cabo
correctamente:

{
"Version": "2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-
stage/GET/"
}
]
}

• Si el valor del token es 'deny', la función del autorizador devolverá una respuesta HTTP 403
Forbidden y una política Deny de IAM similar a la siguiente y se producirá un error en la solicitud del
método:

{
"Version": "2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-
stage/GET/"
}
]
}

• Si el valor del token es 'unauthorized' o una cadena vacía, la función del autorizador devolverá una
respuesta HTTP 401 Unauthorized y la llamada al método producirá un error.
• Si el token es cualquier otra cosa, el cliente recibirá una respuesta 500 Invalid token y la llamada al
método producirá un error.

Note

En el código de producción, es posible que necesite autenticar al usuario antes de conceder

la autorización. En tal caso, también puede agregar la lógica de autenticación a la función de
Lambda llamando a un proveedor de autenticación como se indica en la documentación de ese
proveedor.

Además de devolver una política de IAM, la función del autorizador de Lambda también debe devolver
el identificador principal del intermediario. También puede devolver un objeto context, que contiene
información adicional que puede pasarse al backend de integración. Para obtener más información,
consulte Salida de un autorizador de Lambda de Amazon API Gateway (p. 316).

309
 Amazon API Gateway Guía del desarrollador
Control de acceso

EJEMPLO: Crear una función de autorizador de Lambda basada en solicitudes

Para crear una función de autorizador de Lambda basada en solicitudes, escriba el siguiente código
Node.js en la consola de Lambda y pruébelo en la consola de API Gateway, tal y como se indica a
continuación.

1. En la consola de Lambda, elija Create function (Crear función).

2. Elija Author from scratch.
3. Escriba el nombre de la función.
4. Seleccione Create function (Crear función).
5. Copie y pegue el siguiente código en el editor de códigos.

exports.handler = function(event, context, callback) {

console.log('Received event:', JSON.stringify(event, null, 2));

// A simple request-based authorizer example to demonstrate how to use request

// parameters to allow or deny a request. In this example, a request is
// authorized if the client-supplied headerauth1 header, QueryString1
// query parameter, and stage variable of StageVar1 all match
// specified values of 'headerValue1', 'queryValue1', and 'stageValue1',
// respectively.

// Retrieve request parameters from the Lambda function input:

var headers = event.headers;
var queryStringParameters = event.queryStringParameters;
var pathParameters = event.pathParameters;
var stageVariables = event.stageVariables;

// Parse the input for the parameter values

var tmp = event.methodArn.split(':');
var apiGatewayArnTmp = tmp[5].split('/');
var awsAccountId = tmp[4];
var region = tmp[3];
var restApiId = apiGatewayArnTmp[0];
var stage = apiGatewayArnTmp[1];
var method = apiGatewayArnTmp[2];
var resource = '/'; // root resource
if (apiGatewayArnTmp[3]) {
resource += apiGatewayArnTmp[3];
}

// Perform authorization to return the Allow policy for correct parameters and
// the 'Unauthorized' error, otherwise.
var authResponse = {};
var condition = {};
condition.IpAddress = {};

if (headers.headerauth1 === "headerValue1"

&& queryStringParameters.QueryString1 === "queryValue1"
&& stageVariables.StageVar1 === "stageValue1") {
callback(null, generateAllow('me', event.methodArn));
} else {
callback("Unauthorized");
}
}

// Help function to generate an IAM policy

var generatePolicy = function(principalId, effect, resource) {
// Required output:
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};

310
 Amazon API Gateway Guía del desarrollador
Control de acceso

policyDocument.Version = '2012-10-17'; // default version

policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke'; // default action
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}

var generateAllow = function(principalId, resource) {

return generatePolicy(principalId, 'Allow', resource);
}

var generateDeny = function(principalId, resource) {

return generatePolicy(principalId, 'Deny', resource);
}

6. Elija Deploy (Implementar).

7. En la consola de API Gateway, cree una API sencilla (p. 43) si todavía no tiene una.
8. Elija la API de la lista de API.
9. Elija Authorizers (Autorizadores).
10. Elija Create New Authorizer (Crear nuevo autorizador).
11. Escriba un nombre para el autorizador.
12. En Type (Tipo), seleccione Lambda.
13. Para Lambda Function (Función de Lambda), elija la región donde ha creado la función de autorizador
de Lambda y elija el nombre de la función en el menú desplegable.
14. Deje Lambda Invoque Role (Rol de invocación de Lambda) en blanco.
15. Para Lambda Event Payload (Carga de evento de Lambda), elija Request (Solicitud).
16. En Identity Sources (Orígenes de identidad), agregue un Header (Encabezado) denominado
headerauth1, una Query String (Cadena de consulta) denominada QueryString1 y una Stage
Variable (Variable de etapa) denominada StageVar1.
17. Elija Create (Crear), y, a continuación, elija Grant & Create (Conceder y crear).
18. Elija Test.
19. Para headerauth1, escriba headerValue1. Para QueryString1, escriba queryValue1. Para
StageVar1, escriba stageValue1.
20. Elija Test.

En este ejemplo, la función del autorizador de Lambda comprueba los parámetros de entrada y actúa como
se indica a continuación:

• Si todos los valores de los parámetros necesarios coinciden con los valores previstos, la función del
autorizador devuelve una respuesta HTTP 200 OK y una política de IAM que tiene un aspecto similar al
siguiente, y la solicitud del método se lleva a cabo correctamente:

{
"Version": "2012-10-17",
"Statement": [

311
 Amazon API Gateway Guía del desarrollador
Control de acceso

{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-
stage/GET/"
}
]
}

• De lo contrario, la función del autorizador devuelve una respuesta HTTP 401 Unauthorized y la
llamada al método produce un error.

Note

En el código de producción, es posible que necesite autenticar al usuario antes de conceder

la autorización. En tal caso, también puede agregar la lógica de autenticación a la función de
Lambda llamando a un proveedor de autenticación como se indica en la documentación de ese
proveedor.

Además de devolver una política de IAM, la función del autorizador de Lambda también debe devolver
el identificador principal del intermediario. También puede devolver un objeto context, que contiene
información adicional que puede pasarse al backend de integración. Para obtener más información,
consulte Salida de un autorizador de Lambda de Amazon API Gateway (p. 316).

Configuración de un autorizador de Lambda mediante la consola de API Gateway

Después de crear la función de Lambda y verificar que funciona, siga los pasos siguientes para configurar
el autorizador de Lambda (que anteriormente se denominaba autorizador personalizado) de API Gateway
en la consola de API Gateway.

Para configurar un autorizador de Lambda mediante la consola de API Gateway

1. Inicie sesión en la consola de API Gateway.

2. Cree una nueva API o seleccione una ya existente y elija Authorizers (Autorizadores) en esa API.
3. Elija Create New Authorizer (Crear nuevo autorizador).
4. En Create Authorizer (Crear autorizador), escriba un nombre de autorizador en el campo de entrada
Name (Nombre).
5. En Type (Tipo), seleccione la opción Lambda.
6. Para Lambda Function (Función de Lambda), elija una región y, a continuación, elija una función de
autorizador de Lambda perteneciente a su cuenta.
7. Deje en blanco el campo Lambda Invoke Role (Rol de invocación de Lambda) para permitir que la
consola de API Gateway defina una política basada en recursos. La política concede permisos a API
Gateway para invocar la función de Lambda del autorizador. También puede escribir el nombre de un
rol de IAM para permitir que API Gateway invoque la función de Lambda del autorizador. Para ver un
ejemplo de este rol, consulte Crear un rol de IAM asumible (p. 95).

Si elige permitir que la consola de API Gateway defina la política basada en recursos, se mostrará el
cuadro de diálogo Add Permission to Lambda Function (Agregar permiso a la función de Lambda).
Seleccione OK. Una vez creada la autorización de Lambda, puede probarla con los valores del token
de autorización adecuados para comprobar que funciona según lo previsto.
8. Para Lambda Event Payload (Carga de evento de Lambda), elija Token para un autorizador TOKEN o
bien Request para un autorizador REQUEST. (Es lo mismo que establecer la propiedad type en TOKEN
o REQUEST).
9. Dependiendo de la elección del paso anterior, lleve a cabo alguna de las siguientes operaciones:

a. Para las opciones Token, haga lo siguiente:

312
 Amazon API Gateway Guía del desarrollador
Control de acceso

• Escriba el nombre de un encabezado en Token Source (Origen del token). El cliente de la API
debe incluir un encabezado con este nombre para enviar el token de autorización al autorizador
de Lambda.
• Opcionalmente, proporcione una instrucción RegEx en el campo de entrada Token
Validation. API Gateway realiza la validación inicial del token de entrada contra esta
expresión e invoca el autorizador tras una validación correcta. Esto ayuda a reducir la
posibilidad de que se cobre por tokens no válidos.
• Para Authorization Caching (Almacenamiento en caché de autorizaciones), seleccione o anule
la selección de la opción Enabled (Habilitado), en función de si desea almacenar en caché o
no la política de autorización generada por el autorizador. Cuando se activa el almacenamiento
en caché de políticas, puede modificar el valor TTL. Si establece TTL en cero se desactivará
el almacenamiento en caché de políticas. Cuando el almacenamiento en caché de las políticas
esté habilitado, el nombre del encabezado especificado en Token Source (Origen del token)
pasará a ser la clave de caché.
Note

El valor de TTL predeterminado es de 300 segundos. El valor máximo es de 3600

segundos, este límite no se puede aumentar.
b. Para la opción Request (Solicitud), haga lo siguiente:

• En Identity Sources (Orígenes de identidad), escriba un nombre de parámetro de solicitud de

un tipo de parámetro elegido. Los tipos de parámetro admitidos son Header, Query String,
Stage Variable y Context. Para añadir más fuentes de identidad, elija Add Identity Source
(Añadir origen de identidad).

API Gateway utiliza las fuentes de identidad especificadas como la clave de caché del
autorizador de la solicitud. Cuando está habilitado el almacenamiento en caché, API Gateway
llama a la función de Lambda del autorizador solo después de verificar correctamente que
todas las fuentes de identidad especificadas estén presentes en tiempo de ejecución. Si falta
alguna fuente de identidad especificada, o bien es nula o está vacía, API Gateway devolverá
una respuesta 401 Unauthorized sin llamar a la función de Lambda del autorizador.

Cuando se definen varias fuentes de identidad, todas se utilizan para obtener la clave de caché
del autorizador. Cambiar cualquiera de las partes de la clave de caché hace que el autorizador
descarte el documento de políticas almacenado en caché y genere otro nuevo.
• Para Authorization Caching (Almacenamiento en caché de autorizaciones), seleccione o anule
la selección de la opción Enabled (Habilitado), en función de si desea almacenar en caché o no
la política de autorización generada por el autorizador. Cuando se activa el almacenamiento en
caché de políticas, puede modificar el valor TTL del valor predeterminado (300). Si establece
TTL=0, se desactivará el almacenamiento en caché de políticas.

Cuando está desactivado el almacenamiento en caché, no es necesario especificar ninguna

fuente de identidad.

Note

Para habilitar el almacenamiento en caché, su autorizador debe devolver una política que se
aplique a todos los métodos a través de una API. Para forzar la política especificada por el
método, puede establecer el valor de TTL en cero para deshabilitar el almacenamiento en
caché de políticas para la API.
10. Elija Create (Crear) para crear el nuevo autorizador de Lambda para la API elegida.
11. Una vez que se crea el autorizador para la API, tiene la opción de probar la llamada a un autorizador
antes de configurarlo en un método.

313
 Amazon API Gateway Guía del desarrollador
Control de acceso

Para el autorizador TOKEN, escriba un token válido en el campo de texto de entrada Identity token
(Token de identidad) y seleccione Test (Probar). El token se transferirá a la función de Lambda
como el encabezado que especificó en la configuración de Identity token source (Origen de token de
identidad) del autorizador.

Para el autorizador REQUEST, escriba los parámetros de solicitud válidos correspondientes a las
fuentes de identidad especificadas y, a continuación, seleccione Test (Probar).

Además de utilizar la consola de API Gateway, puede utilizar la CLI de AWS o un SDK de AWS para
API Gateway para probar la llamada a un autorizador. Para hacerlo a través de CLI de AWS, consulte
test-invoke-authorizer.
Note

Los procesos "test-invoke" para ejecuciones de métodos y "test-invoke" para autorizadores

son procesos independientes.
Para probar la llamada a un método usando la consola de API Gateway, consulte Uso de la
consola para probar un método de la API de REST (p. 478). Para probar la llamada a un
método usando CLI de AWS, consulte test-invoke-method.
Para probar la llamada a un método y a un autorizador configurado, implemente la API y, a
continuación, utilice cURL o Postman para llamar al método, proporcionando el token o los
parámetros de solicitud necesarios.

El procedimiento siguiente muestra cómo configurar un método de API para que use el autorizador de
Lambda.

Para configurar un método de API para que use un autorizador de Lambda

1. Vuelva a la API. Cree un nuevo método o elija un método existente. Si es necesario, cree un nuevo
recurso.
2. En Method Execution (Ejecución del método), elija el enlace Method Request (Solicitud de método).
3. En Settings (Configuración), expanda la lista desplegable Authorization (Autorización) para seleccionar
el autorizador de Lambda que acaba de crear (por ejemplo, myTestApiAuthorizer) y, a continuación,
elija el icono de marca de verificación para guardar la selección.
4. Si lo desea, mientras está en la página Method Request (Solicitud de método), elija Add header
(Añadir encabezado) si también quiere pasar el token de autorización al backend. En Name (Nombre),
escriba un nombre de encabezado que coincida con el nombre de Token Source (Origen del token)
que especificó al crear el autorizador de Lambda para la API. A continuación, haga clic en el icono
de marca de verificación para guardar la configuración. Este paso no se aplica a los autorizadores
REQUEST.
5. Elija Deploy API (Implementar API) para implementar la API en una etapa. Anote el valor de Invoke
URL (Invocar URL). Lo necesitará cuando llame a la API. En el caso de los autorizadores REQUEST
que utilizan variables de etapa, también debe definir las variables de etapa necesarias y especificar
sus valores en Stage Editor (Editor de etapas).

Entrada a un autorizador de Lambda de Amazon API Gateway

Para un autorizador de Lambda (que anteriormente se denominaba autorizador personalizado) del
tipo TOKEN, debe especificar un encabezado personalizado como Token Source (Origen del token)
al configurar el autorizador para una API. El cliente de la API debe transmitir el token de autorización
necesario en ese encabezamiento en la solicitud de entrada. Tras recibir la solicitud del método de
entrada, API Gateway extrae el token del encabezado personalizado. A continuación, transmite el token
como propiedad authorizationToken del objeto event de la función de Lambda, además del ARN del
método como propiedad methodArn:

314
 Amazon API Gateway Guía del desarrollador
Control de acceso

{
"type":"TOKEN",
"authorizationToken":"{caller-supplied-token}",
    "methodArn":"arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/
[{resource}/[{child-resources}]]"
}

En este ejemplo, la propiedad type especifica el tipo de autorizador, que es un autorizador TOKEN.
{caller-supplied-token} procede del encabezado de autorización de una solicitud del cliente.
methodArn es el ARN de la solicitud del método de entrada y lo rellena API Gateway de acuerdo con la
configuración del autorizador de Lambda.

Para la función de Lambda del autorizador TOKEN de ejemplo mostrada en la sección anterior, la cadena
caller-supplied-token es allow, deny, unauthorized o cualquier otro valor de cadena. Una
cadena vacía es lo mismo que unauthorized. A continuación se muestra un ejemplo de este tipo de
entrada para obtener una política Allow en el método GET de una API (ymy8tbxw7b) de la cuenta de
AWS (123456789012) en cualquier etapa (*).

{
"type":"TOKEN",
"authorizationToken":"allow",
"methodArn":"arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/*/GET/"
}

Para un autorizador de Lambda del tipo REQUEST, API Gateway transmite los parámetros de solicitud
necesarios a la función de Lambda del autorizador como parte del objeto event. Los parámetros de
solicitud afectados incluyen encabezados, parámetros de ruta, parámetros de cadenas de consulta,
variables de etapa y algunas variables de contexto de solicitud. El intermediario de la API puede definir
parámetros de ruta, encabezados y parámetros de cadenas de consulta. El desarrollador de la API debe
establecer las variables de etapa durante la implementación de la API y API Gateway proporciona el
contexto de la solicitud en tiempo de ejecución.
Note

Los parámetros de la ruta se pueden pasar como parámetros de solicitud a la función del
autorizador de Lambda pero no se pueden usar como fuentes de identidad.

El siguiente ejemplo muestra una entrada de un autorizador REQUEST para un método de la API (GET /
request) con una integración de proxy:

{
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:s4x3opwd6i/test/GET/request",
"resource": "/request",
"path": "/request",
"httpMethod": "GET",
"headers": {
"X-AMZ-Date": "20170718T062915Z",
"Accept": "*/*",
"headerauth1": "headerValue1",
"CloudFront-Viewer-Country": "US",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Is-Mobile-Viewer": "false",
"User-Agent": "...",
"X-Forwarded-Proto": "https",
"CloudFront-Is-SmartTV-Viewer": "false",
"Host": "....execute-api.us-east-1.amazonaws.com",
"Accept-Encoding": "gzip, deflate",
"X-Forwarded-Port": "443",
"X-Amzn-Trace-Id": "...",

315
 Amazon API Gateway Guía del desarrollador
Control de acceso

"Via": "...cloudfront.net (CloudFront)",

"X-Amz-Cf-Id": "...",
"X-Forwarded-For": "..., ...",
"Postman-Token": "...",
"cache-control": "no-cache",
"CloudFront-Is-Desktop-Viewer": "true",
"Content-Type": "application/x-www-form-urlencoded"
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"pathParameters": {},
"stageVariables": {
"StageVar1": "stageValue1"
},
"requestContext": {
"path": "/request",
"accountId": "123456789012",
"resourceId": "05c7jb",
"stage": "test",
"requestId": "...",
"identity": {
"apiKey": "...",
"sourceIp": "..."
},
"resourcePath": "/request",
"httpMethod": "GET",
"apiId": "s4x3opwd6i"
}
}

requestContext es un mapa de pares de clave-valor y se corresponde con la variable

$context (p. 425). Su resultado depende de la API. API Gateway puede agregar nuevas claves al mapa.
Para obtener más información sobre la entrada de la función de Lambda en una integración de proxy,
consulte Formato de entrada de una función de Lambda para la integración de proxy (p. 348).

Salida de un autorizador de Lambda de Amazon API Gateway

La salida de una función de autorizador de Lambda es un objeto similar a un diccionario que debe incluir
el identificador de la entidad principal (principalId) y un documento de política (policyDocument)
que contenga una lista de instrucciones de política. La salida también puede incluir un mapa context
que contenga pares de clave-valor. Si la API utiliza un plan de uso (apiKeySource se ha establecido en
AUTHORIZER), la función de autorizador de Lambda debe devolver una de las claves de API del plan de
uso como valor de la propiedad usageIdentifierKey.

A continuación se muestra un ejemplo de esta salida.

{
  "principalId": "yyyyyyyy", // The principal user identification associated with the token
sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/
[{resource}/[{child-resources}]]"
}
]
},
"context": {
"stringKey": "value",

316
 Amazon API Gateway Guía del desarrollador
Control de acceso

"numberKey": "1",
"booleanKey": "true"
},
"usageIdentifierKey": "{api-key}"
}

Aquí, una instrucción de política especifica si se permite o deniega (Effect) al servicio de ejecución de
API Gateway invocar (Action) el método de API especificado (Resource). Puede utilizar un carácter
comodín (*) para especificar un tipo de recurso (método). Para obtener información sobre la configuración
de políticas válidas para llamar a una API, consulte Referencia de instrucciones de políticas de IAM para
ejecutar la API en API Gateway (p. 296).

En el caso de los ARN del método con autorización habilitada (por ejemplo, arn:aws:execute-
api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-
resources}]]), la longitud máxima es de 1600 bytes. Los valores de parámetros de ruta, cuyo tamaño
se determina en tiempo de ejecución, pueden provocar que la longitud del ARN supere el límite. Cuando
esto ocurra, el cliente de la API recibirá una respuesta 414 Request URI too long.

Además, el ARN de recurso, tal y como se muestra en la instrucción de política de salida que ha realizado
el autorizador, está limitado actualmente a 512 caracteres. Por este motivo, no debe utilizar la URI con un
token JWT que tenga una longitud considerable en una URI de la solicitud. Puede transferir de manera
segura el token JWT en un encabezado de solicitud.

Puede tener acceso al valor principalId de una plantilla de asignación utilizando la variable
$context.authorizer.principalId. Esto resulta útil si desea transmitir el valor al backend. Para
obtener más información, consulte Variables $context para modelos de datos, autorizadores, plantillas
de mapeo y registro de acceso de CloudWatch (p. 425).

Puede obtener acceso al valor de stringKey, numberKey o booleanKey (por ejemplo, "value", "1" o
"true") del mapa context en una plantilla de mapeo llamando a $context.authorizer.stringKey,
$context.authorizer.numberKey o $context.authorizer.booleanKey, respectivamente. Los
valores devueltos se representan en forma de cadena. Observe que no puede establecer un objeto o
matriz JSON como un valor válido de ninguna clave en el mapa context.

Puede utilizar el mapa context para devolver las credenciales almacenadas en caché del autorizador al
backend utilizando una plantilla de mapeo de una solicitud de integración. Esto permite que el backend
proporcione una mejor experiencia de usuario mediante la utilización de las credenciales almacenadas en
caché para reducir la necesidad de obtener acceso a las claves secretas y abrir los tokens de autorización
para cada solicitud.

En el caso de la integración de proxy de Lambda, API Gateway transmite el objeto context de un

autorizador de Lambda directamente a la función de Lambda del backend como parte de la entrada
event. Puede recuperar los pares de clave-valor de context en la función de Lambda llamando a
$event.requestContext.authorizer.key.

{api-key} representa una clave de API en el plan de uso de la etapa de API. Para obtener más
información, consulte the section called “Planes de uso” (p. 574).

El siguiente ejemplo muestra la salida del ejemplo de autorizador de Lambda. La salida del ejemplo
contiene una instrucción de política para bloquear (Deny) las llamadas al método GET de una API
(ymy8tbxw7b) de una cuenta de AWS (123456789012) en cualquier etapa (*).

{
"principalId": "user",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Deny",

317
 Amazon API Gateway Guía del desarrollador
Control de acceso

"Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/*/GET/"
}
]
}
}

Llamada a una API con autorizadores de Lambda de API Gateway

Después de configurar el autorizador de Lambda (que anteriormente se denominaba autorizador
personalizado); e implementar la API, debe probar la API con el autorizador de Lambda habilitado. Para
ello, necesita un cliente REST, como cURL o Postman. En los siguientes ejemplos, usamos Postman.
Note

Al llamar a un método habilitado para un autorizador, API Gateway no registra la llamada a

CloudWatch si el token necesario para el autorizador TOKEN no se establece, es nulo o no
es válido para la expresión Token validation expression (Expresión de validación de token)
especificada. Del mismo modo, API Gateway no registra la llamada a CloudWatch si alguno de los
orígenes de identidad necesarios para el autorizador REQUEST no está establecido, es nulo o está
vacío.

A continuación, mostramos cómo utilizar Postman para llamar a la API o probarla con el autorizador de
Lambda TOKEN (que se ha descrito anteriormente) habilitado. El método puede usarse para llamar a una
API con un autorizador de Lambda REQUEST si se especifican los parámetros de ruta, encabezado o
cadena de consulta necesarios de forma explícita.

Llamar a una API con el autorizador personalizado TOKEN

1. Abra Postman, elija el método GET y pegue el valor de Invoke URL (Invocar URL) de la API en el
campo URL contiguo.

Agregue el encabezado de token de autorización de Lambda y establezca el valor en allow.

Seleccione Send (enviar).

318
 Amazon API Gateway Guía del desarrollador
Control de acceso

La respuesta muestra que el autorizador de Lambda de API Gateway devuelve una respuesta 200
OK y autoriza correctamente a la llamada para que tenga acceso al punto de enlace HTTP (http://
httpbin.org/get) integrado en el método.
2. Sin salir de Postman, cambie el valor del encabezado de token de autorización de Lambda a deny.
Seleccione Send (enviar).

La respuesta muestra que el autorizador de Lambda de API Gateway devuelve una respuesta 403
Forbidden que no autoriza a la llamada para que tenga acceso al punto de enlace HTTP.
3. En Postman, cambie el valor del encabezado de token de autorización de Lambda a unauthorized y
elija Send (Enviar).

319
 Amazon API Gateway Guía del desarrollador
Control de acceso

La respuesta muestra que API Gateway devuelve una respuesta 401 Unauthorized sin autorizar la
llamada para tener acceso al punto de enlace HTTP.
4. Ahora, cambie el valor del encabezado de token de autorización de Lambda a fail. Seleccione Send
(enviar).

La respuesta muestra que API Gateway devuelve una respuesta 500 Internal Server Error sin autorizar
la llamada para tener acceso al punto de enlace HTTP.

Configuración de un autorizador de Lambda entre cuentas

Ahora también se puede utilizar una función de AWS Lambda de otra cuenta de AWS como función de
autorizador de API. Cada cuenta puede estar en cualquier región en la que Amazon API Gateway esté
disponible. La función de autorizador de Lambda puede utilizar estrategias de autenticación de token al
portador como OAuth o SAML. Esto permite administrar y compartir fácilmente de forma centralizada la
función de autorizador de Lambda en distintas API de API Gateway.

En esta sección, mostramos cómo configurar una función de autorización de Lambda entre cuentas
mediante la consola de Amazon API Gateway.

En estas instrucciones, se presupone que ya dispone de una API de API Gateway en una cuenta de AWS
y de una función de autorizador de Lambda en otra cuenta.

Configurar un autorizador de Lambda entre cuentas mediante la consola de API Gateway

Inicie sesión en la consola de Amazon API Gateway de la primera cuenta (la que tiene la API) y haga lo
siguiente:

1. Localice la API y elija Authorizers (Autorizadores).

2. Elija Create New Authorizer (Crear nuevo autorizador).
3. En Create Authorizer (Crear autorizador), escriba un nombre de autorizador en el campo de entrada
Name (Nombre).
4. En Type (Tipo), seleccione la opción Lambda.
5. Para Lambda Function (Función de Lambda), copie y pegue el ARN completo de la función de
autorizador de Lambda que tiene en su segunda cuenta.

320
 Amazon API Gateway Guía del desarrollador
Control de acceso

Note

En la consola de Lambda, puede encontrar el ARN de la función en la esquina superior

derecha de la ventana de la consola.
6. Deje en blanco el campo Lambda Invoke Role (Rol de invocación de Lambda) para permitir que la
consola de API Gateway defina una política basada en recursos. La política concede permisos a API
Gateway para invocar la función de Lambda del autorizador. También puede escribir el nombre de un
rol de IAM para permitir que API Gateway invoque la función de Lambda del autorizador. Para ver un
ejemplo de este rol, consulte Crear un rol de IAM asumible (p. 95).

Si elige permitir que la consola de API Gateway defina la política basada en recursos, se mostrará el
cuadro de diálogo Add Permission to Lambda Function (Agregar permiso a la función de Lambda).
Seleccione OK. Una vez creada la autorización de Lambda, puede probarla con los valores del token
de autorización adecuados para comprobar que funciona según lo previsto.
7. Para Lambda Event Payload (Carga de evento de Lambda), elija Token para un autorizador TOKEN o
bien Request para un autorizador REQUEST.
8. Dependiendo de la opción elegida en el paso anterior, realice una de las siguientes operaciones:

a. Para las opciones Token, haga lo siguiente:

i. Escriba el nombre de un encabezado en Token Source (Origen del token). El cliente de la

API debe incluir un encabezado con este nombre para enviar el token de autorización al
autorizador de Lambda.
ii. Opcionalmente, proporcione una instrucción RegEx en el campo de entrada Token validation
(Validación de token). API Gateway realiza la validación inicial del token de entrada contra
esta expresión e invoca el autorizador tras una validación correcta. Esto ayuda a reducir la
posibilidad de que se cobre por tokens no válidos.
iii. Para Authorization Caching (Almacenamiento en caché de autorizaciones), seleccione o
anule la selección de la opción Enabled (Habilitado), en función de si desea almacenar
en caché o no la política de autorización generada por el autorizador. Cuando se activa el
almacenamiento en caché de políticas, puede modificar el valor TTL del valor predeterminado
(300). Si establece TTL=0, se desactivará el almacenamiento en caché de políticas. Cuando
el almacenamiento en caché de las políticas esté habilitado, el nombre del encabezado
especificado en Token Source (Origen del token) pasará a ser la clave de caché.
b. Para la opción Request (Solicitud), haga lo siguiente:

i. En Identity Sources (Orígenes de identidad), escriba un nombre de parámetro de solicitud

de un tipo de parámetro elegido. Los tipos de parámetro admitidos son Header, Query
String, Stage Variable y Context. Para añadir más fuentes de identidad, elija Add
Identity Source (Añadir origen de identidad).

API Gateway utiliza las fuentes de identidad especificadas como la clave de caché del
autorizador de la solicitud. Cuando está habilitado el almacenamiento en caché, API Gateway
llama a la función de Lambda del autorizador solo después de verificar correctamente que
todas las fuentes de identidad especificadas estén presentes en tiempo de ejecución. Si falta
alguna fuente de identidad especificada, o bien es nula o está vacía, API Gateway devolverá
una respuesta 401 Unauthorized sin llamar a la función de Lambda del autorizador.

Cuando se definen varias fuentes de identidad, se utilizan todas ellas para obtener la clave
de caché del autorizador. Cambiar cualquiera de las partes de la clave de caché hace que el
autorizador descarte el documento de políticas almacenado en caché y genere otro nuevo.
ii. En Authorization Caching (Almacenamiento en caché de autorizaciones), deje seleccionada
la opción Enabled (Habilitado). Deje el valor predeterminado de TTL (300).
9. Elija Create (Crear) para crear el nuevo autorizador de Lambda para la API elegida.

321
 Amazon API Gateway Guía del desarrollador
Control de acceso

10. Verá un mensaje con este texto: Add Permission to Lambda Function: You have selected a Lambda
function from another account (Agregar permiso para función de Lambda: ha seleccionado una función
de Lambda de otra cuenta). Please ensure that you have the appropriate Function Policy on this
function. (Asegúrese de que tiene la política de función apropiada en esta función.) Para ello, ejecute
el siguiente comando de la CLI de AWS desde la cuenta 123456789012:, seguido de una cadena de
comandos aws lambda add-permission.
11. Copie y pegue la cadena de comandos aws lambda add-permission en una ventana de la CLI de
AWS configurada para la segunda cuenta. Este concederá a la primera cuenta acceso a la función de
autorizador de Lambda de la segunda cuenta.
12. En el mensaje emergente del paso anterior, haga clic en OK (Aceptar).

Control del acceso a una API de REST con grupos de usuarios

de Amazon Cognito como autorizador
Además de utilizar roles y políticas de IAM (p. 287) o autorizadores de Lambda (p. 305) (que
anteriormente se denominaban autorizadores personalizados), también puede utilizar un grupo de usuarios
de Amazon Cognito para controlar quién puede tener acceso a la API en Amazon API Gateway.

Para utilizar un grupo de usuarios de Amazon Cognito con la API, primero debe crear un autorizador del
tipo COGNITO_USER_POOLS y configurar después un método de API para que utilice ese autorizador.
Una vez implementada la API, lo primero que debe hacer el cliente es registrar al usuario en el grupo de
usuarios, obtener un token de acceso o identidad para el usuario y llamar al método de API con uno de
los tokens, que normalmente están establecidos en el encabezado Authorization de la solicitud. La
llamada a la API solo tendrá éxito si se suministra el token solicitado y este es válido; de lo contrario, el
cliente no tendrá autorización para hacer la llamada, ya que carecerá de las credenciales que permitirían
autorizarlo.

El token de identidad se utiliza para autorizar las llamadas a la API en función de las solicitudes de
identidad del usuario conectado. El token de acceso se utiliza para autorizar las llamadas a la API en
función de los ámbitos personalizados de los recursos con protección de acceso especificados. Para
obtener más información, consulte Uso de tokens con grupos de usuarios y Servidor de recursos y ámbitos
personalizados.

Si desea crear y configurar un grupo de usuarios de Amazon Cognito para la API, debe realizar las
siguientes tareas:

• Utilice la API, la CLI, el SDK o la consola de Amazon Cognito para crear un grupo de usuarios; también
puede utilizar un grupo de usuarios de otra cuenta de AWS.
• Utilice la API, la CLI, el SDK o la consola de API Gateway para crear un autorizador de API Gateway con
el grupo de usuarios elegido.
• Utilice la API, la CLI, el SDK o la consola de API Gateway para habilitar el autorizador de los métodos de
API seleccionados.

Para llamar a los métodos de API con un grupo de usuarios habilitado, los clientes de la API tienen que
realizar las siguientes tareas:

• Utilice la API, la CLI o el SDK de Amazon Cognito para registrar el usuario en el grupo de usuarios
elegido y obtener un token de identidad o acceso.
• Utilice una plataforma específica del cliente para llamar a la API de API Gateway implementada y
proporcione el token apropiado en el encabezado Authorization.

Como desarrollador de la API, debe proporcionar a los desarrolladores del cliente el ID del grupo de
usuarios, el ID del cliente y, probablemente, los secretos del cliente asociados que se hayan definido con el
grupo de usuarios.

322
 Amazon API Gateway Guía del desarrollador
Control de acceso

Note

Si desea permitir que un usuario inicie sesión con las credenciales de Amazon Cognito y pueda
obtener también unas credenciales temporales para utilizarlas con los permisos de un rol de
IAM, utilice las identidades federadas de Amazon Cognito. Para cada método HTTP de punto de
enlace de recurso de API, establezca el tipo de autorización, categoría Method Execution, en
AWS_IAM.

En esta sección, se explica cómo crear un grupo de usuarios, cómo integrar una API de API Gateway con
el grupo de usuarios y cómo invocar una API que está integrada con el grupo de usuarios.

Temas
• Obtener permisos para crear autorizadores del grupo de usuarios de Amazon Cognito para una API
REST (p. 323)
• Creación de un grupo de usuarios de Amazon Cognito para una API REST (p. 324)
• Integración de una API REST con un grupo de usuarios de Amazon Cognito (p. 325)
• Llamar a una API REST integrada con un grupo de usuarios de Amazon Cognito (p. 329)
• Configuración de un autorizador de Amazon Cognito entre cuentas para una API REST mediante la
consola de API Gateway (p. 330)

Obtener permisos para crear autorizadores del grupo de usuarios de Amazon

Cognito para una API REST
Si desea crear un autorizador con un grupo de usuarios de Amazon Cognito, debe tener permisos Allow
para crear o actualizar un autorizador con el grupo de usuarios de Amazon Cognito elegido. El siguiente
documento de política de IAM muestra un ejemplo de esos permisos:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:POST"
],
"Resource": "arn:aws:apigateway:*::/restapis/*/authorizers",
"Condition": {
"ArnLike": {
"apigateway:CognitoUserPoolProviderArn": [
"arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-
east-1_aD06NQmjO",
"arn:aws:cognito-idp:us-east-1:234567890123:userpool/us-
east-1_xJ1MQtPEN"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"apigateway:PATCH"
],
"Resource": "arn:aws:apigateway:*::/restapis/*/authorizers/*",
"Condition": {
"ArnLike": {
"apigateway:CognitoUserPoolProviderArn": [
"arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-
east-1_aD06NQmjO",

323
 Amazon API Gateway Guía del desarrollador
Control de acceso

"arn:aws:cognito-idp:us-east-1:234567890123:userpool/us-
east-1_xJ1MQtPEN"
]
}
}
}
]
}

Asegúrese de que la política está asociada al usuario de IAM, a un grupo de IAM al que pertenezca o a un
rol de IAM que tenga asignado.

En el documento de la política anterior, la acción apigateway:POST sirve para crear un autorizador y

la acción apigateway:PATCH sirve para actualizar un autorizador existente. Puede restringir la política
a una región específica o a una API concreta anulando los dos primeros caracteres comodín (*) de los
valores de Resource, respectivamente.

Las cláusulas Condition que se utilizan aquí sirven para restringir los permisos Allowed a los grupos
de usuarios especificados. Cuando hay una cláusula Condition, se deniega el acceso a los grupos
de usuarios que no cumplen las condiciones. Cuando un permiso no tiene una cláusula Condition, se
permite el acceso a cualquier grupo de usuarios.

Dispone de las siguientes opciones para configurar la cláusula Condition:

• Puede definir una expresión condicional ArnLike o ArnEquals para permitir la creación o la
actualización de autorizadores de COGNITO_USER_POOLS únicamente con los grupos de usuarios
especificados.
• Puede definir una expresión condicional ArnNotLike o ArnNotEquals para permitir la creación o la
actualización de autorizadores de COGNITO_USER_POOLS con cualquier grupo de usuarios que no esté
especificado en la expresión.
• Puede omitir la cláusula Condition para permitir la creación o la actualización de autorizadores de
COGNITO_USER_POOLS con cualquier grupo de usuarios de cualquier cuenta de AWS y de cualquier
región.

Para obtener más información sobre las expresiones condicionales del nombre de recurso de Amazon
(ARN), consulte Operadores de condición de nombre de recurso de Amazon (ARN). Tal y como se muestra
en el ejemplo, apigateway:CognitoUserPoolProviderArn es una lista de los ARN de los grupos de
usuarios de COGNITO_USER_POOLS que pueden o no utilizarse con un autorizador de API Gateway de tipo
COGNITO_USER_POOLS.

Creación de un grupo de usuarios de Amazon Cognito para una API REST

Antes de integrar la API con un grupo de usuarios, debe crear el grupo de usuarios en Amazon Cognito.
Para obtener instrucciones acerca de cómo crear un grupo de usuarios, consulte Configuración de grupos
de usuarios en la guía para desarrolladores de Amazon Cognito.
Note

Si crea grupos para el grupo de usuarios, asegúrese de que los nombres de grupo utilicen solo
caracteres alfanuméricos.

Apunte el ID del grupo de usuarios, el ID del cliente y la clave secreta del cliente. El cliente debe
proporcionarlos a Amazon Cognito para que el usuario pueda registrarse en el grupo de usuarios, para
iniciar sesión en el grupo de usuarios y para obtener un token de identidad o acceso, que debe incluirse
en las solicitudes para llamar a los métodos de la API configurados con el grupo de usuarios. Además, se
debe especificar el nombre del grupo de usuarios al configurar el grupo de usuarios como autorizador de
API Gateway, tal y como se describe a continuación.

324
 Amazon API Gateway Guía del desarrollador
Control de acceso

Si utiliza tokens de acceso para autorizar las llamadas a los métodos de la API, asegúrese de configurar
la integración de aplicaciones con el grupo de usuarios para establecer los ámbitos que desee en un
determinado servidor de recursos. Para obtener más información sobre el uso de tokens con grupos
de usuarios de Amazon Cognito, consulte Uso de tokens con grupos de usuarios. Para obtener más
información acerca de los servidores de recursos, consulte Definir servidores de recursos para su grupo de
usuarios.

Anote los identificadores del servidor de recursos configurados y los nombres de ámbito personalizados.
Los necesita para generar los nombres completos de los ámbitos de acceso de OAuth Scopes (Ámbitos de
OAuth) que el autorizador de COGNITO_USER_POOLS utiliza.

Integración de una API REST con un grupo de usuarios de Amazon Cognito

Después de crear un grupo de usuarios de Amazon Cognito, en API Gateway, debe crear un autorizador
COGNITO_USER_POOLS que utilice el grupo de usuarios. El siguiente procedimiento le guía por los pasos
para realizar esta operación con la consola de API Gateway.
Important
Después de realizar cualquiera de los procedimientos que aparecen a continuación, deberá
implementar o volver a implementar la API para propagar los cambios. Para obtener más
información acerca cómo implementar una API, consulte Implementación de una API de REST en
Amazon API Gateway (p. 510).

Para crear un autorizador COGNITO_USER_POOLS mediante la consola de API Gateway

1. Cree una nueva API o seleccione una existente en API Gateway.

2. En el panel de navegación principal, elija Authorizers (Autorizadores) en la API especificada.
3. En Authorizers (Autorizadores), seleccione Create New Authorizer (Crear nuevo autorizador).
4. Si desea configurar el nuevo autorizador para que utilice un grupo de usuarios, realice lo siguiente:

a. Escriba el nombre del autorizador en Name (Nombre).

b. Seleccione la opción Cognito.

325
 Amazon API Gateway Guía del desarrollador
Control de acceso

c. Elija una región en Cognito User Pool (Grupo de usuarios de Cognito).

d. Seleccione un grupo de usuarios disponible. Debe haber creado un grupo de usuarios para la
región seleccionada en Amazon Cognito para que este aparezca en la lista desplegable.
e. En Token source (Origen del token), escriba Authorization como nombre del encabezado al
que se va a pasar el token de identidad o acceso devuelto por Amazon Cognito cuando el usuario
inicie sesión correctamente.
f. Si lo desea, especifique una expresión regular en el campo Token validation (Validación de token)
para validar el campo aud (audiencia) del token de identidad antes de autorizar la solicitud con
Amazon Cognito. Tenga en cuenta que cuando se utiliza un token de acceso, esta validación
rechaza la solicitud debido al token de acceso que no contiene el campo aud.
g. Para terminar de integrar el grupo de usuarios con la API, seleccione Create (Crear).
5. Después de crear el autorizador de COGNITO_USER_POOLS, si lo desea, puede realizar una prueba
e invocarlo proporcionando un token de identidad aprovisionado desde el grupo de usuarios. Puede
obtener este token de identidad llamando al SDK de identidad de Amazon Cognito para realizar
el inicio de sesión del usuario. Asegúrese de utilizar el token de identidad devuelto, no el token de
acceso.

El procedimiento anterior crea un autorizador COGNITO_USER_POOLS que utiliza el grupo de usuarios

de Amazon Cognito que acaba de crearse. En función del modo en que se habilite el autorizador en un
método de la API, puede utilizar un token de identidad o un token de acceso aprovisionado desde el grupo
de usuarios integrados. En el siguiente procedimiento, se describen los pasos necesarios para configurar
el autorizador en un método de la API.

Para configurar un autorizador de COGNITO_USER_POOLS en los métodos

1. Elija (o cree) un método en la API.

2. Elija Method Request (Solicitud de método).
3. En Settings (Configuración), haga clic en el icono de lápiz que se encuentra junto a Authorization
(Autorización).
4. Elija uno de los Amazon Cognito user pool authorizers (Autorizadores de grupos de usuarios de
Amazon Cognito) disponibles en la lista desplegable.
5. Para guardar la configuración, seleccione el icono de marca de verificación.
6. Para utilizar un token de identidad, haga lo siguiente:

a. Deje la opción OAuth Scopes (Ámbitos de OAuth) sin especificar (como NONE).
b. Si fuera necesario, seleccione Integration Request (Solicitud de integración) para
agregar las expresiones $context.authorizer.claims['property-name'] o
$context.authorizer.claims.property-name a una plantilla de asignación de cuerpo y
pasar la propiedad especificada de las reclamaciones de identidad desde el grupo de usuarios
al backend. En el caso de los nombres de propiedades sencillos, como sub o custom-sub,
las dos notaciones son idénticas. En el caso de los nombres de propiedades complejos, como
custom:role, no se puede usar la notación de puntos. Por ejemplo, las siguientes expresiones
de asignación pasan los campos estándar sub y email de la reclamación al backend:

{
"context" : {
"sub" : "$context.authorizer.claims.sub",
"email" : "$context.authorizer.claims.email"
}
}

Si declaró un campo de reclamación personalizado al configurar un grupo de usuarios, puede

seguir el mismo patrón para obtener acceso a los campos personalizados. El siguiente ejemplo
obtiene un campo role personalizado de una reclamación:

326
 Amazon API Gateway Guía del desarrollador
Control de acceso

{
"context" : {
"role" : "$context.authorizer.claims.role"
}
}

Si el campo personalizado de la reclamación está declarado como custom:role, utilice el

siguiente ejemplo para obtener la propiedad de la reclamación:

{
"context" : {
"role" : "$context.authorizer.claims['custom:role']"
}
}

7. Para utilizar un token de acceso, haga lo siguiente:

a. Seleccione el icono con forma de lápiz situado junto a OAuth Scopes (Ámbitos de OAuth).
b. Escriba uno o varios nombres completos de un ámbito que se haya configurado cuando creó
el grupo de usuarios de Amazon Cognito. Por ejemplo, siguiendo el ejemplo de Creación de
un grupo de usuarios de Amazon Cognito para una API REST (p. 324), uno de los ámbitos
es com.hamuta.movies/drama.view. Utilice solamente un espacio para separar diferentes
ámbitos.

En tiempo de ejecución, la llamada al método se realiza correctamente si el ámbito especificado

en el método durante este paso coincide con el ámbito solicitado en el token de entrada. De lo
contrario, la solicitud envía una respuesta de error 401 Unauthorized.
c. Para guardar la configuración, seleccione el icono de marca de verificación.
8. Repita estos pasos con otros métodos que elija.

Con el autorizador COGNITO_USER_POOLS, si la opción OAuth Scopes no está especificada, API Gateway
trata el token proporcionado como un token de identidad y comprueba si la identidad solicitada se
corresponde con alguna del grupo de usuarios. De lo contrario, API Gateway trata el token suministrado
como un token de acceso y comprueba si los ámbitos de acceso solicitados en el token tienen
coincidencias con los ámbitos de autorización declarados en el método.

En lugar de utilizar la consola de API Gateway, también puede habilitar un grupo de usuarios de Amazon
Cognito en un método especificando un archivo de definición de OpenAPI e importando la definición de la
API en API Gateway.

Para importar un autorizador COGNITO_USER_POOLS con un archivo de definición de OpenAPI

1. Cree (o exporte) un archivo de definición de OpenAPI para la API.

2. Especifique la definición JSON del autorizador COGNITO_USER_POOLS (MyUserPool) en la sección
securitySchemes de OpenAPI 3.0 o en la sección securityDefinitions de Open API 2.0, tal
como se indica a continuación:

OpenAPI 3.0

"securitySchemes": {
"MyUserPool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {

327
 Amazon API Gateway Guía del desarrollador
Control de acceso

"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}"
]
}
}

OpenAPI 2.0

"securityDefinitions": {
"MyUserPool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}"
]
}
}

3. Para utilizar el token de identidad en la autorización del método, agregue { "MyUserPool": [] }

a la definición security del método, tal y como se muestra en el siguiente método GET del recurso
raíz.

"paths": {
"/": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"text/html"
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
}
},
"security": [
{
"MyUserPool": []
}
],
"x-amazon-apigateway-integration": {
"type": "mock",
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "'text/html'"
},
}
},
"requestTemplates": {
"application/json": "{\"statusCode\": 200}"

328
 Amazon API Gateway Guía del desarrollador
Control de acceso

},
"passthroughBehavior": "when_no_match"
}
},
...
}

4. Si desea utilizar el token de acceso para la autorización del método, cambie la definición de seguridad
anterior a { "MyUserPool": [resource-server/scope, ...] }:

"paths": {
"/": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"text/html"
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
}
},
"security": [
{
"MyUserPool": ["com.hamuta.movies/drama.view", "http://my.resource.com/
file.read"]
}
],
"x-amazon-apigateway-integration": {
"type": "mock",
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "'text/html'"
},
}
},
"requestTemplates": {
"application/json": "{\"statusCode\": 200}"
},
"passthroughBehavior": "when_no_match"
}
},
...
}

5. Si es necesario, puede establecer otra configuración de la API utilizando las definiciones o

extensiones de OpenAPI correspondientes. Para obtener más información, consulte Trabajar con
extensiones de API Gateway para OpenAPI (p. 771).

Llamar a una API REST integrada con un grupo de usuarios de Amazon Cognito
Para llamar a un método con un autorizador de grupo de usuarios configurado, el cliente debe hacer lo
siguiente:

329
 Amazon API Gateway Guía del desarrollador
Control de acceso

• Permitir al usuario inscribirse en el grupo de usuarios.

• Permitir al usuario iniciar sesión en el grupo de usuarios.
• Obtener un token de identidad del usuario conectado del grupo de usuarios.
• Incluir el token de identidad en el encabezado Authorization (u otro encabezado que haya
especificado al crear el autorizador).

Puede utilizar uno de los SDK de AWS para realizar estas tareas. Por ejemplo:

• Para utilizar el SDK de Android, consulte el tema sobre cómo configurar el AWS Mobile SDK para
Android para que funcione con grupos de usuarios.
• Para utilizar el SDK de iOS, consulte el tema sobre cómo configurar el AWS Mobile SDK para iOS para
que funcione con grupos de usuarios.
• Para utilizar JavaScript, consulte el tema sobre cómo configurar el AWS SDK para JavaScript en el
navegador para que funciones con grupos de usuarios.

El siguiente procedimiento describe los pasos necesarios para realizar estas tareas. Para obtener más
información, consulte las entradas de blog en Uso del SDK de Android con grupos de usuarios de Amazon
Cognito y Uso de grupos de usuarios de Amazon Cognito para iOS.

Para llamar a una API que esté integrada con un grupo de usuarios

1. Inscriba a un usuario nuevo en un grupo de usuarios especificado.

2. Inicie sesión al usuario en el grupo de usuarios.
3. Obtenga el token de identidad del usuario.
4. Llame a los métodos de API configurados con un autorizador de grupo de usuarios y proporcione un
token que no haya caducado en el encabezado Authorization o en otro encabezado que elija.
5. Cuando el token caduque, repita los pasos 2 a 4. Los tokens de identidad aprovisionados por Amazon
Cognito caducan en el plazo de una hora.

Para ver ejemplos de código, consulte un ejemplo de Java para Android y un ejemplo de Objective-C para
iOS.

Configuración de un autorizador de Amazon Cognito entre cuentas para una API

REST mediante la consola de API Gateway
Ahora también se puede utilizar un grupo de usuarios de Amazon Cognito de otra cuenta de AWS como
autorizador de API. Cada cuenta puede estar en cualquier región en la que Amazon API Gateway esté
disponible. El grupo de usuarios de Amazon Cognito puede utilizar estrategias de autenticación de token
al portador como OAuth o SAML. Esto permite administrar y compartir fácilmente de forma centralizada un
autorizador de grupo de usuarios de Amazon Cognito en distintas API de API Gateway.

En esta sección, mostramos cómo configurar un grupo de usuarios de Amazon Cognito entre cuentas
mediante la consola de Amazon API Gateway.

En estas instrucciones, se presupone que ya dispone de una API de API Gateway en una cuenta de AWS
y de un grupo de usuarios de Amazon Cognito en otra cuenta.

Configuración de un autorizador de Amazon Cognito entre cuentas mediante la consola de API

Gateway

Inicie sesión en la consola de Amazon API Gateway de la primera cuenta (la que tiene la API) y haga lo
siguiente:

1. Localice la API y elija Authorizers (Autorizadores).

330
 Amazon API Gateway Guía del desarrollador
Integraciones

2. Elija Create New Authorizer (Crear nuevo autorizador).

3. En Create Authorizer (Crear autorizador), escriba un nombre de autorizador en el campo de entrada
Name (Nombre).
4. En Type (Tipo), seleccione la opción Cognito.
5. En Cognito User Pool (Grupo de usuarios de Cognito), copie y pegue el ARN completo del grupo de
usuarios que tiene en su segunda cuenta.
Note

En la consola de Amazon Cognito, puede encontrar el ARN de su grupo de usuarios en el

campo Pool ARN (ARN de grupo) del panel General Settings (Configuración general).
6. Escriba el nombre de un encabezado en Token Source (Origen del token). El cliente de la API debe
incluir un encabezado con este nombre para enviar el token de autorización al autorizador de Amazon
Cognito.
7. Opcionalmente, proporcione una instrucción RegEx en el campo de entrada Token validation
(Validación de token). API Gateway realiza la validación inicial del token de entrada contra esta
expresión e invoca el autorizador tras una validación correcta. Esto ayuda a reducir la posibilidad de
que se cobre por tokens no válidos.
8. Elija Create (Crear) para crear el nuevo autorizador de Amazon Cognito para su API.

Configuración de integraciones de la API REST

Una vez configurado un método de API, debe integrarlo con un punto de enlace en el backend. El punto de
enlace del backend también se conoce como punto de enlace de integración y puede ser una función de
Lambda, una página web HTTP o una acción del servicio de AWS.

Al igual que con el método de API, la integración de la API tiene una solicitud de integración y una
respuesta de integración. La solicitud de integración incluye la solicitud HTTP que recibe el backend.
Podría ser distinta o no de la solicitud de método enviada por el cliente. La respuesta de integración es la
respuesta HTTP que encapsula la salida que devuelve el backend.

Configurar una solicitud de integración implica lo siguiente: configurar cómo transferir las solicitudes de
método enviadas por el cliente al backend; configurar cómo transformar los datos de la solicitud, si fuese
necesario, en los datos de la solicitud de integración; especificar qué función de Lambda se debe llamar,
especificar el servidor HTTP al que se debe reenviar la solicitud entrante o especificar la acción del servicio
de AWS que se debe invocar.

Configurar una respuesta de integración (aplicable únicamente a integraciones que no sean de proxy)
implica lo siguiente: configurar cómo transferir el resultado devuelto por el backend a una respuesta de
método de un determinado código de estado; configurar cómo transformar los parámetros de respuesta de
integración especificados en los parámetros de respuesta de método preconfigurados y configurar cómo
asignar el cuerpo de la respuesta de integración al cuerpo de la respuesta de método con arreglo a las
plantillas de mapeo de cuerpo especificadas.

Mediante programación, el recurso Integration encapsula la solicitud de integración y el recurso de API

Gateway IntegrationResponse, la respuesta de integración.

Para configurar una solicitud de integración, debe crear un recurso Integration y utilizarlo para
configurar la URL del punto de enlace de integración. A continuación, defina los permisos de IAM para
acceder al backend y especifique los mapeos para transformar los datos de la solicitud entrante antes de
transmitirlos al backend. Para configurar una respuesta de integración para una integración que no sea de
proxy, debe crear un recurso IntegrationResponse y utilizarlo para establecer su respuesta de método
de destino. A continuación, configure cómo asignar la salida del backend a la respuesta de método.

Temas

331
 Amazon API Gateway Guía del desarrollador
Integraciones

• Configuración de una solicitud de integración en API Gateway (p. 332)

• Configuración de una respuesta de integración en API Gateway (p. 339)
• Configuración de las integraciones de Lambda en API Gateway (p. 340)
• Configurar integraciones HTTP en API Gateway (p. 361)
• Configurar integraciones privadas de API Gateway (p. 366)
• Configurar integraciones simuladas en API Gateway (p. 373)

Configuración de una solicitud de integración en API Gateway

Para configurar una solicitud de integración, debe llevar a cabo las siguientes tareas obligatorias y
opcionales:

1. Elija un tipo de integración que determine cómo se transfieren los datos de la solicitud de método al
backend.
2. Para las integraciones no simuladas, especifique un método HTTP y la URI del punto de enlace de
integración específico, excepto para la integración MOCK.
3. Para integraciones con funciones de Lambda y otras acciones del servicio de AWS, establezca el rol de
IAM con los permisos necesarios para que API Gateway llame al backend en su nombre.
4. Para las integraciones que no sean de proxy, establezca el mapeo de parámetros necesario para
asignar los parámetros de la solicitud de método predefinidos a los parámetros de la solicitud de
integración adecuados.
5. Para las integraciones que no sean de proxy, establezca el mapeo de cuerpo necesario para asignar el
cuerpo de la solicitud de método entrante de un determinado tipo de contenido con arreglo a la plantilla
de mapeo especificada.
6. Para integraciones que no sean de proxy, especifique la condición bajo la cual los datos de la solicitud
de método entrante se transfieren al backend tal y como están.
7. También puede especificar cómo administrar la conversión de tipo para una carga binaria.
8. También puede indicar un nombre del espacio de nombres de la caché y los parámetros de caché clave
para habilitar el almacenamiento en caché de la API.

Estas tareas conllevan la creación de un recurso Integration de API Gateway y la definición de los valores
adecuados para las propiedades. Puede hacerlo con la consola de API Gateway, los comandos de la CLI
de AWS, un SDK de AWS o la API REST de API Gateway.

Temas
• Tareas básicas de una solicitud de integración de la API (p. 332)
• Elegir un tipo de integración de API de API Gateway (p. 334)
• Configuración de una integración de proxy con un recurso de proxy (p. 336)
• Configuración de una solicitud de integración de la API mediante la consola de API Gateway (p. 337)

Tareas básicas de una solicitud de integración de la API

Una solicitud de integración es una solicitud HTTP que envía API Gateway al backend, por la que se
transfieren los datos de solicitud enviados por el cliente y se transforman los datos, si fuese necesario.
El método HTTP (o verbo) y la URI de la solicitud de integración los dicta el backend (es decir, el punto
de enlace de la integración). Pueden ser iguales o distintos al método HTTP y la URI de la solicitud de
método, respectivamente.

Por ejemplo, cuando una función de Lambda devuelve un archivo que se recupera de Amazon S3,
puede exponer esta operación de forma intuitiva como una solicitud de método GET al cliente, aunque la

332
 Amazon API Gateway Guía del desarrollador
Integraciones

correspondiente solicitud de integración requiere que se utilice una solicitud POST para invocar la función
de Lambda. En el caso de los puntos de enlace HTTP, es probable que tanto la solicitud del método como
la correspondiente solicitud de integración utilicen el mismo verbo HTTP. Sin embargo, no es necesario.
Puede integrar la siguiente solicitud de método:

GET /{var}?query=value
Host: api.domain.net

Con la siguiente solicitud de integración:

POST /
Host: service.domain.com
Content-Type: application/json
Content-Length: ...

{
path: "{var}'s value",
type: "value"
}

Como desarrollador de la API, puede utilizar el verbo HTTP y la URI para la solicitud de método que mejor
se adapte a sus necesidades. Sin embargo, debe cumplir los requisitos del punto de enlace de integración.
Cuando los datos de la solicitud de método son distintos de los datos de la solicitud de integración, puede
solucionar esta diferencia asignando los datos de la solicitud de método a los datos de la solicitud de
integración.

En los ejemplos anteriores, el mapeo traduce los valores de la variable de ruta ({var}) y el parámetro de
consulta (query) de la solicitud de método GET en los valores de las propiedades de carga de la solicitud
de integración para path y type. Podrían asignarse otros datos de la solicitud, como los encabezados y el
cuerpo. Esto se describe en Configuración de mapeo de datos de solicitud y respuesta mediante la consola
de API Gateway (p. 401).

Al configurar la solicitud HTTP o de integración de proxy HTTP, asigne la URL del punto de enlace HTTP
del backend como el valor de la URI de la solicitud de integración. Por ejemplo, en la API de PetStore,
la solicitud de método para obtener una página de mascotas tiene la siguiente URI de la solicitud de
integración:

http://petstore-demo-endpoint.execute-api.com/petstore/pets

Al configurar la integración de Lambda o de proxy de Lambda asigne el nombre de recurso de Amazon

(ARN) para invocar la función de Lambda como el valor de la URI de la solicitud de integración. El ARN
tiene el siguiente formato:

arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-
region:account-id:function:lambda-function-name/invocations

La parte que aparece después de arn:aws:apigateway:api-region:lambda:path/, es decir,

/2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-
function-name/invocations, corresponde a la ruta de URI de la API REST de la acción de Lambda
Invoke. Si utiliza la consola de API Gateway para configurar la integración de Lambda, API Gateway crea
el ARN y lo asigna a la URI de integración después de que se le solicite que elija el lambda-function-
name de una región.

Cuando se configura la solicitud de integración con otra acción del servicio de AWS, la URI de la solicitud
de integración también es un ARN, de modo similar a la integración con la acción de Lambda Invoke.

333
 Amazon API Gateway Guía del desarrollador
Integraciones

Por ejemplo, en el caso de la integración con la acción GetBucket de Amazon S3, la URI de la solicitud de
integración es un ARN con el siguiente formato:

arn:aws:apigateway:api-region:s3:path/{bucket}

La URI de la solicitud de integración utiliza la convención de ruta para especificar la acción, donde
{bucket} es el marcador de posición de un nombre de bucket. También se puede hacer referencia a una
acción del servicio de AWS por su nombre. Si se utiliza el nombre de la acción, la URI de la solicitud de
integración para la acción GetBucket de Amazon S3 se convierte en lo siguiente:

arn:aws:apigateway:api-region:s3:action/GetBucket

Con la URI de la solicitud de integración basada en la acción, el nombre del bucket ({bucket}) se debe
especificar en el cuerpo de la solicitud de integración ({ Bucket: "{bucket}" }), siguiendo el formato
de entrada de la acción GetBucket.

Para las integraciones de AWS, también debe configurar las credenciales para permitir que API Gateway
llame a las acciones integradas. Puede crear uno nuevo o bien elegir un rol de IAM existente para que
API Gateway llame a la acción y, a continuación, especificar el rol mediante su ARN. A continuación se
muestra un ejemplo de este ARN:

arn:aws:iam::account-id:role/iam-role-name

Este rol de IAM debe contener una política para permitir que se ejecute la acción. También se debe haber
declarado API Gateway (en la relación de confianza del rol) como una entidad de confianza para asumir
el rol. Estos permisos se pueden conceder en la propia acción. Se conocen como permisos basados en
recursos. Para la integración de Lambda, puede llamar a la acción addPermission de Lambda para definir
los permisos basados en recursos y, a continuación, establecer credentials en null en la solicitud de
integración de API Gateway.

Hemos analizado los aspectos básicos de la configuración de la integración. La configuración avanzada

implica la asignación de los datos de la solicitud de método a los datos de la solicitud de integración.
Después de analizar la configuración básica de una respuesta de integración, examinamos los temas
avanzados en Configuración de mapeo de datos de solicitud y respuesta mediante la consola de
API Gateway (p. 401), donde también vemos la transferencia de la carga y la administración de las
codificaciones de contenido.

Elegir un tipo de integración de API de API Gateway

El tipo de integración de la API se selecciona con arreglo a los tipos de punto de enlace de integración
con los que trabaje y al modo en que desea transferir los datos hacia y desde el punto de enlace de
integración. Para una función de Lambda, puede tener la integración de proxy de Lambda o la integración
personalizada de Lambda. Para un punto de enlace HTTP, puede elegir entre la integración de proxy
HTTP o una integración HTTP personalizada. Para una acción del servicio de AWS, dispone de la
integración de AWS solo para el tipo que no sea proxy. API Gateway también admite la integración
simulada, donde API Gateway actúa como punto de enlace de integración para responder a una solicitud
de método.

La integración de Lambda personalizada es un caso especial de la integración de AWS, donde el punto de

enlace de integración se corresponde con la acción que invoca las funciones del servicio de Lambda.

Mediante programación, puede seleccionar un tipo de integración configurando la propiedad type

en el recurso Integration. Para la integración de proxy de Lambda, el valor es AWS_PROXY. Para
la integración de Lambda personalizada y el resto de integraciones de AWS, el valor es AWS. Para la

334
 Amazon API Gateway Guía del desarrollador
Integraciones

integración de proxy HTTP y la integración HTTP, el valor es HTTP_PROXY y HTTP, respectivamente. Para
la integración simulada, el valor type es MOCK.

La integración de proxy de Lambda admite una configuración de integración simplificada con una única
función de Lambda. La configuración es sencilla y puede evolucionar con el backend sin tener que eliminar
la configuración existente. Por estas razones, es muy recomendable para la integración con una función de
Lambda.

En cambio, la integración de Lambda personalizada permite la reutilización de las plantillas de mapeo

configuradas para varios puntos de enlace de integración con requisitos similares sobre el formato de
los datos de entrada y salida. Esta configuración es más compleja y se recomienda para situaciones de
aplicación más avanzadas.

Del mismo modo, la integración de proxy HTTP tiene una configuración de integración simplificada y
puede evolucionar con el backend sin tener que eliminar la configuración existente. La integración HTTP
personalizada resulta más compleja de configurar, pero permite la reutilización de las plantillas de mapeo
configuradas para otros puntos de enlace de integración.

En la siguiente lista se resumen los tipos de integración admitidos:

• AWS: este tipo de integración permite a una API exponer acciones del servicio de AWS. En la integración
de AWS, debe configurar tanto la solicitud de integración como la respuesta de integración y también
configurar el mapeo necesario de los datos entre la solicitud de método y la solicitud de integración, y
entre la respuesta de integración y la respuesta de método.
• AWS_PROXY: este tipo de integración permite que se integre un método de la API con la acción de
invocación de la función de Lambda a través de una configuración de integración flexible, versátil y
simplificada. Esta integración se basa en las interacciones directas entre el cliente y la función de
Lambda integrada.

Con este tipo de integración, que también se conoce como integración de proxy de Lambda, no
tiene que establecer la solicitud de integración ni la respuesta de integración. API Gateway transmite
la solicitud entrante del cliente, como entrada, a la función de Lambda del backend. La función de
Lambda integrada toma la entrada de este formato (p. 348) y analiza la entrada de todos los orígenes
disponibles, incluidos los encabezados de solicitudes, las variables de ruta de la URL, los parámetros de
cadena de consulta y el cuerpo aplicable. Esta función devuelve un resultado con el siguiente formato de
salida (p. 351).

Este es el tipo de integración recomendable para llamar a la función de Lambda a través de API
Gateway y no es aplicable a ninguna otra acción del servicio de AWS, incluidas las acciones Lambda
que no sean la acción que invoca las funciones.
• HTTP: este tipo de integración permite que una API exponga puntos de enlace de HTTP en el backend.
Con la integración HTTP, que también se conoce como integración HTTP personalizada, debe configurar
tanto la solicitud de integración como la respuesta de integración. Debe establecer la asignación
necesaria de los datos entre la solicitud de método y la solicitud de integración, y entre la respuesta de
integración y la respuesta de método.
• HTTP_PROXY: La integración de proxy HTTP permite que un cliente tenga acceso a puntos de enlace
HTTP de backend con una configuración de la integración simplificada en un único método de API.
No tiene que establecer la solicitud de integración ni la respuesta de integración. API Gateway pasa la
solicitud entrante del cliente al punto de enlace HTTP y pasa la respuesta saliente del punto de enlace
HTTP al cliente.
• MOCK: este tipo de integración permite que API Gateway devuelva una respuesta sin enviar la solicitud
al backend. Esto es útil en las pruebas de la API, ya que se puede utilizar para probar la configuración
de la integración sin incurrir en cargos por utilizar el backend y para permitir el desarrollo colaborativo de
una API.

En el desarrollo colaborativo, un equipo puede aislar sus esfuerzos de desarrollo configurando

simulaciones de los componentes de la API que son propiedad de otros equipos mediante el uso

335
 Amazon API Gateway Guía del desarrollador
Integraciones

de integraciones MOCK. También se utiliza para devolver encabezados relacionados con CORS y
garantizar que el método de API permita el acceso a CORS. De hecho, la consola de API Gateway
integra el método OPTIONS para admitir CORS con una integración simulada. Las respuestas de
gateway (p. 438) son otros ejemplos de integraciones simuladas.

Configuración de una integración de proxy con un recurso de proxy

Para configurar una integración de proxy en una API de API Gateway con un recurso de proxy (p. 259),
realice las tareas siguientes:

• Crear un recurso de proxy con la variable de ruta expansiva {proxy+}

• Establecer el método ANY en el recurso de proxy
• Integrar el recurso y el método con un backend mediante el tipo de integración HTTP o Lambda.

Note

Las variables de ruta expansiva, los métodos ANY y los tipos de integración de proxy son
características independientes, aunque se utilizan normalmente juntas. Puede configurar un
método HTTP específico en un recurso expansivo o aplicar tipos de integración distintos de proxy
en un recurso de proxy.

API Gateway establece determinadas restricciones y limitaciones al manipular métodos con una
integración de proxy de Lambda o una integración de proxy HTTP. Para obtener más información, consulte
the section called “Notas importantes” (p. 847).
Note

Cuando se utiliza la integración de proxy con acceso directo, API Gateway devuelve el
encabezado predeterminado Content-Type:application/json si no se especifica el tipo de
contenido de una carga.

Un recurso de proxy es más eficaz cuando se integra con un backend que usa la integración de proxy
HTTP o la integración de proxy de Lambda.

Integración de proxy HTTP con un recurso de proxy

La integración de proxy HTTP, designada por HTTP_PROXY en la API REST de API Gateway, es para
la integración de una solicitud de método con un punto de enlace HTTP del backend. Con este tipo de
integración, API Gateway simplemente transmite toda la solicitud y la respuesta entre el frontend y el
backend, aunque esto está sujeto a determinadas restricciones y limitaciones (p. 847).
Note

La integración de proxy HTTP admite encabezados y cadenas de consulta con varios valores.

Cuando aplica la integración de proxy HTTP a un recurso de proxy, puede configurar la API para que
exponga una parte o la totalidad de la jerarquía del punto de enlace del backend HTTP con una sola
integración configurada. Supongamos, por ejemplo, que el backend del sitio web está organizado en varias
ramas de nodos de árbol desde el nodo raíz (/site) como: /site/a0/a1/.../aN, /site/b0/b1/.../
bM, etc. Si integra el método ANY en un recurso de proxy de /api/{proxy+} con los puntos de enlace
del backend con rutas URL de /site/{proxy}, una sola solicitud de integración puede admitir todas las
operaciones HTTP (GET, POST, etc.) en cualquiera de [a0, a1, ..., aN, b0, b1, ...bM, ...]. Si
aplica una integración de proxy a un método HTTP específico (por ejemplo, GET), en su lugar, la solicitud
de integración resultante funcionará con las operaciones especificadas (es decir, GET) en cualquiera de los
nodos del backend.

336
 Amazon API Gateway Guía del desarrollador
Integraciones

Integración de proxy de Lambda con un recurso de proxy

La integración de proxy de Lambda, designada por AWS_PROXY en la API REST de API Gateway, es para
la integración de una solicitud de método con una función de Lambda en el backend. Con este tipo de
integración, API Gateway aplica una plantilla de mapeo predeterminada para enviar toda la solicitud a la
función de Lambda y transforma la salida de la función de Lambda en respuestas HTTP.

Del mismo modo, puede aplicar la integración de proxy de Lambda a un recurso proxy de /api/{proxy
+} para configurar una sola integración, si desea que la función de Lambda del backend reaccione
individualmente a los cambios que se produzcan en cualquiera de los recursos de la API bajo /api.

Configuración de una solicitud de integración de la API mediante la consola de

API Gateway
La configuración de un método de API define el método y describe sus comportamientos. Para configurar
un método, debe especificar un recurso, incluida la raíz ("/"), en el que se expone el método, un método
HTTP (GET, POST, etc.) y la forma en que se integrará con el backend de destino. La solicitud y la
respuesta del método especifican el contrato con la aplicación que realiza la llamada, que estipula los
parámetros que puede recibir la API y el aspecto que tendrá la respuesta.

El siguiente procedimiento describe cómo utilizar la consola de API Gateway para especificar la
configuración de un método.

1. En el panel de navegación Resources (Recursos), elija el método.

2. En el panel Method Execution (Ejecución del método), elija Integration Request (Solicitud de
integración). En Integration type (Tipo de integración), seleccione una de las siguientes opciones:

• Elija Lambda Function (Función de Lambda) si la API se va a integrarse con una función de
Lambda. En el nivel de API, este es un tipo de integración AWS.
• Elija HTTP si la API se va a integrar con un punto de enlace HTTP. En el nivel de API, este es el tipo
de integración HTTP.
• Elija AWS Service (Servicio de AWS) si la API se va a integrar directamente con un servicio de
AWS. En el nivel de API, este es el tipo de integración AWS. La opción Lambda Function (Función de
Lambda) anterior es un caso especial de la integración de AWS para invocar una función de Lambda
y solo está disponible en la consola de API Gateway. Para configurar una API de API Gateway
para crear una nueva función de Lambda en AWS Lambda, establecer un permiso de recurso en
la función de Lambda o realizar cualquier otra acción de servicio de Lambda, debe elegir aquí la
opción AWS Service (Servicio de AWS) .
• Elija Mock (Simulación) si desea que API Gateway actúe como backend y devuelva respuestas
estáticas. En el nivel de API, este es el tipo de integración MOCK. Normalmente, puede usar la
integración MOCK si la API aún no es definitiva, pero desea generar respuestas de API para permitir
que los equipos dependientes realicen pruebas. En el método OPTION, API Gateway establece la
integración MOCK como predeterminada para devolver encabezados que habilitan CORS para el
recurso de la API que se aplicó. Si elige esta opción, omita el resto de las instrucciones de este
tema y consulte Configurar integraciones simuladas en API Gateway (p. 373).
3. Si ha elegido Lambda Function (Función de Lambda), proceda de la forma siguiente:

a. En Lambda Region (Región de Lambda), elija el identificador de región correspondiente a la

región en la que ha creado la función de Lambda. Por ejemplo, si creó la función de Lambda en
la región EE. UU. Este (Norte de Virginia), elija us-east-1. Para ver una lista de nombres e
identificadores de regiones, consulte AWS Lambda en la Referencia general de Amazon Web
Services.
b. En Lambda Function (Función de Lambda), escriba el nombre de la función de Lambda y, a
continuación, elija el ARN correspondiente de la función.
c. Elija Save (Guardar).
4. Si ha elegido HTTP, proceda de la forma siguiente:

337
 Amazon API Gateway Guía del desarrollador
Integraciones

a. En HTTP method (Método HTTP), elija el tipo de método HTTP que más se parezca al método del
backend HTTP.
b. En Endpoint URL (URL del punto de enlace), escriba la dirección URL del backend HTTP que
desea que utilice este método.
c. Seleccione Save.
5. Si ha elegido Mock (Simulación), proceda de la forma siguiente:

• Elija Save (Guardar).

6. Si ha elegido AWS Service (Servicio de AWS), proceda de la forma siguiente:

a. En AWS Region (Región de AWS), elija la región de AWS que desea que utilice este método para
llamar a la acción.
b. En AWS Service (Servicio de AWS), elija el servicio de AWS al que desea que llame este método.
c. En AWS Subdomain (Subdominio de AWS), escriba el subdominio que utilice el servicio de AWS.
Normalmente, puede dejarlo en blanco. Algunos servicios de AWS admiten subdominios como
parte de los hosts. En la documentación del servicio encontrará la disponibilidad y los detalles, si
están disponibles.
d. En HTTP method (Método HTTP), seleccione el tipo de método HTTP correspondiente a
la acción. Para el tipo de método HTTP, consulte la documentación de referencia de la API
correspondiente al servicio de AWS que eligió en AWS Service (Servicio de AWS).
e. En Action (Acción), escriba la acción que desea utilizar. Para ver una lista de las acciones
disponibles, consulte la documentación de referencia de la API correspondiente al servicio de
AWS que eligió en AWS Service (Servicio de AWS).
f. En Execution Role (Rol de ejecución), escriba el ARN del rol de IAM que usará el método para
llamar a la acción.

Para crear el rol de IAM, puede adaptar las instrucciones de "Para crear el rol de invocación de
Lambda y sus políticas" y "Para crear el rol de ejecución de Lambda y sus políticas" de la sección
Crear funciones de Lambda (p. 34). Especifique una política de acceso con el siguiente formato y
con el número de acciones e instrucciones de recursos que desee:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"action-statement"
],
"Resource": [
"resource-statement"
]
},
...
]
}

Para ver la sintaxis de las acciones e instrucciones de recursos, consulte la documentación del
servicio de AWS que eligió en AWS Service (Servicio de AWS).

Para la relación de confianza del rol de IAM, especifique lo siguiente, que permite a API Gateway
realizar una acción en nombre de su cuenta de AWS:

{
"Version": "2012-10-17",
"Statement": [

338
 Amazon API Gateway Guía del desarrollador
Integraciones

{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}

g. Si la acción que especificó para Action (Acción) proporciona una ruta de recurso personalizada
que desea que utilice este método, en Path Override (Invalidación de ruta), escriba esta ruta.
Para la ruta de recurso personalizada, consulte la documentación de referencia de la API
correspondiente al servicio de AWS que eligió en AWS Service (Servicio de AWS).
h. Elija Save (Guardar).

Configuración de una respuesta de integración en API Gateway

Para una integración que no sea de proxy, debe configurar al menos una respuesta de integración, y
convertirla en la respuesta predeterminada, para pasar el resultado que devuelve el backend al cliente.
Puede optar por pasar el resultado como está o transformar los datos de la respuesta de integración en los
datos de la respuesta de método si ambos tienen formatos diferentes.

Para una integración de proxy, API Gateway pasa automáticamente la salida del backend al cliente como
una respuesta HTTP. No debe configurar la respuesta de integración ni la respuesta del método.

Para configurar una respuesta de integración, debe llevar a cabo las siguientes tareas obligatorias y
opcionales:

1. Especifique el código de estado HTTP de la respuesta del método a la que se asignan los datos de la
respuesta de integración. Esto es necesario.
2. Defina una expresión regular para seleccionar que la salida del backend esté representada por esta
respuesta de integración. Si lo deja vacío, la respuesta será la respuesta predeterminada que se utiliza
para detectar las respuestas que no se hayan configurado aún.
3. Si es necesario, declare mapeos compuestos de pares de clave-valor para asignar los parámetros de la
respuesta de integración especificados a los parámetros de una respuesta de método determinada.
4. Si es necesario, añada plantillas de mapeo de cuerpo para transformar las cargas de una respuesta de
integración determinada en las cargas de la respuesta de método especificada.
5. Si es necesario, especifique cómo administrar la conversión de tipo para una carga binaria.

Una respuesta de integración es una respuesta HTTP que encapsula la respuesta del backend. Para
un punto de enlace HTTP, la respuesta del backend es una respuesta HTTP. El código de estado de
la respuesta de integración puede tomar el código de estado que devuelve el backend, y el cuerpo de
la respuesta de integración es la carga que devuelve el backend. Para un punto de enlace Lambda, la
respuesta del backend es la salida que devuelve la función de Lambda. Con la integración de Lambda,
la salida de la función de Lambda se devuelve como una respuesta 200 OK. La carga puede contener
el resultado como datos JSON, incluida una cadena JSON o un objeto JSON, o un mensaje de error
como un objeto JSON. Puede asignar una expresión regular a la propiedad selectionPattern para asignar
una respuesta de error a la respuesta de error HTTP adecuada. Para obtener más información acerca
de la respuesta de error de una función de Lambda, consulte Gestionar los errores de Lambda en API
Gateway (p. 357). Con la integración de proxy de Lambda, la función de Lambda debe devolver una
salida con el siguiente formato:

{
statusCode: "...", // a valid HTTP status code
headers: {

339
 Amazon API Gateway Guía del desarrollador
Integraciones

custom-header: "..." // any API-specific custom header

},
body: "...", // a JSON string.
isBase64Encoded: true|false // for binary support
}

No es necesario asignar la respuesta de la función de Lambda a su respuesta HTTP adecuada.

Para devolver el resultado al cliente, configure la respuesta de integración para pasar la respuesta del
punto de enlace como está a la correspondiente respuesta de método. También puede asignar los datos
de la respuesta del punto de enlace a los datos de la respuesta de método. Entre los datos de respuesta
que se pueden asignar se incluyen el código de estado de la respuesta, los parámetros de encabezado de
la respuesta y el cuerpo de la respuesta. Si no se define ninguna respuesta de método para el código de
estado devuelto, API Gateway devuelve un error 500. Para obtener más información, consulte Trabajo con
modelos y plantillas de asignación (p. 395).

Configuración de las integraciones de Lambda en API Gateway

Puede integrar un método de API con una función de Lambda mediante la integración de proxy de Lambda
o la integración de Lambda que no sea de proxy (personalizada).

En la integración de proxy de Lambda, la configuración es sencilla. Si la API no requiere la codificación

de contenido o el almacenamiento en caché, solo tiene que establecer el método HTTP de integración en
POST, la URI del punto de enlace de integración en el ARN de la acción de invocación de la función de
Lambda de una función de Lambda específica y la credencial en el rol de IAM con permisos para permitir
que API Gateway llame a la función de Lambda en su nombre.

En la integración de Lambda que no sea de proxy, además de los pasos de configuración de integración
de proxy, también debe especificar cómo se asignan los datos entrantes a la solicitud de integración y
cómo se asignan los datos resultantes de respuesta de la integración a la respuesta de método.

Temas
• Configuración de las integraciones de proxy de Lambda en API Gateway (p. 340)
• Configuración de integraciones de Lambda personalizadas en API Gateway (p. 353)
• Configurar la invocación asíncrona de la función de Lambda de backend (p. 356)
• Gestionar los errores de Lambda en API Gateway (p. 357)

Configuración de las integraciones de proxy de Lambda en API Gateway

Temas
• Descripción de la integración de proxy de Lambda en API Gateway (p. 340)
• Compatibilidad con encabezados de varios valores y parámetros de cadenas de consulta (p. 342)
• Configuración de un recurso de proxy con la integración de proxy de Lambda (p. 342)
• Configuración de una integración de proxy de Lambda mediante la CLI de AWS (p. 344)
• Formato de entrada de una función de Lambda para la integración de proxy (p. 348)
• Formato de salida de una función de Lambda para la integración de proxy (p. 351)

Descripción de la integración de proxy de Lambda en API Gateway

La integración de proxy de Lambda de Amazon API Gateway es un mecanismo sencillo, potente y ágil para
desarrollar una API con la configuración de un solo método de API. La integración de proxy de Lambda
permite al cliente llamar a una única función de Lambda en el backend. La función obtiene acceso a
muchos recursos o características de otros servicios de AWS, incluidas las llamadas a otras funciones
Lambda.

340
 Amazon API Gateway Guía del desarrollador
Integraciones

En la integración de proxy de Lambda, cuando un cliente envía una solicitud de API, API Gateway pasa
a la función de Lambda integrada la solicitud sin procesar tal y como está, salvo que no se conserve el
orden de los parámetros de la solicitud. Estos datos de la solicitud (p. 348) incluyen los encabezados
de solicitud, los parámetros de cadena de consulta, las variables de ruta de la URL, la carga y los
datos de configuración de la API. Los datos de configuración pueden incluir el nombre de la etapa de
implementación actual, las variables de la etapa, la identidad del usuario o el contexto de autorización (si
lo hubiera). La función de Lambda del backend analiza los datos de la solicitud entrante para determinar
la respuesta que devuelve. Para que API Gateway transmita la salida de Lambda como la respuesta de la
API al cliente, la función de Lambda debe devolver el resultado en este formato (p. 351).

Dado que API Gateway no interviene mucho entre el cliente y la función de Lambda del backend para
la integración de proxy de Lambda, el cliente y la función de Lambda integrada pueden adaptarse a los
cambios de cada uno sin interrumpir la configuración de integración existente de la API. Para habilitar esto,
el cliente debe seguir los protocolos de aplicación promulgados por la función de Lambda del backend.

Puede configurar una integración de proxy de Lambda para cualquier método de API. Sin embargo,
una integración de proxy de Lambda es más potente cuando se configura para un método de API que
implica un recurso de proxy genérico. El recurso de proxy genérico se puede indicar mediante una variable
especial de ruta basada en plantilla de {proxy+}, el marcador de posición del método catch-all ANY o
ambos. El cliente puede transmitir la entrada a la función de Lambda del backend en la solicitud entrante
según lo soliciten los parámetros o la carga aplicable. Los parámetros de solicitud incluyen encabezados,
variables de ruta de la URL, parámetros de cadenas de consulta y la carga aplicable. La función de
Lambda integrada verifica todas las fuentes de entrada antes de procesar la solicitud y de responder al
cliente con mensajes de error importantes si falta alguna de las entradas requeridas.

Al llamar a un método de API integrado con el método HTTP genérico de ANY y el recurso genérico de
{proxy+}, el cliente envía una solicitud con un método HTTP específico en lugar de ANY. El cliente
también especifica una ruta de URL específica en lugar de {proxy+} e incluye cualquier encabezado,
parámetro de cadena de consulta o una carga aplicable.

En la siguiente lista se resumen los comportamientos de tiempo de ejecución de los diferentes métodos de
API con la integración de proxy de Lambda:

• ANY /{proxy+}: el cliente debe elegir un método HTTP específico, debe establecer una jerarquía de
ruta de recursos específica y puede establecer cualquier encabezado, parámetro de cadena de consulta
y carga aplicable para transmitir los datos como entrada a la función de Lambda integrada.
• ANY /res: el cliente debe elegir un método HTTP específico y puede establecer cualquier encabezado,
parámetro de cadena de consulta y carga aplicable para transmitir los datos como entrada a la función
de Lambda integrada.
• GET|POST|PUT|... /{proxy+}: el cliente puede establecer una jerarquía de ruta de recursos
específica, cualquier encabezado, parámetro de cadena de consulta y carga aplicable para transmitir los
datos como entrada a la función de Lambda integrada.
• GET|POST|PUT|... /res/{path}/...: el cliente debe elegir un segmento de ruta específico (para
la variable {path}) y puede establecer cualquier encabezado de solicitud, parámetro de cadena de
consulta y carga aplicable para transmitir los datos de entrada a la función de Lambda integrada.
• GET|POST|PUT|... /res: el cliente puede elegir cualquier encabezado de solicitud, parámetro
de cadena de consulta y carga aplicable para transmitir los datos de entrada a la función de Lambda
integrada.

Tanto el recurso de proxy de {proxy+} como el recurso personalizado de {custom} se expresan como
variables de ruta basada en plantilla. Sin embargo, {proxy+} puede hacer referencia a cualquier recurso
en una jerarquía de ruta, mientras que {custom} se refiere únicamente a un segmento de ruta específico.
Por ejemplo, una tienda de comestibles podría organizar un inventario de productos en línea por nombres
de departamento, categorías de productos y tipos de productos. El sitio web de la tienda de comestibles
puede entonces representar los productos disponibles con las siguientes variables de ruta basada en
plantilla para los recursos personalizados: /{department}/{produce-category}/{product-type}.
Por ejemplo, las manzanas están representadas con /produce/fruit/apple y las zanahorias con

341
 Amazon API Gateway Guía del desarrollador
Integraciones

/produce/vegetables/carrot. También puede utilizar /{proxy+} para representar a cualquier

departamento, cualquier categoría de producto o cualquier tipo de producto que un cliente puede buscar
mientras realiza sus compras en la tienda en línea. Por ejemplo, /{proxy+} puede hacer referencia a
cualquiera de los siguientes elementos:

• /produce
• /produce/fruit
• /produce/vegetables/carrot

Para que los clientes puedan buscar cualquier producto disponible, su categoría de producto y el
departamento asociado en la tienda, puede exponer un único método de GET /{proxy+} con permisos
de solo lectura. Del mismo modo, para permitir que un supervisor actualice el inventario del departamento
produce, puede configurar otro método único de PUT /produce/{proxy+} con permisos de lectura
y escritura. Para permitir que un cajero actualice el total de unidades de una verdura, puede configurar
un método POST /produce/vegetables/{proxy+} con permisos de lectura y escritura. Para que
el gerente de una tienda pueda realizar cualquier acción posible en cualquier producto disponible, el
desarrollador de la tienda en línea puede exponer el método ANY /{proxy+} con permisos de lectura
y escritura. En cualquier caso, en el tiempo de ejecución, el cliente o el empleado debe seleccionar un
producto específico de un tipo determinado en un departamento elegido o en un departamento específico.

Para obtener más información acerca de la configuración de las integraciones del proxy de API Gateway,
consulte Configuración de una integración de proxy con un recurso de proxy (p. 336).

La integración del proxy requiere que el cliente tenga un conocimiento más detallado de los requisitos del
backend. Por lo tanto, para garantizar un óptimo rendimiento de la aplicación y experiencia del usuario,
el desarrollador del backend debe comunicar con claridad al desarrollador del cliente los requisitos del
backend y proporcionar un mecanismo de comentarios de errores sólido cuando los requisitos no se
cumplan.

Compatibilidad con encabezados de varios valores y parámetros de cadenas de consulta

API Gateway ahora es compatible con varios encabezados y parámetros de cadena de consulta que
tengan el mismo nombre. Los encabezados de varios valores y los encabezados y parámetros de un solo
valor se pueden combinar en las mismas solicitudes y respuestas. Para obtener más información, consulte
Formato de entrada de una función de Lambda para la integración de proxy (p. 348) y Formato de salida
de una función de Lambda para la integración de proxy (p. 351).

Configuración de un recurso de proxy con la integración de proxy de Lambda

Para configurar un recurso de proxy con el tipo de integración de proxy de Lambda, cree un
recurso de API con un parámetro de ruta expansiva (por ejemplo, /parent/{proxy+}) e
integre este recurso con un backend de funciones Lambda (por ejemplo, arn:aws:lambda:us-
west-2:123456789012:function:SimpleLambda4ProxyResource) en el método ANY. El
parámetro de ruta expansiva debe estar al final de la ruta del recurso de la API. Al igual que con un recurso
que no es de proxy, puede configurar el recurso de proxy mediante la consola de API Gateway importando
un archivo de definición de OpenAPI o llamando directamente a la API REST de API Gateway.

El siguiente archivo de definición de API de OpenAPI muestra un ejemplo de una API con un recurso de
proxy que se integra con la función de Lambda denominada SimpleLambda4ProxyResource.

OpenAPI 3.0

{
"openapi": "3.0.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},

342
 Amazon API Gateway Guía del desarrollador
Integraciones

"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/
arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
},
"servers": [
{
"url": "https://gy415nuibc.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/testStage"
}
}
}
]
}

OpenAPI 2.0

{
"swagger": "2.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"host": "gy415nuibc.execute-api.us-east-1.amazonaws.com",
"basePath": "/testStage",
"schemes": [
"https"
],
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [

343
 Amazon API Gateway Guía del desarrollador
Integraciones

{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/
arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
}
}

Con la integración de proxy de Lambda, API Gateway asigna en tiempo de ejecución una solicitud entrante
en el parámetro de entrada event de la función de Lambda. La entrada incluye el método de solicitud, la
ruta, los encabezados, todos los parámetros de cadena de consulta, todas las cargas, el contexto asociado
y todas las variables de etapa definidas. El formato de entrada se explica en Formato de entrada de una
función de Lambda para la integración de proxy (p. 348). Para que API Gateway asigne la salida de
Lambda a respuestas HTTP correctamente, la función de Lambda debe producir el resultado en el formato
que se describe en Formato de salida de una función de Lambda para la integración de proxy (p. 351).

Con la integración de proxy de Lambda de un recurso de proxy a través del método ANY, la función de
Lambda del backend actúa como el controlador de eventos de todas las solicitudes a través del recurso
de proxy. Por ejemplo, para registrar patrones de tráfico, puede hacer que el dispositivo móvil envíe la
información de ubicación del país, la ciudad, la calle y el edificio enviando una solicitud con /state/
city/street/house en la ruta URL del recurso de proxy. La función de Lambda del backend puede
analizar la ruta URL e insertar tuplas de ubicación en una tabla de DynamoDB.

Configuración de una integración de proxy de Lambda mediante la CLI de AWS

En esta sección, mostraremos cómo utilizar la CLI de AWS para configurar una API con la integración de
proxy de Lambda.
Note
Para obtener instrucciones detalladas acerca de cómo utilizar la consola de API Gateway
para configurar un recurso de proxy con la integración de proxy de Lambda, consulte Tutorial:
Desarrollo de una API de REST Hello World con integración de proxy de Lambda (p. 27).

Como ejemplo, utilizaremos la siguiente función de Lambda de muestra como el backend de la API:

exports.handler = function(event, context, callback) {

console.log('Received event:', JSON.stringify(event, null, 2));
var res ={
"statusCode": 200,
"headers": {

344
 Amazon API Gateway Guía del desarrollador
Integraciones

"Content-Type": "*/*"
}
};
var greeter = 'World';
if (event.greeter && event.greeter!=="") {
greeter = event.greeter;
} else if (event.body && event.body !== "") {
var body = JSON.parse(event.body);
if (body.greeter && body.greeter !== "") {
greeter = body.greeter;
}
} else if (event.queryStringParameters && event.queryStringParameters.greeter &&
event.queryStringParameters.greeter !== "") {
greeter = event.queryStringParameters.greeter;
} else if (event.multiValueHeaders && event.multiValueHeaders.greeter &&
event.multiValueHeaders.greeter != "") {
greeter = event.multiValueHeaders.greeter.join(" and ");
} else if (event.headers && event.headers.greeter && event.headers.greeter != "") {
greeter = event.headers.greeter;
}

res.body = "Hello, " + greeter + "!";

callback(null, res);
};

Si lo comparamos con la configuración de la integración de Lambda personalizada (p. 353), la entrada

de esta función de Lambda se puede expresar en los parámetros de la solicitud y en el cuerpo. Tiene
más libertad para permitir al cliente transferir los mismos datos de entrada. En este caso el cliente
puede transferir el nombre de greeter como un parámetro de cadena de consulta, un encabezado o una
propiedad del cuerpo. La función también puede admitir la integración de Lambda personalizada. La
configuración de la API es más sencilla. No se configura ninguna respuesta de método ni de integración.

Para configurar una integración de proxy de Lambda mediante la CLI de AWS

1. Llame al comando create-rest-api para crear una API:

aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)' --region us-west-2

Anote el valor id (te6si5ach7) de la API resultante en la respuesta:

{
"name": "HelloWorldProxy (AWS CLI)",
"id": "te6si5ach7",
"createdDate": 1508461860
}

Necesitará el id de la API en esta sección.

2. Llame al comando get-resources para obtener el id del recurso raíz:

aws apigateway get-resources --rest-api-id te6si5ach7 --region us-west-2

La respuesta correcta se muestra del modo siguiente:

{
"items": [
{
"path": "/",
"id": "krznpq9xpg"
}

345
 Amazon API Gateway Guía del desarrollador
Integraciones

]
}

Anote el valor id (krznpq9xpg) del recurso raíz. Lo necesitará en el siguiente paso y más adelante.
3. Llame a create-resource para crear un recurso de API Gateway para /greeting:

aws apigateway create-resource --rest-api-id te6si5ach7 \

--region us-west-2 \
--parent-id krznpq9xpg \
--path-part {proxy+}

La respuesta correcta será similar a la que se muestra a continuación:

{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}

Anote el valor id del recurso {proxy+} (2jf6xt) resultante. Lo necesitará para crear un método en
el recurso /{proxy+} en el siguiente paso.
4. Llame a put-method para crear una solicitud de método ANY para ANY /{proxy+}:

aws apigateway put-method --rest-api-id te6si5ach7 \

--region us-west-2 \
--resource-id 2jf6xt \
--http-method ANY \
--authorization-type "NONE"

La respuesta correcta será similar a la que se muestra a continuación:

{
"apiKeyRequired": false,
"httpMethod": "ANY",
"authorizationType": "NONE"
}

Este método de API permite al cliente recibir o enviar saludos de la función de Lambda al backend.
5. Llame a put-integration para configurar la integración del método ANY /{proxy+} con una
función de Lambda denominada HelloWorld. Esta función responde a la solicitud con un mensaje de
"Hello, {name}!", si se proporciona el parámetro greeter, o bien "Hello, World!", si no se
ha establecido el parámetro de cadena de consulta.

aws apigateway put-integration \

--region us-west-2 \
--rest-api-id vaz7da96z6 \
--resource-id 2jf6xt \
--http-method ANY \
--type AWS_PROXY \
--integration-http-method POST \
--uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/
arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole

346
 Amazon API Gateway Guía del desarrollador
Integraciones

Important

Para las integraciones Lambda, debe utilizar el método HTTP de POST para la solicitud
de integración, según la especificación de la acción del servicio de Lambda para las
invocaciones de funciones. El rol de IAM de apigAwsProxyRole debe tener políticas que
permitan al servicio apigateway invocar funciones Lambda. Para obtener más información
sobre los permisos de IAM, consulte the section called “ Modelo de permisos de API Gateway
para invocar una API” (p. 288).

La salida correcta será similar a la que se muestra a continuación:

{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/
arn:aws:lambda:us-east-1:1234567890:function:HelloWorld/invocations",
"httpMethod": "POST",
"cacheNamespace": "vvom7n",
"credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole",
"type": "AWS_PROXY"
}

En lugar de proporcionar un rol de IAM para credentials, puede llamar al comando add-permission
para agregar permisos basados en recursos. Esto es lo que hace la consola de API Gateway.
6. Llame a create-deployment para implementar la API en una etapa test:

aws apigateway create-deployment --rest-api-id te6si5ach7 --stage-name test

7. Pruebe la API mediante los siguientes comandos cURL en un terminal.

Llame a la API con el parámetro de cadena de consulta de ?greeter=jane:

curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?

greeter=jane' \
-H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/
execute-api/aws4_request, \
SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751'

Llame a la API con un parámetro de encabezado de greeter:jane:

curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \

-H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/
execute-api/aws4_request, \
SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751' \
-H 'content-type: application/json' \
-H 'greeter: jane'

Llame a la API con un cuerpo de {"greeter":"jane"}:

curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test \

-H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/
execute-api/aws4_request, \
SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751' \
-H 'content-type: application/json' \
-d '{ "greeter": "jane" }'

347
 Amazon API Gateway Guía del desarrollador
Integraciones

En todos estos casos, la salida es una respuesta 200 con el siguiente cuerpo de respuesta:

Hello, jane!

Formato de entrada de una función de Lambda para la integración de proxy

Con la integración de proxy de Lambda, API Gateway mapea toda la solicitud cliente al parámetro de
entrada event de la función de Lambda del backend de la siguiente manera:

{
"resource": "Resource path",
"path": "Path parameter",
"httpMethod": "Incoming request's method name"
"headers": {String containing incoming request headers}
"multiValueHeaders": {List of strings containing incoming request headers}
"queryStringParameters": {query string parameters }
"multiValueQueryStringParameters": {List of query string parameters}
"pathParameters": {path parameters}
"stageVariables": {Applicable stage variables}
"requestContext": {Request context, including authorizer-returned key-value pairs}
"body": "A JSON string of the request payload."
"isBase64Encoded": "A boolean flag to indicate if the applicable request payload is
Base64-encoded"
}

Note
En la entrada:

• La clave headers solo puede contener encabezados de un solo valor.

• La clave multiValueHeaders puede contener encabezados de varios valores y encabezados
de un solo valor.
• Si especifica valores para headers y multiValueHeaders, API Gateway los combina en
una sola lista. Si se especifica el mismo par de clave-valor en ambos, solo los valores de
multiValueHeaders aparecerán en la lista combinada.

La siguiente solicitud POST muestra una API implementada en testStage con una variable de etapa de
stageVariableName=stageVariableValue:

POST /testStage/hello/world?name=me HTTP/1.1

Host: gy415nuibc.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
headerName: headerValue

{
"a": 1
}

Esta solicitud produce la siguiente carga de respuesta que contiene la salida devuelta por la función de
Lambda del backend, donde input se ha establecido en el parámetro event de la función de Lambda.

{
"message": "Hello me!",
"input": {
"resource": "/{proxy+}",
"path": "/hello/world",
"httpMethod": "POST",

348
 Amazon API Gateway Guía del desarrollador
Integraciones

"headers": {
"Accept": "*/*",
"Accept-Encoding": "gzip, deflate",
"cache-control": "no-cache",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Desktop-Viewer": "true",
"CloudFront-Is-Mobile-Viewer": "false",
"CloudFront-Is-SmartTV-Viewer": "false",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Viewer-Country": "US",
"Content-Type": "application/json",
"headerName": "headerValue",
"Host": "gy415nuibc.execute-api.us-east-1.amazonaws.com",
"Postman-Token": "9f583ef0-ed83-4a38-aef3-eb9ce3f7a57f",
"User-Agent": "PostmanRuntime/2.4.5",
"Via": "1.1 d98420743a69852491bbdea73f7680bd.cloudfront.net (CloudFront)",
"X-Amz-Cf-Id": "pn-PWIJc6thYnZm5P0NMgOUglL1DYtl0gdeJky8tqsg8iS_sgsKD1A==",
"X-Forwarded-For": "54.240.196.186, 54.182.214.83",
"X-Forwarded-Port": "443",
"X-Forwarded-Proto": "https"
},
"multiValueHeaders":{
'Accept':[
"*/*"
],
'Accept-Encoding':[
"gzip, deflate"
],
'cache-control':[
"no-cache"
],
'CloudFront-Forwarded-Proto':[
"https"
],
'CloudFront-Is-Desktop-Viewer':[
"true"
],
'CloudFront-Is-Mobile-Viewer':[
"false"
],
'CloudFront-Is-SmartTV-Viewer':[
"false"
],
'CloudFront-Is-Tablet-Viewer':[
"false"
],
'CloudFront-Viewer-Country':[
"US"
],
'':[
""
],
'Content-Type':[
"application/json"
],
'headerName':[
"headerValue"
],
'Host':[
"gy415nuibc.execute-api.us-east-1.amazonaws.com"
],
'Postman-Token':[
"9f583ef0-ed83-4a38-aef3-eb9ce3f7a57f"
],
'User-Agent':[
"PostmanRuntime/2.4.5"

349
 Amazon API Gateway Guía del desarrollador
Integraciones

],
'Via':[
"1.1 d98420743a69852491bbdea73f7680bd.cloudfront.net (CloudFront)"
],
'X-Amz-Cf-Id':[
"pn-PWIJc6thYnZm5P0NMgOUglL1DYtl0gdeJky8tqsg8iS_sgsKD1A=="
],
'X-Forwarded-For':[
"54.240.196.186, 54.182.214.83"
],
'X-Forwarded-Port':[
"443"
],
'X-Forwarded-Proto':[
"https"
]
},
"queryStringParameters": {
"name": "me",
"multivalueName": "me"
},
"multiValueQueryStringParameters":{
"name":[
"me"
],
"multivalueName":[
"you",
"me"
]
},
"pathParameters": {
"proxy": "hello/world"
},
"stageVariables": {
"stageVariableName": "stageVariableValue"
},
"requestContext": {
"accountId": "12345678912",
"resourceId": "roq9wj",
"stage": "testStage",
"requestId": "deef4878-7910-11e6-8f14-25afc3e9ae33",
"identity": {
"cognitoIdentityPoolId": null,
"accountId": null,
"cognitoIdentityId": null,
"caller": null,
"apiKey": null,
"sourceIp": "192.168.196.186",
"cognitoAuthenticationType": null,
"cognitoAuthenticationProvider": null,
"userArn": null,
"userAgent": "PostmanRuntime/2.4.5",
"user": null
},
"resourcePath": "/{proxy+}",
"httpMethod": "POST",
"apiId": "gy415nuibc"
},
"body": "{\r\n\t\"a\": 1\r\n}",
"isBase64Encoded": false
}
}

350
 Amazon API Gateway Guía del desarrollador
Integraciones

En la entrada a la función de Lambda de backend, el objeto requestContext es un mapa de pares de

clave-valor. En cada par, la clave es el nombre de una propiedad de la variable $context (p. 425) y el
valor es el valor de esa propiedad. API Gateway puede agregar nuevas claves al mapa.

En función de las características habilitadas, el mapa requestContext puede variar de API en API.
Por ejemplo, en el ejemplo anterior, no se especifica ningún tipo de autorización, por lo que no hay
propiedades $context.authorizer.* o $context.identity.* presentes. Cuando se especifica un
tipo de autorización, esto hace que API Gateway transfiera información del usuario autorizado al punto de
enlace de integración en un objeto requestContext.identity tal y como se indica a continuación:

• Cuando el tipo de autorización es AWS_IAM, la información del usuario autorizado incluye propiedades
$context.identity.*.
• Cuando el tipo de autorización es COGNITO_USER_POOLS (autorizador de Amazon Cognito), la
información del usuario autorizado incluye las propiedades $context.identity.cognito* y
$context.authorizer.claims.*.
• Cuando el tipo de autorización es CUSTOM (autorizador de Lambda), la información del usuario
autorizado incluye las propiedades $context.authorizer.principalId y otras propiedades
$context.authorizer.* aplicables.

A continuación se muestra un ejemplo de requestContext pasado a un punto de enlace de integración

de proxy de Lambda cuando el tipo de autorización está establecido en AWS_IAM.

{
...,
"requestContext": {
"requestTime": "20/Feb/2018:22:48:57 +0000",
"path": "/test/",
"accountId": "123456789012",
"protocol": "HTTP/1.1",
"resourceId": "yx5mhem7ye",
"stage": "test",
"requestTimeEpoch": 1519166937665,
"requestId": "3c3ecbaa-1690-11e8-ae31-8f39f1d24afd",
"identity": {
"cognitoIdentityPoolId": null,
"accountId": "123456789012",
"cognitoIdentityId": null,
"caller": "AIDAJ........4HCKVJZG",
"sourceIp": "51.240.196.104",
"accessKey": "IAM_user_access_key",
"cognitoAuthenticationType": null,
"cognitoAuthenticationProvider": null,
"userArn": "arn:aws:iam::123456789012:user/alice",
"userAgent": "PostmanRuntime/7.1.1",
"user": "AIDAJ........4HCKVJZG"
},
"resourcePath": "/",
"httpMethod": "GET",
"apiId": "qr2gd9cfmf"
},
...
}

Formato de salida de una función de Lambda para la integración de proxy

Con la integración de proxy de Lambda, API Gateway requiere que la función de Lambda del backend
devuelva la salida de acuerdo con el siguiente formato JSON:

351
 Amazon API Gateway Guía del desarrollador
Integraciones

"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headerName": "headerValue", ... },
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"body": "..."
}

En la salida:

• Las claves headers y multiValueHeaders pueden no estar especificadas si no se van a devolver

más encabezados de respuesta.
• La clave headers solo puede contener encabezados de un solo valor.
• La clave multiValueHeaders puede contener encabezados de varios valores y encabezados de
un solo valor. Puede utilizar la clave multiValueHeaders para especificar todos los encabezados
adicionales, incluidos los que solo contienen un valor.
• Si especifica valores para headers y multiValueHeaders, API Gateway los combina en una sola
lista. Si se especifica el mismo par de clave-valor en ambos, solo los valores de multiValueHeaders
aparecerán en la lista combinada.

Para habilitar CORS para la integración de proxy de Lambda, debe agregar Access-Control-Allow-
Origin:domain-name a la salida headers. domain-name puede ser * para cualquier nombre de
dominio. La salida body se serializa en el frontend como la carga de respuesta del método. Si body es un
blob binario, puede codificarlo como una cadena codificada en Base64 estableciendo isBase64Encoded
en true y configurando */* como Binary Media Type (Tipo de medio binario). De lo contrario, puede
establecerlo en false o dejarlo sin especificar.
Note

Para obtener más información acerca de cómo habilitar la compatibilidad con datos
binarios, consulte Habilitar la compatibilidad con datos binarios mediante la consola de API
Gateway (p. 457). Para ver una función de Lambda de ejemplo, consulte Devolver medios
binarios desde una integración de proxy de Lambda (p. 465).

Si la salida de la función tiene un formato diferente, API Gateway devuelve una respuesta de error 502
Bad Gateway.

Para devolver una respuesta en una función de Lambda de Node.js, puede utilizar comandos como los
siguientes:

• Para devolver un resultado correcto, llame a callback(null, {"statusCode": 200, "body":

"results"}).
• Para producir una excepción, llame a callback(new Error('internal server error')).
• En caso de que se produzca un error del lado del cliente (por ejemplo, si falta un parámetro necesario),
puede llamar a callback(null, {"statusCode": 400, "body": "Missing parameters
of ..."}) para devolver el error sin iniciar una excepción.

En una función de Lambda de async de Node.js, la sintaxis correspondiente sería:

• Para devolver un resultado correcto, llame a return {"statusCode": 200, "body":

"results"}.
• Para producir una excepción, llame a throw new Error("internal server error").
• En caso de que se produzca un error en el lado del cliente (por ejemplo, si falta un parámetro necesario),
puede llamar a return {"statusCode": 400, "body": "Missing parameters of ..."}
para devolver el error sin iniciar una excepción.

352
 Amazon API Gateway Guía del desarrollador
Integraciones

Configuración de integraciones de Lambda personalizadas en API Gateway

Para mostrar cómo configurar la integración de Lambda personalizada, creamos una API de API Gateway,
para exponer el método GET /greeting?greeter={name} para invocar una función de Lambda. La
función responde con un mensaje de "Hello, {name}!" si el valor del parámetro greeter es una
cadena no vacía. Si el valor "Hello, World!" es una cadena vacía, devuelve un mensaje de greeter.
La función devuelve un mensaje de error de "Missing the required greeter parameter." si
el parámetro greeter no se ha establecido en la solicitud entrante. Asignamos un nombre a la función
HelloWorld.

Como referencia, se muestra una versión Node.js de la función de Lambda:

exports.handler = function(event, context, callback) {

var res ={
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
};
if (event.greeter==null) {
callback(new Error('Missing the required greeter parameter.'));
} else if (event.greeter === "") {
res.body = "Hello, World";
callback(null, res);
} else {
res.body = "Hello, " + event.greeter +"!";
callback(null, res);
}
};

Puede crearla en la consola de Lambda o mediante la CLI de AWS. En esta sección, hacemos referencia a
esta función mediante los siguientes ARN:

arn:aws:lambda:us-east-1:123456789012:function:HelloWorld

Una vez establecida la función de Lambda en el backend, proceda a configurar la API.

Para configurar una integración de Lambda personalizada mediante la CLI de AWS

1. Llame al comando create-rest-api para crear una API:

aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)' --region us-west-2

Anote el valor id (te6si5ach7) de la API resultante en la respuesta:

{
"name": "HelloWorld (AWS CLI)",
"id": "te6si5ach7",
"createdDate": 1508461860
}

Necesitará el id de la API en esta sección.

2. Llame al comando get-resources para obtener el id del recurso raíz:

aws apigateway get-resources --rest-api-id te6si5ach7 --region us-west-2

La respuesta correcta es la siguiente:

353
 Amazon API Gateway Guía del desarrollador
Integraciones

{
"items": [
{
"path": "/",
"id": "krznpq9xpg"
}
]
}

Anote el valor id (krznpq9xpg) del recurso raíz. Lo necesitará en el siguiente paso y más adelante.
3. Llame a create-resource para crear un recurso de API Gateway para /greeting:

aws apigateway create-resource --rest-api-id te6si5ach7 \

--region us-west-2 \
--parent-id krznpq9xpg \
--path-part greeting

La respuesta correcta será similar a la que se muestra a continuación:

{
"path": "/greeting",
"pathPart": "greeting",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}

Anote el valor id del recurso greeting (2jf6xt) resultante. Lo necesitará para crear un método en
el recurso /greeting en el siguiente paso.
4. Llame a put-method para crear una solicitud de método de API para GET /greeting?
greeter={name}:

aws apigateway put-method --rest-api-id te6si5ach7 \

--region us-west-2 \
--resource-id 2jf6xt \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.greeter=false

La respuesta correcta será similar a la que se muestra a continuación:

{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.querystring.greeter": false
}
}

Este método de API permite al cliente recibir saludos de la función de Lambda al backend. El
parámetro greeter es opcional, ya que el backend debería administrar un intermediario anónimo o
bien un intermediario identificado.
5. Llame a put-method-response para configurar la respuesta 200 OK en la solicitud de método para
GET /greeting?greeter={name}:

354
 Amazon API Gateway Guía del desarrollador
Integraciones

aws apigateway put-method-response \

--region us-west-2 \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200

6. Llame a put-integration para configurar la integración del método GET /greeting?

greeter={name} con una función de Lambda denominada HelloWorld. Esta función responde a
la solicitud con un mensaje de "Hello, {name}!", si se proporciona el parámetro greeter, o bien
"Hello, World!", si no se ha establecido el parámetro de cadena de consulta.

aws apigateway put-integration \

--region us-west-2 \
--rest-api-id vaz7da96z6 \
--resource-id 2jf6xt \
--http-method GET \
--type AWS \
--integration-http-method POST \
--uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/
arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \
--request-templates file://path/to/integration-request-template.json \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole

A continuación, el valor del parámetro request-template, file://path/to/integration-

request-template.json señala a un archivo JSON denominado integration-request-
template.json en el directorio path/to, que contiene un mapa de clave-valor como objeto JSON.
La clave es un tipo de medio de la carga de solicitud y el valor es una plantilla de mapeo para el
cuerpo del tipo de contenido especificado. En este ejemplo, el archivo JSON contiene el siguiente
objeto JSON:

{"application/json":"{\"greeter\":\"$input.params('greeter')\"}"}

La plantilla de mapeo proporcionada aquí traslada el parámetro de cadena de consulta greeter a

la propiedad greeter de la carga de JSON. Esto es necesario porque la entrada de una función
de Lambda se debe expresar en el cuerpo. Puede utilizar la cadena JSON del mapa (por ejemplo,
"{\"greeter"\: \"'john'\"}") como el valor de entrada request-template para el comando
put-integration. Sin embargo, cuando se utiliza la entrada de archivo se evita la difícil, y a veces
imposible, inclusión de comillas en caracteres de escape que se necesitan para aplicar el método
stringify a un objeto JSON.
Important

Para las integraciones Lambda, debe utilizar el método HTTP de POST para la solicitud
de integración, según la especificación de la acción del servicio de Lambda para las
invocaciones de funciones. El parámetro uri es el ARN de la acción que invoca las
funciones.
La salida correcta es similar a la siguiente:

{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/
arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\"greeter\":\"$input.params('greeter')\"}"

355
 Amazon API Gateway Guía del desarrollador
Integraciones

},
"cacheNamespace": "krznpq9xpg",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"type": "AWS"
}

El rol de IAM de apigAwsProxyRole debe tener políticas que permiten al servicio apigateway
invocar funciones de Lambda. En lugar de proporcionar un rol de IAM para credentials, puede
llamar al comando add-permission para agregar permisos basados en recursos. De este modo es
como la consola de API Gateway agrega estos permisos.
7. Llame a put-integration-response para configurar la respuesta de integración para transferir la
salida de la función de Lambda al cliente como respuesta del método 200 OK.

aws apigateway put-integration-response \

--region us-west-2 \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200 \
--selection-pattern ""

Si se establece el patrón de selección en una cadena vacía, la respuesta 200 OK es la opción

predeterminada.

La respuesta correcta debería ser similar a la siguiente:

{
"selectionPattern": "",
"statusCode": "200"
}

8. Llame a create-deployment para implementar la API en una etapa test:

aws apigateway create-deployment --rest-api-id te6si5ach7 --stage-name test

9. Pruebe la API mediante el siguiente comando cURL en un terminal:

curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?

greeter=me' \
-H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-
west-2/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date,
Signature=f327...5751'

Configurar la invocación asíncrona de la función de Lambda de backend

En la integración de Lambda no de proxy (personalizada), se invoca la función de Lambda de backend,
de forma síncrona y de forma predeterminada. Este es el comportamiento deseado para la mayoría de
operaciones de API de REST. Algunas aplicaciones, sin embargo, requieren que el trabajo se realice
de forma asíncrona (como una operación por lotes o una operación de latencia), normalmente por un
componente backend independiente. En este caso, la función de Lambda del backend se invoca de forma
asíncrona y el método de la API REST de front-end no devuelve el resultado.

Puede configurar la función de Lambda para una integración de Lambda que no sea proxy para invocarla
de forma asíncrona especificando 'Event' como el tipo de invocación de Lambda. Esto se realiza de la
siguiente manera:

356
 Amazon API Gateway Guía del desarrollador
Integraciones

Configurar la invocación asíncrona de Lambda en la consola de API Gateway

Para que todas las invocaciones sean asincrónicas:

• En Integration Request (Solicitud de integración), agregue un encabezado X-Amz-Invocation-

Type con un valor estático de 'Event'.

Para que los clientes decidan si las invocaciones son asincrónicas o sincrónicas:

1. En Method Request (Solicitud de método), agregue un encabezado de InvocationType.

2. En Integration Request (Solicitud de integración) agregue un encabezado X-Amz-Invocation-Type
con una expresión de asignación de method.request.header.InvocationType.
3. Los clientes pueden incluir el encabezado InvocationType: Event en solicitudes de API para
invocaciones asincrónicas o InvocationType: RequestResponse para invocaciones sincrónicas.

Gestionar los errores de Lambda en API Gateway

Para las integraciones de Lambda personalizadas, debe asignar los errores devueltos por Lambda en la
respuesta de integración a las respuestas de error de HTTP estándar para sus clientes. De lo contrario, los
errores de Lambda se devuelven como respuestas 200 OK de forma predeterminada y el resultado no es
intuitivo para los usuarios de la API.

Hay dos tipos de errores que Lambda puede devolver: errores estándar y errores personalizados. En la
API, debe tratarlos de forma diferente.

Con la integración de proxy de Lambda, Lambda debe devolver una salida con el siguiente formato:

{
"isBase64Encoded" : "boolean",
"statusCode": "number",
"headers": { ... },
"body": "JSON string"
}

En esta salida, statusCode es normalmente 4XX para un error del cliente y 5XX para un error del
servidor. API Gateway trata estos errores asignando el error de Lambda a una respuesta de error HTTP,
de acuerdo con el statusCode especificado. Para que API Gateway transmita el tipo de error (por
ejemplo, InvalidParameterException), como parte de la respuesta al cliente, la función de Lambda
debe incluir un encabezado (por ejemplo, "X-Amzn-ErrorType":"InvalidParameterException")
en la propiedad headers.

Temas
• Gestionar los errores de Lambda estándares en API Gateway. (p. 357)
• Gestionar los errores de Lambda personalizados en API Gateway (p. 359)

Gestionar los errores de Lambda estándares en API Gateway.

Un error estándar de AWS Lambda tiene el siguiente formato:

{
"errorMessage": "<replaceable>string</replaceable>",
"errorType": "<replaceable>string</replaceable>",
"stackTrace": [
"<replaceable>string</replaceable>",
...
]

357
 Amazon API Gateway Guía del desarrollador
Integraciones

Aquí, errorMessage es una expresión de cadena del error. errorType es un tipo de error o excepción
dependiente del lenguaje. stackTrace es una lista de expresiones de cadena que indican la pila de
rastreo que conduce a la aparición del error.

Por ejemplo, observe la siguiente función de Lambda en JavaScript (Node.js).

exports.handler = function(event, context, callback) {

callback(new Error("Malformed input ..."));
};

Esta función devuelve el siguiente error de Lambda estándar, que contiene Malformed input ... como
el mensaje de error:

{
"errorMessage": "Malformed input ...",
"errorType": "Error",
"stackTrace": [
"exports.handler (/var/task/index.js:3:14)"
]
}

Asimismo, considere la siguiente función de Lambda de Python, que produce una Exception con el
mismo mensaje de error Malformed input ....

def lambda_handler(event, context):

raise Exception('Malformed input ...')

Esta función devuelve el siguiente error de Lambda estándar:

{
"stackTrace": [
[
"/var/task/lambda_function.py",
3,
"lambda_handler",
"raise Exception('Malformed input ...')"
]
],
"errorType": "Exception",
"errorMessage": "Malformed input ..."
}

Tenga en cuenta que los valores de las propiedades errorType y stackTrace dependen del lenguaje.
El error estándar también se aplica a cualquier objeto de error que sea una extensión del objeto Error o
una subclase de la clase Exception.

Para asignar el error de Lambda estándar a una respuesta del método, primero debe decidir cuál es el
código de estado HTTP para un error de Lambda determinado. Seguidamente, debe establecer un patrón
de expresiones regulares en la propiedad selectionPattern del recurso IntegrationResponse asociado
con el código de estado HTTP especificado. En la consola de API Gateway, selectionPattern se
indica como Lambda Error Regex (Expresión regular de error Lambda) en el editor de configuración de
Integration Response (Respuesta de integración).
Note
API Gateway utiliza expresiones regulares de estilo de patrón de Java para el mapeo de
respuesta. Para obtener más información, consulte Pattern (Patrón) en la documentación de
Oracle.

358
 Amazon API Gateway Guía del desarrollador
Integraciones

Por ejemplo, para configurar una nueva expresión selectionPattern mediante la CLI de AWS, llame al
siguiente comando put-integration-response:

aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --

http-method GET --status-code 400 --selection-pattern "Invalid*" --region us-west-2

Asegúrese de configurar también el código de error correspondiente (400) en la respuesta del

método (p. 264). De lo contrario, API Gateway produce una respuesta de error de configuración no válida
en tiempo de ejecución.
Note

En el tiempo de ejecución, API Gateway coteja el errorMessage de error de Lambda con el

patrón de la expresión regular en la propiedad selectionPattern. Si hay una coincidencia,
API Gateway devuelve el error de Lambda como una respuesta HTTP del código de estado
HTTP correspondiente. Si no hay ninguna coincidencia, API Gateway devuelve el error como
una respuesta predeterminada o produce una excepción de configuración no válida si no se ha
configurado una respuesta predeterminada.
Configurar el valor selectionPattern a .* para una determinada respuesta equivale a
restablecer esta respuesta como la predeterminada. Esto se debe a que un patrón de solicitud
de este tipo coincidirá con todos los mensajes de error, incluidos los nulos, es decir, cualquier
mensaje de error no especificado. El mapeo resultante anula al predeterminado.

Para actualizar un valor de selectionPattern existente mediante la CLI de AWS, llame a la operación
update-integration-response para reemplazar el valor de ruta de /selectionPattern por la expresión
regular especificada con el patrón Malformed*.

Para establecer la expresión selectionPattern con la consola de API Gateway, escriba la expresión en
el cuadro de texto Lambda Error Regex (Expresión regular de error Lambda) cuando configure o actualice
una respuesta de integración de un código de estado HTTP especificado.

Gestionar los errores de Lambda personalizados en API Gateway

En lugar del error estándar descrito en la sección anterior, AWS Lambda le permite devolver un objeto
de error personalizado como una cadena JSON. El error puede ser cualquier objeto JSON válido. Por
ejemplo, la siguiente función de Lambda en JavaScript (Node.js) devuelve un error personalizado:

exports.handler = (event, context, callback) => {

...
// Error caught here:
var myErrorObj = {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
callback(JSON.stringify(myErrorObj));
};

Debe activar el objeto myErrorObj en una cadena JSON antes de llamar a callback para salir de la
función. De lo contrario, myErrorObj se devuelve como una cadena de "[object Object]". Cuando
un método de la API está integrado con la función API Gateway anterior, Lambda recibe una respuesta de
integración con la siguiente carga:

359
 Amazon API Gateway Guía del desarrollador
Integraciones

"errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId
\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,
\"file\":\"abc.js\"}}"
}

Al igual que con cualquier respuesta de integración, puede transferir esta respuesta de error tal como está
a la respuesta del método. O puede usar una plantilla de asignación de cuerpo para transformar la carga
en un formato diferente. Considere, por ejemplo, la siguiente plantilla de asignación de cuerpo para una
respuesta de método del código de estado 500:

{
errorMessage: $input.path('$.errorMessage');
}

Esta plantilla traduce el cuerpo de respuesta de la integración que contiene la cadena JSON del error
personalizado en el siguiente cuerpo de respuesta del método. Este cuerpo de respuesta del método
contiene el objeto JSON del error personalizado:

{
"errorMessage" : {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
};

En función de los requisitos de la API, es posible que tenga que pasar algunas o todas las propiedades
de errores personalizados como parámetros de encabezado de la respuesta del método. Para ello,
puede aplicar asignaciones de errores personalizados desde el cuerpo de respuesta de integración a los
encabezados de respuesta del método.

Por ejemplo, la siguiente extensión de OpenAPI define una asignación desde las propiedades
errorMessage.errorType, errorMessage.httpStatus, errorMessage.trace.function y
errorMessage.trace a error_type, error_status, error_trace_function y error_trace,
respectivamente.

"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.error_trace_function":
"integration.response.body.errorMessage.trace.function",
"method.response.header.error_status":
"integration.response.body.errorMessage.httpStatus",
"method.response.header.error_type":
"integration.response.body.errorMessage.errorType",
"method.response.header.error_trace":
"integration.response.body.errorMessage.trace"
},
...
}
}
}

360
 Amazon API Gateway Guía del desarrollador
Integraciones

En tiempo de ejecución, API Gateway deserializa el parámetro integration.response.body cuando

realiza mapeos de encabezado. Sin embargo, esta deserialización se aplica únicamente a los mapeos
de cuerpo a encabezado para respuestas de errores personalizados de Lambda y no se aplica a los
mapeos de cuerpo a cuerpo que utilizan $input.body. Con estas asignaciones de cuerpo a encabezado
de errores personalizados, el cliente recibe los siguientes encabezados como parte de la respuesta del
método, siempre que los encabezados error_status, error_trace, error_trace_function y
error_type estén declarados en la solicitud del método.

"error_status":"500",
"error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}",
"error_trace_function":"abc()",
"error_type":"InternalServerError"

La propiedad errorMessage.trace del cuerpo de respuesta de integración es una propiedad compleja.

Se asigna al encabezado error_trace como una cadena JSON.

Configurar integraciones HTTP en API Gateway

Puede integrar un método de API con un punto de enlace HTTP mediante la integración de proxy HTTP o
la integración HTTP personalizada.

API Gateway admite los siguientes puertos de punto de enlace: 80, 443 y 1024-65535.

Con la integración de proxy, la configuración es sencilla. Solo tiene que establecer el método HTTP y el
URI del punto de enlace HTTP, según los requisitos de backend, si no le preocupa la codificación o el
almacenamiento en caché del contenido.

Con la integración personalizada, la configuración requiere más pasos. Además de los pasos de
configuración de integración de proxy, debe especificar cómo se mapean los datos entrantes de la solicitud
a la solicitud de integración y cómo se mapean los datos resultantes de respuesta de la integración a la
respuesta del método.

Temas
• Configurar integraciones de proxy HTTP en API Gateway (p. 361)
• Configurar integraciones HTTP personalizadas en API Gateway (p. 365)

Configurar integraciones de proxy HTTP en API Gateway

Para configurar un recurso de proxy con el tipo de integración de proxy HTTP, cree un recurso de API con
un parámetro de ruta extensiva (por ejemplo, /parent/{proxy+}) e integre este recurso con un punto
de enlace HTTP del backend (por ejemplo, https://petstore-demo-endpoint.execute-api.com/
petstore/{proxy}) en el método ANY. El parámetro de ruta expansiva debe estar al final de la ruta del
recurso.

Al igual que con un recurso que no es de proxy, puede configurar un recurso de proxy con la integración
de proxy HTTP mediante la consola de API Gateway, importando un archivo de definición de OpenAPI
o llamando a la API REST de API Gateway directamente. Para obtener instrucciones detalladas acerca
de cómo utilizar la consola de API Gateway para configurar un recurso de proxy con la integración HTTP,
consulte Tutorial: Desarrollo de una API de REST con integración de proxy HTTP (p. 51).

El siguiente archivo de definición de API de OpenAPI muestra un ejemplo de una API con un recurso de
proxy que está integrado en el sitio web PetStore.

OpenAPI 3.0

361
 Amazon API Gateway Guía del desarrollador
Integraciones

"openapi": "3.0.0",
"info": {
"version": "2016-09-12T23:19:28Z",
"title": "PetStoreWithProxyResource"
},
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.proxy": "method.request.path.proxy"
},
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"cacheNamespace": "rbftud",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "http_proxy"
}
}
}
},
"servers": [
{
"url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
]
}

OpenAPI 2.0

{
"swagger": "2.0",
"info": {
"version": "2016-09-12T23:19:28Z",
"title": "PetStoreWithProxyResource"
},
"host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],

362
 Amazon API Gateway Guía del desarrollador
Integraciones

"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.proxy": "method.request.path.proxy"
},
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"cacheNamespace": "rbftud",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "http_proxy"
}
}
}
}
}

En este ejemplo, una clave de caché se declara en el parámetro de ruta method.request.path.proxy

del recurso de proxy. Esta es la configuración predeterminada al crear la API utilizando la consola de API
Gateway. La ruta base de la API (/test, correspondiente a una etapa) se mapea a la página PetStore
del sitio web (/petstore). La solicitud de integración replica todo el sitio web de PetStore utilizando
la variable de ruta expansiva de la API y el método catch-all ANY. Los siguientes ejemplos ilustran esta
replicación.

• Establecer ANY en GET y {proxy+} en pets

Solicitud de método iniciada desde el frontend:

GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1

Solicitud de integración enviada al backend:

GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1

Las instancias en tiempo de ejecución del método ANY y el recurso de proxy son válidas. La llamada
devolverá una respuesta 200 OK con la carga que contiene el primer lote de mascotas, tal y como se
devuelve desde el backend.
• Establecer ANY en GET y {proxy+} en pets?type=dog

363
 Amazon API Gateway Guía del desarrollador
Integraciones

GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1

Solicitud de integración enviada al backend:

GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1

Las instancias en tiempo de ejecución del método ANY y el recurso de proxy son válidas. La llamada
devolverá una respuesta 200 OK con la carga que contiene el primer lote de perros especificados, tal y
como se devuelve desde el backend.
• Establecer ANY en GET y {proxy+} en pets/{petId}

Solicitud de método iniciada desde el frontend:

GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1

Solicitud de integración enviada al backend:

GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1

Las instancias en tiempo de ejecución del método ANY y el recurso de proxy son válidas. La llamada
devolverá una respuesta 200 OK con la carga que contiene la mascota especificada, tal y como se
devuelve desde el backend.
• Establecer ANY en POST y {proxy+} en pets

Solicitud de método iniciada desde el frontend:

POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1

Content-Type: application/json
Content-Length: ...

{
"type" : "dog",
"price" : 1001.00
}

Solicitud de integración enviada al backend:

POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1

Content-Type: application/json
Content-Length: ...

{
"type" : "dog",
"price" : 1001.00
}

Las instancias en tiempo de ejecución del método ANY y el recurso de proxy son válidas. La llamada
devolverá una respuesta 200 OK con la carga que contiene la mascota recién creada, tal y como se
devuelve desde el backend.
• Establecer ANY en GET y {proxy+} en pets/cat

Solicitud de método iniciada desde el frontend:

364
 Amazon API Gateway Guía del desarrollador
Integraciones

GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat

Solicitud de integración enviada al backend:

GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat

La instancia en tiempo de ejecución de la ruta del recurso de proxy no se corresponde con un punto de
enlace del backend y la solicitud resultante no es válida. Como resultado, se devuelve una respuesta
400 Bad Request con el siguiente mensaje de error.

{
"errors": [
{
"key": "Pet2.type",
"message": "Missing required field"
},
{
"key": "Pet2.price",
"message": "Missing required field"
}
]
}

• Establecer ANY en GET y {proxy+} en null

Solicitud de método iniciada desde el frontend:

GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test

Solicitud de integración enviada al backend:

GET http://petstore-demo-endpoint.execute-api.com/petstore/pets

El recurso de destino es el elemento principal del recurso de proxy, pero la instancia en tiempo de
ejecución del método ANY no está definida en la API de ese recurso. Como resultado, esta solicitud GET
devuelve una respuesta 403 Forbidden con el mensaje de error Missing Authentication Token
devuelto por API Gateway. Si la API expone el método ANY o GET en el recurso principal (/), la llamada
devuelve una respuesta 404 Not Found con el mensaje Cannot GET /petstore, tal y como se
devuelve desde el backend.

Para cualquier solicitud cliente, si la URL del punto de enlace de destino no es válida o el verbo HTTP
es válido pero no es compatible, el backend devuelve una respuesta 404 Not Found. Para un método
HTTP no admitido, se devuelve una respuesta 403 Forbidden.

Configurar integraciones HTTP personalizadas en API Gateway

Con la integración HTTP personalizada, obtiene más control sobre qué datos se transfieren entren un
método de API y una integración de API y cómo transferir los datos. Para ello, se utilizan mapeos de datos.

Como parte de la configuración de solicitud de método, debe establecer la propiedad requestParameters

en un recurso Method. Esto declara qué parámetros de solicitud de método, que se aprovisionan desde
el cliente, se mapean a los parámetros de solicitud de integración o son aplicables a las propiedades de
cuerpo antes de que se envíen al backend. A continuación, como parte de la configuración de solicitud de
integración, debe establecer la propiedad requestParameters en el recurso correspondiente de Integration
para especificar los mapeos entre parámetros. También debe establecer la propiedad requestTemplates

365
 Amazon API Gateway Guía del desarrollador
Integraciones

para especificar plantillas de mapeo, una para cada tipo de contenido admitido. Dichas plantillas mapean
los parámetros de solicitud de método, o el cuerpo, al cuerpo de solicitud de integración.

De forma similar, como parte de la configuración de respuesta de método, debe establecer la propiedad
responseParameters en el recurso MethodResponse. Esto declara qué parámetros de respuesta de
método, que se van a enviar al cliente, se mapean desde los parámetros de respuesta de integración o
ciertas propiedades de cuerpo aplicables que se devolvieron desde el backend. A continuación, como
parte de la configuración de respuesta de integración, debe establecer la propiedad responseParameters
en el recurso IntegrationResponse correspondiente para especificar los mapeos entre parámetros.
También debe establecer el mapa responseTemplates para especificar plantillas de mapeo, una para cada
tipo de contenido admitido. Dichas plantillas mapean los parámetros de respuesta de integración, o bien
las propiedades de cuerpo de respuesta de integración, al cuerpo de respuesta del método.

Para obtener más información sobre la configuración de plantillas de mapeo, consulte Configuración de
transformaciones de datos para API REST (p. 389).

Configurar integraciones privadas de API Gateway

La integración privada de API Gateway facilita la exposición de los recursos HTTP/HTTPS dentro de
una Amazon VPC para que puedan obtener acceso los clientes que están fuera de la VPC. Para ampliar
el acceso a los recursos de su VPC privada más allá de los límites de la VPC, puede crear una API
con integración privada. Puede controlar el acceso a la API mediante cualquiera de los métodos de
autorización (p. 269) admitidos por API Gateway.

Para crear una integración privada, primero debe crear un Balanceador de carga de red. El Balanceador
de carga de red debe tener un agente de escucha que enrute las solicitudes a los recursos de la VPC. A
continuación, cree un vínculo de VPC que utilice para conectar la API y el Balanceador de carga de red.
Después de crear un vínculo de VPC, se crean integraciones privadas para enrutar el tráfico de la API a los
recursos de la VPC a través de dicho vínculo y el Balanceador de carga de red.
Note
El balanceador de carga de red y la API deben pertenecer a la misma cuenta de AWS.

Con la integración privada de API Gateway, puede habilitar el acceso a recursos HTTP/HTTPS dentro de
una VPC sin conocer al detalle la configuración de las redes privadas o los dispositivos específicos de las
tecnologías.

Temas
• Configuración de un balanceador de carga de red para integraciones privadas de API
Gateway (p. 366)
• Concesión de permisos para crear un enlace VPC (p. 367)
• Configurar una API de API Gateway con integración privada a través de la consola de API
Gateway (p. 368)
• Configurar una API de API Gateway con integración privada a través de la CLI de AWS (p. 368)
• Configuración de una API con integraciones privadas a través de OpenAPI (p. 371)
• Cuentas de API Gateway utilizadas para integraciones privadas (p. 372)

Configuración de un balanceador de carga de red para integraciones privadas de

API Gateway
En el siguiente procedimiento, se describen los pasos necesarios para configurar un balanceador de carga
de red para integraciones privadas de API Gateway utilizando la consola de Amazon EC2 y se incluyen
referencias a instrucciones detalladas sobre cada paso.

Para cada VPC en la que disponga de recursos, solo necesita configurar un NLB y un VPCLink. El NLB
admite varios agentes de escucha y grupos de destino por NLB. Puede configurar cada servicio como un

366
 Amazon API Gateway Guía del desarrollador
Integraciones

agente de escucha específico en el NLB y utilizar un único VPCLink para conectarse al NLB. Al crear la
integración privada en API Gateway, defina cada servicio utilizando el puerto específico asignado a cada
servicio. Para obtener más información, consulte the section called “Tutorial: Creación de una API con
integración privada” (p. 87).
Note

El balanceador de carga de red y la API deben pertenecer a la misma cuenta de AWS.

Si desea crear un balanceador de carga de red privada para una integración privada con la
consola de API Gateway

1. Inicie sesión en la consola de Amazon EC2 en https://console.aws.amazon.com/ec2/ y elija una región

(por ejemplo, us-east-1) en la barra de navegación.
2. Instale un servidor web en una instancia de Amazon EC2. Para ver una instalación de ejemplo,
consulte Instalar un servidor web LAMP en Amazon Linux.
3. Cree un balanceador de carga de red, registre la instancia EC2 con un grupo de destino y agregue el
grupo de destino a un agente de escucha del balanceador de carga de red. Para obtener información
más detallada, siga las instrucciones que se describen en Introducción a los balanceadores de carga
de red.

Una vez que haya creado el balanceador de carga de red, anote su ARN. Lo necesitará para crear un
enlace VPC en API Gateway e integrar la API con los recurso de la VPC detrás del balanceador de
carga de red.

Concesión de permisos para crear un enlace VPC

Para que usted o un usuario de la cuenta puedan crear y mantener un enlace VPC, deben tener permiso
para crear, eliminar y consultar configuraciones de servicios de punto de enlace de la VPC y examinar los
balanceadores de carga. Para conceder este tipo de permisos, siga estos pasos.

Si desea conceder permisos para crear y actualizar un enlace VpcLink

1. Cree una política de IAM similar a la siguiente:

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ec2:CreateVpcEndpointServiceConfiguration",
"ec2:DeleteVpcEndpointServiceConfigurations",
"ec2:DescribeVpcEndpointServiceConfigurations",
"ec2:ModifyVpcEndpointServicePermissions"
],
"Resource":"*"
},
{
"Effect":"Allow",
"Action":[
"elasticloadbalancing:DescribeLoadBalancers"
],
"Resource":"*"
}
]
}

2. Cree o seleccione un rol de IAM y asocie la política anterior al rol.

367
 Amazon API Gateway Guía del desarrollador
Integraciones

3. Asigne el rol de IAM a sí mismo o al usuario de la cuenta que está creando los enlaces VPC.

Configurar una API de API Gateway con integración privada a través de la

consola de API Gateway
Si desea consultar instrucciones en las que se utiliza la consola de API Gateway para configurar una
API con integración privada, visite Tutorial: Crear una API REST con la integración privada de API
Gateway (p. 87).

Configurar una API de API Gateway con integración privada a través de la CLI de
AWS
Antes de crear una API con la integración privada, debe haber configurado el recurso de VPC y haber
creado y configurado un balanceador de carga de red con el origen de la VPC como el objetivo. Si no se
cumplen los requisitos, siga Configuración de un balanceador de carga de red para integraciones privadas
de API Gateway (p. 366) para instalar el recurso de VPC, crear un balanceador de carga de red y definir
el recurso de VPC como objetivo del balanceador de carga de red.
Note

El balanceador de carga de red y la API deben pertenecer a la misma cuenta de AWS.

Para crear y administrar un VpcLink, también debe haber configurado los permisos correspondientes.
Para obtener más información, consulte Concesión de permisos para crear un enlace VPC (p. 367).
Note

Solo necesita los permisos para crear un VpcLink en la API. No necesita los permisos para
utilizar el VpcLink.

Una vez que haya creado el balanceador de carga de red, anote su ARN. Lo necesitará para crear un
enlace VPC para la integración privada.

Para configurar una API con integración privada a través de la CLI de AWS

1. Cree un enlace VpcLink que tenga como destino el balanceador de carga de red especificado.

En esta explicación, supondremos que el ARN del balanceador de carga de red es

arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/my-
vpclink-test-nlb/1f8df693cd094a72.

aws apigateway create-vpc-link \

--name my-test-vpc-link \
--target-arns arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/
my-vpclink-test-nlb/1f8df693cd094a72

El comando anterior devuelve inmediatamente la siguiente respuesta, donde se acusa la recepción de

la solicitud y se muestra el estado PENDING del enlace VpcLink que se está creando.

{
"status": "PENDING",
"targetArns": [
"arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/my-
vpclink-test-nlb/1f8df693cd094a72"
],
"id": "gim7c3",
"name": "my-test-vpc-link"
}

368
 Amazon API Gateway Guía del desarrollador
Integraciones

API Gateway tarda de 2 a 4 minutos en completar la creación de VpcLink. Si la operación finaliza

correctamente, el valor de status es AVAILABLE. Puede comprobarlo llamando al siguiente
comando de la CLI:

aws apigateway get-vpc-link --vpc-link-id gim7c3

Si se produce un error en la operación, obtendrá el estado FAILED y statusMessage contendrá

el mensaje de error. Por ejemplo, si intenta crear un enlace VpcLink con un balanceador de carga
de red que ya está asociado a un punto de enlace de la VPC, obtendrá lo siguiente en la propiedad
statusMessage:

"NLB is already associated with another VPC Endpoint Service"

Solo si VpcLink se crea correctamente, podremos crear la API e integrarla con el recurso de la VPC
a través de VpcLink.

Anote el valor id del enlace VpcLink creado (gim7c3 en la salida anterior). Lo necesitará para
configurar la integración privada.
2. Configure una API creando un recurso RestApi de API Gateway:

aws apigateway create-rest-api --name 'My VPC Link Test'

Hemos quitado los parámetros de entrada endpoint-url y region para utilizar la región
predeterminada especificada en la configuración de AWS.

Anote el valor id de RestApi del resultado devuelto. En este ejemplo, supondremos que es
6j4m3244we. Necesitará este valor para realizar otras operaciones en la API, como la configuración
de los métodos e integraciones.

A efectos de esta explicación, crearemos una API con un solo método GET en el recurso raíz (/) y lo
integraremos con VpcLink.
3. Configure el método GET /. En primer lugar, obtenga el identificador del recurso raíz (/):

aws apigateway get-resources --rest-api-id 6j4m3244we

En la salida, anote el valor id de la ruta de acceso /. En este ejemplo, supondremos que es

skpp60rab7.

Cree la solicitud del método GET / de la API:

aws apigateway put-method \

--rest-api-id 6j4m3244we \
--resource-id skpp60rab7 \
--http-method GET \
--authorization-type "NONE"

Si desea utilizar los permisos de IAM, un autorizador de Lambda o un grupo de usuarios de Amazon
Cognito para autenticar al intermediario, establezca authorization-type en AWS_IAM, CUSTOM o
COGNITO_USER_POOLS, respectivamente.

Si no utiliza la integración de proxy con VpcLink, también debe configurar al menos un método de
respuesta del código de estado 200. Aquí, utilizaremos la integración de proxy.
4. Configure la integración privada de tipo HTTP_PROXY y llame al comando put-integration tal y
como se indica a continuación:

369
 Amazon API Gateway Guía del desarrollador
Integraciones

aws apigateway put-integration \

--rest-api-id 6j4m3244we \
--resource-id skpp60rab7 \
--uri 'http://myApi.example.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id gim7c3

En las integraciones privadas, debe establecer connection-type en VPC_LINK y connection-id

en el identificador de VpcLink o en una variable de etapa que haga referencia al ID de VpcLink. El
parámetro uri no se utiliza para direccionar las solicitudes al punto de enlace, sino para configurar el
encabezado Host y validar el certificado.

Si la operación se realiza correctamente, el comando devuelve la salida siguiente:

{
"passthroughBehavior": "WHEN_NO_MATCH",
"timeoutInMillis": 29000,
"connectionId": "gim7c3",
"uri": "http://myApi.example.com",
"connectionType": "VPC_LINK",
"httpMethod": "GET",
"cacheNamespace": "skpp60rab7",
"type": "HTTP_PROXY",
"cacheKeyParameters": []
}

Al utilizar una variable de etapa, la propiedad connectionId queda definida al crear la integración:

aws apigateway put-integration \

--rest-api-id 6j4m3244we \
--resource-id skpp60rab7 \
--uri 'http://myApi.example.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkId}"

No olvide utilizar comillas dobles en la expresión de la variable de etapa

(${stageVariables.vpcLinkId}) y utilizar caracteres de escape con $.

Si lo desea, también puede actualizar la integración para restablecer el valor connectionId con una
variable de etapa:

aws apigateway update-integration \

--rest-api-id 6j4m3244we \
--resource-id skpp60rab7 \
--http-method GET \
--patch-operations '[{"op":"replace","path":"/
connectionId","value":"${stageVariables.vpcLinkId}"}]'

No olvide utilizar una lista JSON con forma de cadena como valor del parámetro patch-
operations.

370
 Amazon API Gateway Guía del desarrollador
Integraciones

Si utiliza una variable de etapa para establecer el valor de connectionId, tiene la ventaja de que
puede integrar la misma API con diferentes enlaces VpcLink restableciendo el valor de esta variable.
Esto resulta útil para establecer la API en diferentes enlaces VPC y migrar a otro balanceador de
carga de red u otra VPC.

Como hemos utilizado la integración de proxy privada, ahora la API está lista para la implementación
y para que la prueba se ejecute. En las integraciones que no son de proxy, también debe configurar
la respuesta del método y la integración, al igual que haría al configurar una API con integraciones
personalizadas de HTTP (p. 57).
5. Para probar la API, impleméntela. Esto es necesario si ha utilizado la variable de etapa como
marcador del ID de VpcLink. Para implementar la API con una variable de etapa, llame al comando
create-deployment tal y como se muestra a continuación:

aws apigateway create-deployment \

--rest-api-id 6j4m3244we \
--stage-name test \
--variables vpcLinkId=gim7c3

Para actualizar la variable de etapa con un ID de VpcLink diferente (por ejemplo, asf9d7), llame al
comando update-stage:

aws apigateway update-stage \

--rest-api-id 6j4m3244we \
--stage-name test \
--patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7'

Para probar la API, invóquela utilizando el siguiente comando cURL:

curl -X GET https://6j4m3244we.beta.execute-api.us-east-1.amazonaws.com/test

Si lo desea, también puede escribir la URL de invocación de la API en un navegador web para ver los
resultados.

Si codifica la propiedad connection-id con el literal del ID de VpcLink, también puede llamar a
test-invoke-method para probar la invocación de la API antes de implementarla.

Configuración de una API con integraciones privadas a través de OpenAPI

Puede configurar una API con la integración privada importando el archivo de OpenAPI de la API. La
configuración es similar a las definiciones de OpenAPI de una API con integraciones HTTP, con las
siguientes excepciones:

• Debe establecer connectionType explícitamente en VPC_LINK.

• Debe establecer connectionId explícitamente en el ID de un enlace VpcLink o en una variable de
etapa que haga referencia al ID de un enlace VpcLink.
• El parámetro uri de la integración privada apunta a un punto de enlace HTTP/HTTPS de la VPC, pero
se utiliza para configurar el encabezado Host de la solicitud de integración.
• El parámetro uri de la integración privada que tiene un punto de enlace HTTPS en la VPC se utiliza
para contrastar el nombre de dominio especificado con el del certificado instalado en el punto de enlace
de la VPC.

Puede utilizar una variable de etapa para hacer referencia al ID de VpcLink. También puede asignar el
valor del ID directamente a connectionId.

371
 Amazon API Gateway Guía del desarrollador
Integraciones

El archivo de OpenAPI con formato JSON contiene un ejemplo de una API con un enlace VPC al que hace
referencia una variable de etapa (${stageVariables.vpcLinkId}):

OpenAPI 2.0

{
"swagger": "2.0",
"info": {
"version": "2017-11-17T04:40:23Z",
"title": "MyApiWithVpcLink"
},
"host": "p3wocvip9a.execute-api.us-west-2.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "http://myApi.example.com",
"passthroughBehavior": "when_no_match",
"connectionType": "VPC_LINK",
"connectionId": "${stageVariables.vpcLinkId}",
"httpMethod": "GET",
"type": "http_proxy"
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}

Cuentas de API Gateway utilizadas para integraciones privadas

Los siguientes ID de cuenta de API Gateway específicos de la región se agregan automáticamente al
servicio de punto de enlace de la VPC como AllowedPrincipals cuando se crea un VpcLink.

372
 Amazon API Gateway Guía del desarrollador
Integraciones

Región ID de cuenta

us-east-1 392220576650

us-east-2 718770453195

us-west-1 968246515281

us-west-2 109351309407

ca-central-1 796887884028

eu-west-1 631144002099

eu-west-2 544388816663

eu-west-3 061510835048

eu-central-1 474240146802

eu-north-1 394634713161

ap-northeast-1 969236854626

ap-northeast-2 020402002396

ap-southeast-1 195145609632

ap-southeast-2 798376113853

ap-south-1 507069717855

ap-east-1 174803364771

sa-east-1 287228555773

me-south-1 855739686837

Configurar integraciones simuladas en API Gateway

Amazon API Gateway admite integraciones simuladas para métodos API. Esta característica permite a los
desarrolladores de API generar respuestas de API directamente desde API Gateway sin necesidad de un
backend de integración. Como desarrollador de una API, puede utilizar esta característica para que los
equipos dependientes puedan trabajar con una API antes de que se complete el desarrollo del proyecto.
También puede usar esta característica para aprovisionar una página de inicio para la API, en la que se
proporcione una descripción general de la API y cómo navegar por ella. Para ver un ejemplo de una página
de inicio como esta, consulte la solicitud y la respuesta de integración del método GET en el recurso raíz
de la API de ejemplo que se describe en Tutorial: Crear una API de REST importando un ejemplo (p. 43).

Como desarrollador de una API, puede decidir cómo API Gateway responde a una solicitud de integración
simulada. Para ello, configura la solicitud de integración y la respuesta de integración del método para
asociar una respuesta a un código de estado determinado. Para que un método con la integración
simulada devuelva una respuesta 200, configure la plantilla de asignación del cuerpo de la solicitud de
integración para que devuelva lo siguiente.

{"statusCode": 200}

Configure una respuesta de integración 200 para que tenga la siguiente plantilla de asignación de cuerpo;
por ejemplo:

373
 Amazon API Gateway Guía del desarrollador
Integraciones

{
"statusCode": 200,
"message": "Go ahead without me."
}

De igual modo, para que el método devuelva, por ejemplo, una respuesta de error 500, configure la
plantilla de asignación del cuerpo de la solicitud de integración para que devuelva lo siguiente.

{"statusCode": 500}

Configure una respuesta de integración 500 con, por ejemplo, la siguiente plantilla de asignación:

{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}

Si lo desea, también puede hacer que un método de la integración simulada devuelva la respuesta de
integración predeterminada sin definir la plantilla de asignación de solicitudes de integración. La respuesta
de integración predeterminada es la única que tiene la opción HTTP status regex (Expresión regular de
estado de HTTP) sin definir. Asegúrese de que se establecen los comportamientos de acceso directo
apropiados.
Note
Las integraciones simuladas no se han diseñado para admitir plantillas de respuestas grandes. Si
las necesita para su caso de uso, considere el uso de una integración de Lambda en su lugar.

Si utiliza una plantilla de asignación de solicitudes de integración, puede insertar la lógica de la aplicación
para decidir qué respuesta de integración simulada debe devolverse en función de unas determinadas
condiciones. Por ejemplo, puede utilizar un parámetro de consulta scope en la solicitud de entrada para
determinar si se va a devolver una respuesta de éxito o error:

{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}

De esta forma, el método de la integración simulada permite realizar llamadas internas mientras que otros
tipos de llamadas se rechazan con respuestas de error.

En esta sección, se describe cómo utilizar la consola de API Gateway para habilitar la integración simulada
para un método de la API.

Temas
• Habilitar la integración simulada a través de la consola de API Gateway (p. 374)

Habilitar la integración simulada a través de la consola de API Gateway

El método debe estar disponible en API Gateway. Siga las instrucciones en Tutorial: Desarrollo de una API
de REST con integración HTTP no de proxy (p. 56).

1. Elija un recurso de API y cree un método. En el panel del método Setup (Configuración), seleccione
Mock (Simulación) en Integration type (Tipo de integración) y elija Save (Gaurdar).

374
 Amazon API Gateway Guía del desarrollador
Integraciones

2. En Method Execution (Ejecución del método), elija Method Request (Solicitud de método). Expanda
URL Query String Parameters (Parámetros de cadena de consulta URL). Seleccione Add query string
(Añadir cadena de consulta) para agregar un parámetro de consulta scope. Esto determina si el
intermediario es o no interno.
3. En Method Execution (Ejecución del método), elija Method Response (Respuesta de método).
4. En HTTP Status (Estado HTTP), agregue 500.
5. Seleccione Integration Request (Solicitud de integración) en Method Execution (Ejecución del
método). Expanda Mapping Templates (Plantillas de asignación). Seleccione o añada una plantilla de
asignación application/json. Escriba lo siguiente el editor de la plantilla:

{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}

Elija Save (Guardar).

6. Seleccione Integration Response (Respuesta de integración) en Method Execution (Ejecución del
método). Expanda la respuesta 200 y después la sección Mapping Templates (Plantillas de mapeo).
Elija o agregue una plantilla de mapeo application/json y escriba la siguiente plantilla de mapeo de
cuerpo de respuesta en el editor de la plantilla.

{
"statusCode": 200,
"message": "Go ahead without me"
}

Elija Save (Guardar).

7. Seleccione Add integration response (Añadir respuesta de integración) para agregar una respuesta
500. Escriba 5\d{2} en HTTP status regex (Expresión regular de estado de HTTP). En Method
response status (Estado de respuesta del método), elija 500 y, a continuación, Save (Guardar).
8. Expanda 5\d{2} y, a continuación, Mapping Templates (Plantillas de mapeo) y elija Add mapping
template (Agregar plantilla de mapeo). Escriba application/json para Content-Type (Tipo de
contenido) y, a continuación, elija el icono de marca de comprobación para guardar el valor. En el
editor de la plantilla, escriba la siguiente plantilla de mapeo de cuerpo de respuesta de integración:

{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}

Elija Save (Guardar).

9. Elija Test (Probar) en Method Execution (Ejecución del método). Haga lo siguiente:

a. Escriba scope=internal en Query Strings (Cadenas de consulta). Elija Test. El resultado de la

prueba es:

Request: /?scope=internal
Status: 200
Latency: 26 ms
Response Body

375
 Amazon API Gateway Guía del desarrollador
Validación de solicitudes

"statusCode": 200,
"message": "Go ahead without me"
}

Response Headers

{"Content-Type":"application/json"}

b. Escriba scope=public en Query Strings o déjelo en blanco. Elija Test. El resultado de la

prueba es:

Request: /
Status: 500
Latency: 16 ms
Response Body

{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}

Response Headers

{"Content-Type":"application/json"}

También puede devolver los encabezados de una respuesta de integración simulada agregando primero
un encabezado a la respuesta del método y configurando después una asignación de encabezado en la
respuesta de integración. De hecho, es así como la consola de API Gateway permite la compatibilidad con
CORS, devolviendo los encabezados requeridos por CORS.

Habilitar la validación de solicitudes en API Gateway

Puede configurar API Gateway para que realice una validación básica de una solicitud de API antes
de continuar con la solicitud de integración. Cuando no se supera la validación, API Gateway invalida
inmediatamente la solicitud, devuelve una respuesta de error 400 al intermediario y publica los resultados
de la validación en logs de CloudWatch Logs. Esto reduce las llamadas innecesarias al backend. Y lo que
es más importante, le permite centrarse en el trabajo de validación específico de su aplicación.

Temas
• Información general de la validación básica de solicitudes en API Gateway (p. 376)
• Configuración de la validación básica de solicitudes en API Gateway (p. 377)
• Prueba de la validación básica de solicitudes en API Gateway (p. 383)
• Definiciones de OpenAPI de una API de ejemplo con la validación básica de solicitudes (p. 386)

Información general de la validación básica de solicitudes en API

Gateway
API Gateway puede realizar la validación básica. Este le permite a usted, como desarrollador de la API,
centrarse en una validación más detallada específica de su aplicación en el backend. Para la validación
básica, API Gateway verifica una o ambas de las condiciones siguientes:

• Los parámetros de la solicitud necesarios en el URI, cadena de consulta y encabezados de una solicitud
de entrada están presentes y no están vacíos.

376
 Amazon API Gateway Guía del desarrollador
Validación de solicitudes

• La carga de la solicitud aplicable sigue el modelo (p. 395) de solicitud del esquema JSON del método.

Para habilitar la validación básica, especifica reglas de validación en un validador de solicitudes, agregue
el validador al mapa de validadores de solicitudes de la API y asigne el validador a métodos de la API
individuales.
Note

Solicitar la validación del cuerpo y solicitar el "acceso directo" (o passthrough) al cuerpo (p. 424)
son dos cosas distintas. Cuando una carga de solicitud no se puede validar porque no se
encuentra un esquema de modelo coincidente, puede elegir acceder directamente a ella
(passthrough) o bloquear la carga original.
Por ejemplo, cuando se habilita la validación de solicitudes con una plantilla de mapeo para el
tipo de medios application/json, es posible que desee transmitir una carga XML a través del
backend aún sabiendo que la validación de solicitudes habilitada devolverá un error. Este puede
ser el caso si espera que la carga XML sea compatible con el método en el futuro. Para que la
solicitud con una carga XML devuelva un error, debe elegir la opción NEVER en el comportamiento
de "acceso directo" (o passthrough) del contenido.

Configuración de la validación básica de solicitudes en API

Gateway
Puede configurar validadores de solicitudes en un archivo de definición de OpenAPI de la API y después
importar las definiciones de OpenAPI en API Gateway. También puede configurarlos en la consola de API
Gateway o llamando a la API REST de API Gateway, a la CLI de AWS o a uno de los SDK de AWS. Aquí,
le mostramos cómo hacer esto con un archivo de OpenAPI, en la consola, y usando la API REST de API
Gateway.

Temas
• Configuración de la validación básica de solicitudes importando la definición de OpenAPI (p. 377)
• Configurar validadores de solicitudes mediante la API REST de API Gateway (p. 381)
• Configurar la validación básica de solicitudes mediante la consola de API Gateway (p. 382)

Configuración de la validación básica de solicitudes importando la definición de

OpenAPI
Los siguientes pasos describen cómo habilitar la validación básica de solicitudes importando un archivo de
OpenAPI.

Para habilitar la validación de solicitudes importando un archivo de OpenAPI en API Gateway

1. Declare los validadores de solicitudes en OpenAPI especificando un conjunto de los objetos Objeto
x-amazon-apigateway-request-validators.requestValidator (p. 804) en el mapa Objeto x-amazon-
apigateway-request-validators (p. 803) en el nivel de API. Por ejemplo, el archivo de OpenAPI de la
API de ejemplo (p. 386) contiene el mapa x-amazon-apigateway-request-validators, con
los nombres de los validadores como claves.

OpenAPI 3.0

{
"openapi": "3.0.0",
"info": {
"title": "ReqValidation Sample",
"version": "1.0.0"
},
"servers": [

377
 Amazon API Gateway Guía del desarrollador
Validación de solicitudes

{
"url": "/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"x-amazon-apigateway-request-validators": {
"all": {
"validateRequestBody": true,
"validateRequestParameters": true
},
"params-only": {
"validateRequestBody": false,
"validateRequestParameters": true
}
}
}

OpenAPI 2.0

{
"swagger": "2.0",
"info": {
"title": "ReqValidation Sample",
"version": "1.0.0"
},
"schemes": [
"https"
],
"basePath": "/v1",
"produces": [
"application/json"
],
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
"params-only" : {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
},
...
}

El nombre de un validador se selecciona cuando se habilita el validador en la API o en un método, tal

y como se muestra en el siguiente paso.
2. Para habilitar un validador de solicitudes en todos los métodos de una API, especifique una propiedad
Propiedad x-amazon-apigateway-request-validator (p. 803) en el nivel de API del archivo de
definición de OpenAPI de la API. Para habilitar un validador de solicitudes para un método individual,
especifique la propiedad x-amazon-apigateway-request-validator en el nivel de método. Por
ejemplo, la siguiente propiedad x-amazon-apigateway-request-validator habilita el validador
params-only en todos los métodos de la API, a menos que se invalide de otro modo.

OpenAPI 3.0

378
 Amazon API Gateway Guía del desarrollador
Validación de solicitudes

"openapi": "3.0.0",
"info": {
"title": "ReqValidation Sample",
"version": "1.0.0"
},
"servers": [
{
"url": "/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"x-amazon-apigateway-request-validator": "params-only",
...
}

OpenAPI 2.0

{
"swagger": "2.0",
"info": {
"title": "ReqValidation Sample",
"version": "1.0.0"
},
"schemes": [
"https"
],
"basePath": "/v1",
"produces": [
"application/json"
],
...
"x-amazon-apigateway-request-validator" : "params-only",
...
}

Para habilitar un validador de solicitudes para un método individual, especifique la propiedad x-

amazon-apigateway-request-validator en el nivel de método. Por ejemplo, la siguiente
propiedad x-amazon-apigateway-request-validator habilita el validador all en el método
POST /validation. Este validador invalida el validador params-only que se hereda de la API.

OpenAPI 3.0

{
"openapi": "3.0.0",
"info": {
"title": "ReqValidation Sample",
"version": "1.0.0"
},
"servers": [
{
"url": "/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],

379
 Amazon API Gateway Guía del desarrollador
Validación de solicitudes

"paths": {
"/validation": {
"post": {
"x-amazon-apigateway-request-validator": "all",
...
}
}
}
...
}

OpenAPI 2.0

{
"swagger": "2.0",
"info": {
"title": "ReqValidation Sample",
"version": "1.0.0"
},
"schemes": [
"https"
],
"basePath": "/v1",
"produces": [
"application/json"
],
...
"paths": {
"/validation": {
"post": {
"x-amazon-apigateway-request-validator" : "all",
...
},
...
}
}
...
}

3. En API Gateway, cree la API con validadores de solicitudes habilitados importando esta definición de
OpenAPI de ejemplo (p. 386):

POST /restapis?mode=import&failonwarning=true HTTP/1.1

Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20170306T234936Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170306/us-east-1/
apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date,
Signature={sig4_hash}

Copy the JSON object from this sample OpenAPI definition (p. 386) and paste it here.

4. Implemente la API recién creada (fjd6crafxc) en una etapa específica (testStage).

POST /restapis/fjd6crafxc/deployments HTTP/1.1

Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20170306T234936Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170306/us-east-1/
apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date,
Signature={sig4_hash}

380
 Amazon API Gateway Guía del desarrollador
Validación de solicitudes

{
"stageName" : "testStage",
"stageDescription" : "Test stage",
"description" : "First deployment",
"cacheClusterEnabled" : "false"
}

Para obtener instrucciones sobre cómo probar la validación de solicitudes mediante la API REST
de API Gateway, consulte Probar la validación básica de solicitudes mediante la API REST de API
Gateway (p. 383). Para obtener instrucciones sobre cómo realizar las pruebas mediante la consola
de API Gateway, consulte Probar la validación básica de solicitudes mediante la consola de API
Gateway (p. 386).

Configurar validadores de solicitudes mediante la API REST de API Gateway

En la API REST de API Gateway, un validador de solicitudes se representa mediante un recurso
RequestValidator. Para que una API admita los mismos validadores de solicitudes que la API de
ejemplo (p. 386), agregue a la colección RequestValidators un validador de solo parámetros con
params-only como clave y agregue un validador completo con all como clave.

Para habilitar la validación básica de solicitudes mediante la API REST de API Gateway

Suponemos que tiene una API similar a la API de ejemplo (p. 386), pero que no ha
configurado validadores de solicitudes. Si su API ya tiene validadores de solicitudes, llame
a la acción requestvalidator:update o method:put correspondiente en lugar de a
requestvalidator:create o method:put.

1. Para configurar el validador de solicitudes params-only, llame a la acción requestvalidator:create

como se indica a continuación:

POST /restapis/restapi-id/requestvalidators HTTP/1.1

Content-Type: application/json
Host: apigateway.region.amazonaws.com
X-Amz-Date: 20170223T172652Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170223/region/apigateway/
aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature={sig4_hash}

{
"name" : "params-only",
"validateRequestBody" : "false",
"validateRequestParameters" : "true"
}

2. Para configurar el validador de solicitudes all, llame a la acción requestvalidator:create del

siguiente modo:

POST /restapis/restapi-id/requestvalidators HTTP/1.1

Content-Type: application/json
Host: apigateway.region.amazonaws.com
X-Amz-Date: 20170223T172652Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170223/region/apigateway/
aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature={sig4_hash}

{
"name" : "all",
"validateRequestBody" : "true",
"validateRequestParameters" : "true"
}

381
 Amazon API Gateway Guía del desarrollador
Validación de solicitudes

Si las claves del validador anteriores ya existen en el mapa RequestValidators, llame a la acción
requestvalidator:update en lugar de restablecer las reglas de validación.
3. Para aplicar el validador de solicitudes