Tipos de medios binarios para las API de REST en API Gateway
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 Devolución de medios binarios desde una integración de proxy de Lambda en API Gateway.
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 lacontentHandling
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 debinaryMediaTypes
y que los comportamientos del acceso directo están habilitados para la API.
-
-
Establezca la propiedad
contentHandling
del recurso IntegrationResponse. La propiedadcontentHandling
, el encabezadoAccept
en las solicitudes de cliente y losbinaryMediaTypes
de su API combinados determinan cómo API Gateway trata las conversiones de los tipos de contenido. Para obtener 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.