Einrichten von benutzerdefinierten Domänennamen für REST-APIs - Amazon API Gateway
Registrieren eines DomänennamensEdge-optimierte benutzerdefinierte DomänennamenRegionale benutzerdefinierte DomänennamenBenutzerdefinierte Domänennamen mit PlatzhalterZertifikate für benutzerdefinierte Domänennamen

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.

Einrichten von benutzerdefinierten Domänennamen für REST-APIs

Benutzerdefinierte Domänennamen 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

api-id wird von API Gateway generiert, region (AWS-Region) wird von Ihnen bei der Erstellung der API angegeben, und stage wird von Ihnen bei der Bereitstellung der API angegeben.

Der Hostname-Teil der URL (d. h. api-id.execute-api.region.amazonaws.com) verweist auf einen API-Endpunkt. Der Standard-API-Endpunkt hat möglicherweise einen schwer zu merkenden, wenig benutzerfreundlichen Namen.

Mit benutzerdefinierten Domänennamen 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
Anmerkung

Eine regionale benutzerdefinierte Domäne kann REST-APIs and HTTP-APIs zugeordnet werden. Sie können API Gateway Version 2-APIs verwenden, um regionale benutzerdefinierte Domänennamen für REST-APIs zu erstellen und zu verwalten.

Benutzerdefinierte Domänennamen werden für private APIs nicht unterstützt.

Sie können eine von Ihrer REST-API unterstützte minimale TLS-Version auswählen. Für REST-APIs können Sie TLS 1.2 oder TLS 1.0 auswählen.

Registrieren eines Domänennamens

Wenn Sie benutzerdefinierte Domänennamen für Ihre APIs einrichten möchten, müssen Sie eine Internetdomäne registrieren. Falls erforderlich, können Sie eine Internetdomäne mit Amazon Route 53 oder mit einem Domain-Registrar Ihrer Wahl registrieren. Der benutzerdefinierte Domänenname einer API kann dem Namen einer Unter- oder Stammdomäne (auch als „Zone Apex“ bezeichnet) einer registrierten Internetdomäne entsprechen.

Nachdem ein benutzerdefinierter Domänenname in API Gateway erstellt wurde, müssen Sie den Ressourceneintrag Ihres DNS-Providers erstellen oder aktualisieren, um ihn Ihrem API-Endpunkt zuzuordnen. Ohne ein solches Mapping können API-Anfragen für den benutzerdefinierten Domänennamen API Gateway nicht erreichen.

Anmerkung

Ein Edge-optimierter benutzerdefinierter Domänenname wird in einer bestimmten Region erstellt und ist einem bestimmten AWS-Konto zugeordnet. Wenn Sie einen solchen benutzerdefinierten Domänennamen zwischen Regionen oder AWS-Konten verschieben möchten, müssen Sie die vorhandene CloudFront-Verteilung löschen und eine neue erstellen. Der Prozess kann ca. 30 Minuten in Anspruch nehmen; erst dann ist der neue benutzerdefinierte Domänenname verfügbar. Weitere Informationen finden Sie unter Aktualisieren von CloudFront-Verteilungen.

Edge-optimierte benutzerdefinierte Domänennamen

Wenn Sie eine Edge-optimierte API bereitstellen, richtet API Gateway eine Amazon CloudFront-Verteilung und einen DNS-Datensatz ein, um den API-Domänennamen dem Domänennamen der CloudFront-Verteilung zuzuordnen. Anforderungen an die API werden daraufhin über die zugeordnete CloudFront-Verteilung an API Gateway geleitet.

Wenn Sie einen benutzerdefinierten Domänennamen für eine Edge-optimierte API erstellen, richtet API Gateway eine CloudFront-Verteilung ein. Sie müssen jedoch einen DNS-Eintrag einrichten, um den benutzerdefinierten Domänennamen dem Namen der CloudFront-Verteilungsdomäne zuzuordnen. Das Mapping ist notwendig, damit API-Anforderungen, die an den benutzerdefinierten Domänennamen gebunden sind, über die zugeordnete CloudFront-Verteilung an API Gateway weitergeleitet werden. Außerdem müssen Sie ein Zertifikat für den benutzerdefinierten Domänennamen bereitstellen.

Anmerkung

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 mithilfe von CloudWatch Logs nachverfolgen, müssen Sie die ID Ihres API Gateway-Kontos verwenden. Weitere Informationen finden Sie unter Protokollieren der Erstellung eines benutzerdefinierten Domänennamens in CloudTrail.

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

Um Zugriff zu gewähren, fügen Sie Ihren Benutzern, Gruppen oder Rollen Berechtigungen hinzu:

Die folgenden Berechtigungen sind erforderlich, um CloudFront-Verteilungen zu aktualisieren. 

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

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

Wenn Sie einen benutzerdefinierten Domänennamen als API-Host-Namen einrichten möchten, müssen Sie als Eigentümer der API ein SSL-/TLS-Zertifikat für den benutzerdefinierten Domänennamen bereitstellen.

Um ein Zertifikat für einen Edge-optimierten benutzerdefinierten Domänennamen bereitzustellen, können Sie AWS Certificate Manager (ACM) anweisen, ein neues Zertifikat in ACM zu generieren oder ein von der Zertifizierungsstelle eines Drittanbieters in der us-east-1-Region (USA Ost (Nord-Virginia)) ausgestelltes Zertifikat in ACM zu importieren.

Regionale benutzerdefinierte Domänennamen

Wenn Sie einen benutzerdefinierten Domänennamen für eine regionale API erstellen, erstellt API Gateway einen regionalen Domänennamen für die API. Sie müssen einen DNS-Datensatz so einrichten, dass der benutzerdefinierte Domänenname dem regionalen Domänennamen zugeordnet wird. Außerdem müssen Sie ein Zertifikat für den benutzerdefinierten Domänennamen bereitstellen.

Benutzerdefinierte Domänennamen mit Platzhalter

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

Um einen benutzerdefinierten Platzhalterdomänennamen zu erstellen, geben Sie einen Platzhalter (*) als erste Subdomäne einer benutzerdefinierten Domäne an, die alle möglichen Subdomänen einer Root-Domäne darstellt.

Der benutzerdefinierte Domänenname mit Platzhalter *.example.com führt beispielsweise zu Unterdomänen wie a.example.com, b.example.com und c.example.com, die alle zur gleichen Domäne weiterleiten.

Benutzerdefinierte Domänennamen mit Platzhaltern unterstützen andere Konfigurationen als die benutzerdefinierten Standarddomänennamen 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 Domänennamen 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 Domänennamen 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 Domänennamen mit Platzhalter erstellen, wenn ein anderes AWS-Konto einen benutzerdefinierten Domänennamen erstellt hat, der mit dem benutzerdefinierten Domänennamen mit Platzhalter in Konflikt steht. Wurde a.example.com beispielsweise von Konto A erstellt, dann kann Konto B als benutzerdefinierten Domänennamen 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.

Zertifikate für benutzerdefinierte Domänennamen

Wichtig

Sie geben das Zertifikat für Ihren benutzerdefinierten Domänennamen an. 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.

Um ein Zertifikat für einen benutzerdefinierten Domänennamen in einer Region bereitzustellen, in der ACM unterstützt wird, müssen Sie ein Zertifikat von ACM anfordern. Um ein Zertifikat für einen regionalen benutzerdefinierten Domänennamen in einer von ACM nicht unterstützten Region bereitzustellen, 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 Domänennamen bereitstellen. Ein in ACM gespeichertes Zertifikat wird durch seinen ARN angegeben. Wenn Sie also ein von AWS verwaltetes Zertifikat für einen Domänenamen verwenden möchten, müssen Sie lediglich auf dessen ARN verweisen.

Die Einrichtung und Verwendung eines benutzerdefinierten Domänennamens für eine API in ACM ist ganz einfach. Sie erstellen ein Zertifikat für den angegebenen Domänennamen (oder importieren ein Zertifikat), richten den Domänennamen in API Gateway mit dem ARN des von ACM bereitgestellten Zertifikats ein und ordnen einen Basispfad unter dem benutzerdefinierten Domänennamen einer Bereitstellungsphase der API zu. Wenn Sie Zertifikate verwenden, die von ACM ausgestellt werden, brauchen sich keine Gedanken über vertrauliche Zertifikatdetails wie private Schlüssel zu machen.

Themen