Configuration des noms de domaine personnalisés pour les REST APIs - Amazon API Gateway

Configuration des noms de domaine personnalisés pour les REST APIs

Les noms de domaine personnalisés sont des URL plus simples et plus intuitives que vous pouvez fournir à vos utilisateurs d'API.

Après avoir déployé votre API, vous (et vos clients) pouvez appeler cette API à l'aide de l'URL de base par défaut au format suivant :

https://api-id.execute-api.region.amazonaws.com/stage

api-id est généré par API Gateway, region (Région AWS) est spécifiée par vous-même lors de la création de l'API et stage est spécifié par vous lors du déploiement de l'API.

La partie nom d'hôte de l'URL (c'est-à-dire, api-id.execute-api.region.amazonaws.com) fait référence à un point de terminaison de l’API. Le point de terminaison d'API par défaut peut être difficile à retenir et non convivial.

Avec des noms de domaine personnalisés, vous pouvez configurer le nom d'hôte de votre API et choisir un chemin de base (par exemple, myservice) pour mapper l'URL alternative à votre API. Par exemple, une URL de base de l’API plus conviviale peut devenir :

https://api.example.com/myservice

Si vous ne définissez pas de mappage de base sous un nom de domaine personnalisé, l'URL de base de l'API résultante est la même que le domaine personnalisé (par exemple, https://api.example.com). Dans ce cas, le nom de domaine personnalisé ne peut pas prendre en charge plusieurs API.

Note

Un domaine régional personnalisé peut être associé à REST API ou HTTP API. Vous pouvez utiliser les Versions d’API 2 d’API Gateway pour créer et gérer des noms de domaine personnalisés régionaux pour REST APIs.

Les noms de domaine personnalisés ne sont pas pris en charge pour les API privées.

Vous pouvez choisir une version de TLS minimale prise en charge par votre compte REST API. Pour les API REST, vous pouvez choisir TLS 1.2 ou TLS 1.0.

Enregistrement d'un nom de domaine

Pour pouvoir configurer des noms de domaine personnalisés pour vos API, vous devez avoir enregistré un nom de domaine Internet. Si nécessaire, vous pouvez enregistrer un domaine Internet à l'aide de Amazon Route 53 ou utiliser le bureau d'enregistrement de domaine tiers de votre choix. Le nom de domaine personnalisé d'une API peut être le nom d'un sous-domaine ou du domaine racine (également nommé « zone apex ») d'un domaine Internet enregistré.

Après avoir créé un nom de domaine personnalisé dans API Gateway, vous devez créer ou mettre à jour l'enregistrement de ressource de votre fournisseur DNS pour mapper à votre point de terminaison API. Sans ce mappage, les demandes d'API destinés au nom de domaine personnalisé ne peuvent pas atteindre API Gateway.

Note

Un nom de domaine personnalisé optimisé pour les périphériques est créé dans une région spécifique et appartient à un compte AWS spécifique. Le déplacement d'un nom de domaine personnalisé entre régions ou comptes AWS implique de supprimer la distribution CloudFront existante et d'en créer une nouvelle. Le processus peut prendre environ 30 minutes avant que le nouveau nom de domaine personnalisé devienne disponible. Pour plus d'informations, consultez la section Mise à jour des distributions CloudFront.

Noms de domaine personnalisés optimisés pour la périphérie

Lorsque vous déployez une API optimisée pour les périphériques, API Gateway configure une distribution Amazon CloudFront et un enregistrement DNS pour mapper le nom de domaine de l'API au nom de domaine de la distribution CloudFront. Les demandes pour l'API sont ensuite acheminées vers API Gateway via la distribution CloudFront mappée.

Lorsque vous créez un nom de domaine personnalisé pour une API optimisée pour les périphériques, API Gateway configure une distribution CloudFront. Mais vous devez configurer un enregistrement DNS pour mapper le nom de domaine personnalisé au nom de domaine de distribution CloudFront. Ce mappage concerne les demandes d'API qui sont liées au nom de domaine personnalisé à acheminer vers API Gateway via la distribution mappée CloudFront. Vous devez également fournir un certificat pour le nom de domaine personnalisé.

Note

La distribution CloudFront créée par API Gateway appartient à un compte spécifique à une région affiliée avec API Gateway. Lors du suivi d'opérations pour créer et mettre à jour une telle distribution CloudFront dans CloudWatch Logs, vous devez utiliser cet ID de compte API Gateway. Pour plus d'informations, consultez Consignation de la création du nom de domaine personnalisé dans CloudTrail.

Pour configurer un nom de domaine personnalisé optimisé pour les périphériques ou mettre à jour son certificat, vous devez être autorisé à mettre à jour les distributions CloudFront. Vous pouvez le faire en attachant la déclaration de stratégie IAM suivante à un utilisateur, un groupe ou un rôle IAM dans votre compte :

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront:updateDistribution" ], "Resource": [ "*" ] } ] }

API Gateway prend en charge les noms de domaine personnalisés optimisés pour les périphériques en exploitant Server Name Indication (SNI) sur la distribution CloudFront. Pour plus d'informations sur l'utilisation de noms de domaine personnalisés sur une distribution CloudFront, notamment sur le format de certificat requis et la longueur maximale d'une clé de certificat, consultez la section Utilisation de noms de domaines alternatifs et de HTTPS du Amazon CloudFront Manuel du développeur.

Pour configurer un nom de domaine personnalisé en tant que nom d'hôte de l'API, vous devez, en tant que propriétaire de celle-ci, fournir un certificat SSL/TLS pour ce nom de domaine.

Afin de fournir un certificat pour un nom de domaine personnalisé optimisé pour les périphériques, vous pouvez demander à AWS Certificate Manager (ACM) de générer un nouveau certificat dans ACM ou d'importer dans ACM un certificat personnalisé émis par une autorité de certification tierce dans la région us-east-1 (Virginie du Nord).

Noms de domaine personnalisés régionaux

Lorsque vous créez un nom de domaine personnalisé pour une API régionale, API Gateway crée un nom de domaine régional pour l'API. Vous devez configurer un enregistrement DNS pour mapper le nom de domaine personnalisé vers le nom de domaine régional. Vous devez également fournir un certificat pour le nom de domaine personnalisé.

Noms de domaine personnalisés génériques

API Gateway prend également en charge les noms de domaine personnalisés génériques. Vous pouvez spécifier un caractère générique (*) comme premier sous-domaine d'un domaine personnalisé qui représente tous les sous-domaines possibles d'un domaine racine.

Par exemple, le nom de domaine personnalisé générique *.example.com se traduit par des sous-domaines tels que a.example.com, b.example.com et c.example.com, qui effectuent tous un routage vers le même domaine.

Les noms de domaine personnalisés génériques prennent en charge des configurations distinctes des noms de domaine personnalisés standard d'API Gateway. Par exemple, dans un seul compte AWS, vous pouvez configurer *.example.com et a.example.com pour qu'ils se comportent différemment.

Vous pouvez utiliser les variables de contexte $context.domainName et $context.domainPrefix pour déterminer le nom de domaine utilisé par un client pour appeler votre API. Pour en savoir plus sur les variables de contexte, reportez-vous à la section Modèle de mappage API Gateway et référence à la variable de journalisation des accès.

Pour créer un nom de domaine personnalisé générique, vous devez fournir un certificat émis par ACM qui a été validé à l'aide du DNS ou de la méthode de validation par e-mail.

Note

Vous ne pouvez pas créer un nom de domaine personnalisé générique si un autre compte AWS a créé un nom de domaine personnalisé en conflit avec ce nom. Par exemple, si le compte A a créé a.example.com, le compte B ne peut pas créer le nom de domaine personnalisé générique *.example.com.

Si les comptes A et B ont le même propriétaire, vous pouvez contacter AWS Support Center pour demander une exception.

Certificats pour les noms de domaine personnalisés

Pour fournir un certificat pour un nom de domaine personnalisé dans une région où ACM est pris en charge, vous devez demander un certificat à ACM. Pour fournir un certificat pour un nom de domaine personnalisé régional dans une région où ACM n'est pas pris en charge, vous devez importer un certificat vers API Gateway dans cette région.

Pour importer un certificat SSL/TLS, vous devez fournir le corps du certificat SSL/TLS au format PEM, sa clé privée, ainsi que la chaîne de certificats du nom de domaine personnalisé. Chaque certificat stocké dans ACM est identifié par son ARN. Pour utiliser un certificat géré par AWS pour un nom de domaine, indiquez simplement son ARN.

ACM permet de configurer et d'utiliser un nom de domaine personnalisé pour une API. Vous créez un certificat pour le nom de domaine donné (ou vous importez un certificat), configurez le nom de domaine dans API Gateway, avec l'ARN du certificat fourni par ACM, et vous mappez un chemin de base sous le nom de domaine personnalisé à une étape déployée de l'API. Avec les certificats émis par ACM, vous n'avez pas à vous inquiéter d'une éventuelle exposition des informations sensibles du certificat, par exemple sa clé privée.