Comment configurer API Gateway avec ma propre distribution CloudFront ?

Lecture de 10 minute(s)

Je souhaite un point de terminaison d'API optimisé pour les périphériques dans Amazon API Gateway, mais j'ai besoin de davantage de contrôle sur la distribution Amazon CloudFront. Comment puis-je créer et utiliser ma propre distribution ?

Brève description

Si vos clients d'API sont dispersés géographiquement, envisagez d'utiliser un point de terminaison d'API optimisé pour les périphériques dans API Gateway. Ce type de point de terminaison agit comme un point de terminaison régional avec une distribution Web CloudFront gérée par AWS afin d'améliorer le temps de connexion du client.

Pour utiliser le réseau global de diffusion de contenu CloudFront et conserver un meilleur contrôle sur la distribution, vous pouvez utiliser une API régionale avec une distribution Web CloudFront personnalisée.

Solution

Créez une API régionale dans API Gateway. Puis, procédez comme suit :

Configurer une méthode GET pour votre API

1. Dans la console API Gateway, choisissez le nom de votre nouvelle API régionale.

2. Dans le panneau Resources (Ressources), choisissez Actions. Sélectionnez Create Method (Créer une méthode). Une liste apparaît sous le nœud /resource .

3. Choisissez GET dans la liste. Ensuite, choisissez l'icône de coche.

4. Dans / - GET - Setup (/ - GET - Configuration), pour Integration Type (Type d'intégration), choisissez Mock (Fictif). Ensuite, choisissez Save (Enregistrer).
Remarque : une intégration fictive répond à toutes les requêtes qui l’atteignent, ce qui nous permettra d'effectuer des tests.

Déployez votre API et identifiez l'URL d'appel de votre API

1. Déployez votre API à une étape.

2. Dans la partie supérieure du volet Stage Editor (Éditeur d'étape), copiez Invoke URL (URL d'appel) dans le presse-papier.

Exemple d'URL d'appel de l'API Gateway API

https://restApiId.execute-api.region.amazonaws.com/stageName.

Testez votre API pour une réponse 200 OK

Pour vérifier que votre API renvoie une réponse 200 OK, testez l'URL d'appel de votre API à l'aide de la console API Gateway, de l'application Postman ou de curl.

Pour tester votre API pour une réponse 200 OK en utilisant curl

En fonction de votre système d'exploitation, exécutez les commandes suivantes :

Remarque : remplacez https://restApiId.execute-api.region.amazonaws.com/stageName par l'URL d'appel de votre API avant d'exécuter une des commandes suivantes.

Pour Linux, exécutez la commande suivante :

curl -IX GET https://restApiId.execute-api.region.amazonaws.com/stageName

Pour Windows PowerShell et exécutez la commande suivante :

curl https://restApiId.execute-api.region.amazonaws.com/stageName

Remarque : si vous obtenez un code d'état autre qu'une réponse 200 OK, vérifiez la console pour confirmer les éléments suivants :
Votre API est déployée sur votre scène.
Votre étape est spécifiée dans votre URL d'appel.

Création d'une distribution Web CloudFront

1. Dans la console CloudFront, choisissez Créer une distribution.

2. Sur la page Select a delivery method for your content (Sélectionner une méthode de livraison pour votre contenu) sous Web, choisissez Get Started (Démarrer).

3. Sur la page Create Distribution (Créer une distribution), pour Origin Domain Name (Nom du domaine d'origine), collez l'URL d'appel de votre API. Supprimez ensuite le nom de la scène.

Exemple de nom du domaine d'origine

https://1a2bc3d456.execute-api.us-east-1.amazonaws.com

4. Pour Origin Path (Chemin d'origine), entrez le nom de l'étape de votre API avec une barre oblique devant (/stageName) [(/nom d’étape)]. Ou, si vous souhaitez entrer vous-même le nom de l'étape lors de l'appel de l'URL, ne saisissez pas de Origin Path (Chemin d'origine).
Remarque : La saisie d'un nom d'étape incorrect pour Origin Path lors de l'appel de la distribution CloudFront génère parfois une erreur. Par exemple, une erreur de requête non autorisée qui renvoie le message « Missing Authentication Token » (« Jeton d'authentification manquant ») et un code de réponse 403 Forbidden (403 Interdit).

5. Pour le protocole SSL d'origine minimale, il est recommandé de choisir TLSv1.2. Ne choisissez pas SSLv3. API Gateway ne prend pas en charge le protocole SSLv3.

6. Pour Stratégie de protocole d'origine, choisissez HTTPS uniquement.
Remarque : API Gateway ne prend pas en charge les points de terminaison non chiffrés (HTTP). Pour plus d'informations, consultez FAQ sur Amazon API Gateway.

7. (Facultatif) Pour transférer des en-têtes personnalisés vers votre origine, indiquez un ou plusieurs en-têtes personnalisés pour En-têtes personnalisés d'origine.
Remarque : il existe plusieurs en-têtes personnalisés que CloudFront ne peut pas acheminer vers votre origine.

8. Suivez les instructions de la section Si vous utilisez l'authentification IAM pour votre API ou des noms de domaine personnalisés pour votre distribution, le cas échéant.

9. (Facultatif) Sous Distribution Settings (Paramètres de distribution), configurez les paramètres supplémentaires que vous souhaitez personnaliser.

10. Choisissez Create Distribution (Créer une distribution).

11. Attendez la fin du déploiement de votre distribution. Cela prend 15 à 20 minutes. Lorsque Status (Statut) affiche Deployed (Déployé) dans la console, la distribution est prête.

Pour plus d'informations, consultez Creating a Distribution (Création d'une distribution).

Test de votre distribution Web CloudFront

1. Dans la console CloudFront, copiez le nom de domaine de votre distribution dans votre presse-papiers.

Exemple de nom de domaine non personnalisé

a222222bcdefg5.cloudfront.net.

2. Testez le nom de domaine pour obtenir une réponse 200 OK à l'aide de l'une des commandes mentionnées précédemment dans la section Test your API (Tester votre API). Si vous obtenez un code d'erreur de serveur « 500 », il est possible que la distribution ne soit pas déployée. Si vous n'obtenez pas de réponse, il est possible que l'enregistrement DNS CloudFront DNS n'ait pas encore été propagé. Dans les deux cas, confirmez que 15 à 20 minutes se sont écoulées depuis la création de votre distribution. Ensuite, réessayez la procédure.

Important : si vous avez activé l'authentification AWS Identity et Access Management (IAM) sur une méthode pour une ressource d'API particulière, vous devez ajouter le nom de la ressource à la fin du nom de domaine de distribution lors de l'appel de votre API. L'URL d'appel complète (y compris le nom de la ressource) ressemble à l'un des exemples suivants. La sortie dépend de la saisie ou non d'un chemin d'origine lors de la création de la distribution :

API API Gateway invoque l'URL avec un exemple de chemin d'origine

https://distributionDomainName/stageName/resourceName

API API Gateway invoque l'URL sans un chemin d'origine exemple

https://distributionDomainName/resourceName

Pour plus d'informations sur les tests, consultez Comment activer l'authentification IAM pour les API API Gateway ?

Votre API utilise désormais la distribution Web que vous avez créée. Les ressources sont accessibles via l'URL de l'API CloudFront.

Si vous utilisez l'authentification IAM pour votre API ou des noms de domaine personnalisés pour votre distribution Web CloudFront

Par défaut, CloudFront ne transmet pas les en-têtes d'autorisation entrants à l'origine (pour ce cas d'utilisation, API Gateway). Si vous utilisez l'authentification IAM pour votre API ou des noms de domaine personnalisés pour votre distribution, vous devez effectuer l'une des opérations suivantes :

(Pour l'authentification IAM) Ajoutez l'en-tête Authorization à votre liste d'autorisation CloudFront

1. Si vous ne l'avez pas encore fait, suivez les étapes 1 à 7 de la section Créer une distribution Web CloudFront de cet article.

2. Sur la page Create Distribution (Créer une distribution), pour les paramètres de demande de cache et d'origine, choisissez Use a cache policy and origin request policy (Utiliser une stratégie de cache et une stratégie de demande d'origine). Ensuite, sous Cache Policy (Stratégie de cache), choisissez une stratégie de cache existante ou créez une nouvelle stratégie de cache qui ajoute l'en-tête Authorization (Autorisation) à votre liste d'autorisations CloudFront.

3. Si vous utilisez une stratégie de cache existante, pour Cache Based on Selected Request Headers (Cache basé sur les en-têtes de demande sélectionnés), choisissez Whitelist (Liste blanche). Puis, pour Whitelist Headers (En-têtes sur liste blanche), ajoutez Authorization (Autorisation) à la liste des en-têtes autorisés.

Important : si vous modifiez le paramètre Cache Based on Selected Request Headers (Cache basé sur les en-têtes de requêtes sélectionnés) sur All (Tout) ou si vous autorisez l'en-tête Host (Hôte), votre configuration ne fonctionnera pas. Pour plus d'informations, consultez Mise en cache de contenu basée sur des en-têtes de requêtes.

4. (Facultatif) Pour tester le programme d'installation, procédez comme suit :
Créez la signature Signature Version 4 requise pour votre point de terminaison API Gateway par programme. Pour la valeur d'hôte, entrez l'URL de votre API Gateway invoquer. Pour la valeur du point de terminaison, entrez votre URL de distribution Web CloudFront.

Exemple d'URL d'appel de passerelle API

<api-id>.execute.<region>.amazon.com

Exemple d'URL de distribution Web CloudFront

dxxxxx.cloudfront.net

Remarque : si vous utilisez l'application Postman, dans l'onglet Authorization (Autorisation), pour Type, assurez-vous de choisir AWS Signature. Ensuite, entrez la clé d'accès et la clé secrète. Les en-têtes requis sont générés par Postman à l'aide des informations d'identification que vous entrez.

Ensuite, envoyez la requête API à la distribution CloudFront en utilisant l'en-tête Authorization (et tous les signedHeaders) générés à partir du processus Signature Version 4.

(Pour les noms de domaine personnalisés ou l'authentification IAM) Configurez un nom de domaine personnalisé régional dans API Gateway pour accéder à votre API

1. Créez une nouvelle API régionale dans API Gateway ou modifiez votre API API Gateway optimisée pour les bords en une API régionale.

2. Configurez un nom de domaine personnalisé régional pour l'API et créez un mappage d'API pour votre API.
Remarque : utilisez ce nom de domaine personnalisé lorsque vous accédez à votre API via CloudFront.

3. Créez une distribution Web CloudFront en suivant les instructions de la section Créer une distribution Web CloudFront de cet article, à une exception près. À l'étape 3, pour Origin Domain Name, entrez votre nom de domaine cible API Gateway au lieu de l'URL d'appel de votre API.
Remarque : vous pouvez trouver votre nom de domaine cible API Gateway dans la configuration Endpoint (point de terminaison) de vos détails de domaine personnalisés.

Exemple de nom de domaine cible API Gateway

d-xxxx..execute-api.<region>.amazonaws.com

4. Sur la page Create Distribution (Créer une distribution), pour les paramètres de demande de cache et d'origine, choisissez Use a cache policy and origin request policy (Utiliser une stratégie de cache et une stratégie de demande d'origine). Ensuite, sous Stratégie de cache (Stratégie de cache), choisissez une stratégie de cache existante ou créez une nouvelle stratégie de cache qui ajoute les en-têtes Authorization (Autorisation) et Host (Hôte) à votre liste d'autorisations CloudFront.

5. Si vous utilisez une stratégie de cache existante, pour Cache Based on Selected Request Headers (Cache basé sur les en-têtes de demande sélectionnés), choisissez Whitelist (Liste blanche). Pour Whitelist Headers (En-têtes sur liste blanche), ajoutez Authorization (Autorisation) et Host (Hôte) à la liste des en-têtes autorisés.

6. Sous Distribution Settings (Paramètres de distribution), pour Alternate Domain Name (Autre nom de domaine), entrez le nom de domaine personnalisé que vous avez créé.

7. Pour Certificat SSL, sélectionez Certificat SSL personnalisé. Ajoutez ensuite le certificat AWS Certificate Manager (ACM) pour ce domaine.

Après avoir déployé la distribution Web CloudFront, configurez l'enregistrement DNS pour mapper le domaine personnalisé à la distribution Web CloudFront. Pour ce faire, créez un alias ou un enregistrement CNAME. Pour en savoir plus, consultez Utilisation d'URL personnalisées pour les fichiers en ajoutant d'autres noms de domaine (CNAME).

9. (Facultatif) Pour tester la configuration, créez une demande signée Signature Version 4 pour votre nom de domaine personnalisé par programme.
Remarque : L'application Postman peut être utilisée pour tester la configuration.