Erstellen eines Edge-optimierten benutzerdefinierten Domänennamens

Einrichten eines Edge-optimierten benutzerdefinierten Domänennamens für eine API Gateway-API

Im folgenden Verfahren wird beschrieben, wie Sie einen benutzerdefinierten Domain-Namen für eine API mit der API Gateway-Konsole erstellen.

So erstellen Sie einen benutzerdefinierten Domänennamen mit der API Gateway-Konsole

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 unter Konfiguration die Option Edge-optimiert aus.

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

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

   Anmerkung

   Um ein ACM-Zertifikat mit einem Edge-optimierten benutzerdefinierten API Gateway-Domänennamen zu verwenden, müssen Sie das Zertifikat in der Region us-east-1 (USA Ost (Nord-Virginia)) anfordern oder importieren.

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

9. Nach der Erstellung des benutzerdefinierten Domänennamens werden in der Konsole der verknüpfte CloudFront-Verteilungsdomänenname im Format distribution-id.cloudfront.net sowie der ARN des Zertifikats angezeigt. Notieren Sie sich den in der Ausgabe angezeigten CloudFront-Verteilungsdomänennamen. 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.

   Anmerkung

   Die Erstellung des neuen benutzerdefinierten Domänennamen dauert ca. 40 Minuten. In der Zwischenzeit können Sie den DNS-Datensatz folgendermaßen konfigurieren: Weisen Sie während der Initialisierung den benutzerdefinierten Domänennamen dem Namen der zugehörigen CloudFront-Verteilungsdomäne zu und richten Sie das Mapping des Basispfads für den benutzerdefinierten Domänennamen ein.

10. Als Nächstes konfigurieren Sie DNS-Einträge mit Ihrem DNS-Anbieter, um den benutzerdefinierten Domain-Namen der zugehörigen CloudFront-Distribution zuzuordnen. 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.

    Bei den meisten DNS-Anbietern wird der gehosteten Zone ein benutzerdefinierter Domänenname als CNAME-Ressourcendatensatz hinzugefügt. Der Name des CNAME-Datensatzes entspricht dem von Ihnen zuvor unter Domänenname eingegebenen benutzerdefinierten Domänennamen (z. B. api.example.com). Der Wert des CNAME-Datensatzes gibt den CloudFront-Verteilungsdomänennamen 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.

    Sie können mit Route 53 einen A-Datensatzalias für den benutzerdefinierten Domain-Namen erstellen und den CloudFront-Verteilungsdomain-Namen als Aliasziel angeben. 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.

    Bei Verwendung von A-Datensatzaliasnamen entfällt zudem das Risiko für den Namen der zugrundeliegenden CloudFront-Verteilungsdomäne, da das Mapping des Namens ausschließlich in Route 53 erfolgt. Aus diesen Gründen empfehlen wir die Verwendung von Route 53-A-Datensatzaliasnamen.

Neben der API-Gateway-Konsole können Sie auch die API-Gateway-REST-API, die CLIAWS oder eines der AWS SDKs zum Einrichten eines benutzerdefinierten Domänennamens für Ihre APIs verwenden. Zur Veranschaulichung wird das Verfahren im Folgenden unter Verwendung der REST-API-Aufrufe beschrieben.

So richten Sie einen benutzerdefinierten Domänennamen mit der API Gateway-REST-API ein

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.

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

2. Notieren Sie sich den in der Ausgabe angezeigten CloudFront-Verteilungsdomänennamen. 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.

3. Befolgen Sie das vorherige Verfahren, um einen A-Datensatzalias einzurichten und den benutzerdefinierten Domänennamen dem CloudFront-Verteilungsnamen zuzuordnen.

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

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

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

Sie können einen einzelnen benutzerdefinierten Domänennamen als Hostnamen mehrerer APIs verwenden. Dies erreichen Sie durch Konfigurieren der Basispfad-Mappings im benutzerdefinierten Domänennamen. Mit den Basispfad-Mappings kann auf eine API, die sich unter der benutzerdefinierten Domäne befindet, über die Kombination aus benutzerdefiniertem Domänennamen und zugehörigem Basispfad zugegriffen werden.

Wenn Sie beispielsweise eine API mit dem Namen PetStore und eine weitere mit dem Namen PetShop erstellt haben und den benutzerdefinierten Domänennamen api.example.com in API Gateway einrichten, können Sie als URL der API PetStore wahlweise https://api.example.com oder https://api.example.com/myPetStore festlegen. Die API PetStore ist mit dem Basispfad einer leeren Zeichenfolge oder myPetStore unterhalb des benutzerdefinierten Domänennamens api.example.com verknüpft. Gleichermaßen können Sie einen Basispfad yourPetShop für die API PetShop zuweisen. Die URL https://api.example.com/yourPetShop ist dann die Stamm-URL der API PetShop.

Bevor Sie den Basispfad für eine API festlegen, führen Sie die Schritte unter au Einrichten eines Edge-optimierten benutzerdefinierten Domänennamens für eine API Gateway-API.

Das folgende Verfahren richtet API-Mappings ein, um Pfade aus Ihrem benutzerdefinierten Domänennamen Ihren API-Stufen zuzuordnen.

So erstellen Sie den Namen des API-Mappings mithilfe der API Gateway-Konsole

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

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

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

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

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

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

Außerdem können Sie die API-Gateway-REST-API, die AWS CLI oder eines der AWS SDKs zum Einrichten des Basispfad-Mappings einer API mit einem benutzerdefinierten Domänennamen als Hostnamen verwenden. Zur Veranschaulichung wird das Verfahren im Folgenden unter Verwendung der REST-API-Aufrufe beschrieben.

So richten Sie das Basispfad-Mapping einer API mit der API Gateway-REST-API ein

• 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. 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. Wenn Sie ein neues ACM-Zertifikat erstellen oder importieren möchten, führen Sie die Schritte zum Anfordern oder Importieren neuer ACM-Zertifikate für den jeweiligen Domänennamen aus.

Wenn Sie ein Zertifikat für einen Domänennamen austauschen möchten, können Sie dies mit der API-Gateway-Konsole, der API-Gateway-REST-API, der AWS CLI oder einem der AWS SDKs tun.

So tauschen Sie ein ablaufendes Zertifikat, das in ACM importiert wurde, mit der API Gateway-Konsole aus

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

2. Gehen Sie zurück zur API Gateway-Konsole.

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.

   Anmerkung

   Es dauert ca. 40 Minuten, bis der Prozess abgeschlossen ist. Nach Abschluss des Austauschvorgangs können Sie durch Klicken auf den Doppelpfeil neben dem ACM Certificate das ursprüngliche Zertifikat wiederherstellen.

Im Folgenden wird der programmgesteuerte Austausch eines importieren Zertifikats für einen benutzerdefinierten Domänennamen unter Verwendung der API Gateway-REST-API veranschaulicht.

Austauschen eines importierten Zertifikats mit der API Gateway-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	pro	https://udxjef.execute-api.us-east-1.amazonaws.com/pro	/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 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.