Einrichten eines Edge-optimierten benutzerdefinierten Domainnamens in API Gateway - Amazon API Gateway
ÜberlegungenErstellen eines Edge-optimierten benutzerdefinierten DomainnamensKonfigurieren einer Basispfadzuweisung einer API mit einem benutzerdefinierten Domainnamen als HostnameErstellen eines DNS-Eintrags für Ihren Edge-optimierten benutzerdefinierten DomainnamenProtokollieren der Erstellung eines benutzerdefinierten Domänennamens in CloudTrailWechseln eines in ACM importierten ZertifikatsAufrufen einer API mit benutzerdefinierten Domainnamen bei Verwendung einer Basispfadzuweisung

Einrichten eines Edge-optimierten benutzerdefinierten Domainnamens in API Gateway

Wenn Sie einen benutzerdefinierten Domainnamen für eine Edge-optimierte API erstellen, richtet API Gateway eine CloudFront-Verteilung und einen DNS-Datensatz ein, um den API-Domainnamen dem Domainnamen zur CloudFront-Verteilung zuzuweisen. Anfragen an die API werden daraufhin über die zugeordnete CloudFront-Verteilung an API Gateway weitergeleitet. Diese Zuweisung gilt für API-Anfragen, die an den benutzerdefinierten Domainnamen gebunden sind und über die zugewiesene CloudFront-Verteilung an API Gateway weitergeleitet werden.

Überlegungen

Die folgenden Punkte sind für Ihren Edge-optimierten benutzerdefinierten Domainnamen zu beachten:

  • Für die Einrichtung eines Edge-optimierten benutzerdefinierten Domainnamens oder die Aktualisierung des entsprechenden Zertifikats benötigen Sie die Berechtigung zum Aktualisieren von CloudFront-Verteilungen.

    Die folgenden Berechtigungen sind für die Aktualisierung von CloudFront-Verteilungen erforderlich:

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

  • Sie müssen ein Zertifikat für Ihren Edge-optimierten benutzerdefinierten Domainnamen in der us-east-1-Region (USA Ost (Nord-Virginia)) anfordern oder importieren.

  • Die von API Gateway erstellte CloudFront-Verteilung gehört zu einem regionsspezifischen Konto, das mit API Gateway verbunden ist. Wenn Sie Erstellungs- und Aktualisierungsvorgänge einer solchen CloudFront-Verteilung in CloudTrail nachverfolgen möchten, müssen Sie hierzu die ID Ihres API-Gateway-Kontos verwenden. Weitere Informationen finden Sie unter Protokollieren der Erstellung eines benutzerdefinierten Domänennamens in CloudTrail.

  • API Gateway unterstützt Edge-optimierte benutzerdefinierte Domainnamen durch Nutzung der Servernamensanzeige (Server Name Indication, SNI) in der CloudFront-Verteilung. Weitere Informationen zur Verwendung von benutzerdefinierten Domainnamen in einer CloudFront-Verteilung, einschließlich des erforderlichen Zertifikatformats und der maximalen Schlüssellänge eines Zertifikats finden Sie unter Verwenden alternativer Domainnamen in Verbindung mit HTTPS im Amazon CloudFront-Entwicklerhandbuch.

  • Die Fertigstellung eines Edge-optimierten benutzerdefinierte Domainnamens dauert etwa 40 Minuten.

  • Nach der Erstellung Ihres Edge-optimierten benutzerdefinierten Domainnamens müssen Sie noch einen DNS-Datensatz erstellen, um den benutzerdefinierten Domainnamen dem Namen der CloudFront-Verteilung zuzuweisen.

Erstellen eines Edge-optimierten benutzerdefinierten Domainnamens

Im folgenden Verfahren wird beschrieben, wie Sie einen benutzerdefinierten Domainnamen für eine API erstellen.

AWS Management Console

  1. Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

  2. Wählen Sie Benutzerdefinierte Domainnamen im Hauptnavigationsbereich aus.

  3. Wählen Sie Domainnamen hinzufügen aus.

  4. Geben Sie unter Domänenname einen Domainnamen ein.

  5. Wählen Sie unter Routing-Modus die Option API_MAPPING_ONLY aus.

  6. Wählen Sie unter API-Endpunkttyp die Option Edge-optimiert aus.

  7. Wählen Sie eine minimale TLS-Version aus.

  8. Wählen Sie ein ACM-Zertifikat aus.

  9. Klicken Sie auf Domainnamen hinzufügen.

REST API

  1. Rufen Sie domainname:create auf und geben Sie den benutzerdefinierten Domainnamen und den ARN eines in AWS Certificate Manager gespeicherten Zertifikats an.

    Wenn der API-Aufruf erfolgreich war, gibt er die Antwort 201 Created mit dem ARN des Zertifikats sowie dem verknüpften CloudFront-Verteilungsnamen in den Nutzdaten zurück.

  2. Notieren Sie sich den in der Ausgabe angezeigten Domainnamen der CloudFront-Verteilung. Diesen benötigen Sie im nächsten Schritt, um das A-Datensatz-Aliasziel der benutzerdefinierten Domain in Ihrem DNS festzulegen.

Code-Beispiele für diesen REST-API-Aufruf finden Sie unter domainname:create.

Die Fertigstellung eines Edge-optimierten benutzerdefinierten Domainnamens dauert etwa 40 Minuten. In der Konsole wird jedoch sofort der verknüpfte CloudFront-Verteilungsdomainname als distribution-id.cloudfront.net mit dem Zertifikat-ARN angezeigt. In der Zwischenzeit können Sie eine Basispfadzuweisung oder eine Routing-Regel erstellen und anschließend den DNS-Datensatzalias konfigurieren, um den benutzerdefinierten Domainnamen der entsprechenden CloudFront-Verteilungsdomain zuzuweisen.

Konfigurieren einer Basispfadzuweisung einer API mit einem benutzerdefinierten Domainnamen als Hostname

Da Sie den Routing-Modus auf API_MAPPING_ONLY gesetzt haben, können Sie die Basispfadzuweisung verwenden, um einen einzelnen benutzerdefinierten Domainnamen als Hostnamen für mehrere APIs zu nutzen. So wird eine API mithilfe der Kombination aus benutzerdefiniertem Domainnamen und dem zugehörigen Basispfad zugänglich gemacht.

Wenn Sie beispielsweise eine API mit dem Namen PetStore und eine weitere mit dem Namen Dogs in API Gateway erstellt haben und dann einen benutzerdefinierten Domainnamen api.example.com einrichten, können Sie die URL der PetStore-API als https://api.example.com festlegen.

Dadurch wird die PetStore-API mit dem Basispfad einer leeren Zeichenfolge verknüpft. Wenn Sie die URL der PetStore-API auf https://api.example.com/PetStore festlegen, verknüpft dies die PetStore-API mit dem Basispfad von PetStore. Sie können einen Basispfad MyDogList für die Dogs-API zuweisen. Die URL https://api.example.com/MyDogList ist dann die Stamm-URL der Dogs-API.

Es kann nur ein regionaler benutzerdefinierter Domainname für das Konfigurieren von API-Zuweisungen auf mehreren Ebenen verwendet werden. Edge-optimierte benutzerdefinierte Domainnamen werden nicht unterstützt. Weitere Informationen finden Sie unter Verwenden von API-Zuweisungen zum Verbinden von API-Stufen mit einem benutzerdefinierten Domainnamen für REST-APIs.

Das folgende Verfahren richtet API-Zuweisungen ein, um Pfade von Ihrem benutzerdefinierten Domainnamen zu Ihren API-Stufen zuzuordnen.

AWS Management Console

  1. Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

  2. Wählen Sie Benutzerdefinierte Domainnamen im Hauptnavigationsbereich der API Gateway-Konsole aus.

  3. Wählen Sie einen benutzerdefinierten Domainnamen aus.

  4. Wählen Sie API-Zuweisungen konfigurieren aus.

  5. Wählen Sie Neue Zuweisung hinzufügen aus.

  6. Geben Sie die API, die Stufe und den Pfad (optional) für die Zuweisung an.

  7. Wählen Sie Speichern aus.

REST API

Rufen Sie basepathmapping:create für einen bestimmten benutzerdefinierten Domainnamen auf und geben Sie in den Nutzdaten der Anfrage die Eigenschaften basePath und restApiId sowie eine Bereitstellungs-stage an.

Ein erfolgreicher API-Aufruf gibt die Antwort 201 Created zurück.

Codebeispiele des REST-API-Aufrufs finden Sie unter basepathmapping:create.

Für mehr Flexibilität beim Weiterleiten des Datenverkehrs an Ihre APIs können Sie den Routing-Modus in ROUTING_RULE_ONLY oder ROUTING_RULE_THEN_API_MAPPING ändern und eine Routing-Regel erstellen. Weitere Informationen finden Sie unter Senden von Datenverkehr an Ihre APIs über Ihren benutzerdefinierten Domainnamen in API Gateway.

Erstellen eines DNS-Eintrags für Ihren Edge-optimierten benutzerdefinierten Domainnamen

Richten Sie den Alias für den DNS-Datensatz ein, nachdem Sie mit die Erstellung Ihres Edge-optimierten benutzerdefinierten Domainnamens angestoßen haben.

Wir empfehlen, Route 53 zur Erstellung eines A-Datensatzalias für Ihren benutzerdefinierten Domainnamen zu verwenden und den Domainnamen der CloudFront-Verteilung als Aliasziel anzugeben. Das bedeutet, dass Route 53 den benutzerdefinierten Domänennamen auch dann weiterleiten kann, wenn es sich um einen Zone Apex handelt. Weitere Informationen finden Sie im Amazon Route 53-Entwicklerhandbuch unter Wählen zwischen Alias- und Nicht-Alias-Ressourcendatensätzen.

Anweisungen für Amazon Route 53 finden Sie unter Weiterleiten des Datenverkehrs an eine Amazon API Gateway API unter Verwendung Ihres Domain-Namens im Amazon Route 53-Entwicklerhandbuch.

Protokollieren der Erstellung eines benutzerdefinierten Domänennamens in CloudTrail

Wenn in CloudTrail die Protokollierung von API Gateway-Aufrufen aktiviert ist, die von Ihrem Konto ausgehen, protokolliert API Gateway die Aktualisierungen zugehöriger CloudFront -Verteilungen, wenn ein benutzerdefinierter Domänenname für eine API erstellt oder aktualisiert wird. Diese Protokolle sind in us-east-1 verfügbar. Da diese CloudFront-Verteilungen API Gateway gehören, werden alle gemeldeten CloudFront-Verteilungen durch eines der folgenden regionsspezifischen API Gateway-Konto-IDs bestimmt und nicht durch die Konto-ID des API-Besitzers.

Region

Konto-ID
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

Wechseln eines in ACM importierten Zertifikats

ACM übernimmt automatisch die Verlängerung eigener ausgestellter Zertifikate. Es ist nicht nötig, Zertifikate, die von ACM für Ihre benutzerdefinierten Domänennamen ausgestellt wurden, auszuwechseln. Dies übernimmt CloudFront in Ihrem Namen.

Wenn Sie jedoch ein Zertifikat in ACM importieren und für einen benutzerdefinierten Domänennamen verwenden, müssen Sie das Zertifikat vor seinem Ablauf auswechseln. Dies umfasst das Importieren eines neuen Drittanbieter-Zertifikats für den Domänennamen und das Auswechseln des vorhandenen durch ein neues Zertifikat. Diesen Vorgang müssen Sie wiederholen, wenn das neu importierten Zertifikat abläuft. Alternativ können Sie in ACM die Ausstellung eines neuen Zertifikats für den Domänennamen beauftragen und das vorhandene durch das neue auswechseln. Danach übernehmen automatisch ACM und CloudFront das Auswechseln von Zertifikaten. Führen Sie die Schritte unter Erstellen eines SSL/TLS-Zertifikats oder Importieren des Zertifikats in ACM aus, um ein neues ACM-Zertifikat zu erstellen oder zu importieren.

Im folgenden Verfahren wird beschrieben, wie ein Zertifikat für einen Domainnamen rotiert wird.

Anmerkung

Das Rotieren eines in ACM importierten Zertifikats dauert etwa 40 Minuten.

AWS Management Console

  1. Fordern Sie ein Zertifikat in ACM an oder importieren Sie es.

  2. Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

  3. Wählen Sie Benutzerdefinierte Domainnamen im Hauptnavigationsbereich der API Gateway-Konsole aus.

  4. Wählen Sie einen Edge-optimierten benutzerdefinierten Domainnamen aus.

  5. Klicken Sie unter Endpunktkonfiguration auf Bearbeiten.

  6. Wählen Sie unter ACM-Zertifikat ein Zertifikat aus der Dropdown-Liste aus.

  7. Klicken Sie auf Änderungen speichern, um mit dem Rotieren des Zertifikats für den benutzerdefinierten Domainnamen zu beginnen.

REST API

Rufen Sie die Aktion domainname:update unter Angabe des ARN des neuen ACM-Zertifikats für den jeweiligen Domänennamen auf.

AWS CLI

Die folgende Aktion update-domain-name aktualisiert das ACM-Zertifikat für einen Edge-optimierten Domainnamen.

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'"

Die folgende Aktion update-domain-name aktualisiert das ACM-Zertifikat für einen regionalen Domainnamen.

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'"

Aufrufen einer API mit benutzerdefinierten Domainnamen bei Verwendung einer Basispfadzuweisung

Sofern die korrekte URL verwendet wird, macht es keinen Unterschied, ob eine API mit einem benutzerdefinierten oder dem standardmäßigen Domänennamen aufgerufen wird.

In den folgenden Beispielen werden mehrere Standard-URLs mit den entsprechenden benutzerdefinierten URLs zweier APIs (udxjef und qf3duz) in einer bestimmten Region (us-east-1) mit einem bestimmten benutzerdefinierten Domänennamen (api.example.com) verglichen.

API-ID Stufe Standard-URL Basispfad Custom URL
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

Für mehr Flexibilität beim Weiterleiten des Datenverkehrs an Ihre APIs können Sie eine Routing-Regel erstellen. Weitere Informationen finden Sie unter Senden von Datenverkehr an Ihre APIs über Ihren benutzerdefinierten Domainnamen in API Gateway.

API Gateway unterstützt benutzerdefinierte Domainnamen für eine API über die Server Name Indication (SNI). Sie können die API mit einem benutzerdefinierten Domänennamen über einen Browser oder eine Client-Bibliothek aufrufen, die SNI unterstützt.

API Gateway setzt die SNI in der CloudFront-Verteilung durch. Weitere Informationen über die Verwendung von benutzerdefinierten Domänennamen in CloudFront finden Sie unter Benutzerdefiniertes SSL für Amazon CloudFront.