Richten Sie einen Edge-optimierten benutzerdefinierten Domainnamen in API Gateway ein - Amazon API Gateway

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Richten Sie einen Edge-optimierten benutzerdefinierten Domainnamen in API Gateway ein

Wenn Sie einen benutzerdefinierten Domainnamen für eine Edge-optimierte API erstellen, richtet API Gateway eine CloudFront Verteilung und einen DNS-Eintrag ein, um den API-Domainnamen dem CloudFront Distributionsdomänennamen zuzuordnen. Anfragen für die API werden dann über die zugeordnete CloudFront Verteilung an API Gateway weitergeleitet. Diese Zuordnung ist für API-Anfragen vorgesehen, die daran gebunden sind, dass der benutzerdefinierte Domainname über die zugeordnete CloudFront Verteilung an API Gateway weitergeleitet wird.

Überlegungen

Im Folgenden finden Sie Überlegungen zu Ihrem Edge-optimierten benutzerdefinierten Domainnamen.

  • Um einen Edge-optimierten benutzerdefinierten Domainnamen einzurichten oder das zugehörige Zertifikat zu aktualisieren, benötigen Sie die Berechtigung, Distributionen zu aktualisieren. CloudFront

    Die folgenden Berechtigungen sind erforderlich, um Distributionen zu aktualisieren: CloudFront

    { "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 Region USA Ost (Nord-Virginia) — Region anfordern oder importieren. us-east-1

  • Die von API Gateway erstellte CloudFront Distribution gehört einem regionsspezifischen Konto, das mit API Gateway verbunden ist. Bei der Ablaufverfolgung von Vorgängen zur Erstellung und Aktualisierung einer solchen CloudFront Verteilung müssen Sie diese API Gateway Gateway-Konto-ID verwenden. CloudTrail Weitere Informationen finden Sie unter Protokollieren Sie die Erstellung eines benutzerdefinierten Domainnamens CloudTrail.

  • API Gateway unterstützt Edge-optimierte benutzerdefinierte Domainnamen, indem es Server Name Indication (SNI) für die Verteilung nutzt. CloudFront Weitere Informationen zur Verwendung benutzerdefinierter Domainnamen in einer CloudFront Distribution, einschließlich des erforderlichen Zertifikatsformats und der maximalen Länge eines Zertifikatsschlüssels, finden Sie unter Verwenden alternativer Domainnamen und HTTPS im Amazon CloudFront Developer Guide

  • Es dauert etwa 40 Minuten, bis ein Edge-optimierter benutzerdefinierter Domainname fertig ist.

  • Nachdem Sie Ihren Edge-optimierten benutzerdefinierten Domainnamen erstellt haben, müssen Sie einen DNS-Eintrag erstellen, um den benutzerdefinierten Domainnamen dem Distributionsnamen zuzuordnen. CloudFront

Erstellen Sie einen benutzerdefinierten Domainnamen für Edge-Optimize

Das folgende Verfahren beschreibt, wie Sie einen Edge-optimierten 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 Benutzerdefinierten Domänennamen im Hauptnavigationsbereich aus.

  3. Wählen Sie Create aus.

  4. Geben Sie für Domänenname einen Domänennamen ein.

  5. Wählen Sie für TLS-Mindestversion eine Version aus.

  6. Wählen Sie unter Endpunktkonfiguration für API-Endpunkttyp die Option Edge-optimized aus.

  7. Wählen Sie für ein ACM-Zertifikat ein ACM-Zertifikat aus.

  8. Wählen Sie Domain-Namen erstellen aus.

REST API
  1. Rufen Sie die Methode domainname:create auf und geben Sie den benutzerdefinierten Domänennamen und den ARN eines in AWS Certificate Manager gespeicherten Zertifikats an.

    Der erfolgreiche API-Aufruf gibt eine 201 Created Antwort zurück, die den Zertifikat-ARN sowie den zugehörigen CloudFront Distributionsnamen in der Nutzlast enthält.

  2. Notieren Sie sich den Namen der CloudFront Distributionsdomäne, der in der Ausgabe angezeigt wird. Sie benötigen ihn im nächsten Schritt zur Festlegung des CNAME-Werts oder des Aliasziels für den A-Datensatz des benutzerdefinierten Domänennamens im DNS.

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

Es dauert etwa 40 Minuten, bis ein Edge-optimierter benutzerdefinierter Domainname fertig ist. In der Konsole wird jedoch sofort der zugehörige CloudFront Distributionsdomänenname in der Form von distribution-id.cloudfront.net zusammen mit dem Zertifikat-ARN angezeigt. In der Zwischenzeit können Sie mit dem nächsten Schritt fortfahren und den Alias für den DNS-Datensatz so konfigurieren, dass der benutzerdefinierte Domainname dem zugehörigen CloudFront Distributionsdomänennamen zugeordnet wird.

Erstellen Sie einen DNS-Eintrag für Ihren Edge-optimierten benutzerdefinierten Domainnamen

Nachdem Sie mit der Erstellung Ihres Edge-optimierten benutzerdefinierten Domainnamens begonnen haben, richten Sie den Alias für den DNS-Datensatz ein.

Wir empfehlen, dass Sie Route 53 verwenden, um einen A-Record-Alias für Ihren benutzerdefinierten Domainnamen zu erstellen und den CloudFront Distributionsdomänennamen als Alias-Ziel 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.

Stattdessen können Sie Ihre benutzerdefinierte Domain als CNAME-Ressourcendatensatz zur Hosting-Zone hinzufügen. Der Name des CNAME-Datensatzes entspricht dem von Ihnen zuvor unter Domänenname eingegebenen benutzerdefinierten Domänennamen (z. B. api.example.com). Der CNAME-Eintragswert gibt den Domainnamen für die CloudFront Verteilung an.

Mit einem CNAME-Datensatz funktioniert dies allerdings nicht, wenn es sich bei Ihrer benutzerdefinierten Domäne um einen Zone Apex handelt (d. h. example.com und nicht api.example.com). Ein Zone Apex wird auch als Stammdomäne Ihrer Organisation bezeichnet. Für einen Zone Apex müssen Sie einen A-Datensatzalias verwenden, vorausgesetzt, dieser wird von Ihrem DNS-Anbieter unterstützt.

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 Sie die Erstellung eines benutzerdefinierten Domainnamens CloudTrail

Wenn für die Protokollierung von API-Gateway-Aufrufen, die von Ihrem Konto getätigt wurden, aktiviert CloudTrail ist, protokolliert API Gateway die zugehörigen CloudFront Distributionsupdates, wenn ein benutzerdefinierter Domainname für eine API erstellt oder aktualisiert wird. Diese Protokolle sind verfügbar inus-east-1. Da diese CloudFront Distributionen Eigentum von API Gateway sind, wird jede dieser gemeldeten CloudFront Distributionen durch eine der folgenden regionsspezifischen API Gateway Gateway-Konto-IDs und nicht durch die Konto-ID des API-Besitzers identifiziert.

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

Konfigurieren eines Basispfad-Mappings einer API mit einem benutzerdefinierten Domänennamen als Hostname

Sie können die Basispfadzuordnung verwenden, um einen einzelnen benutzerdefinierten Domainnamen als Hostnamen für mehrere APIs zu verwenden. Dadurch wird über die Kombination aus dem benutzerdefinierten Domainnamen und dem zugehörigen Basispfad auf eine API zugegriffen.

Wenn Sie beispielsweise in API Gateway eine API mit dem Namen PetStore und eine weitere API mit dem Namen erstellt Dogs und dann einen benutzerdefinierten Domainnamen von eingerichtet habenapi.example.com, können Sie die URL der PetStore API als festlegenhttps://api.example.com.

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

Um API-Zuordnungen auf mehreren Ebenen zu konfigurieren, können Sie nur einen regionalen benutzerdefinierten Domainnamen verwenden. Edge-optimierte benutzerdefinierte Domainnamen werden nicht unterstützt. Weitere Informationen finden Sie unter Ordnen Sie API-Stufen einem benutzerdefinierten Domainnamen zu.

Das folgende Verfahren richtet API-Mappings ein, um Pfade aus Ihrem benutzerdefinierten Domänennamen 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 Custom domain names (Benutzerdefinierte Domänennamen) im Hauptnavigationsbereich der API Gateway-Konsole aus.

  3. Wählen Sie einen benutzerdefinierten Domänennamen aus.

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

  5. Wählen Sie Neues Mapping hinzufügen aus.

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

  7. Wählen Sie Save (Speichern) aus.

REST API

Rufen Sie die Methode basepathmapping:create für einen bestimmten benutzerdefinierten Domänennamen auf und geben Sie in der Nutzlast der Anforderung die basePath- und restApiId-Eigenschaft sowie eine stage-Eigenschaft für die Bereitstellung an.

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

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

Wechseln eines in ACM importierten Zertifikats

ACM übernimmt automatisch die Verlängerung eigener ausgestellter Zertifikate. Sie müssen keine von ACM ausgestellten Zertifikate für Ihre benutzerdefinierten Domainnamen rotieren. CloudFront kümmert sich in Ihrem Namen darum.

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 können Sie ACM verlassen und CloudFront die Zertifikatsrotation automatisch für Sie übernehmen. Um ein neues ACM-Zertifikat zu erstellen oder zu importieren, folgen Sie den Schritten unter. Um ein SSL/TLS-Zertifikat zu erstellen oder in ACM zu importieren

Das folgende Verfahren beschreibt, wie Sie ein Zertifikat für einen Domainnamen rotieren.

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 Custom domain names (Benutzerdefinierte Domänennamen) im Hauptnavigationsbereich der API Gateway-Konsole aus.

  4. Wählen Sie einen benutzerdefinierten Domänennamen aus.

  5. Wählen Sie Edit aus.

  6. Wählen Sie das gewünschte Zertifikat aus der Dropdown-Liste ACM-Zertifikat aus.

  7. Klicken Sie auf Speichern, um mit dem Austausch des Zertifikats für den benutzerdefinierten Domänennamen zu beginnen.

  8. Nach Abschluss des Austauschvorgangs können Sie durch Klicken auf den Doppelpfeil neben dem ACM Certificate das ursprüngliche Zertifikat wiederherstellen.

REST API

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

Aufrufen Ihrer API mit benutzerdefinierten Domänennamen

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.

Stamm-URLs von APIs mit standardmäßigen und benutzerdefinierten Domänennamen
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

API Gateway unterstützt benutzerdefinierte Domänennamen 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 erzwingt SNI bei der CloudFront Distribution. Informationen zur CloudFront Verwendung benutzerdefinierter Domainnamen finden Sie unter Amazon CloudFront Custom SSL.