Types de médias binaires pour REST APIs dans API Gateway

Dans API Gateway, la API demande et la réponse ont une charge utile textuelle ou binaire. Une charge utile de texte est une chaîne UTF-8 codéeJSON. Une charge utile binaire est tout élément autre qu'une charge utile textuelle. La charge utile binaire peut être, par exemple, un JPEG fichier, un GZip fichier ou un XML fichier. La API configuration requise pour prendre en charge les supports binaires varie selon que vous utilisez API des intégrations avec ou sans proxy.

AWS Lambda intégrations de proxy

Pour gérer les charges utiles binaires pour les intégrations de AWS Lambda proxy, vous devez encoder la réponse de votre fonction en base64. Vous devez également configurer le binaryMediaTypespour votreAPI. Votre binaryMediaTypes configuration API est une liste de types de contenus que vous API traitez comme des données binaires. Par exemple, les types de média binaire incluent image/png ou application/octet-stream. Vous pouvez utiliser le caractère générique (*) pour couvrir plusieurs types de support. Par exemple, */* inclut tous les types de contenu.

Pour obtenir un exemple de code, consultez Renvoie un média binaire à partir d'une intégration de proxy Lambda dans Gateway API.

Intégrations non proxy

Pour gérer les charges utiles binaires pour les intégrations sans proxy, vous devez ajouter les types de média à la binaryMediaTypesliste de la ressource. RestApi Votre binaryMediaTypes configuration API est une liste de types de contenus que vous API traitez comme des données binaires. Vous pouvez également définir les contentHandlingpropriétés de l'intégration et des IntegrationResponseressources. La valeur contentHandling peut être CONVERT_TO_BINARY, CONVERT_TO_TEXT ou indéfinie.

Selon la contentHandling valeur et si l'Content-Typeen-tête de la réponse ou de la demande entrante correspond à une entrée de la binaryMediaTypes liste, API Gateway peut encoder les octets binaires bruts sous forme de chaîne codée en base64, décoder une chaîne codée en base64 pour la ramener à ses octets bruts ou en faire passer le corps sans modification. Accept

Vous devez configurer les éléments API suivants pour prendre en charge les charges utiles binaires pour votre API in API Gateway :

• Ajoutez les types de supports binaires souhaités à la binaryMediaTypes liste de la RestApiressource. Si cette propriété et la contentHandling propriété ne sont pas définies, les charges utiles sont traitées sous forme de chaînes codées JSON en UTF -8.

• Adressez la propriété contentHandling de la ressource Integration.

  • Pour que la charge utile de la demande soit convertie d'une chaîne codée en Base64 en son blob binaire, définissez la propriété sur CONVERT_TO_BINARY.

  • Pour que la charge utile de la demande soit convertie d'un blob binaire en une chaîne codée en Base64, définissez la propriété sur CONVERT_TO_TEXT.

  • Pour transmettre la charge utile sans modification, laissez la propriété indéfinie. Pour transmettre une charge utile binaire sans modification, vous devez également vous assurer qu'elle Content-Type correspond à l'une des binaryMediaTypes entrées et que les comportements de transmission sont activés pour le. API

• Définissez la contentHandling propriété de la IntegrationResponseressource. La contentHandling propriété, l'Accepten-tête des demandes des clients et la vôtre binaryMediaTypes combinés déterminent API la manière dont API Gateway gère les conversions par type de contenu. Pour plus de détails, consultez Conversions de type de contenu dans API Gateway.

Important

Lorsqu'une demande contient plusieurs types de média dans son Accept en-tête, API Gateway honore uniquement le premier type de Accept média. Si vous ne pouvez pas contrôler l'ordre des types de Accept média et que le type de média de votre contenu binaire n'est pas le premier de la liste, ajoutez le premier type de Accept média dans la binaryMediaTypes liste de votreAPI. APIGateway gère tous les types de contenu de cette liste sous forme binaire.

Par exemple, pour envoyer un JPEG fichier à l'aide d'un <img> élément d'un navigateur, le navigateur peut envoyer Accept:image/webp,image/*,*/*;q=0.8 une demande. En l'ajoutant image/webp à la binaryMediaTypes liste, le point de terminaison reçoit le JPEG fichier sous forme binaire.

Pour des informations détaillées sur la façon dont API Gateway gère les charges utiles textuelles et binaires, consultezConversions de type de contenu dans API Gateway.