

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.

# Verwenden von API-Zuweisungen zum Verbinden von API-Stufen mit einem benutzerdefinierten Domainnamen für REST-APIs

Sie verwenden API-Mappings, um API-Stufen mit einem benutzerdefinierten Domain-Namen zu verbinden. Dadurch wird Traffic über Ihren benutzerdefinierten Domainnamen an Ihre APIs gesendet.

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

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 [Einrichten eines regionalen benutzerdefinierten Domainnamens in API Gateway](apigateway-regional-api-custom-domain-create.md).

## Eingehende Anfragen an Ihren benutzerdefinierten Domainnamen
<a name="rest-api-mappings-incoming-requests"></a>

Wenn Sie einen benutzerdefinierten Domainnamen einer Stufe Ihrer API zuweisen, entfernt API Gateway den eingehenden Basispfad. Dadurch wird der zugewiesene Basispfad aus dem Aufruf an die API entfernt. Wenn beispielsweise Ihre Basispfad-Zuweisung `https://api.example.com/orders/shop/5` der `test`-Stufe zugeordnet war und Sie die folgende Anfrage `https://api.example.com/orders/shop/5/hats` verwendet haben, würde API Gateway die Ressource `/hats` der `test`-Stufe Ihrer API aufrufen – nicht die Ressource `orders/shop/5/hats`.

## Zuweisen von API-Anforderungen
<a name="rest-api-mappings-evalutation"></a>

Im Folgenden wird erklärt, wie API Gateway API-Zuweisungen auswertet.

Sie können eine API-Zuweisung mit ein­stufigen Zuweisungen erstellen, z. B. eine API-Zuweisung von `orders` zur `beta`-Stufe einer API und eine API-Zuweisung von `shipping` zur `alpha`-Stufe einer API. Für regionale benutzerdefinierte Domainnamen mit der TLS-1.2-Sicherheitsrichtlinie unterstützt API Gateway mehrstufige API-Zuweisungen. Sie können z. B. eine API-Zuweisung von `orders/v1/items` zur `alpha`-Stufe einer API und `orders/v2/items` zur `beta`-Stufe einer API erstellen. Wenn Sie eine Zuweisung mit mehreren Ebenen erstellen, leitet API Gateway Anfragen an die API-Zuweisung weiter, die den längsten übereinstimmenden Pfad hat.

Sie können auch eine API-Zuweisung für den leeren Pfad `(none)` erstellen. Wenn kein Pfad mit der Anfrage übereinstimmt, sendet API Gateway die Anfrage an den leeren Pfad `(none)`.

In diesem Beispiel hat der benutzerdefinierte Domainname `https://api.example.com` die folgenden API-Zuweisungen.


|  API-Zuweisungen  |  Ausgewählte API  | 
| --- | --- | 
| `(none)` |  API 1  | 
|  `orders`  |  API 2  | 
| `orders/v1/items` |  API 3  | 
| `orders/v2/items` |  API 4  | 
| `orders/v1/items/categories` |  API 5  | 

Die folgende Tabelle zeigt, wie API Gateway die vorherigen API-Zuweisungen auf Beispielanfragen anwendet.


| Anfrage | Ausgewählte API | Erklärung | 
| --- | --- | --- | 
| `https://api.example.com/orders` | API 2 | Die Anforderung stimmt genau mit dieser API-Zuweisung überein. | 
| `https://api.example.com/orders/v1/items` | API 3 | Die Anforderung stimmt genau mit diesem API-Zuweisung überein. | 
| `https://api.example.com/orders/v2/items` | API 4 | Die Anforderung stimmt genau mit diesem API-Zuweisung überein. | 
| `https://api.example.com/orders/v1/items/123` | API 3 | API Gateway wählt die Zuweisung aus, die den längsten übereinstimmenden Pfad hat. Das `123` am Ende der Anforderung hat keinen Einfluss auf die Auswahl. Siehe [Eingehende Anfragen an Ihren benutzerdefinierten Domainnamen](#rest-api-mappings-incoming-requests). | 
| `https://api.example.com/orders/v1/items/categories/5` | API 5 | API Gateway wählt die Zuweisung aus, die den längsten übereinstimmenden Pfad hat. | 
| `https://api.example.com/customers` | API 1 | API Gateway verwendet die leere Zuweisung als Catch-All. | 
| `https://api.example.com/ordersandmore` | API 2 | API Gateway wählt die Zuweisung aus, die den längsten übereinstimmenden Präfix hat.<br />Bei einem benutzerdefinierten Domainnamen, der mit einstufigen Zuweisungen 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
<a name="rest-api-mappings-restrictions"></a>
+ Bei einer API-Zuordnung müssen sich der benutzerdefinierte Domainname und die zugewiesenen APIs im selben AWS Konto befinden.
+ API-Zuweisungen dürfen nur Buchstaben, Zahlen und die folgenden Zeichen enthalten: `$-_.+!*'()/`.
+ Die maximale Länge für den Pfad in einer API-Zuweisung beträgt 300 Zeichen.
+ Es können 200 API-Zuweisungen mit mehreren Ebenen für jeden Domainnamen vorhanden sein. Dieses Limit beinhaltet keine API-Zuweisungen mit einer einzigen Ebene, wie z. B. `/prod`
+ Sie können HTTP-APIs nur einem regionalen benutzerdefinierten Domainnamen mit der TLS 1.2-Sicherheitsrichtlinie zuordnen.
+ Sie können WebSocket APIs nicht demselben benutzerdefinierten Domainnamen wie eine HTTP-API oder REST-API zuordnen.
+ Sie müssen den Ressourceneintrag Ihres DNS-Anbieters erstellen oder aktualisieren, um ihn dem API-Endpunkt zuzuordnen, nachdem Sie Ihre API-Zuweisungen erstellt haben.
+ Wenn Sie mehrstufige API-Zuweisungen erstellen, konvertiert API Gateway alle Header-Namen in Kleinbuchstaben.

## Ein API-Mapping erstellen
<a name="rest-api-mappings-examples"></a>

Um ein API-Mapping zu erstellen, müssen Sie zuerst einen benutzerdefinierten Domain-Namen, eine API und eine Phase erstellen. Für Ihren benutzerdefinierten Domainnamen muss der Routing-Modus entweder auf `ROUTING_RULE_THEN_API_MAPPING` oder `API_MAPPING_ONLY` eingestellt sein. Weitere Informationen zum Einrichten des Routing-Modus finden Sie unter [Festlegen des Routing-Modus für Ihren benutzerdefinierten Domainnamen](set-routing-mode.md).

Beispiele für AWS Serverless Application Model Vorlagen, die alle Ressourcen erstellen, finden Sie unter [ Sitzungen mit ](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) eingeschaltem SAM GitHub.

------
#### [ AWS-Managementkonsole ]

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

1. Wählen Sie **Benutzerdefinierte Domainnamen** im Hauptnavigationsbereich aus. 

1. Wählen Sie einen benutzerdefinierten Domainnamen aus.

1. Wählen Sie auf der Registerkarte **Routing-Details** die Option **API-Zuweisungen konfigurieren** aus.

1. Geben Sie die **API**, die **Stufe** und den **Pfad** für die Zuweisung an.

1. Wählen Sie **Speichern** aus.

------
#### [ AWS CLI ]

Der folgende [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html)-Befehl erstellt eine API-Zuweisung. In diesem Beispiel sendet API Gateway Anforderungen an `api.example.com/v1/orders` an die angegebene API und Phase.

**Anmerkung**  
Um API-Mappings mit mehreren Ebenen zu erstellen, müssen Sie `apigatewayv2` verwenden.

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

------
#### [ CloudFormation ]

Im folgenden CloudFormation Beispiel wird eine API-Zuordnung erstellt.

**Anmerkung**  
Um API-Mappings mit mehreren Ebenen zu erstellen, müssen Sie `AWS::ApiGatewayV2` verwenden.

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

------