Noms de domaine personnalisés pour WebSocket les API dans API Gateway

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 est la région et le AWS stage est spécifié par vous lors du déploiement de l'API.

La partie nom d'hôte de l'URL api-id.execute-api.region.amazonaws.com fait référence à un point de terminaison d'API. Le nom du point de terminaison de l'API par défaut est généré de manière aléatoire, difficile à mémoriser et peu 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

Considérations

Les considérations suivantes peuvent avoir un impact sur votre utilisation d'un nom de domaine personnalisé.

• Si vous mappez un nom de domaine personnalisé à une WebSocket API, vous ne pouvez pas le mapper à une API REST ou à une API HTTP.

• Seuls les noms de domaine personnalisés régionaux sont pris en charge.

• Pour la version minimale de TLS, seul le protocole TLS 1.2 est pris en charge.

• Vous devez créer ou mettre à jour l'enregistrement des ressources de votre fournisseur DNS pour le mapper à votre point de terminaison d'API. Sans ce mappage, les demandes d'API destinées au nom de domaine personnalisé ne peuvent pas atteindre API Gateway.

• Vous pouvez prendre en charge un nombre presque infini de noms de domaine sans dépasser le quota par défaut en utilisant un certificat générique. Pour plus d’informations, consultez Noms de domaine personnalisés génériques.

Prérequis

Les conditions requises pour un nom de domaine personnalisé sont les suivantes.

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. Vous pouvez enregistrer votre nom de domaine Internet à l'aide d'Amazon Route 53 ou auprès d'un bureau d'enregistrement de domaines tiers de votre choix. Votre nom de domaine personnalisé peut être le nom d'un sous-domaine ou le domaine racine (également appelé « zone apex ») d'un domaine Internet enregistré.

Votre nom de domaine doit respecter la spécification RFC 1035 et peut comporter un maximum de 63 octets par étiquette et 255 octets au total.

Certificats pour les noms de domaine personnalisés

Avant de configurer un nom de domaine personnalisé pour une API, vous devez disposer d'un certificat SSL/TLS dans ACM. Si ACM n'est pas disponible dans la AWS région où vous créez votre nom de domaine personnalisé, 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. 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. Pour utiliser un certificat AWS géré pour un nom de domaine, il suffit de référencer son ARN.

Si votre application utilise l'épinglage de certificat, parfois appelé épinglage SSL, pour épingler un certificat ACM, il est possible que l'application ne puisse pas se connecter à votre domaine après le AWS renouvellement du certificat. Pour plus d'informations, consultez la section Problèmes d'épinglage de certificat dans le Guide de l'utilisateur AWS Certificate Manager .

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 AWS compte, vous pouvez configurer *.example.com et a.example.com vous comporter 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 de nom de domaine personnalisé générique si un autre AWS compte a créé un nom de domaine personnalisé en conflit avec le nom de domaine personnalisé générique. 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 AWS Centre de support pour demander une exception.

Prochaines étapes pour les noms de domaine personnalisés

Pour configurer un nom de domaine personnalisé pour une API HTTP, vous devez utiliser la documentation de la section API REST du guide du développeur d'API Gateway.

Spécifiez d'abord un certificat pour votre nom de domaine personnalisé. Pour plus d’informations, consultez Préparez les certificats AWS Certificate Manager. Ensuite, vous créez un nom de domaine personnalisé régional. Pour plus d'informations, voir Configurer un nom de domaine personnalisé régional dans API Gateway.