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.
Tutoriel : Création d'une API REST en tant que proxy Amazon S3 dans API Gateway
À 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.
-
Exposition de la méthode GET sur une ressource Folder pour afficher la liste de tous les objets d'un compartiment Amazon S3.
-
Exposition de la méthode GET sur une ressource Folder/Item pour afficher ou télécharger un objet à partir d'un compartiment Amazon S3.
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. Cet échantillon contient des méthodes plus exposées. Pour de plus amples informations sur l'importation d'une API à l'aide de la définition OpenAPI, veuillez consulter Configuration d'une API REST à l'aide d'OpenAPI.
Note
Pour intégrer votre API Amazon API Gateway à 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, veuillez consulter les points de terminaison et quotas Amazon API Gateway.
Rubriques
- Configuration d'autorisations IAM pour l'API afin d'appeler des actions Amazon S3
- Création de ressources d'API pour représenter des ressources Amazon S3
- Exposition d'une méthode d'API pour afficher la liste des compartiments Amazon S3 de l'appelant
- Exposition de méthodes d'API pour accéder à un compartiment Amazon S3
- Exposition de méthodes d'API pour accéder à un objet Amazon S3 dans un compartiment
- Définitions OpenAPI de l'exemple d'API en tant que proxy Amazon S3
- Appel de l'API à l'aide d'un client d'API REST
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.
Pour créer le rôle d’exécution du proxy de service AWS
Connectez-vous à l’outil AWS Management Console, puis ouvrez la console IAM à l'adresse https://console.aws.amazon.com/iam/
. -
Sélectionnez Roles (Rôles).
-
Sélectionnez Create role (Créer un rôle).
-
Choisissez Service AWS sous Sélectionner le type d’entité de confiance, puis choisissez API Gateway et sélectionnez Autoriser API Gateway à transmettre des journaux à CloudWatch Logs.
-
Choisissez Suivant, puis Suivant.
-
Pour Nom du rôle, saisissez
APIGatewayS3ProxyPolicy
, puis choisissez Créer un rôle. -
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.
-
Pour le rôle sélectionné, sélectionnez l'onglet Ajouter des autorisations.
-
Choisissez Attacher des politiques dans la liste déroulante.
-
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é. Il est recommandé de créer votre propre stratégie IAM afin d'accorder les autorisations minimales requises.
-
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
Nous allons utiliser la ressource racine de l'API (/
) comme conteneur des compartiments Amazon S3 d'un appelant authentifié. Nous allons é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
-
Dans la même Région AWS où 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}.
-
Sélectionnez la ressource racine de l’API, puis choisissez Créer une ressource.
Maintenez Ressource proxy désactivée.
Pour Chemin de ressource, sélectionnez
/
.Sous Resource Name (Nom de la ressource), entrez
{folder}
.Gardez CORS (Partage des ressources entre origines multiples) non coché.
Choisissez Créer une ressource.
Sélectionnez la ressource /{folder}, puis choisissez Créer une ressource.
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 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 à Amazon S3, comme suit.
Pour créer et initialiser la méthode GET /
de l'API
-
Sélectionnez la ressource /, puis choisissez Créer une méthode.
Pour le type de méthode, sélectionnez GET.
Pour Type d’intégration, sélectionnez Service AWS.
Pour Région AWS, sélectionnez la Région AWS où vous avez créé votre compartiment Amazon S3.
Pour Service AWS, sélectionnez Amazon Simple Storage Service.
Laissez Sous-domaine AWS vide.
Pour Méthode HTTP, sélectionnez GET.
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, 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 les3-host-name
et transmet les valeurs spécifiées par le clientbucket
etkey
du client vers Amazon S3.Pour Remplacement de chemin, saisissez /.
Pour Rôle d’exécution, saisissez l’ARN de rôle pour
APIGatewayS3ProxyPolicy
.Choisissez Créer une méthode.
Cette configuration intègre la demande GET
https://
frontale à la méthode your-api-host
/stage
/GET https://
principale.your-s3-host
/
Note
Après la configuration initiale, vous pouvez modifier ces paramètres sur la page Integration Request de la méthode.
Pour contrôler qui peut appeler cette méthode de notre API, nous activons l'indicateur d'autorisation de la méthode et nous le définissons sur AWS_IAM
.
Pour activer IAM de façon à contrôler l'accès à la méthode GET /
-
Dans l'onglet Demande de méthode, sous Paramètres de demande de méthode, choisissez Modifier.
-
Pour Autorisation, dans le menu déroulant, sélectionnez
AWS_IAM
. -
Choisissez Save (Enregistrer).
Pour que notre API renvoie correctement des réponses de succès et des exceptions à l'appelant, nous déclarons les réponses 200, 400 et 500 dans Method Response. Nous utilisons le mappage par défaut pour les réponses 200 pour que les réponses principales 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 /
-
Dans l’onglet Méthode de réponse, sous Réponse 200, choisissez Modifier.
-
Choisissez Ajouter un en-tête, puis procédez comme suit :
Pour Nom de l’en-tête, saisissez
Content-Type
.Sélectionnez Add header.
Répétez ces étapes pour créer un en-tête
Timestamp
et un en-têteContent-Length
. Choisissez Save (Enregistrer).
Dans l’onglet Réponse de méthode, sous Réponses de méthode, choisissez Créer une réponse.
Pour Code de statut HTTP, saisissez 400.
Vous ne définissez aucun en-tête pour cette réponse.
Choisissez Save (Enregistrer).
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.
Dans la mesure où la réponse d'intégration réussie d'Amazon S3 renvoie la liste de compartiments en tant que charge utile XML et où la réponse de méthode par défaut d'API Gateway renvoie une charge utile JSON, nous devons mapper la valeur du paramètre d'en-tête Content-Type du backend à celle du frontend. 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, nous souhaitons é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 /
-
Dans l’onglet Réponse d’intégration, sous Par défaut - Réponse, choisissez Modifier.
Pour l’en-tête Content-Length, saisissez
integration.response.header.Content-Length
pour la valeur de mappage.Pour l’en-tête Content-Type, saisissez
integration.response.header.Content-Type
pour la valeur de mappage.Pour l’en-tête Timestamp, saisissez
integration.response.header.Date
pour la valeur de mappage.Choisissez Save (Enregistrer). Le résultat devrait ressembler à ce qui suit :
-
Dans l’onglet Réponse d’intégration, sous Réponses d’intégration, choisissez Créer une réponse.
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.Pour Code de statut de la réponse de méthode, sélectionnez
400
.Choisissez Créer.
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}
.
Comme bonne pratique, testons l'API que nous avons configurée jusqu'à présent.
Pour tester la méthode GET /
-
Choisissez l’onglet Test. Vous devrez peut-être choisir la flèche droite pour afficher l'onglet.
-
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, nous exposons 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. 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.
Pour exposer la méthode GET sur une ressource de dossier
Sélectionnez la ressource /{folder}, puis choisissez Créer une méthode.
Pour le type de méthode, sélectionnez GET.
Pour Type d’intégration, sélectionnez Service AWS.
Pour Région AWS, sélectionnez la Région AWS où vous avez créé votre compartiment Amazon S3.
Pour Service AWS, sélectionnez Amazon Simple Storage Service.
Laissez Sous-domaine AWS vide.
Pour Méthode HTTP, sélectionnez GET.
Pour Type d’action, sélectionnez Utiliser un remplacement de chemin.
Pour Remplacement de chemin, saisissez
{bucket}
.Pour Rôle d’exécution, saisissez l’ARN de rôle pour
APIGatewayS3ProxyPolicy
.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}
-
Dans l’onglet Requête d’intégration, sous Paramètres de requête d’intégration, choisissez Modifier.
Choisissez Paramètres de chemin d’URL, puis choisissez Ajouter un paramètre de chemin.
Pour Name (Nom), saisissez
bucket
.Pour Mappage à partir de, entrez
method.request.path.folder
. La configuration doit ressembler à ce qui suit :Choisissez Save (Enregistrer).
Maintenant, vous testez votre API.
Pour tester la méthode /{folder} GET
.
-
Choisissez l’onglet Test. Vous devrez peut-être choisir la flèche droite pour afficher l'onglet.
-
Sous Chemin, pour le dossier, saisissez le nom de votre compartiment.
-
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.
Pour exposer la méthode GET sur une ressource d’élément
-
Sélectionnez la ressource /{item}, puis choisissez Créer une méthode.
-
Pour le type de méthode, sélectionnez GET.
-
Pour Type d’intégration, sélectionnez Service AWS.
-
Pour Région AWS, sélectionnez la Région AWS où vous avez créé votre compartiment Amazon S3.
-
Pour Service AWS, sélectionnez Amazon Simple Storage Service.
-
Laissez Sous-domaine AWS vide.
-
Pour Méthode HTTP, sélectionnez GET.
-
Pour Type d’action, sélectionnez Utiliser un remplacement de chemin.
-
Pour Remplacement de chemin, saisissez {bucket}/{object}.
-
Pour Rôle d’exécution, saisissez l’ARN de rôle pour
APIGatewayS3ProxyPolicy
. -
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}
-
Dans l’onglet Requête d’intégration, sous Paramètres de requête d’intégration, choisissez Modifier.
-
Choisissez paramètres de chemin d’URL.
-
Choisissez Ajouter un paramètre de chemin.
-
Pour Name (Nom), saisissez
bucket
. -
Pour Mappage à partir de, entrez
method.request.path.folder
. -
Choisissez Ajouter un paramètre de chemin.
-
Pour Name (Nom), saisissez
object
. -
Pour Mappage à partir de, entrez
method.request.path.item
. -
Choisissez Save (Enregistrer).
Pour tester la méthode /{folder}/{object} GET
.
-
Choisissez l’onglet Test. Vous devrez peut-être choisir la flèche droite pour afficher l'onglet.
-
Sous Chemin, pour le dossier, saisissez le nom de votre compartiment.
-
Sous Chemin, pour l’élément, saisissez le nom d’un élément.
-
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é (DOC-EXAMPLE-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
-
Enregistrez les types de médias du fichier concerné dans l'attribut binaryMediaTypes de l'API. Vous pouvez réaliser cette opération dans la console :
-
Choisissez Paramètres de l’API pour l’API.
-
Sous Types de médias binaires, choisissez Ajouter un type de média binaire.
-
Choisissez Ajouter un type de média binaire, puis saisissez le type de média requis, par exemple
image/png
. -
Choisissez Save changes (Enregistrer les modifications) pour sauvegarder le paramètre.
-
-
Ajoutez l'en-tête
Content-Type
(pour charger) et/ouAccept
(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. -
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 Comportements de transfert direct et Sélection d'un modèle de mappage VTL.
La taille de la charge utile ne doit pas dépasser 10 Mo. Voir Quotas API Gateway pour la configuration et l'exécution d'une API REST.
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 de plus amples informations sur la prise en charge des fichiers binaires dans API Gateway, veuillez consulter Conversions du type de contenu dans API Gateway.