Tutorial: Creación de una API de REST como proxy de Amazon S3

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 GET en un recurso de carpeta o elemento para ver o descargar un objeto de un bucket de Amazon S3.

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 un proxy de Amazon S3. Este ejemplo contiene métodos más expuestos. Para obtener instrucciones sobre cómo importar una API mediante la definición de OpenAPI, consulte Desarrollo de API de REST mediante OpenAPI en API Gateway.

nota

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.

Temas

• Configurar permisos de IAM para que la API invoque acciones de Amazon S3
• Crear recursos de API para representar recursos de Amazon S3
• Exponer un método de API para enumerar los buckets de Amazon S3 del intermediario
• Exponer métodos de API para tener acceso a un bucket de Amazon S3
• Exponer métodos de API para tener acceso a un objeto de Amazon S3 en un bucket
• Definiciones de OpenAPI de la API de ejemplo como un proxy de Amazon S3
• Llamar a la API mediante un cliente API de REST

Configurar permisos de IAM para que la API invoque acciones de Amazon S3

Para permitir que la API invoque las acciones de Amazon S3, debe tener las políticas de IAM adecuadas asociadas a un rol de IAM.

Para crear el rol de ejecución del proxy de servicio de AWS

1. Inicie sesión en AWS Management Console Management Console y abra la consola IAM en https://console.aws.amazon.com/iam/.

2. Elija Roles.

3. Elija Crear rol.

4. Elija Servicio de AWS en Seleccionar el tipo de entidad de confianza y, a continuación, elija API Gateway y seleccione Permite que API Gateway envíe registros a CloudWatch Logs.

5. Seleccione Siguiente y de nuevo Siguiente.

6. En Role name (Nombre de rol), escriba APIGatewayS3ProxyPolicy y luego elija Create role (Crear rol).

7. En la lista Roles (Roles), elija el rol que acaba de crear. Puede que tenga que desplazarse o usar la barra de búsqueda para encontrar el rol.

8. Para el rol seleccionado, seleccione la pestaña Agregar permisos.

9. Elija Adjuntar políticas en la lista desplegable.

10. En la barra de búsqueda, escriba AmazonS3FullAccess y, a continuación, elija Añadir permisos.

    nota

    Para simplificar el proceso, este tutorial utiliza una política administrada. Como práctica recomendada, se deben crear políticas de IAM propias para otorgar los permisos mínimos requeridos.

11. Anote el ARN del rol recién creado, ya que lo usará más adelante.

Crear recursos de API para representar recursos de Amazon S3

Debe utilizar el recurso raíz (/) de la API como contenedor de buckets de Amazon S3 de un intermediario autenticado. También debe crear los recursos Folder y Item para representar un bucket de Amazon 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.

nota

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 misma Región de AWS que creó el bucket de Amazon S3, cree una API llamada MyS3. Este recurso raíz de la API (/) representa el servicio Amazon S3. En este paso, creará dos recursos adicionales,/{folder} y /{item}.

2. Elija Crear recurso.

3. Mantenga Recurso proxy desactivado.

4. En Ruta de recurso, seleccione /.

5. En Nombre del recurso, escriba {folder}.

6. Mantenga desactivado CORS (uso compartido de recursos entre orígenes).

7. Elija Crear recurso.

8. Seleccione el recurso /{folder} y, a continuación, elija Crear recurso.

9. Siga los pasos anteriores para crear un recurso secundario de /{folder} denominado {item}.

   Su API final debería parecerse a la siguiente:

   

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. Seleccione el recurso / y, a continuación, elija Crear método.

2. En el tipo de método, seleccione GET.

3. En Tipo de integración, seleccione Servicio de AWS.

4. Para Región de AWS, seleccione la Región de AWS donde creó su bucket de Amazon S3.

5. Para Servicio de AWS, elija Amazon Simple Storage Service.

6. Deje Subdominio de AWS en blanco.

7. En Método HTTP, seleccione GET.

8. En Tipo de acción, elija Usar sustitució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. En Sustitución de ruta, escriba /.

10. En Rol de ejecución, escriba el ARN del rol para APIGatewayS3ProxyPolicy.

11. Elija Configuración de solicitud de método.

    Debe utilizar la configuración de solicitud de método para controlar quién puede llamar a este método de la API.

12. En Autorización, en el menú desplegable, seleccione AWS_IAM.

    

13. Elija Crear 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.

Para que la API devuelva respuestas correctas y excepciones al intermediario, debe declarar las respuestas 200, 400 y 500 en Respuesta de método. Debe utilizar la asignación predeterminada 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 la pestaña Respuesta del método, en Respuesta 200, elija Editar.

2. Elija Añadir encabezado y haga lo siguiente:

   1. En Nombre de encabezado, escriba Content-Type.

   2. Elija Add header (Añadir encabezado).

   Repita estos pasos para crear un encabezado Timestamp y un encabezado Content-Length.

3. Seleccione Guardar.

4. En la pestaña Método de respuesta, en Respuestas de método, seleccione Crear respuesta.

5. En Código de estado HTTP, introduzca 400.

   No establezca ningún encabezado para esta respuesta.

6. Seleccione Guardar.

7. Repita los pasos siguientes para crear la respuesta 500.

   No establezca ningún encabezado para esta respuesta.

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, debe 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 la respuesta sea en realidad una cadena XML. El siguiente procedimiento muestra cómo realizar esta configuración. Además, también quiere 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 pestaña Respuesta de integración, en Predeterminado: respuesta, seleccione Editar.

2. Para el encabezado Content-Length, introduzca integration.response.header.Content-Length en el valor de mapeo.

3. Para el encabezado Content-Type, introduzca integration.response.header.Content-Type en el valor de mapeo.

4. Para el encabezado Timestamp, introduzca integration.response.header.Date en el valor de mapeo.

5. Seleccione Guardar. El resultado debería ser similar al siguiente:

   

6. En la pestaña Respuesta de integración, en Respuestas de integración, seleccione Crear respuesta.

7. En HTTP status regex (Expresión regular de estado HTTP), escriba 4\d{2}. Esto asigna todos los códigos de estado de respuesta HTTP 4xx a la respuesta del método.

8. En Código de estado de respuesta del método, seleccione 400.

9. Seleccione Crear.

10. Repita los siguientes pasos para crear una respuesta de integración para la respuesta del método 500. En HTTP status regex (Expresión regular de estado HTTP), escriba 5\d{2}.

Como práctica recomendada, puede probar la API tal y como está configurada de momento.

Para probar el método GET /

1. Elija la pestaña Prueba. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.

2. Seleccione Probar. El resultado debe ser similar al de la siguiente imagen:

   

Exponer métodos de API para tener acceso a un bucket de Amazon S3

Para trabajar con un bucket de Amazon S3, exponga el método GET en el recurso /{folder} para mostrar los objetos de un bucket. 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. Para ver más métodos, puede importar la API de ejemplo aquí, Definiciones de OpenAPI de la API de ejemplo como un proxy de Amazon S3.

Para exponer el método GET en un recurso de carpeta

1. Seleccione el recurso /{folder} y, a continuación, elija Crear método.

2. En el tipo de método, seleccione GET.

3. En Tipo de integración, seleccione Servicio de AWS.

4. Para Región de AWS, seleccione la Región de AWS donde creó su bucket de Amazon S3.

5. Para Servicio de AWS, elija Amazon Simple Storage Service.

6. Deje Subdominio de AWS en blanco.

7. En Método HTTP, seleccione GET.

8. En Tipo de acción, elija Usar sustitución de ruta.

9. En Sustitución de ruta, escriba {bucket}.

10. En Rol de ejecución, escriba el ARN del rol para APIGatewayS3ProxyPolicy.

11. Elija Crear método.

Establezca el parámetro de ruta {folder} en la URL del punto de conexión de Amazon S3. Debe mapear el parámetro de ruta {folder} de la solicitud de método al parámetro de ruta {bucket} de la solicitud de integración.

Para mapear {folder} a {bucket}:

1. En la pestaña Solicitud de integración, en Configuración de la solicitud de integración, seleccione Editar.

2. Elija Parámetros de la ruta URL y, a continuación, elija Agregar parámetro de ruta.

3. En Nombre, escriba bucket.

4. En Mapeado de, introduzca method.request.path.folder.

5. Seleccione Guardar.

Ahora, pruebe la API.

Para probar el método /{folder} GET

1. Elija la pestaña Prueba. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.

2. En Ruta, para la carpeta, introduzca el nombre de tu bucket.

3. Seleccione Probar.

   El resultado de la prueba incluirá una lista de los objetos del bucket.

   

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. En este tutorial, expondrá un método GET del recurso {folder}/{item} para obtener una imagen de un bucket. Para ver más aplicaciones del recurso {folder}/{item}, consulte la API de ejemplo, Definiciones de OpenAPI de la API de ejemplo como un proxy de Amazon S3.

Para exponer el método GET en un recurso de elemento

1. Seleccione el recurso /{item} y, a continuación, elija Crear método.

2. En el tipo de método, seleccione GET.

3. En Tipo de integración, seleccione Servicio de AWS.

4. Para Región de AWS, seleccione la Región de AWS donde creó su bucket de Amazon S3.

5. Para Servicio de AWS, elija Amazon Simple Storage Service.

6. Deje Subdominio de AWS en blanco.

7. En Método HTTP, seleccione GET.

8. En Tipo de acción, elija Usar sustitución de ruta.

9. En Sustitución de ruta, introduzca {bucket}/{object}.

10. En Rol de ejecución, escriba el ARN del rol para APIGatewayS3ProxyPolicy.

11. Elija Crear método.

Establezca los parámetros de ruta {folder} y {item} en la URL del punto de conexión de Amazon S3. Debe mapear el parámetro de ruta de la solicitud de método al parámetro de ruta de la solicitud de integración.

En este paso, hará lo siguiente:

• Mapee el parámetro de ruta {folder} de la solicitud de método al parámetro de ruta {bucket} de la solicitud de integración.

• Mapee el parámetro de ruta {item} de la solicitud de método al parámetro de ruta {object} de la solicitud de integración.

Para mapear {folder} a {bucket} y {item} a {object}

1. En la pestaña Solicitud de integración, en Configuración de la solicitud de integración, seleccione Editar.

2. Elija los Parámetros de la ruta URL.

3. Elija Añadir parámetro de ruta.

4. En Nombre, escriba bucket.

5. En Mapeado de, introduzca method.request.path.folder.

6. Elija Añadir parámetro de ruta.

7. En Nombre, escriba object.

8. En Mapeado de, introduzca method.request.path.item.

9. Seleccione Guardar.

Para probar el método /{folder}/{object} GET

1. Elija la pestaña Prueba. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.

2. En Ruta, para la carpeta, introduzca el nombre de tu bucket.

3. En Ruta, para el elemento, introduzca el nombre de un elemento.

4. Seleccione Probar.

   El cuerpo de la respuesta incluirá el contenido del elemento.

   

   La solicitud devuelve correctamente el texto sin formato ("Hello world") como el contenido del archivo especificado (test.txt) en el bucket de Amazon S3 indicado (DOC-EXAMPLE-BUCKET).

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:

   1. Elija Configuración de API para la API.

   2. En Tipos de medios binarios, seleccione Gestionar tipos de medios.

   3. Seleccione Añadir tipo de medio binario y, a continuación, introduzca el tipo de medio requerido, por ejemplo, image/png.

   4. 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, consulte Comportamiento del acceso directo a la integración y Seleccionar una plantilla de asignación VTL.

El límite de tamaño de carga es 10 MB. Consulte Cuotas de API Gateway para configurar y ejecutar una API REST.

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.