Benutzerdefinierte Domainnamen für WebSocket-APIs in API Gateway

Benutzerdefinierte Domainnamen sind einfachere und intuitivere URLs, die Sie Ihren API-Benutzern zur Verfügung stellen können.

Nach der Bereitstellung der API können Sie (und Ihre Kunden) die API mit der Standardstamm-URL im folgenden Format aufrufen:

https://api-id.execute-api.region.amazonaws.com/stage

hierzu wird api-id in API Gateway generiert, region ist die AWS-Region und stage wird als Stufe angegeben wenn Sie die API bereitstellen.

Der Hostname-Teil der URL (also api-id.execute-api.region.amazonaws.com) verweist auf einen API-Endpunkt. Der Standard-API-Endpunkt hat möglicherweise einen schwer zu merkenden, zufallsgenerierten Namen, der nicht besonders benutzerfreundlich ist.

Mit benutzerdefinierten Domainnamen können Sie den Hostnamen Ihrer API einrichten und einen Basispfad (z. B. myservice) auswählen, um die alternative URL Ihrer API zuzuordnen. Eine benutzerfreundlichere API-Basis-URL kann dann folgendermaßen aussehen:

https://api.example.com/myservice

Überlegungen

Die folgenden Überlegungen können sich auf Ihre Verwendung eines benutzerdefinierten Domainnamens auswirken.

• Wenn Sie einen benutzerdefinierten Domainnamen einer WebSocket-API zuweisen, können Sie ihn keiner REST-API oder HTTP-API zuweisen.

• Es werden ausschließlich regionale benutzerdefinierte Domainnamen unterstützt.

• Als Mindest-TLS-Version wird ausschließlich TLS 1.2 unterstützt.

• Sie müssen den Ressourceneintrag Ihres DNS-Anbieters erstellen oder aktualisieren, bevor Sie ihn dem API-Endpunkt zuordnen können. Ohne ein solches Mapping können API-Anfragen für den benutzerdefinierten Domainnnamen API Gateway nicht erreichen.

• Mit einem Wildcard-Zertifikat können Sie eine nahezu unendliche Anzahl von Domainnamen unterstützen, ohne das Standardkontingent zu überschreiten. Weitere Informationen finden Sie unter Benutzerdefinierte Domänennamen mit Platzhalter.

Voraussetzungen

Im Folgenden sind die Voraussetzungen für einen benutzerdefinierten Domainnamen aufgeführt.

Registrieren eines Domainnamens

Wenn Sie benutzerdefinierte Domainnamen für Ihre APIs einrichten möchten, müssen Sie eine Internetdomäne registrieren. Sie können Ihre Internetdomain mithilfe von Amazon Route 53 oder mit einem Domain-Registrar Ihrer Wahl registrieren. Ihr benutzerdefinierter Domainname kann der Name einer Unter- oder Root-Domain (Zone Apex) einer registrierten Internetdomain sein.

Ihr Domainname muss der RFC 1035-Spezifikation entsprechen und darf ein Maximum von 63 Oktetten pro Label und insgesamt 255 Oktetten nicht überschreiten.

Zertifikate für benutzerdefinierte Domainnamen

Vor der Einrichtung eines benutzerdefinierten Domainnamens für eine API müssen Sie ein SSL-/TLS-Zertifikat in ACM vorbereiten. Wenn ACM in der AWS-Region nicht verfügbar ist, in der Sie Ihren benutzerdefinierten Domainnamen erstellen, müssen Sie ein Zertifikat für API Gateway in dieser Region importieren.

Wenn Sie ein SSL-/TLS-Zertifikat importieren möchten, müssen Sie den PEM-formatierten Hauptteil des SSL-/TLS-Zertifikats, den persönlichen Schlüssel und die Zertifikatkette für den benutzerdefinierten Domainnamen bereitstellen.

Ein in ACM gespeichertes Zertifikat wird durch seinen ARN angegeben. Wenn Sie Zertifikate verwenden, die von ACM ausgestellt werden, brauchen sich keine Gedanken über vertrauliche Zertifikatdetails wie private Schlüssel zu machen. Wenn Sie also ein von AWS verwaltetes Zertifikat für einen Domainnamen verwenden möchten, müssen Sie lediglich auf dessen ARN verweisen.

Wenn Ihre Anwendung, manchmal auch als Zertifikats-Pinning bekannt, verwendet, um ein ACM-Zertifikat zu pinnen, kann die Anwendung möglicherweise keine Verbindung zu Ihrer Domain herstellen, nachdem AWS das Zertifikat erneuert hat. Weitere Informationen finden Sie unter Probleme beim Zertifikats-Pinning im AWS Certificate Manager-Benutzerhandbuch.

Benutzerdefinierte Domainnamen mit Platzhalter

Mit benutzerdefinierten Platzhalter-Domainnamen können Sie eine nahezu unendliche Anzahl von Domainnamen unterstützen, ohne das Standardkontingentzu überschreiten. Zum Beispiel könnten Sie jedem Ihrer Kunden einen eigenen Domainnamen geben, customername.api.example.com.

Um einen benutzerdefinierten Platzhalterdomainnamen zu erstellen, geben Sie einen Platzhalter (*) als erste Subdomain einer benutzerdefinierten Domain an, die alle möglichen Subdomains einer Root-Domain darstellt.

Der benutzerdefinierte Domainnamen mit Platzhalter *.example.com führt beispielsweise zu Unterdomains wie a.example.com, b.example.com und c.example.com, die alle zur gleichen Domain weiterleiten.

Benutzerdefinierte Domainnamen mit Platzhaltern unterstützen andere Konfigurationen als die benutzerdefinierten Standarddomainnamen von API Gateway. Beispielsweise können Sie in einem einzelnen AWS-Konto *.example.com und a.example.com so konfigurieren, dass sie sich anders verhalten.

Sie können die Kontextvariablen $context.domainName und $context.domainPrefix verwenden, um den Domainnamen zu bestimmen, mit dem ein Client Ihre API aufruft. Weitere Informationen zu Kontextvariablen finden Sie unter Referenz zu API Gateway-Mapping-Vorlage und -Zugriffsprotokollierungsvariablen.

Um einen benutzerdefinierten Domainnamen mit Platzhalter zu erstellen, müssen Sie ein von ACM ausgestelltes Zertifikat angeben, das mithilfe der DNS- oder der E-Mail-Validierungsmethode validiert wurde.

Anmerkung

Sie können keinen benutzerdefinierten Domainnamen mit Platzhalter erstellen, wenn ein anderes AWS-Konto einen benutzerdefinierten Domainnamen erstellt hat, der mit dem benutzerdefinierten Domainnamen mit Platzhalter in Konflikt steht. Wurde a.example.com beispielsweise von Konto A erstellt, dann kann Konto B als benutzerdefinierten Domainnamen mit Platzhalter nicht *.example.com erstellen.

Wenn Konto A und Konto B den gleichen Besitzer haben, können Sie sich an das AWS Supportcenter wenden, um eine Ausnahme anzufordern.

Die nächsten Schritte für benutzerdefinierte Domainnamen

Verwenden Sie die Dokumentation aus dem REST-API-Abschnitt des API-Gateway-Entwicklerhandbuchs für die Einrichtung eines benutzerdefinierten Domainnamens für eine HTTP-API.

Geben Sie zunächst ein Zertifikat für Ihren benutzerdefinierten Domainnamen an. Weitere Informationen finden Sie unter Vorbereiten von Zertifikaten in AWS Certificate Manager. Dann erstellen Sie einen regionalen benutzerdefinierten Domainnamen. Weitere Informationen finden Sie unter Einrichten eines regionalen benutzerdefinierten Domainnamens in API Gateway.