Configuration des noms de domaine personnalisés pour les API REST - Amazon API Gateway
Enregistrement d'un nom de domaineNoms de domaine personnalisés optimisés pour la périphérieNoms de domaine personnalisés régionauxNoms de domaine personnalisés génériquesCertificats pour les noms de domaine personnalisés

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.

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

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

où api-id est généré par API Gateway, region (Région AWS) est spécifié par vous-même lors de la création de l'API et stage est spécifié par vous-même 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
Note

Un domaine personnalisé régional peut être associé aux API REST et aux API HTTP. Vous pouvez utiliser les API API Gateway version 2 pour créer et gérer des noms de domaine régionaux personnalisés pour les API REST.

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

Vous pouvez choisir une version TLS minimale prise en charge par votre compte API REST. 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ées au nom de domaine personnalisé ne peuvent pas atteindre API Gateway.

Note

Un nom de domaine personnalisé optimisé pour la périphérie est créé dans une Région spécifique et appartient à un compte AWS spécifique. Le déplacement d'un tel nom de domaine personnalisé entre Régions ou comptes AWS implique la suppression de la distribution CloudFront existante et la création d'une nouvelle. Le processus peut prendre environ 30 minutes avant que le nouveau nom de domaine personnalisé devienne disponible. Pour de plus amples informations, veuillez consulter 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 la périphérie, API Gateway configure une distribution Amazon CloudFront et un enregistrement DNS pour mapper le nom de domaine API au nom de domaine de 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 la périphérie, 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 CloudFront mappée. 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 à la région affilié à API Gateway. Lorsque vous effectuez des opérations de suivi pour créer et mettre à jour une telle distribution CloudFront dans CloudWatch Logs, vous devez utiliser cet ID de compte API Gateway. Pour de plus amples informations, veuillez consulter Consignation de la création du nom de domaine personnalisé dans CloudTrail.

Pour configurer un nom de domaine personnalisé optimisé pour la périphérie ou mettre à jour son certificat, vous devez être autorisé à mettre à jour les distributions CloudFront.

Pour activer l'accès, ajoutez des autorisations à vos utilisateurs, groupes ou rôles :

Les autorisations suivantes sont nécessaires pour mettre à jour les distributions CloudFront. 

{
    "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 la périphérie pour les API en exploitant Server Name Indication (SNI) sur la distribution CloudFront. Pour de plus amples 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, veuillez consulter Utilisation de noms de domaines alternatifs et de HTTPS dans le Manuel du développeur Amazon CloudFront.

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 la périphérie, vous pouvez demander à AWS Certificate Manager (ACM) de générer un nouveau certificat dans ACM ou d'importer dans ACM un certificat émis par une autorité de certification tierce dans la Région us-east-1 (USA Est (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

Avec les noms de domaine personnalisés génériques, vous pouvez prendre en charge un nombre presque infini de noms de domaine sans dépasser le quota par défaut. Par exemple, vous pouvez donner à chacun de vos clients son propre nom de domaine, customername.api.example.com.

Pour créer un nom de domaine personnalisé générique, 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, veuillez consulter 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 le AWSCentre de support pour demander une exception.

Certificats pour les noms de domaine personnalisés

Important

Vous spécifiez le certificat de votre nom de domaine personnalisé. Si votre application utilise l'épinglage de certificat, parfois appelé épinglage SSL, pour épingler un certificat ACM, l'application ne pourra peut-être pas se connecter à votre domaine une fois qu'AWS aura renouvelé le certificat. Pour plus d'informations, consultez la section Problèmes d'épinglage de certificat dans le Guide de l'utilisateur AWS Certificate Manager.

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

Rubriques