Trabajar con tipos de medios binarios para API REST

En API Gateway, la solicitud y respuesta de la API tienen una carga de texto o binaria. Una carga de texto es una cadena JSON codificada en UTF-8. Una carga binaria es cualquier otra cosa distinta de una carga de texto. La carga binaria puede ser, por ejemplo, un archivo JPEG, un archivo GZip o un archivo XML. La configuración de la API necesaria para admitir medios binarios depende de si la API utiliza integraciones de proxy o que no son de proxy.

Integraciones proxy de AWS Lambda

Para tratar cargas útiles binarias para integraciones proxy de AWS Lambda, debe codificar a base64 la respuesta de su función. También debe configurar binaryMediaTypes para su API. La configuración binaryMediaTypes de su API es una lista de tipos de contenido que su API trata como datos binarios. Los tipos de medios binarios de ejemplo incluyen image/png o application/octet-stream. Puede utilizar el carácter comodín (*) para cubrir varios tipos de medios. Por ejemplo, */* incluye todos los tipos de contenido.

Para ver el código de ejemplo, consulte Devolver medios binarios desde una integración de proxy de Lambda.

Integraciones que no son de proxy

Para tratar cargas binarias para integraciones que no son de proxy, agregue los tipos de medios a la lista binaryMediaTypes del recurso RestApi. La configuración binaryMediaTypes de su API es una lista de tipos de contenido que su API trata como datos binarios. Como alternativa, puede establecer las propiedades contentHandling en los recursos Integration e IntegrationResponse. El valor contentHandling puede ser CONVERT_TO_BINARY, CONVERT_TO_TEXT o no estar definido.

En función del valor de contentHandling y de si el encabezado Content-Type de la respuesta o el encabezado Accept de la solicitud coinciden con una entrada de la lista binaryMediaTypes, API Gateway puede codificar los bytes binarios sin formato como una cadena codificada en base64, descodificar una cadena codificada en base64 en sus bytes sin formato o transferir el cuerpo sin realizar ninguna modificación.

Debe configurar la API como se indica a continuación para que su API de API Gateway admita cargas binarias:

• Agregue los tipos de medios binarios que desee a la lista binaryMediaTypes en el recurso RestApi. Si esta propiedad y la contentHandling propiedad no se definen, las cargas se administran como cadenas JSON codificadas en UTF-8.

• Diríjase a la propiedad contentHandling del recurso Integration.

  • Para que la carga de solicitud se convierta de una cadena codificada en base64 a su blob binario, establezca la propiedad en CONVERT_TO_BINARY.

  • Para que la carga de solicitud se convierta de un blob binario a una cadena codificada en base64, establezca la propiedad en CONVERT_TO_TEXT.

  • Para pasar la carga útil sin modificaciones, deje la propiedad sin definir. Para pasar una carga binaria sin modificaciones, también debe asegurarse de que Content-Type coincide con una de las entradas de binaryMediaTypes y que los comportamientos del acceso directo están habilitados para la API.

• Establezca la propiedad contentHandling del recurso IntegrationResponse. La propiedad contentHandling, el encabezado Accept en las solicitudes de cliente y los binaryMediaTypes de su API combinados determinan cómo API Gateway trata las conversiones de los tipos de contenido. Para más información, consulte Conversiones de tipo de contenido en API Gateway.

importante

Cuando una solicitud contiene varios tipos de medios en su encabezado Accept, API Gateway solo respeta el primer tipo de medio Accept. Si no puede controlar el orden de los tipos de medios Accept y el tipo de medio del contenido binario no sea el primero de la lista, agregue el primer tipo de medio Accept en la lista binaryMediaTypes de la API. API Gateway gestiona todos los tipos de contenido de esta lista como binarios.

Por ejemplo, para enviar un archivo JPEG utilizando un elemento <img> en un navegador, el navegador puede enviar Accept:image/webp,image/*,*/*;q=0.8 en una solicitud. Al añadir image/webp a la lista binaryMediaTypes, el punto de enlace recibe el archivo JPEG como binario.

Para obtener información detallada sobre cómo API Gateway trata el texto y las cargas binarias, consulte Conversiones de tipo de contenido en API Gateway.