Types de supports binaires pour les API REST dans API Gateway - Amazon API Gateway
Intégrations de proxy AWS LambdaIntégrations autres que de proxy

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Types de supports binaires pour les API REST dans API Gateway

Dans API Gateway, la demande et la réponse d’API peuvent avoir une charge utile textuelle ou binaire. Une charge utile de texte est une chaîne JSON codée en UTF-8. Une charge utile binaire est tout élément autre qu’une charge utile textuelle. Par exemple, une charge utile binaire peut être un fichier JPEG, un fichier GZip ou un fichier XML. La configuration d’API requise pour prendre en charge les supports binaires varie selon que votre API utilise des intégrations de proxy ou autre que de proxy.

Intégrations de proxy AWS Lambda

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

API Gateway utilise le premier en-tête Accept des clients pour déterminer si une réponse doit renvoyer un support binaire. Pour renvoyer un support binaire lorsque vous ne pouvez pas contrôler l’ordre des valeurs d’en-tête Accept, telles que les demandes d’un navigateur, définissez les types de supports binaires de votre API sur */*.

Pour obtenir un exemple de code, consultez Renvoi d’un support binaire d’une intégration de proxy Lambda dans API Gateway.

Intégrations autres que de proxy

Pour gérer les charges utiles binaires pour les intégrations autres que de proxy, ajoutez les types de supports à la liste binaryMediaTypes de la ressource RestApi. La configuration binaryMediaTypes de votre API est une liste de types de contenu que votre API traite comme des données binaires. Vous pouvez également définir les propriétés contentHandling sur les ressources Integration et IntegrationResponse. La valeur contentHandling peut être CONVERT_TO_BINARY, CONVERT_TO_TEXT ou indéfinie.

Note

Pour les intégrations MOCK ou privées, la définition des propriétés contentHandling n’est pas prise en charge dans la AWS Management Console. Vous devez utiliser l’AWS CLI, AWS CloudFormation ou un kit SDK pour définir les propriétés contentHandling.

Selon la valeur de contentHandling et si l’en-tête Content-Type de la réponse ou l’en-tête Accept de la demande entrante correspond à une entrée de la liste binaryMediaTypes, 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 obtenir les octets bruts ou passer le corps sans modification.

Vous devez configurer l’API comme suit pour prendre en charge les charges utiles binaires de votre API API Gateway :

  • Ajoutez les types de supports binaires souhaités pour la liste binaryMediaTypes sur la ressource RestApi. Si cette propriété et la propriété contentHandling ne sont pas définies, les charges utiles sont traitées en tant que chaînes JSON codées 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 que Content-Type correspond à l’une des entrées binaryMediaTypes et que les comportements de transmission sont activés pour l’API.

  • Définissez la propriété contentHandling de la ressource IntegrationResponse. La propriété contentHandling, l’en-tête Accept dans les demandes client et les binaryMediaTypes de vos API déterminent la façon dont API Gateway gère les conversions de type de contenu. Pour en savoir plus, consultez Conversions du type de contenu dans API Gateway.

Important

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

Par exemple, pour envoyer un fichier JPEG en utilisant un élément <img> dans un navigateur, ce dernier peut envoyer Accept:image/webp,image/*,*/*;q=0.8 dans une demande. Si vous ajoutez image/webp à la liste binaryMediaTypes, le point de terminaison reçoit le fichier JPEG sous forme binaire.

Pour plus d’informations sur la façon dont API Gateway gère les charges utiles textuelles et binaires, consultez Conversions du type de contenu dans API Gateway.