Ordnen Sie API-Stufen einem benutzerdefinierten Domainnamen für HTTP-APIs zu

Sie verwenden API-Mappings, um API-Stufen mit einem benutzerdefinierten Domain-Namen zu verbinden. Nachdem Sie einen Domain-Namen erstellt und DNS-Einträge konfiguriert haben, verwenden Sie API-Mappings, um Datenverkehr über Ihren benutzerdefinierten Domain-Namen an Ihre APIs zu senden.

Ein API-Mapping gibt eine API, eine Phase und optional einen Pfad an, die für das Mapping verwendet werden sollen. Sie können beispielsweise die production-Phase einer API in https://api.example.com/orders abbilden.

Sie können HTTP-API- und REST-API--Stufen demselben benutzerdefinierten Domain-Namen zuweisen.

Bevor Sie ein API-Mapping erstellen, benötigen Sie eine API, eine Phase und einen benutzerdefinierten Domain-Namen. Weitere Informationen zum Erstellen eines benutzerdefinierten Domain-Namens finden Sie unter Richten Sie einen regionalen benutzerdefinierten Domainnamen in API Gateway ein.

Weiterleiten von API-Anforderungen

Sie können API-Mappings mit mehreren Ebenen konfigurieren, z. B. orders/v1/items und orders/v2/items.

Bei API-Mappings mit mehreren Ebenen leitet API Gateway Anfragen an das API-Mapping weiter, die den längsten Übereinstimmungspfad hat. API Gateway berücksichtigt nur die für API-Mappings konfigurierten Pfade und keine API-Routen, um die aufzurufende API auszuwählen. Wenn kein Pfad mit der Anforderung übereinstimmt, sendet API Gateway die Anforderung an die API, die Sie dem leeren Pfad zugeordnet habe (none).

Bei benutzerdefinierten Domain-Namen, die API-Mappings mit mehreren Ebenen verwenden, leitet API Gateway Anfragen an das API-Mapping weiter, die den längsten Übereinstimmungspräfix hat.

Betrachten Sie beispielsweise einen benutzerdefinierten Domain-Namen https://api.example.com mit den folgenden API-Mappings:

1. (none) API 1 zugewiesen.

2. orders API 2 zugewiesen.

3. orders/v1/items API 3 zugewiesen.

4. orders/v2/items API 4 zugewiesen.

5. orders/v2/items/categories API 5 zugewiesen.

Anfrage	Ausgewählte API	Erklärung
https://api.example.com/orders	API 2	Die Anforderung stimmt genau mit diesem API-Mapping überein.
https://api.example.com/orders/v1/items	API 3	Die Anforderung stimmt genau mit diesem API-Mapping überein.
https://api.example.com/orders/v2/items	API 4	Die Anforderung stimmt genau mit diesem API-Mapping überein.
https://api.example.com/orders/v1/items/123	API 3	API Gateway wählt das Mapping aus, das den längsten Übereinstimmungspfad hat. Das 123 am Ende der Anforderung hat keinen Einfluss auf die Auswahl.
https://api.example.com/orders/v2/items/categories/5	API 5	API Gateway wählt das Mapping aus, das den längsten Übereinstimmungspfad hat.
https://api.example.com/customers	API 1	API Gateway verwendet das leere Mapping als Catch-All.
https://api.example.com/ordersandmore	API 2	API Gateway wählt das Mapping aus, das den längsten Übereinstimmungspräfix hat. Bei einem benutzerdefinierten Domain-Namen, der mit einstufigen Mappings konfiguriert ist, z. B. nur https://api.example.com/orders und https://api.example.com/, würde API Gateway API 1 auswählen, da es keinen passenden Pfad mit ordersandmore gibt.

Einschränkungen

• Bei einer API-Zuordnung müssen sich der benutzerdefinierte Domainname und die zugewiesenen APIs im selben AWS Konto befinden.

• API-Mappings dürfen nur Buchstaben, Zahlen und die folgenden Zeichen enthalten: $-_.+!*'()/.

• Die maximale Länge für den Pfad in eines API-Mappings beträgt 300 Zeichen.

• Es können 200 API-Zuweisungen mit mehreren Ebenen für jeden Domainnamen vorhanden sein.

• Sie können HTTP-APIs nur einem regionalen benutzerdefinierten Domain-Namen mit der TLS 1.2-Sicherheitsrichtlinie zuordnen.

• Sie können WebSocket APIs nicht demselben benutzerdefinierten Domainnamen zuordnen wie eine HTTP-API oder REST-API.

Ein API-Mapping erstellen

Um ein API-Mapping zu erstellen, müssen Sie zuerst einen benutzerdefinierten Domain-Namen, eine API und eine Phase erstellen. Informationen zum Erstellen eines benutzerdefinierten Domain-Namens finden Sie unter Richten Sie einen regionalen benutzerdefinierten Domainnamen in API Gateway ein.

AWS Serverless Application Model Vorlagen, die alle Ressourcen erstellen, finden Sie beispielsweise unter Sessions With SAM on GitHub.

AWS Management Console

So erstellen Sie ein API-Mapping

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

2. Wählen Sie benutzerdefinierte Domain-Namen aus.

3. Wählen Sie einen benutzerdefinierten Domain-Namen aus, den Sie bereits erstellt haben.

4. Wählen Sie API-Mappings aus.

5. Wählen Sie API-Zuordnungen konfigurieren aus.

6. Wählen Sie Neue Zuordnung hinzufügen aus.

7. Geben Sie eine API, eine Phase und optional einen Pfad ein.

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

AWS CLI

Der folgende AWS CLI Befehl erstellt eine API-Zuordnung. In diesem Beispiel sendet API Gateway Anforderungen an api.example.com/v1/orders an die angegebene API und Phase.

aws apigatewayv2 create-api-mapping \
    --domain-name api.example.com \
    --api-mapping-key v1/orders \
    --api-id a1b2c3d4 \
    --stage test

AWS CloudFormation

Das folgende AWS CloudFormation Beispiel erstellt eine API-Zuordnung.

MyApiMapping:
  Type: 'AWS::ApiGatewayV2::ApiMapping'
  Properties:
    DomainName: api.example.com
    ApiMappingKey: 'orders/v2/items'
    ApiId: !Ref MyApi
    Stage: !Ref MyStage