Configuration d’un nom de domaine personnalisé optimisé pour la périphérie dans API Gateway - Amazon API Gateway
ConsidérationsCréation d’un nom de domaine personnalisé optimisé pour la périphérieConfiguration du mappage de chemin de base d’une API à l’aide d’un nom de domaine personnalisé servant de nom d’hôteCréation d’un enregistrement DNS pour votre nom de domaine personnalisé optimisé pour la périphérieConsignation de la création du nom de domaine personnalisé dans CloudTrailRotation d’un certificat importé dans ACMAppel de votre API avec des noms de domaine personnalisés lorsque vous utilisez un mappage de chemin de base

Configuration d’un nom de domaine personnalisé optimisé pour la périphérie dans API Gateway

Lorsque vous créez un nom de domaine personnalisé pour 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. 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.

Considérations

Voici quelques points à prendre en compte pour votre nom de domaine personnalisé optimisé pour la périphérie :

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

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

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

  • Vous devez demander ou importer un certificat pour votre nom de domaine personnalisé optimisé pour la périphérie dans la région us-east-1 USA Est (Virginie du Nord).

  • 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 ce type de distribution CloudFront dans CloudTrail, 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.

  • 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 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 Using Alternate Domain Names and HTTPS dans le Guide du développeur Amazon CloudFront.

  • Il faut compter environ 40 minutes pour qu’un nom de domaine personnalisé optimisé pour la périphérie soit prêt.

  • Une fois que vous avez créé votre nom de domaine personnalisé optimisé pour la périphérie, vous devez créer un enregistrement DNS pour mapper le nom de domaine personnalisé au nom de la distribution CloudFront.

Création d’un nom de domaine personnalisé optimisé pour la périphérie

La procédure suivante décrit comment créer un nom de domaine personnalisé optimisé pour la périphérie pour une API.

AWS Management Console

  1. Connectez-vous à la console API Gateway à l’adresse https://console.aws.amazon.com/apigateway.

  2. Sélectionnez Noms de domaine personnalisés dans le volet de navigation principal.

  3. Choisissez Ajouter un nom de domaine.

  4. Pour Nom de domaine, entrez un nom de domaine.

  5. Pour Mode de routage, choisissez API_MAPPING_ONLY.

  6. Pour Type de point de terminaison d’API, choisissez Optimisé pour la périphérie.

  7. Choisissez une version TLS minimale.

  8. Choisissez un certificat ACM.

  9. Choisissez Ajouter un nom de domaine.

REST API

  1. Appelez domainname:create, en spécifiant le nom de domaine personnalisé et l’ARN d’un certificat stocké dans AWS Certificate Manager.

    Si l’appel d’API aboutit, il renvoie un code de réponse 201 Created contenant l’ARN du certificat et le nom de la distribution CloudFront associée dans sa charge utile.

  2. Notez le nom de domaine de la distribution CloudFront affiché dans la sortie. Vous en aurez besoin à l’étape suivante pour définir la cible de l’alias d’enregistrement A du domaine personnalisé dans votre DNS.

Pour des exemples de code de cet appel d’API REST, consultez domainname:create.

Il faut compter environ 40 minutes pour qu’un nom de domaine personnalisé optimisé pour la périphérie soit prêt, mais la console affiche immédiatement le nom de domaine de la distribution CloudFront associée sous la forme distribution-id.cloudfront.net, ainsi que l’ARN du certificat. En attendant, vous pouvez créer un mappage du chemin de base ou une règle de routage, puis configurer l’alias de l’enregistrement DNS afin de mapper le nom de domaine personnalisé au nom de domaine de la distribution CloudFront associée.

Configuration du mappage de chemin de base d’une API à l’aide d’un nom de domaine personnalisé servant de nom d’hôte

Étant donné que vous avez défini le mode de routage sur API_MAPPING_ONLY, vous pouvez utiliser un mappage du chemin de base pour utiliser un seul nom de domaine personnalisé comme nom d’hôte de plusieurs API. Le mappage de chemin de base rend une API accessible par la combinaison du nom de domaine personnalisé et du chemin de base associé.

Par exemple, si vous avez créé dans API Gateway une API nommée PetStore et une autre nommée Dogs et que vous avez configuré un nom de domaine personnalisé api.example.com, vous pouvez définir l’URL de l’API PetStore comme https://api.example.com.

Cette opération associe l’API PetStore au chemin de base d’une chaîne vide. Si vous définissez l’URL de l’API PetStore comme https://api.example.com/PetStore, l’API PetStore est associée au chemin de base PetStore. Vous pouvez affecter un chemin de base MyDogList pour l’API Dogs. L’URL de https://api.example.com/MyDogList est alors l’URL racine de l’API Dogs.

Pour configurer des mappages d’API à plusieurs niveaux, vous ne pouvez utiliser qu’un nom de domaine personnalisé régional. Les noms de domaine personnalisés optimisés pour la périphérie ne sont pas pris en charge. Pour plus d’informations, consultez Utilisation de mappages d’API pour connecter des étapes d’API REST à un nom de domaine personnalisé.

La procédure suivante configure les mappages d’API pour mapper les chemins de votre nom de domaine personnalisé à vos étapes d’API.

AWS Management Console

  1. Connectez-vous à la console API Gateway à l’adresse https://console.aws.amazon.com/apigateway.

  2. Sélectionnez Custom Domain Names dans le panneau de navigation principal de la console API Gateway.

  3. Choisissez un nom de domaine personnalisé.

  4. Choisissez Configurer les mappages d’API.

  5. Choisissez Ajouter un nouveau mappage.

  6. Spécifiez l’API, l’étape, et le chemin (facultatif) pour le mappage.

  7. Choisissez Enregistrer.

REST API

Appelez basepathmapping:create sur un nom de domaine personnalisé donné, en spécifiant le basePath, restApiId et une propriété stage de déploiement dans la charge utile de la demande.

Si l’appel d’API aboutit, il renvoie le code de réponse 201 Created.

Pour des exemples de code de l’appel d’API REST, consultez basepathmapping:create.

Pour plus de flexibilité dans l’acheminement du trafic vers vos API, vous pouvez remplacer le mode de routage par ROUTING_RULE_ONLY ou ROUTING_RULE_THEN_API_MAPPING et créer une règle de routage. Pour plus d’informations, consultez Envoi du trafic à vos API via votre nom de domaine personnalisé dans API Gateway.

Création d’un enregistrement DNS pour votre nom de domaine personnalisé optimisé pour la périphérie

Après avoir créé votre nom de domaine personnalisé optimisé pour la périphérie, configurez l’alias de l’enregistrement DNS.

Nous vous recommandons d’utiliser Route 53 pour créer un alias d’enregistrement A pour votre nom de domaine personnalisé et de spécifier le nom de domaine de la distribution CloudFront en tant que cible de l’alias. Cela signifie que Route 53 peut acheminer votre nom de domaine personnalisé, même s’il s’agit d’une zone apex. Pour plus d’informations, consultez Choix entre des jeux d’enregistrements de ressources avec ou sans alias dans le guide du développeur Amazon Route 53.

Pour obtenir des instructions sur Amazon Route 53, consultez Acheminement du trafic vers Amazon API Gateway à l’aide de votre nom de domaine dans le Manuel du développeur Amazon Route 53.

Consignation de la création du nom de domaine personnalisé dans CloudTrail

Lorsque CloudTrail est activé pour la journalisation des appels API Gateway effectués par votre compte, API Gateway enregistre les mises à jour de distribution CloudFront associées lorsqu’un nom de domaine personnalisé est créé ou mis à jour pour une API. Ces journaux sont disponibles dans us-east-1. Étant donné que ces distributions CloudFront appartiennent à API Gateway, chacune de ces distributions CloudFront signalées est identifiée par l’un des ID de compte API Gateway spécifiques à la région suivants, au lieu de l’ID de compte du propriétaire de l’API.

Région

ID de compte
us-east-1 392220576650
us-east-2 718770453195
us-west-1 968246515281
us-west-2 109351309407
ca-central-1 796887884028
eu-west-1 631144002099
eu-west-2 544388816663
eu-west-3 061510835048
eu-central-1 474240146802
eu-central-2 166639821150
eu-north-1 394634713161
eu-south-1 753362059629
eu-south-2 359345898052
ap-northeast-1 969236854626
ap-northeast-2 020402002396
ap-northeast-3 360671645888
ap-southeast-1 195145609632
ap-southeast-2 798376113853
ap-southeast-3 652364314486
ap-southeast-4 849137399833
ap-south-1 507069717855
ap-south-2 644042651268
ap-east-1 174803364771
sa-east-1 287228555773
me-south-1 855739686837
me-central-1 614065512851

Rotation d’un certificat importé dans ACM

ACM gère automatiquement le renouvellement des certificats qu’il émet. Vous n’avez pas besoin d’effectuer la rotation des certificats émis par ACM pour vos noms de domaine personnalisés. CloudFront le gère en votre nom.

Toutefois, si vous importez un certificat dans ACM et que vous l’utilisez pour un nom de domaine personnalisé, vous devez effectuer la rotation de ce certificat avant qu’il n’arrive à expiration. Cela implique d’importer un nouveau certificat tiers pour le nom de domaine et d’effectuer la rotation du certificat existant vers le nouveau. Vous devez répéter ce processus lorsque le certificat nouvellement importé arrive à expiration. Sinon, vous pouvez demander à ACM d’émettre un nouveau certificat pour le nom de domaine et d’effectuer la rotation du certificat existant vers le nouveau certificat émis par ACM. Après cela, vous pouvez laisser ACM et CloudFront gérer automatiquement la rotation de certificat. Pour créer ou importer un nouveau certificat ACM, suivez les étapes décrites dans Pour créer ou importer un certificat SSL/TLS dans ACM.

La procédure suivante explique comment effectuer la rotation d’un certificat pour un nom de domaine.

Note

Il faut compter environ 40 minutes pour effectuer la rotation d’un certificat importé dans ACM.

AWS Management Console

  1. Demandez ou importez un certificat dans ACM.

  2. Connectez-vous à la console API Gateway à l’adresse https://console.aws.amazon.com/apigateway.

  3. Sélectionnez Custom Domain Names dans le panneau de navigation principal de la console API Gateway.

  4. Choisissez un nom de domaine personnalisé optimisé pour la périphérie.

  5. Pour Configuration du point de terminaison, choisissez Modifier.

  6. Pour Certificat ACM, choisissez un certificat dans la liste déroulante.

  7. Sélectionnez Enregistrer les modifications pour commencer la rotation du certificat pour le nom de domaine personnalisé.

REST API

Appelez l’action domainname:update, en spécifiant l’ARN du nouveau certificat ACM pour le nom de domaine personnalisé spécifié.

AWS CLI

La commande update-domain-name suivante met à jour le certificat ACM d’un nom de domaine optimisé pour la périphérie.

aws apigateway update-domain-name \
    --domain-name edge.example.com \
    --patch-operations "op='replace',path='/certificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"

La commande update-domain-name suivante met à jour le certificat ACM d’un nom de domaine régional.

aws apigateway update-domain-name \
    --domain-name regional.example.com \
    --patch-operations "op='replace',path='/regionalCertificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"

Appel de votre API avec des noms de domaine personnalisés lorsque vous utilisez un mappage de chemin de base

L’appel d’une API avec un nom de domaine personnalisé est identique à l’appel de l’API avec son nom de domaine par défaut, sous réserve que l’URL correcte soit utilisée.

Les exemples suivants comparent et opposent un ensemble d’URL par défaut aux URL personnalisées correspondantes de deux API (udxjef et qf3duz) dans une région (us-east-1) et pour un nom de domaine personnalisé (api.example.com) donnés.

ID d’API Étape URL par défaut Chemin de base URL personnalisé
udxjef prod https://udxjef.execute-api.us-east-1.amazonaws.com/prod /petstore https://api.example.com/petstore
udxjef tst https://udxjef.execute-api.us-east-1.amazonaws.com/tst /petdepot https://api.example.com/petdepot
qf3duz dev https://qf3duz.execute-api.us-east-1.amazonaws.com/dev /bookstore https://api.example.com/bookstore
qf3duz tst https://qf3duz.execute-api.us-east-1.amazonaws.com/tst /bookstand https://api.example.com/bookstand

Pour plus de flexibilité dans l’acheminement du trafic vers vos API, vous pouvez créer une règle de routage. Pour plus d’informations, consultez Envoi du trafic à vos API via votre nom de domaine personnalisé dans API Gateway.

API Gateway prend en charge les noms de domaine personnalisés pour une API à l’aide de Server Name Indication (SNI). Vous pouvez appeler l’API avec un nom de domaine personnalisé en utilisant un navigateur ou une bibliothèque client prenant en charge SNI.

API Gateway applique SNI sur la distribution CloudFront. Pour plus d’informations sur la manière dont CloudFront utilise les noms de domaine personnalisés, consultez Certificats SSL personnalisés Amazon CloudFront.