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.
# Didacticiel : création d’une API REST en tant que proxy Amazon S3
À titre d’exemple pour présenter l’utilisation d’une API REST dans API Gateway comme proxy Amazon S3, cette section explique comment créer et configurer une API REST pour exposer les opérations Amazon S3 suivantes :
+ Exposition de la méthode GET sur la ressource racine de l’API pour [afficher la liste de tous les compartiments Amazon S3 d’un appelant](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html).
+ Exposition de la méthode GET sur une ressource Folder pour [afficher la liste de tous les objets d’un compartiment Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html).
+ Exposez GET sur une Folder/Item ressource pour [afficher ou télécharger un objet depuis un compartiment Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html).
Vous pouvez importer l’exemple d’API en tant que proxy Amazon S3, comme illustré dans [Définitions OpenAPI de l’exemple d’API en tant que proxy Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md). Cet échantillon contient des méthodes plus exposées. Pour plus d’informations sur l’importation d’une API à l’aide de la définition OpenAPI, consultez [Développez REST APIs à l'aide d'OpenAPI dans API Gateway](api-gateway-import-api.md).
**Note**
Pour intégrer votre API Amazon API Gateway avec Amazon S3, vous devez choisir une région où les services API Gateway et Amazon S3 sont disponibles. Pour connaître la disponibilité dans les régions, consultez les [points de terminaison et quotas Amazon API Gateway](https://docs.aws.amazon.com/general/latest/gr/apigateway.html).
**Topics**
+ [Configuration d’autorisations IAM pour l’API afin d’appeler des actions Amazon S3](#api-as-s3-proxy-iam-permissions)
+ [Création de ressources d’API pour représenter des ressources Amazon S3](#api-as-s3-proxy-create-resources)
+ [Exposition d’une méthode d’API pour afficher la liste des compartiments Amazon S3 de l’appelant](#api-root-get-as-s3-get-service)
+ [Exposition de méthodes d’API pour accéder à un compartiment Amazon S3](#api-folder-operations-as-s3-bucket-actions)
+ [Exposition de méthodes d’API pour accéder à un objet Amazon S3 dans un compartiment](#api-items-in-folder-as-s3-objects-in-bucket)
+ [Définitions OpenAPI de l’exemple d’API en tant que proxy Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md)
+ [Appel de l’API à l’aide d’un client d’API REST](api-as-s3-proxy-test-using-postman.md)
## Configuration d’autorisations IAM pour l’API afin d’appeler des actions Amazon S3
Pour autoriser l’API à invoquer les actions Amazon S3 requises, vous devez avoir attaché les politiques IAM appropriées à un rôle IAM. Au cours de cette étape, vous allez créer un rôle IAM.
**Pour créer le rôle d'exécution du proxy de AWS service**
1. Connectez-vous à la console IAM AWS Management Console et ouvrez-la à [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)l'adresse.
1. Sélectionnez **Roles**.
1. Choisissez **Créer un rôle**.
1. Choisissez le **AWS service** sous **Sélectionner le type d'entité de confiance**, puis sélectionnez **API Gateway** et sélectionnez **Allows API Gateway to push CloudWatch logs vers Logs**.
1. Choisissez **Suivant**, puis **Suivant**.
1. Pour **Nom du rôle**, saisissez **APIGatewayS3ProxyPolicy**, puis choisissez **Créer un rôle**.
1. Dans la liste **Roles**, choisissez le rôle que vous venez de créer. Vous devrez peut-être faire défiler la page ou utiliser la barre de recherche pour rechercher le rôle.
1. Pour le rôle sélectionné, sélectionnez l’onglet **Ajouter des autorisations**.
1. Choisissez **Attacher des politiques** dans la liste déroulante.
1. Dans la barre de recherche, saisissez **AmazonS3FullAccess** et choisissez **Ajouter des autorisations**.
**Note**
Ce didacticiel utilise une politique gérée pour plus de simplicité. Il est recommandé de créer votre propre politique IAM afin d’accorder les autorisations minimales requises.
1. Notez l’**ARN du rôle** nouvellement créé. Vous l’utiliserez ultérieurement.
## Création de ressources d’API pour représenter des ressources Amazon S3
Vous allez utiliser la ressource racine de l’API (`/`) comme conteneur des compartiments Amazon S3 d’un appelant authentifié. Vous allez également créer les ressources `Folder` et `Item` pour représenter respectivement un compartiment Amazon S3 spécifique et un objet Amazon S3 spécifique. Le nom du dossier et la clé de l’objet seront spécifiés sous la forme de paramètres de chemin dans le cadre d’une URL de demande, par l’appelant.
**Note**
Lorsque vous accédez à des objets dont la clé d’objet inclut `/` ou n’importe quel autre caractère spécial, ce caractère doit être encodé en URL. Par exemple, `test/test.txt` doit être codé en `test%2Ftest.txt`.
**Pour créer une ressource d’API qui expose les fonctions de service Amazon S3**
1. Dans le même temps Région AWS que vous avez créé votre compartiment Amazon S3, créez une API nommée **MyS3**. La ressource racine de cette API (**/**) représente le service Amazon S3. Dans cette étape, vous créez deux ressources supplémentaires **/\{folder\}** et **/\{item\}**.
1. Choisissez **Créer une ressource**.
1. Maintenez **Ressource proxy** désactivée.
1. Pour **Chemin de ressource**, sélectionnez `/`.
1. Sous **Resource Name (Nom de la ressource)**, entrez **\{folder\}**.
1. Gardez **CORS (Partage des ressources entre origines multiples)** non coché.
1. Choisissez **Créer une ressource**.
1. Sélectionnez la ressource **/\{folder\}**, puis choisissez **Créer une ressource**.
1. Suivez les étapes précédentes pour créer une ressource enfant de **/\{folder\}** nommée **\{item\}**.
Votre API finale doit ressembler à ce qui suit :
## Exposition d’une méthode d’API pour afficher la liste des compartiments Amazon S3 de l’appelant
L’obtention de la liste des compartiments Amazon S3 de l’appelant implique l’appel de l’action [GET Service](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) sur Amazon S3. Sur la ressource racine de l’API (**/**), créez la méthode GET. Configurez la méthode GET de façon à ce qu’elle s’intègre avec Amazon S3, comme suit.
**Pour créer et initialiser la méthode `GET /` de l’API**
1. Sélectionnez la ressource **/**, puis choisissez **Créer une méthode**.
1. Pour le type de méthode, sélectionnez **GET**.
1. Pour **Type d’intégration**, sélectionnez **Service AWS**.
1. Pour **Région AWS**, sélectionnez l' Région AWS endroit où vous avez créé votre compartiment Amazon S3.
1. Pour **Service AWS**, sélectionnez **Amazon Simple Storage Service**.
1. Laissez **Sous-domaine AWS ** vide.
1. Pour **Méthode HTTP**, sélectionnez **GET**.
1. Pour **Type d’action**, sélectionnez **Utiliser un remplacement de chemin**.
Avec le remplacement du chemin, API Gateway transfère la demande client à Amazon S3 en tant que [demande de type chemin d’API REST Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAPI.html), dans laquelle une ressource Amazon S3 est exprimée par le chemin de ressource du modèle `s3-host-name/bucket/key`. API Gateway définit le `s3-host-name` et transmet les valeurs spécifiées par le client `bucket` et `key` du client vers Amazon S3.
1. Pour **Remplacement de chemin**, saisissez **/**.
1. Pour **Rôle d’exécution**, saisissez l’ARN de rôle pour **APIGatewayS3ProxyPolicy**.
1. Choisissez **Paramètres de requête de méthode**.
Vous allez utiliser les paramètres de requête de méthode pour contrôler qui peut appeler cette méthode de votre API.
1. Pour **Autorisation**, dans le menu déroulant, sélectionnez `AWS_IAM`.
1. Choisissez **Créer une méthode**.
Cette configuration intègre la demande `GET https://{{your-api-host}}/{{stage}}/` front-end avec la méthode `GET https://{{your-s3-host}}/` back-end.
Pour que votre API renvoie correctement à l’appelant les réponses positives et les exceptions, vous allez déclarer les réponses 200, 400 et 500 dans **Réponse de méthode**. Vous allez utiliser le mappage par défaut pour les réponses 200 afin que les réponses back-end du code de statut non déclarées ici soient renvoyées à l’appelant en tant que réponses 200.
**Pour déclarer les types de réponse pour la méthode `GET /`**
1. Dans l’onglet **Méthode de réponse**, sous **Réponse 200**, choisissez **Modifier**.
1. Choisissez **Ajouter un en-tête**, puis procédez comme suit :
1. Pour **Nom de l’en-tête**, saisissez **Content-Type**.
1. Sélectionnez **Add header**.
Répétez ces étapes pour créer un en-tête **Timestamp** et un en-tête **Content-Length**.
1. Choisissez **Enregistrer**.
1. Dans l’onglet **Réponse de méthode**, sous **Réponses de méthode**, choisissez **Créer une réponse**.
1. Pour **Code de statut HTTP**, saisissez **400**.
Vous ne définissez aucun en-tête pour cette réponse.
1. Choisissez **Enregistrer**.
1. Répétez les étapes suivantes pour créer la réponse 500.
Vous ne définissez aucun en-tête pour cette réponse.
Étant donné que la réponse d’intégration réussie d’Amazon S3 renvoie la liste des compartiments en tant que données utiles XML et que la réponse de méthode par défaut d’API Gateway renvoie des données utiles JSON, vous devez mapper la valeur du paramètre d’en-tête Content-Type du back-end à celle du front-end. Sinon, le client recevra `application/json` pour le type de contenu quand le corps de la réponse est en fait une chaîne XML. La procédure suivante montre comment effectuer cette configuration. En outre, vous souhaitez également afficher au client d’autres paramètres d’en-tête, comme Date et Content-Length.
**Pour configurer des mappages d’en-tête de réponse pour la méthode GET /**
1. Dans l’onglet **Réponse d’intégration**, sous **Par défaut - Réponse**, choisissez **Modifier**.
1. Pour l’en-tête **Content-Length**, saisissez **integration.response.header.Content-Length** pour la valeur de mappage.
1. Pour l’en-tête **Content-Type**, saisissez **integration.response.header.Content-Type** pour la valeur de mappage.
1. Pour l’en-tête **Timestamp**, saisissez **integration.response.header.Date** pour la valeur de mappage.
1. Choisissez **Enregistrer**. Le résultat devrait ressembler à ce qui suit :
1. Dans l’onglet **Réponse d’intégration**, sous **Réponses d’intégration**, choisissez **Créer une réponse**.
1. Pour **HTTP status regex (Regex statut HTTP)**, saisissez **4\\d\{2\}**. Cela mappe tous les codes de statut de réponse HTTP 4xx à la réponse de la méthode.
1. Pour **Code de statut de la réponse de méthode**, sélectionnez **400**.
1. Choisissez **Créer**.
1. Répétez les étapes suivantes afin de créer une réponse d’intégration pour la réponse de la méthode 500. Pour **HTTP status regex (Regex statut HTTP)**, saisissez **5\\d\{2\}**.
À titre de bonne pratique, vous pouvez tester l’API que vous avez configurée jusqu’à présent.
**Pour tester la méthode `GET /`**
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Sélectionnez **Tester)**. Le résultat doit ressembler à l’image suivante :
## Exposition de méthodes d’API pour accéder à un compartiment Amazon S3
Pour utiliser un compartiment Amazon S3, vous allez exposer la méthode `GET` sur la ressource /\{folder\} afin de répertorier les objets dans un compartiment. Les instructions sont similaires à celles décrites dans [Exposition d’une méthode d’API pour afficher la liste des compartiments Amazon S3 de l’appelant](#api-root-get-as-s3-get-service). Pour d’autres méthodes, vous pouvez importer l’exemple d’API ici, [Définitions OpenAPI de l’exemple d’API en tant que proxy Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md).
**Pour exposer la méthode GET sur une ressource de dossier**
1. Sélectionnez la ressource **/\{folder\}**, puis choisissez **Créer une méthode**.
1. Pour le type de méthode, sélectionnez **GET**.
1. Pour **Type d’intégration**, sélectionnez **Service AWS**.
1. Pour **Région AWS**, sélectionnez l' Région AWS endroit où vous avez créé votre compartiment Amazon S3.
1. Pour **Service AWS**, sélectionnez **Amazon Simple Storage Service**.
1. Laissez **Sous-domaine AWS ** vide.
1. Pour **Méthode HTTP**, sélectionnez **GET**.
1. Pour **Type d’action**, sélectionnez **Utiliser un remplacement de chemin**.
1. Pour **Remplacement de chemin**, saisissez **\{bucket\}**.
1. Pour **Rôle d’exécution**, saisissez l’ARN de rôle pour **APIGatewayS3ProxyPolicy**.
1. Choisissez **Créer une méthode**.
Vous définissez le paramètre de chemin `{folder}` dans l’URL de point de terminaison Amazon S3. Vous devez mapper le paramètre de chemin `{folder}` de la requête de méthode au paramètre de chemin `{bucket}` de la requête d’intégration.
**Pour mapper `{folder}` à `{bucket}`**
1. Dans l’onglet **Requête d’intégration**, sous **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Choisissez **Paramètres de chemin d’URL**, puis choisissez **Ajouter un paramètre de chemin**.
1. Pour **Nom**, saisissez **bucket**.
1. Pour **Mappage à partir de**, entrez **method.request.path.folder**.
1. Choisissez **Enregistrer**.
Maintenant, vous testez votre API.
**Pour tester la méthode `/{folder} GET`.**
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Sous **Chemin**, pour le **dossier**, saisissez le nom de votre compartiment.
1. Sélectionnez **Tester)**.
Le résultat du test contient une liste des objets contenus dans votre compartiment.
## Exposition de méthodes d’API pour accéder à un objet Amazon S3 dans un compartiment
Amazon S3 prend en charge les actions GET, DELETE, HEAD, OPTIONS, POST et PUT pour accéder aux objets d’un compartiment donné et les gérer. Dans ce didacticiel, vous allez exposer une méthode `GET` sur la ressource `{folder}/{item}` pour obtenir une image à partir d’un compartiment. Pour d’autres applications de la ressource `{folder}/{item}`, consultez l’exemple d’API,[Définitions OpenAPI de l’exemple d’API en tant que proxy Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md).
**Pour exposer la méthode GET sur une ressource d’élément**
1. Sélectionnez la ressource **/\{item\}**, puis choisissez **Créer une méthode**.
1. Pour le type de méthode, sélectionnez **GET**.
1. Pour **Type d’intégration**, sélectionnez **Service AWS**.
1. Pour **Région AWS**, sélectionnez l' Région AWS endroit où vous avez créé votre compartiment Amazon S3.
1. Pour **Service AWS**, sélectionnez **Amazon Simple Storage Service**.
1. Laissez **Sous-domaine AWS ** vide.
1. Pour **Méthode HTTP**, sélectionnez **GET**.
1. Pour **Type d’action**, sélectionnez **Utiliser un remplacement de chemin**.
1. Pour **Remplacement de chemin**, saisissez **\{bucket\}/\{object\}**.
1. Pour **Rôle d’exécution**, saisissez l’ARN de rôle pour **APIGatewayS3ProxyPolicy**.
1. Choisissez **Créer une méthode**.
Vous définissez les paramètres de chemin `{folder}` et `{item}` dans l’URL de point de terminaison Amazon S3. Vous devez mapper le paramètre de chemin de la requête de méthode au paramètre de chemin de la requête d’intégration.
Dans cette étape, vous effectuez les opérations suivantes :
+ Mappez le paramètre de chemin `{folder}` de la demande de méthode au paramètre de chemin `{bucket}` de la demande d’intégration.
+ Mappez le paramètre de chemin `{item}` de la demande de méthode au paramètre de chemin `{object}` de la demande d’intégration.
**Pour mapper `{folder}` à `{bucket}` et `{item}` à `{object}`**
1. Dans l’onglet **Requête d’intégration**, sous **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Choisissez **paramètres de chemin d’URL**.
1. Choisissez **Ajouter un paramètre de chemin**.
1. Pour **Nom**, saisissez **bucket**.
1. Pour **Mappage à partir de**, entrez **method.request.path.folder**.
1. Choisissez **Ajouter un paramètre de chemin**.
1. Pour **Nom**, saisissez **object**.
1. Pour **Mappage à partir de**, entrez **method.request.path.item**.
1. Choisissez **Enregistrer**.
**Pour tester la méthode `/{folder}/{object} GET`.**
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Sous **Chemin**, pour le **dossier**, saisissez le nom de votre compartiment.
1. Sous **Chemin**, pour l’**élément**, saisissez le nom d’un élément.
1. Sélectionnez **Tester)**.
Le corps de la réponse contiendra le contenu de l’élément.
La requête renvoie correctement le texte brut (« Hello world ») comme contenu du fichier spécifié (test.txt) dans le compartiment Amazon S3 donné (amzn-s3-demo-bucket).
Pour télécharger ou charger des fichiers binaires (dans API Gateway, tout contenu autre que du contenu JSON codé en UTF-8), des paramètres d’API supplémentaires sont requis. La procédure à suivre est expliquée ci-après :
**Pour télécharger ou charger des fichiers binaires à partir de S3**
1. Enregistrez les types de média du fichier concerné dans les API binaryMediaTypes. Vous pouvez réaliser cette opération dans la console :
1. Choisissez **Paramètres de l’API** pour l’API.
1. Sous **Types de supports binaires**, choisissez **Gérer les types de supports**.
1. Choisissez **Ajouter un type de support binaire**, puis saisissez le type de support requis, par exemple `image/png`.
1. Choisissez **Save changes** (Enregistrer les modifications) pour sauvegarder le paramètre.
1. Ajoutez l'en-tête `Content-Type` (pour le téléchargement) and/or `Accept` (pour le téléchargement) à la demande de méthode pour demander au client de spécifier le type de support binaire requis et de le mapper à la demande d'intégration.
1. Définissez **Traitement du contenu** sur `Passthrough` dans la demande d’intégration (pour charger) et dans une réponse d’intégration (pour télécharger). Assurez-vous qu’aucun modèle de mappage n’est défini pour le type de contenu en question. Pour de plus amples informations, veuillez consulter [Transformations de données pour REST APIs dans API Gateway](rest-api-data-transformations.md).
La taille de la charge utile ne doit pas dépasser 10 Mo. Voir [Quotas pour la configuration et l’exécution d’une API REST dans API Gateway](api-gateway-execution-service-limits-table.md).
Assurez-vous que les types de contenu appropriés ont été ajoutés dans les métadonnées des fichiers sur Amazon S3. Pour du contenu multimédia lisible en streaming, `Content-Disposition:inline` peut également être ajouté aux métadonnées.
Pour plus d’informations sur la prise en charge des fichiers binaires dans API Gateway, consultez [Conversions du type de contenu dans API Gateway](api-gateway-payload-encodings-workflow.md).