Tutoriel : Création REST API d'un proxy Amazon S3

À titre d'exemple pour illustrer l'utilisation d'une REST API API passerelle intégrée pour un proxy Amazon S3, cette section décrit comment créer et configurer un REST API pour exposer les opérations Amazon S3 suivantes :

• Exposez GET sur API la ressource racine du pour répertorier tous les compartiments Amazon S3 d'un appelant.

• Exposez GET sur une ressource Folder pour afficher la liste de tous les objets d'un compartiment Amazon S3.

• Exposez GET sur une ressource de dossier/élément pour afficher ou télécharger un objet depuis un compartiment Amazon S3.

Vous souhaiterez peut-être importer l'exemple API en tant que proxy Amazon S3, comme indiqué dansAPIDéfinitions ouvertes de l'exemple API en tant que proxy Amazon S3. Cet échantillon contient des méthodes plus exposées. Pour obtenir des instructions sur la façon d'importer un fichier à l'APIaide de la API définition Open, consultezDéveloppez REST APIs à l'aide d'Open API in API Gateway.

Note

Pour intégrer votre API passerelle API à Amazon S3, vous devez choisir une région dans laquelle les services API Gateway et Amazon S3 sont disponibles. Pour connaître la disponibilité par région, consultez Amazon API Gateway Endpoints and Quotas.

Rubriques

• Configurez IAM les autorisations permettant API d'invoquer les actions Amazon S3
• Créez API des ressources pour représenter les ressources Amazon S3
• Exposer une API méthode pour répertorier les compartiments Amazon S3 de l'appelant
• Exposer API les méthodes permettant d'accéder à un compartiment Amazon S3
• Exposer API les méthodes permettant d'accéder à un objet Amazon S3 dans un compartiment
• APIDéfinitions ouvertes de l'exemple API en tant que proxy Amazon S3
• Appelez-le à l'APIaide d'un REST API client

Configurez IAM les autorisations permettant API d'invoquer les actions Amazon S3

Pour pouvoir invoquer API des actions Amazon S3, vous devez disposer des IAM politiques appropriées associées à un IAM rôle.

Pour créer le rôle d'exécution du proxy de AWS service

1. Connectez-vous à la IAM console AWS Management Console et ouvrez-la à l'adresse https://console.aws.amazon.com/iam/.

2. Sélectionnez Roles.

3. Sélectionnez Créer un rôle.

4. Choisissez le AWS service sous Sélectionner le type d'entité de confiance, puis sélectionnez APIPasserelle et sélectionnez Autoriser la API passerelle à transférer les journaux vers CloudWatch les journaux.

5. Choisissez Suivant, puis Suivant.

6. Pour Nom du rôle, saisissez APIGatewayS3ProxyPolicy, puis choisissez Créer un rôle.

7. 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.

8. Pour le rôle sélectionné, sélectionnez l'onglet Ajouter des autorisations.

9. Choisissez Attacher des politiques dans la liste déroulante.

10. Dans la barre de recherche, saisissez AmazonS3FullAccess et choisissez Ajouter des autorisations.

    Note

    Ce didacticiel utilise une stratégie gérée pour plus de simplicité. La meilleure pratique consiste à créer votre propre IAM politique pour accorder les autorisations minimales requises.

11. Notez le rôle nouvellement crééARN, vous l'utiliserez ultérieurement.

Créez API des ressources pour représenter les ressources Amazon S3

Vous utilisez la ressource API's root (/) comme conteneur des compartiments Amazon S3 d'un appelant authentifié. Vous créez également Item des ressources Folder et pour représenter respectivement un compartiment Amazon S3 et un objet Amazon S3 particuliers. Le nom du dossier et la clé de l'objet seront spécifiés, sous forme de paramètres de chemin dans le cadre d'une demandeURL, par l'appelant.

Note

Lorsque vous accédez à des objets dont la clé d'objet inclut un caractère spécial / ou tout autre caractère spécial, le caractère doit être URL codé. Par exemple, test/test.txt doit être codé en test%2Ftest.txt.

Pour créer une API ressource présentant les fonctionnalités du service Amazon S3

1. Dans le même temps Région AWS que vous avez créé votre compartiment Amazon S3, créez un compartiment API nommé MyS3. Cette API ressource racine (/) représente le service Amazon S3. Dans cette étape, vous créez deux ressources supplémentaires /{folder} et /{item}.

2. Choisissez Créer une ressource.

3. Maintenez Ressource proxy désactivée.

4. Pour Chemin de ressource, sélectionnez /.

5. Sous Resource Name (Nom de la ressource), entrez {folder}.

6. Ne cochez pas la case CORS(Cross Origin Resource Sharing).

7. Choisissez Créer une ressource.

8. Sélectionnez la ressource /{folder}, puis choisissez Créer une ressource.

9. Suivez les étapes précédentes pour créer une ressource enfant de /{folder} nommée {item}.

   Votre finale API devrait ressembler à ce qui suit :

   

Exposer une API méthode pour répertorier les compartiments Amazon S3 de l'appelant

Pour obtenir la liste des compartiments Amazon S3 de l'appelant, il faut appeler l'action GETService sur Amazon S3. Sur API la ressource racine, (/), créez la GET méthode. Configurez la GET méthode d'intégration à Amazon S3, comme suit.

Pour créer et initialiser la méthode API's GET /

1. Sélectionnez la ressource /, puis choisissez Créer une méthode.

2. Pour le type de méthode, sélectionnez GET.

3. Pour Type d’intégration, sélectionnez AWS service.

4. Pour Région AWS, sélectionnez l' Région AWS endroit où vous avez créé votre compartiment Amazon S3.

5. Pour AWS service, sélectionnez Amazon Simple Storage Service.

6. Laissez Sous-domaine AWS vide.

7. Pour la HTTPméthode, sélectionnez GET.

8. Pour Type d’action, sélectionnez Utiliser un remplacement de chemin.

   Avec le remplacement du chemin, API Gateway transmet la demande du client à Amazon S3 en tant que demande de REST API type chemin Amazon S3 correspondante, dans laquelle une ressource Amazon S3 est exprimée par le chemin de ressource du modèle. s3-host-name/bucket/key APIGateway définit le s3-host-name client spécifié bucket et le key transmet à Amazon S3.

9. Pour Remplacement de chemin, saisissez /.

10. Pour Rôle d'exécution, entrez le rôle ARN pourAPIGatewayS3ProxyPolicy.

11. Choisissez les paramètres de demande de méthode.

    Vous utilisez les paramètres de demande de méthode pour contrôler qui peut appeler cette méthode de votre choixAPI.

12. Pour Autorisation, dans le menu déroulant, sélectionnez AWS_IAM.

    

13. Choisissez Créer une méthode.

Cette configuration intègre la demande GET https://your-api-host/stage/ frontale à la méthode GET https://your-s3-host/ principale.

Pour que vous API puissiez renvoyer correctement les réponses réussies et les exceptions à l'appelant, vous devez déclarer les réponses 200, 400 et 500 dans Method response. Vous utilisez le mappage par défaut pour 200 réponses afin que les réponses du backend dont le code de statut n'est pas déclaré ici soient renvoyées à l'appelant sous la forme de 200 réponses.

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.

2. Choisissez Ajouter un en-tête, puis procédez comme suit :

   1. Pour Nom de l’en-tête, saisissez Content-Type.

   2. Sélectionnez Add header.

   Répétez ces étapes pour créer un en-tête Timestamp et un en-tête Content-Length.

3. Choisissez Enregistrer.

4. Dans l’onglet Réponse de méthode, sous Réponses de méthode, choisissez Créer une réponse.

5. Pour HTTPle code d'état, entrez 400.

   Vous ne définissez aucun en-tête pour cette réponse.

6. Choisissez Enregistrer.

7. 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 de compartiments sous forme de XML charge utile et que la réponse de méthode par défaut de API Gateway renvoie une JSON charge utile, vous devez mapper la valeur du paramètre d'en-tête Content-Type du backend à son homologue du frontend. Dans le cas contraire, le client recevra application/json le type de contenu lorsque le corps de la réponse est en fait une XML chaîne. 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, tels que la date et la longueur du contenu.

Pour configurer les mappages d'en-têtes de réponse pour la méthodeGET/

1. Dans l’onglet Réponse d’intégration, sous Par défaut - Réponse, choisissez Modifier.

2. Pour l’en-tête Content-Length, saisissez integration.response.header.Content-Length pour la valeur de mappage.

3. Pour l’en-tête Content-Type, saisissez integration.response.header.Content-Type pour la valeur de mappage.

4. Pour l’en-tête Timestamp, saisissez integration.response.header.Date pour la valeur de mappage.

5. Choisissez Enregistrer. Le résultat devrait ressembler à ce qui suit :

   

6. Dans l’onglet Réponse d’intégration, sous Réponses d’intégration, choisissez Créer une réponse.

7. Pour HTTPstatus regex, entrez4\d{2}. Cela fait correspondre tous les codes d'état de HTTP réponse 4xx à la réponse de la méthode.

8. Pour Code de statut de la réponse de méthode, sélectionnez 400.

9. Choisissez Créer.

10. 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 HTTPstatus regex, entrez5\d{2}.

Comme bonne pratique, vous pouvez tester le API que vous avez configuré 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.

2. Sélectionnez Tester). Le résultat doit ressembler à l’image suivante :

   

Exposer API les méthodes permettant d'accéder à un compartiment Amazon S3

Pour utiliser un compartiment Amazon S3, vous devez exposer la GET méthode sur la ressource/{folder} pour répertorier les objets d'un compartiment. Les instructions sont similaires à celles décrites dans Exposer une API méthode pour répertorier les compartiments Amazon S3 de l'appelant. Pour d'autres méthodes, vous pouvez importer l'échantillon API ici,APIDéfinitions ouvertes de l'exemple API en tant que proxy Amazon S3.

Pour exposer la GET méthode sur une ressource de dossier

1. Sélectionnez la ressource /{folder}, puis choisissez Créer une méthode.

2. Pour le type de méthode, sélectionnez GET.

3. Pour Type d’intégration, sélectionnez AWS service.

4. Pour Région AWS, sélectionnez l' Région AWS endroit où vous avez créé votre compartiment Amazon S3.

5. Pour AWS service, sélectionnez Amazon Simple Storage Service.

6. Laissez Sous-domaine AWS vide.

7. Pour la HTTPméthode, sélectionnez GET.

8. Pour Type d’action, sélectionnez Utiliser un remplacement de chemin.

9. Pour Remplacement de chemin, saisissez {bucket}.

10. Pour Rôle d'exécution, entrez le rôle ARN pourAPIGatewayS3ProxyPolicy.

11. Choisissez Créer une méthode.

Vous définissez le paramètre de {folder} chemin dans le point de terminaison Amazon S3URL. 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.

2. Choisissez les paramètres de URL chemin, puis choisissez Ajouter un paramètre de chemin.

3. Pour Name (Nom), saisissez bucket.

4. Pour Mappage à partir de, entrez method.request.path.folder.

5. Choisissez Enregistrer.

Maintenant, vous testez votreAPI.

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.

2. Sous Chemin, pour le dossier, saisissez le nom de votre compartiment.

3. Sélectionnez Tester).

   Le résultat du test contient une liste des objets contenus dans votre compartiment.

   

Exposer API les méthodes permettant d'accéder à un objet Amazon S3 dans un compartiment

Amazon S3 prend en chargeGET,DELETE, HEADOPTIONS, POST et PUT les actions permettant d'accéder aux objets d'un compartiment donné et de 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 {folder}/{item} ressource, consultez l'exempleAPI,APIDéfinitions ouvertes de l'exemple API en tant que proxy Amazon S3.

Pour exposer la GET méthode sur un article, une ressource

1. Sélectionnez la ressource /{item}, puis choisissez Créer une méthode.

2. Pour le type de méthode, sélectionnez GET.

3. Pour Type d’intégration, sélectionnez AWS service.

4. Pour Région AWS, sélectionnez l' Région AWS endroit où vous avez créé votre compartiment Amazon S3.

5. Pour AWS service, sélectionnez Amazon Simple Storage Service.

6. Laissez Sous-domaine AWS vide.

7. Pour la HTTPméthode, sélectionnez GET.

8. Pour Type d’action, sélectionnez Utiliser un remplacement de chemin.

9. Pour Remplacement de chemin, saisissez {bucket}/{object}.

10. Pour Rôle d'exécution, entrez le rôle ARN pourAPIGatewayS3ProxyPolicy.

11. Choisissez Créer une méthode.

Vous définissez les paramètres {folder} et le {item} chemin dans le point de terminaison Amazon S3URL. 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.

2. Choisissez les paramètres du URL chemin.

3. Choisissez Ajouter un paramètre de chemin.

4. Pour Name (Nom), saisissez bucket.

5. Pour Mappage à partir de, entrez method.request.path.folder.

6. Choisissez Ajouter un paramètre de chemin.

7. Pour Name (Nom), saisissez object.

8. Pour Mappage à partir de, entrez method.request.path.item.

9. 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.

2. Sous Chemin, pour le dossier, saisissez le nom de votre compartiment.

3. Sous Chemin, pour l’élément, saisissez le nom d’un élément.

4. Sélectionnez Tester).

   Le corps de la réponse contiendra le contenu de l’élément.

   

   La demande renvoie correctement le texte brut de (« Hello world ») en tant que contenu du fichier spécifié (test.txt) dans le compartiment Amazon S3 donné (DOC- EXAMPLE -BUCKET).

Pour télécharger ou charger des fichiers binaires, qui dans API Gateway sont considérés comme n'importe quoi d'autre que du JSON contenu codé en UTF-8, des API paramètres supplémentaires sont nécessaires. 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 API les binaryMediaTypes. Vous pouvez réaliser cette opération dans la console :

   1. Choisissez APIles paramètres pourAPI.

   2. Sous Types de médias binaires, choisissez Ajouter un type de média binaire.

   3. Choisissez Ajouter un type de média binaire, puis saisissez le type de média requis, par exemple image/png.

   4. Choisissez Save changes (Enregistrer les modifications) pour sauvegarder le paramètre.

2. Ajoutez l'en-tête Content-Type (pour charger) et/ou Accept (pour télécharger) à la demande de méthode pour exiger que le client indique le type de média binaire requis et l'associe à la demande d'intégration.

3. 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 plus d'informations, consultez les sections Comportements intermédiaires d'intégration et Sélectionnez des modèles de VTL mappage.

La taille de la charge utile ne doit pas dépasser 10 Mo. Voir APIQuotas de passerelle pour configurer et exécuter un REST API.

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 le support binaire dans API Gateway, consultezConversions de type de contenu dans API Gateway.