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 médias binaires pour REST APIs 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. La charge utile binaire peut être, par exemple, un fichier JPEG, un GZip fichier 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. Si vous utilisez une intégration proxy avec le streaming de réponse à la charge utile, vous n'avez pas besoin de configurer vos types de médias binaires. Pour de plus amples informations, veuillez consulter [Diffusez la réponse d'intégration pour vos intégrations de proxy dans API Gateway](response-transfer-mode.md). ## 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 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-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](lambda-proxy-binary-media.md). Si vous utilisez une intégration de proxy Lambda avec le streaming de réponse à la charge utile, vous n'avez pas besoin de configurer vos types de supports binaires. Pour de plus amples informations, veuillez consulter [Configurer une intégration de proxy Lambda avec le streaming des réponses de charge utile dans API Gateway](response-transfer-mode-lambda.md). ## Intégrations autres que de proxy Pour gérer les charges utiles binaires pour les intégrations sans proxy, vous devez ajouter les types de média à la [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)liste 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](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) sur l'intégration et les ressources. [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 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 le AWS CLI CloudFormation, ou un SDK pour définir les `contentHandling` propriétés. 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 à la `binaryMediaTypes` liste de la [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource. 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](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). + 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](integration-passthrough-behaviors.md) sont activés pour l’API. + Définissez la `contentHandling` propriété de la [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)ressource. 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](api-gateway-payload-encodings-workflow.md). **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 `` 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](api-gateway-payload-encodings-workflow.md). # Conversions du type de contenu dans API Gateway La combinaison des `binaryMediaTypes` de vos API, les en-têtes dans les demandes client et la propriété `contentHandling` d’intégration déterminent la manière dont API Gateway encode les charges utiles. Le tableau suivant montre comment API Gateway convertit la charge utile de la demande pour des configurations spécifiques de l'`Content-Type`en-tête d'une demande, de la `binaryMediaTypes` liste d'une [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource et de la valeur de `contentHandling` propriété de la ressource d'[intégration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). | Charge utile de la demande de méthode | En-tête `Content-Type` de la demande | `binaryMediaTypes` | `contentHandling` | Charge utile de la demande d’intégration | | --- | --- | --- | --- | --- | | Données de texte | Tout type de données | Non défini | Non défini | UTF8-chaîne codée | | Données de texte | Tout type de données | Non défini | CONVERT\$1TO\$1BINARY | Blob binaire décodé en Base64 | | Données de texte | Tout type de données | Non défini | CONVERT\$1TO\$1TEXT | UTF8-chaîne codée | | Données de texte | Un type de données texte | Défini avec les types de supports correspondants | Non défini | Données de texte | | Données de texte | Un type de données texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Blob binaire décodé en Base64 | | Données de texte | Un type de données texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | Données de texte | | Données binaires | Un type de données binaires | Défini avec les types de supports correspondants | Non défini | Données binaires | | Données binaires | Un type de données binaires | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Données binaires | | Données binaires | Un type de données binaires | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | Chaîne d'encodage en Base64 | Le tableau suivant montre comment API Gateway convertit la charge utile de réponse pour des configurations spécifiques de l'`Accept`en-tête d'une demande, de la `binaryMediaTypes` liste d'une [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource et de la valeur de `contentHandling` propriété de la [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)ressource. **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 `` 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. | Charge utile de la réponse d’intégration | En-tête `Accept` de la demande | `binaryMediaTypes` | `contentHandling` | Charge utile de la réponse de méthode | | --- | --- | --- | --- | --- | | Données texte ou binaires | Un type de texte | Non défini | Non défini | UTF8-chaîne codée | | Données texte ou binaires | Un type de texte | Non défini | CONVERT\$1TO\$1BINARY | Blob décodé en Base64 | | Données texte ou binaires | Un type de texte | Non défini | CONVERT\$1TO\$1TEXT | UTF8-chaîne codée | | Données de texte | Un type de texte | Défini avec les types de supports correspondants | Non défini | Données de texte | | Données de texte | Un type de texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Blob décodé en Base64 | | Données de texte | Un type de texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | UTF8-chaîne codée | | Données de texte | Un type binaire | Défini avec les types de supports correspondants | Non défini | Blob décodé en Base64 | | Données de texte | Un type binaire | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Blob décodé en Base64 | | Données de texte | Un type binaire | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | UTF8-chaîne codée | | Données binaires | Un type de texte | Défini avec les types de supports correspondants | Non défini | Chaîne d'encodage en Base64 | | Données binaires | Un type de texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Données binaires | | Données binaires | Un type de texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | Chaîne d'encodage en Base64 | | Données binaires | Un type binaire | Défini avec les types de supports correspondants | Non défini | Données binaires | | Données binaires | Un type binaire | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Données binaires | | Données binaires | Un type binaire | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | Chaîne d'encodage en Base64 | Lors de la conversion d’une charge utile de texte en blob binaire, API Gateway suppose que les données de texte sont une chaîne encodée en base64 et génère les données binaires comme blob décodé en base64. Si la conversion échoue, elle retourne une réponse `500` indiquant une erreur de configuration de l’API. Vous ne fournissez pas de modèle de mappage pour ce type de conversion, même si vous devez activer les [comportements relais](integration-passthrough-behaviors.md) sur l’API. Lors de la conversion d’une charge utile binaire en une chaîne de texte, API Gateway applique toujours un encodage en base64 sur les données binaires. Vous pouvez définir un modèle de mappage pour une charge utile de ce type, mais vous pouvez uniquement accéder à la chaîne d’encodage base64 dans le modèle de mappage via `$input.body`, comme illustré dans l’extrait d’un exemple de modèle de mappage. ``` { "data": "$input.body" } ``` Pour que la charge utile binaire soit passée sans modification, vous devez activer les [comportements relais](integration-passthrough-behaviors.md) sur l’API. # Activation de la prise en charge binaire à l’aide de la console API Gateway Cette section explique comment activer la prise en charge binaire à l’aide de la console API Gateway. À titre d’exemple, nous utilisons une API intégrée avec Amazon S3. Nous nous concentrons sur les tâches visant à définir les types de supports pris en charge afin de spécifier la façon dont la charge utile doit être gérée. Pour obtenir des informations détaillées sur la création d’une API intégrée avec Amazon S3, consultez [Didacticiel : création d’une API REST en tant que proxy Amazon S3](integrating-api-with-aws-services-s3.md). **Pour activer la prise en charge binaire à l’aide de la console API Gateway** 1. Définissez les types de supports binaires pour l’API : 1. Créez une API ou choisissez une API existante. Pour cet exemple, nous appelons l’API `FileMan`. 1. Sous l’API sélectionnée dans le panneau de navigation principal, choisissez **Paramètres de l’API**. 1. Dans le volet **Paramètres de l’API**, choisissez **Gérer les types de supports** dans la section **Types de supports binaires**. 1. Choisissez **Ajouter un type de support binaire**. 1. Saisissez un type de support requis, par exemple **image/png**, dans le champ de texte d’entrée. Si nécessaire, répétez cette étape pour ajouter d’autres types de supports. Pour prendre en charge tous les types de supports binaires, spécifiez `*/*`. 1. Sélectionnez **Enregistrer les modifications**. 1. Définissez la façon dont les charges utiles du message sont traitées pour la méthode de l’API : 1. Créez une nouvelle ressource ou choisissez-en une existante dans l’API. Dans le cadre de cet exemple, nous utilisons la ressource `/{folder}/{item}`. 1. Créez une méthode ou choisissez-en une existante sur la ressource. À titre d’exemple, nous utilisons la méthode `GET /{folder}/{item}` intégrée avec l’action `Object GET` dans Amazon S3. 1. Dans **Gestion de contenu**, choisissez une option. ![\[Configuration de la méthode dans la console API Gateway.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png) Choisissez **Passthrough** si vous ne souhaitez pas convertir le corps lorsque le client et le backend acceptent le même format binaire. Choisissez **Convertir en texte** pour convertir le corps binaire en chaîne encodée en base64 lorsque, par exemple, le backend a besoin qu’une charge utile de requête binaire soit passée en tant que propriété JSON. Choisissez **Convertir en binaire** lorsque le client envoie une chaîne encodée en base64 et si le backend nécessite le format binaire d’origine, ou lorsque le point de terminaison retourne une chaîne encodée en base64 et si le client accepte uniquement la sortie binaire. 1. Pour **Transmission du corps de requête**, choisissez **Lorsqu’aucun modèle n’est défini (recommandé)** pour activer le comportement de transmission pour le corps de la requête. Vous pouvez également choisir **Jamais**. Cela signifie que l’API rejettera les données avec des types de contenus qui ne disposent pas d’un modèle de mappage. 1. Conservez l’en-tête `Accept` de la demande entrante dans la demande d’intégration. Procédez ainsi si vous avez défini `contentHandling` sur `passthrough` et que vous souhaitez remplacer ce paramètre au moment de l’exécution. ![\[Conservez l’en-tête Accept dans la demande d’intégration.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png) 1. Pour la conversion en texte, définissez un modèle de mappage afin de convertir les données binaires encodées en base64 au format requis. Voici un exemple de modèle de mappage à convertir en texte : ``` { "operation": "thumbnail", "base64Image": "$input.body" } ``` Le format de ce modèle de mappage s’appuie sur les exigences de point de terminaison de l’entrée. 1. Choisissez **Enregistrer**. # Activation de la prise en charge binaire à l’aide de l’API REST API Gateway Les tâches suivantes montrent comment activer la prise en charge binaire à l’aide des appels de l’API REST API Gateway. **Topics** + [Ajout et mise à jour des types de supports binaires d’une API](#api-gateway-payload-encodings-setup-with-api-set-encodings-map) + [Configuration des conversions de charge utile de la demande](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding) + [Configuration des conversions de charge utile pour la réponse](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding) + [Conversion des données binaires en données de texte](#api-gateway-payload-encodings-convert-binary-to-string) + [Conversion des données de texte en charge utile binaire](#api-gateway-payload-encodings-convert-string-to-binary) + [Passage via une charge utile binaire](#api-gateway-payload-encodings-pass-binary-as-is) ## Ajout et mise à jour des types de supports binaires d’une API Pour permettre à API Gateway de prendre en charge un nouveau type de support binaire, vous devez ajouter le type de support binaire à la liste `binaryMediaTypes` de la ressource `RestApi`. Par exemple, pour qu’API Gateway gère les images JPEG, envoyez une demande `PATCH` à la ressource `RestApi` : ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/image~1jpeg" } ] } ``` La spécification de type MIME de `image/jpeg` qui fait partie de la valeur de propriété `path` est échappée comme `image~1jpeg`. Pour mettre à jour les types de supports binaires pris en charge, remplacez ou supprimez le type de support de la liste `binaryMediaTypes` de la ressource `RestApi`. Par exemple, pour remplacer la prise en charge binaire des fichiers JPEG par celle des octets bruts, soumettez une demande `PATCH` à la ressource `RestApi`, comme suit : ``` PATCH /restapis/ { "patchOperations" : [{ "op" : "replace", "path" : "/binaryMediaTypes/image~1jpeg", "value" : "application/octet-stream" }, { "op" : "remove", "path" : "/binaryMediaTypes/image~1jpeg" }] } ``` ## Configuration des conversions de charge utile de la demande Si le point de terminaison nécessite une entrée binaire, définissez la propriété `contentHandling` de la ressource `Integration` sur `CONVERT_TO_BINARY`. Pour ce faire, présentez une `PATCH` demande, comme suit : ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] } ``` ## Configuration des conversions de charge utile pour la réponse Si le client accepte le résultat comme blob binaire au lieu de la charge utile encodée en base64 renvoyée par le point de terminaison, définissez la propriété `contentHandling` de la ressource `IntegrationResponse` sur `CONVERT_TO_BINARY`. Pour ce faire, soumettez une demande `PATCH`, comme suit : ``` PATCH /restapis//resources//methods//integration/responses/ { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] } ``` ## Conversion des données binaires en données de texte Pour envoyer des données binaires sous forme de propriété JSON de l'entrée à AWS Lambda ou à Kinesis via API Gateway, procédez comme suit : 1. Activez la prise en charge de la charge utile binaire de l’API en ajoutant le nouveau type de support binaire de `application/octet-stream` à la liste de l’API `binaryMediaTypes`. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] } ``` 1. Définissez `CONVERT_TO_TEXT` sur la propriété `contentHandling` de la ressource `Integration` et fournissez fournir un modèle de mappage pour attribuer la chaîne encodée en base64 des données binaires à une propriété JSON. Dans l’exemple suivant, la propriété JSON est `body` et `$input.body` contient la chaîne encodée en base64. ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_TEXT" }, { "op" : "add", "path" : "/requestTemplates/application~1octet-stream", "value" : "{\"body\": \"$input.body\"}" } ] } ``` ## Conversion des données de texte en charge utile binaire Supposons qu’une fonction Lambda renvoie un fichier d’image sous forme de chaîne encodée en base64. Pour transmettre cette sortie binaire au client via API Gateway, procédez comme suit : 1. Mettez à jour la liste `binaryMediaTypes` de l’API en ajoutant le type de support binaire de `application/octet-stream`, s’il n’est pas déjà dans la liste. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream", }] } ``` 1. Définissez la propriété `contentHandling` de la ressource `Integration` sur `CONVERT_TO_BINARY`. Ne définissez pas de modèle de mappage. Si vous ne définissez pas de modèle de mappage, API Gateway appelle le modèle de relais pour renvoyer le blob binaire encodé en base64 sous forme de fichier image au client. ``` PATCH /restapis//resources//methods//integration/responses/ { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" } ] } ``` ## Passage via une charge utile binaire Pour stocker une image dans un compartiment Amazon S3 à l’aide d’API Gateway, procédez comme suit : 1. Mettez à jour la liste `binaryMediaTypes` de l’API en ajoutant le type de support binaire de `application/octet-stream`, s’il n’est pas déjà dans la liste. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] } ``` 1. Sur la propriété `contentHandling` de la ressource `Integration`, définissez `CONVERT_TO_BINARY`. Définissez `WHEN_NO_MATCH` comme valeur de propriété `passthroughBehavior` sans définir de modèle de mappage. Cela permet à API Gateway d’appeler le modèle de relais. ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }, { "op" : "replace", "path" : "/passthroughBehaviors", "value" : "WHEN_NO_MATCH" } ] } ``` # Importation et exportation d’encodages de contenu pour API Gateway Pour importer la `binaryMediaTypes` liste sur un [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), utilisez l'extension API Gateway suivante dans le fichier de définition OpenAPI de l'API. L’extension est également utilisée pour exporter les paramètres de l’API. + [x-amazon-apigateway-binarypropriété -media-types](api-gateway-swagger-extensions-binary-media-types.md) Pour importer et exporter la valeur de propriété `contentHandling` sur une ressource `Integration` ou `IntegrationResponse`, utilisez les extensions API Gateway suivantes pour les définitions OpenAPI : + [x-amazon-apigateway-integration objet](api-gateway-swagger-extensions-integration.md) + [x-amazon-apigateway-integrationobjet .response](api-gateway-swagger-extensions-integration-response.md) # Renvoi d’un support binaire d’une intégration de proxy Lambda dans API Gateway Pour renvoyer un support binaire à partir d’une [intégration de proxy AWS Lambda](set-up-lambda-proxy-integrations.md), encodez en base64 la réponse de votre fonction Lambda. Vous devez également [configurer les types de supports binaires de votre API](api-gateway-payload-encodings-configure-with-console.md). Lorsque vous configurez les types de médias binaires de votre API, celle-ci traite ce type de contenu comme des données binaires. La taille de la charge utile ne doit pas dépasser 10 Mo. **Note** Pour utiliser un navigateur web pour appeler une API avec cet exemple d’intégration, définissez les types de supports binaires de votre API sur `*/*`. 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 tous les types de contenu). L’exemple de fonction Lambda suivant peut renvoyer aux clients une image binaire à partir d’Amazon S3 ou du texte. La réponse de la fonction inclut un en-tête `Content-Type` pour indiquer au client le type de données qu’elle renvoie. La fonction définit de manière conditionnelle la propriété `isBase64Encoded` dans sa réponse, en fonction du type de données qu’elle renvoie. ------ #### [ Node.js ] ``` import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3" const client = new S3Client({region: 'us-east-2'}); export const handler = async (event) => { var randomint = function(max) { return Math.floor(Math.random() * max); } var number = randomint(2); if (number == 1){ const input = { "Bucket" : "bucket-name", "Key" : "image.png" } try { const command = new GetObjectCommand(input) const response = await client.send(command); var str = await response.Body.transformToByteArray(); } catch (err) { console.error(err); } const base64body = Buffer.from(str).toString('base64'); return { 'headers': { "Content-Type": "image/png" }, 'statusCode': 200, 'body': base64body, 'isBase64Encoded': true } } else { return { 'headers': { "Content-Type": "text/html" }, 'statusCode': 200, 'body': "

This is text

", } } } ``` ------ #### [ Python ] ``` import base64 import boto3 import json import random s3 = boto3.client('s3') def lambda_handler(event, context): number = random.randint(0,1) if number == 1: response = s3.get_object( Bucket='bucket-name', Key='image.png', ) image = response['Body'].read() return { 'headers': { "Content-Type": "image/png" }, 'statusCode': 200, 'body': base64.b64encode(image).decode('utf-8'), 'isBase64Encoded': True } else: return { 'headers': { "Content-type": "text/html" }, 'statusCode': 200, 'body': "

This is text

", } ``` ------ Pour plus d’informations sur les types de supports binaires, consultez [Types de médias binaires pour REST APIs dans API Gateway](api-gateway-payload-encodings.md). # Accès aux fichiers binaires dans Amazon S3 via une API API Gateway Les exemples suivants illustrent le fichier OpenAPI utilisé pour accéder aux images dans Amazon S3, le téléchargement d’une image depuis Amazon S3 et le chargement d’une image vers Amazon S3. **Topics** + [Fichier OpenAPI d’un exemple d’API pour accéder aux images dans Amazon S3](#api-gateway-content-encodings-example-image-s3-swagger-file) + [Téléchargement d’une image depuis Amazon S3](#api-gateway-content-encodings-example-download-image-from-s3) + [Chargement d’une image sur Amazon S3](#api-gateway-content-encodings-example-upload-image-to-s3) ## Fichier OpenAPI d’un exemple d’API pour accéder aux images dans Amazon S3 Le fichier OpenAPI suivant présent un exemple d’API qui illustre le téléchargement d’un fichier image depuis Amazon S3 et le chargement d’un fichier image vers Amazon S3. Cette API expose les méthodes `GET /s3?key={file-name}` et `PUT /s3?key={file-name}` de téléchargement et de chargement d’un fichier image spécifié. La méthode `GET` renvoie le fichier image sous la forme d'une chaîne encodée en base64 dans le cadre d'une sortie JSON, selon le modèle de mappage fourni, dans une réponse 200 OK. La méthode `PUT` prend un blob binaire brut comme entrée et renvoie une réponse 200 OK avec une charge utile vide. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "paths": { "/s3": { "get": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws", "contentHandling": "CONVERT_TO_BINARY" } } } }, "x-amazon-apigateway-binary-media-types": [ "application/octet-stream", "image/jpeg" ], "servers": [ { "url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "host": "abcdefghi.execute-api.us-east-1.amazonaws.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/s3": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "produces": [ "application/json", "application/octet-stream" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws", "contentHandling" : "CONVERT_TO_BINARY" } } } }, "x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"], "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Téléchargement d’une image depuis Amazon S3 Pour télécharger un fichier image (`image.jpg`) comme blob binaire depuis Amazon S3 : ``` GET /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/octet-stream ``` La réponse de réussite ressemble à ceci : ``` 200 OK HTTP/1.1 [raw bytes] ``` Les octets bruts sont renvoyés car l’en-tête `Accept` est défini sur un type de support binaire de `application/octet-stream` et la prise en charge binaire est activée pour l’API. Vous pouvez également télécharger un fichier image (`image.jpg`) en tant que chaîne encodée en base64, au format d’une propriété JSON, à partir d’Amazon S3, ajouter un modèle de réponse à la réponse d’intégration 200, comme illustré dans le bloc de définition OpenAPI en caractères gras suivant : ``` "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } }, ``` La demande pour télécharger le fichier image ressemble à ce qui suit : ``` GET /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json ``` La réponse de réussite ressemble à ce qui suit : ``` 200 OK HTTP/1.1 { "image": "W3JhdyBieXRlc10=" } ``` ## Chargement d’une image sur Amazon S3 Pour charger un fichier image (`image.jpg`) comme blob binaire vers Amazon S3 : ``` PUT /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/octet-stream Accept: application/json [raw bytes] ``` La réponse de réussite ressemble à ce qui suit : ``` 200 OK HTTP/1.1 ``` Pour charger un fichier image (`image.jpg`) sous la forme d’une chaîne encodée en base64 vers Amazon S3 : ``` PUT /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json W3JhdyBieXRlc10= ``` La charge utile d’entrée doit être une chaîne encodée en base64 car la valeur de l’en-tête `Content-Type` est définie sur `application/json`. La réponse de réussite ressemble à ce qui suit : ``` 200 OK HTTP/1.1 ``` # Accès aux fichiers binaires dans Lambda à l’aide d’une API API Gateway L'exemple OpenAPI suivant montre comment accéder à un fichier binaire AWS Lambda via une API API Gateway. Cette API expose les méthodes `GET /lambda?key={file-name}` et `PUT /lambda?key={file-name}` de téléchargement et de chargement d’un fichier image spécifié. La méthode `GET` renvoie le fichier image sous la forme d'une chaîne encodée en base64 dans le cadre d'une sortie JSON, selon le modèle de mappage fourni, dans une réponse 200 OK. La méthode `PUT` prend un blob binaire brut comme entrée et renvoie une réponse 200 OK avec une charge utile vide. Vous créez la fonction Lambda que votre API appelle, et elle doit renvoyer une chaîne codée en base64 avec l’en-tête `Content-Type` `application/json`. **Topics** + [Fichier OpenAPI d’un exemple d’API pour accéder aux images dans Lambda](#api-gateway-content-encodings-example-image-lambda-swagger-file) + [Téléchargement d’une image depuis Lambda](#api-gateway-content-encodings-example-download-image-from-lambda) + [Chargement d’une image vers Lambda](#api-gateway-content-encodings-example-upload-image-to-lambda) ## Fichier OpenAPI d’un exemple d’API pour accéder aux images dans Lambda Le fichier OpenAPI suivant présente un exemple d’API qui illustre le téléchargement d’un fichier image depuis Lambda et le chargement d’un fichier image vers Lambda. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "paths": { "/lambda": { "get": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } } } }, "put": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } } } } } }, "x-amazon-apigateway-binary-media-types": [ "application/octet-stream", "image/jpeg" ], "servers": [ { "url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "host": "abcdefghi.execute-api.us-east-1.amazonaws.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/lambda": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } } } }, "put": { "produces": [ "application/json", "application/octet-stream" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "contentHandling" : "CONVERT_TO_TEXT", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } } } } } }, "x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"], "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Téléchargement d’une image depuis Lambda Pour télécharger un fichier image (`image.jpg`) comme blob binaire depuis Lambda : ``` GET /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/octet-stream ``` La réponse de réussite ressemble à ce qui suit : ``` 200 OK HTTP/1.1 [raw bytes] ``` Pour télécharger un fichier image (`image.jpg`) sous la forme d’une chaîne encodée en base64, au format d’une propriété JSON, depuis Lambda : ``` GET /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json ``` La réponse de réussite ressemble à ce qui suit : ``` 200 OK HTTP/1.1 { "image": "W3JhdyBieXRlc10=" } ``` ## Chargement d’une image vers Lambda Pour charger un fichier image (`image.jpg`) comme blob binaire vers Lambda : ``` PUT /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/octet-stream Accept: application/json [raw bytes] ``` La réponse de réussite ressemble à ce qui suit : ``` 200 OK ``` Pour charger un fichier image (`image.jpg`) sous la forme d’une chaîne encodée en base64 vers Lambda : ``` PUT /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json W3JhdyBieXRlc10= ``` La réponse de réussite ressemble à ce qui suit : ``` 200 OK ```