` sowie statische Werte.
Im HTTP-Protokoll, in dem Anforderungen und Antworten synchron gesendet werden, ist die Kommunikation im Wesentlichen unidirektional. Im WebSocket Protokoll erfolgt die Kommunikation in beide Richtungen. Antworten sind asynchron und werden vom Client nicht unbedingt in der gleichen Reihenfolge empfangen, in der die Client-Nachrichten gesendet wurden. Darüber hinaus kann das Backend Nachrichten an den Client senden.
**Anmerkung**
Für eine Route, die zur Verwendung der Integration `AWS_PROXY` oder `LAMBDA_PROXY` konfiguriert wurde, ist die Kommunikation unidirektional. API Gateway übergibt die Backend-Antwort nicht automatisch über die Routenantwort. Wenn bei der `LAMBDA_PROXY`-Integration wird der von der Lambda-Funktion zurückgegebene Text beispielsweise nicht an den Client zurückgegeben. Wenn Sie möchten, dass der Client Integrationsantworten erhält, müssen Sie eine Routenantwort definieren, um eine bidirektionale Kommunikation zu ermöglichen.
# WebSocket Auswahlausdrücke
API Gateway verwendet Auswahlausdrücke als Möglichkeit, den Anfrage- und Antwortkontext auszuwerten und einen Schlüssel zu erzeugen. Anhand des Schlüssels wird dann aus einem Satz möglicher Werte ausgewählt, die gewöhnlich von Ihnen, dem API-Entwickler, bereitgestellt werden. Der genaue Satz der unterstützten Variablen ist vom jeweiligen Ausdruck abhängig. Jeder Ausdruck wird nachstehend weiter erörtert.
Für alle Ausdrücke folgt die Sprache dem gleichen Satz von Regeln:
+ Einer Variable wird vorangestell `"$"`.
+ Variablen können explizit durch geschweifte Klammern abgegrenzt werden, z. ., `"${request.body.version}-beta"`.
+ Mehrere Variablen werden unterstützt, aber die Auswertung findet nur einmal statt (keine rekursive Auswertung).
+ Ein Dollarzeichen (`$`) kann durch die Escape-Zeichen `"\"` geschützt werden. Dies ist besonders nützlich, wenn ein Ausdruck definiert wird, der dem reservierten `$default`-Schlüssel zugeordnet wird, z. B. `"\$default"`.
+ In einigen Fällen ist ein Musterformat erforderlich. In diesem Fall sollte der Ausdruck entsprechend `"/"`-Statuscodes mit Schrägstrichen (`"/2\d\d/"`) verpackt werden, z. B. `2XX`.
**Topics**
+ [Routenantwort-Auswahlausdrücke](#apigateway-websocket-api-route-response-selection-expressions)
+ [API-Schlüssel-Auswahlausdrücke](#apigateway-websocket-api-apikey-selection-expressions)
+ [API-Zuordnungs-Auswahlausdrücke](#apigateway-websocket-api-mapping-selection-expressions)
+ [WebSocket Zusammenfassung des Auswahlausdrucks](#apigateway-websocket-api-selection-expression-table)
## Routenantwort-Auswahlausdrücke
Eine [Routenantwort](apigateway-websocket-api-route-response.md) wird für die Modellierung einer Antwort vom Backend zum Client verwendet. Für WebSocket APIs ist eine Routenantwort optional. Wenn es definiert ist, signalisiert es API Gateway, dass es beim Empfang einer WebSocket Nachricht eine Antwort an einen Client zurückgeben soll.
Die Auswertung des *Routenantwort-Auswahlausdrucks* ergibt einen Routenantwort-Schlüssel. Zukünftig wird dieser Schlüssel zur Auswahl unter einer der mit der API verknüpften [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html) dienen. Zurzeit wird jedoch nur der Schlüssel `$default` unterstützt.
## API-Schlüssel-Auswahlausdrücke
Dieser Ausdruck wird ausgewertet, wenn der Service bestimmt, dass mit der vorliegenden Anforderung nur fortgefahren werden soll, wenn der Client einen gültigen [API-Schlüssel](api-gateway-basic-concept.md#apigateway-definition-api-key) bereitstellt.
Zurzeit werden als einzigen Werte `$request.header.x-api-key` und `$context.authorizer.usageIdentifierKey` unterstützt.
## API-Zuordnungs-Auswahlausdrücke
Dieser Ausdruck wird ausgewertet, um zu bestimmen, welche API-Stufe bei einer über eine benutzerdefinierte Domäne gestellten Anforderung auszuwählen ist.
Derzeit wird als einziger Wert unterstütz `$request.basepath`.
## WebSocket Zusammenfassung des Auswahlausdrucks
In der folgenden Tabelle sind die Anwendungsfälle für Auswahlausdrücke zusammengefasst in WebSocket APIs:
| Auswahlausdrücke | Ausgewertet auf Schlüssel für | Hinweise | Beispielanwendungsfall |
| --- | --- | --- | --- |
| Api.RouteSelectionExpression | Route.RouteKey | \$1default wird als Catch-all-Route unterstützt. | Leitet WebSocket Nachrichten auf der Grundlage des Kontextes einer Client-Anfrage weiter. |
| Route.ModelSelectionExpression | Schlüssel für Route.RequestModels | Optional. Bei Angabe für Nicht-Proxy-Integrationen findet eine Modellvalidierung statt. `$default` wird als Catch-all-Route unterstützt. | Führt die Anforderungsvalidierung dynamisch innerhalb derselben Route aus. |
| Integration.TemplateSelectionExpression | Schlüssel für Integration.RequestTemplates | Optional. Kann für Nicht-Proxy-Integrationen zum Bearbeiten von eingehenden Nutzlasten bereitgestellt werden. `${request.body.jsonPath}`Unterstützte Werte sind und statische Werte. `$default` wird als Catch-all-Route unterstützt. | Dient zur Bearbeitung der Anforderung der aufrufenden Methode je nach den dynamischen Eigenschaften der Anforderung. |
| Integration.IntegrationResponseSelectionExpression | IntegrationResponse.IntegrationResponseKey | Optional. Kann für Nicht-Proxy-Integrationen bereitgestellt werden. Dient als Mustervergleich für Fehlermeldungen (von Lambda) oder Statuscodes (von HTTP-Integrationen). `$default` ist erforderlich, damit Nicht-Proxy-Integrationen als Catch-All für erfolgreiche Antworten fungieren. | Dient zum Bearbeiten der Antwort vom Backend. Wählen Sie, welche Aktion basierend auf der dynamischen Antwort des Backends ausgeführt werden soll (z. B. unterschiedliche Behandlung bestimmter Fehler). |
| IntegrationResponse.TemplateSelectionExpression | Schlüssel für IntegrationResponse.ResponseTemplates | Optional. Kann für Nicht-Proxy-Integrationen bereitgestellt werden. \$1default wird unterstützt. | In einigen Fällen kann eine dynamische Eigenschaft der Antwort verschiedene Transformationen innerhalb derselben Route und zugehörigen Integration vorgeben. `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}`, Unterstützte Werte sind , , , und statische Werte. `$default` wird als Catch-all-Route unterstützt. |
| Route.RouteResponseSelectionExpression | RouteResponse.RouteResponseKey | Sollte bereitgestellt werden, um die bidirektionale Kommunikation für eine WebSocket Route zu initiieren. Zurzeit ist dieser Wert ausschließlich auf `$default` eingeschränkt. | |
| RouteResponse.ModelSelectionExpression | Schlüssel für RouteResponse.RequestModels | Wird derzeit nicht unterstützt. | |
# WebSocket APIs In API Gateway entwickeln
Dieser Abschnitt enthält Einzelheiten zu den API Gateway Gateway-Funktionen, die Sie bei der Entwicklung Ihres API Gateway benötigen APIs.
Während Sie Ihre API Gateway-API entwickeln, entscheiden Sie sich für eine Reihe von Merkmalen Ihrer API. Diese Eigenschaften hängen davon ab, wofür Ihre API verwendet werden soll. So könnte es beispielsweise sein, dass Sie es nur bestimmten Clients gestatten möchten, die API aufzurufen. Vielleicht soll die API aber auch für alle verfügbar sein. Vielleicht benötigen Sie einen API-Aufruf, um eine Lambda-Funktion auszuführen, eine Datenbankabfrage durchzuführen oder eine Anwendung aufzurufen.
**Topics**
+ [WebSocket APIs Im API Gateway erstellen](apigateway-websocket-api-create-empty-api.md)
+ [IP-Adresstypen für WebSocket-APIs im API Gateway](websocket-api-ip-address-type.md)
+ [Routen für WebSocket APIs im API Gateway erstellen](websocket-api-develop-routes.md)
+ [Steuern und verwalten Sie den Zugriff WebSocket APIs auf das API Gateway](apigateway-websocket-api-control-access.md)
+ [Integrationen für das WebSocket APIs API Gateway](apigateway-websocket-api-integrations.md)
+ [Validierung für WebSocket APIs im API Gateway anfordern](websocket-api-request-validation.md)
+ [Datentransformationen für WebSocket APIs im API Gateway](websocket-api-data-transformations.md)
+ [Binäre Medientypen für WebSocket-APIs in API Gateway](websocket-api-develop-binary-media-types.md)
+ [Aufrufen WebSocket APIs](apigateway-how-to-call-websocket-api.md)
# WebSocket APIs Im API Gateway erstellen
Sie können eine WebSocket API in der API Gateway Gateway-Konsole erstellen, indem Sie den Befehl AWS CLI [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) oder den `CreateApi` Befehl in einem AWS SDK verwenden. Die folgenden Verfahren zeigen, wie Sie eine neue WebSocket API erstellen.
**Anmerkung**
WebSocket APIs unterstützt nur TLS 1.2 und TLS 1.3. Frühere TLS-Versionen werden nicht unterstützt.
## Erstellen Sie eine WebSocket API mithilfe von AWS CLI Befehlen
Der folgende [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html)-Befehl erstellt eine API mit dem Routen-Auswahlausdruck `$request.body.action`:
```
aws apigatewayv2 --region us-east-1 create-api --name "myWebSocketApi3" --protocol-type WEBSOCKET --route-selection-expression '$request.body.action'
```
Die Ausgabe sollte wie folgt aussehen:
```
{
"ApiKeySelectionExpression": "$request.header.x-api-key",
"Name": "myWebSocketApi3",
"CreatedDate": "2018-11-15T06:23:51Z",
"ProtocolType": "WEBSOCKET",
"RouteSelectionExpression": "'$request.body.action'",
"ApiId": "aabbccddee"
}
```
## Erstellen Sie eine WebSocket API mit der API Gateway Gateway-Konsole
Sie können eine WebSocket API in der Konsole erstellen, indem Sie das WebSocket Protokoll auswählen und der API einen Namen geben.
**Wichtig**
Sobald Sie die API erstellt haben, können Sie das für sie ausgewählte Protokoll nicht mehr ändern. Es gibt keine Möglichkeit, eine WebSocket API in eine REST-API umzuwandeln oder umgekehrt.
**So erstellen Sie eine WebSocket API mit der API Gateway Gateway-Konsole**
1. Melden Sie sich bei der API Gateway-Konsole an und wählen Sie **Create API (API erstellen)**.
1. Wählen Sie unter **WebSocket API** die Option **Build** aus. Es werden nur regionale Endpunkte unterstützt.
1. Geben Sie unter **API-Name** den Namen Ihrer API ein.
1. Geben Sie unter **Ausdruck für die Routenauswahl** einen Wert ein. Beispiel, `$request.body.action`.
Weitere Informationen zu Routen-Auswahlausdrücken finden Sie unter [Routen-Auswahlausdrücke](websocket-api-develop-routes.md#apigateway-websocket-api-route-selection-expressions).
1. Führen Sie eine der folgenden Aktionen aus:
+ Wählen Sie **Leere API erstellen** aus, wenn Sie eine API ohne Routen erstellen möchten.
+ Klicken Sie auf **Weiter**, um Ihrer API Routen anzuhängen.
Sie können Routen anhängen, nachdem Sie Ihre API erstellt haben.
# IP-Adresstypen für WebSocket-APIs im API Gateway
Beim Erstellen einer API geben Sie den Typ der IP-Adressen an, die Ihre API aufrufen dürfen. Sie können IPv4 auswählen, um IPv4-Adressen für den Aufruf Ihrer API zuzulassen, oder Sie können Dualstack auswählen, um sowohl IPv4- als auch IPv6-Adressen zuzulassen. Wir empfehlen, den IP-Adresstyp auf Dualstack zu setzen, um Engpässe im IP-Adressraum zu vermeiden und Ihre Sicherheitsposition zu verbessern. Weitere Informationen zu den Vorteilen eines Dualstack-IP-Adresstyps finden Sie unter [IPv6 in AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Überlegungen zu IP-Adresstypen
Die folgenden Überlegungen können Ihre Verwendung von IP-Adresstypen beeinflussen:
+ Der Standard-IP-Adresstyp für alle WebSocket-APIs ist IPv4.
+ Wenn Sie den IP-Adresstyp einer bestehende API von IPv4 in Dualstack ändern, stellen Sie sicher, dass alle Richtlinien, die den Zugriff auf Ihre APIs steuern, aktualisiert wurden, um IPv6-Aufrufe zu berücksichtigen. Wenn Sie den IP-Adresstyp ändern, wird die Änderung sofort wirksam.
+ Ihre API kann einem benutzerdefinierten Domainnamen mit einem anderen IP-Adresstyp als Ihre API zugewiesen werden. Wenn Sie Ihren Standard-API-Endpunkt deaktivieren, kann dies die Art und Weise beeinflussen, wie Aufrufer Ihre API aufrufen können.
## Ändern des IP-Adresstyps einer WebSocket-API
Sie können den IP-Adresstyp ändern, indem Sie die API-Konfiguration aktualisieren. Dies ist über die AWS-Managementkonsole, die AWS CLI, CloudFormation oder ein AWS SDK möglich. Wenn Sie den IP-Adresstyp der API ändern, müssen Sie Ihre API nicht erneut bereitstellen, damit die Änderungen wirksam werden.
------
#### [ AWS-Managementkonsole ]
**So ändern Sie den IP-Adresstypen einer WebSocket-API**
1. Melden Sie sich bei der API Gateway-Konsole unter [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) an.
1. Wählen Sie eine WebSocket-API.
1. Wählen Sie **API-Einstellungen** und anschließend **Bearbeiten** aus.
1. Wählen Sie unter „IP-Adresstyp“ entweder **IPv4** oder **Dualstack** aus.
1. Wählen Sie **Speichern** aus.
Die Änderung der API-Konfiguration wird sofort wirksam.
------
#### [ AWS CLI ]
Der folgende [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html)-Befehl aktualisiert eine API, sodass sie den IP-Adresstyp Dualstack verwendet:
```
aws apigatewayv2 update-api \
--api-id abcd1234 \
--ip-address-type dualstack
```
Die Ausgabe sieht wie folgt aus:
```
{
"ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com",
"ApiId": "abcd1234",
"ApiKeySelectionExpression": "$request.header.x-api-key",
"CreatedDate": "2025-02-04T22:20:20+00:00",
"DisableExecuteApiEndpoint": false,
"Name": "My-WebSocket-API",
"ProtocolType": "WEBSOCKET",
"RouteSelectionExpression": "$request.method $request.path",
"Tags": {},
"NotificationUris": [],
"IpAddressType": "dualstack"
}
```
------
# Routen für WebSocket APIs im API Gateway erstellen
In Ihrer WebSocket API werden eingehende JSON-Nachrichten auf der Grundlage von Routen, die Sie konfigurieren, an Backend-Integrationen weitergeleitet. (Nicht-JSON-Nachrichten werden an eine von Ihnen konfigurierte `$default`-Route weitergeleitet.)
Eine *Route* umfasst einen *Routenschlüssel*. Dabei handelt es sich um den Wert, der bei der Auswertung eines *Routen-Auswahlausdrucks* erwartet wird. Das `routeSelectionExpression` ist ein auf API-Ebene definiertes Attribut. Es gibt eine JSON-Eigenschaft an, von der erwartet wird, dass sie in der Nachricht-Nutzlast vorhanden ist. Weitere Informationen zu Routen-Auswahlausdrücken finden Sie unter [Routen-Auswahlausdrücke](#apigateway-websocket-api-route-selection-expressions).
Beispiel: Wenn Ihre JSON-Nachrichten eine `action`-Eigenschaft enthalten und Sie basierend auf dieser Eigenschaft verschiedene Aktionen durchführen möchten, könnte Ihr Routen-Auswahlausdruck `${request.body.action}` lauten. Ihre Routing-Tabelle würde in diesem Fall angeben, welche Aktion ausgeführt werden soll, indem der Wert der `action`-Eigenschaft gegen die benutzerdefinierten Routenschlüssel-Werte abgeglichen wird, die Sie in der Tabelle definiert haben.
Es gibt drei vordefinierte Routen, die verwendet werden können: `$connect`, `$disconnect` und `$default`. Darüber hinaus können Sie benutzerdefinierte Routen erstellen.
+ API Gateway ruft die `$connect` Route auf, wenn eine persistente Verbindung zwischen dem Client und einer WebSocket API initiiert wird.
+ API Gateway ruft die `$disconnect`-Route auf, wenn der Client oder der Server die Verbindung mit der API unterbricht.
+ API Gateway ruft eine benutzerdefinierte Route auf, wenn nach der Auswertung des Routen-Auswahlausdrucks im Hinblick auf die Nachricht eine übereinstimmende Route gefunden wird. Die Übereinstimmung bestimmt, welche Integration aufgerufen wird.
+ API Gateway ruft die Route `$default` auf, wenn der Routen-Auswahlausdruck nicht im Hinblick auf die Nachricht ausgewertet werden kann oder wenn keine übereinstimmende Route gefunden wird.
## Routen-Auswahlausdrücke
Ein *Routen-Auswahlausdruck* wird ausgewertet, wenn der Service die Route auswählt, der eine eingehende Nachricht folgen soll. Der Service verwendet die Route, deren `routeKey` genau dem ausgewerteten Wert entspricht. Wenn bei fehlender Übereinstimmung eine Route mit dem Routenschlüssel `$default` vorhanden ist, wird diese Route ausgewählt. Wenn keine Routen dem ausgewählten Wert entsprechen und keine `$default`-Route vorhanden ist, gibt der Service einen Fehler zurück. Für WebSocket -based APIs sollte der Ausdruck die folgende Form haben`$request.body.{path_to_body_element}`.
Angenommen, Sie senden die folgende JSON-Nachricht:
```
{
"service" : "chat",
"action" : "join",
"data" : {
"room" : "room1234"
}
}
```
Möglicherweise möchten Sie das Verhalten Ihrer API basierend auf der Eigenschaft `action` auswählen. In diesem Fall könnten Sie den folgenden Routen-Auswahlausdruck definieren:
```
$request.body.action
```
`request.body`Bezieht sich in diesem Beispiel auf die JSON-Nutzlast Ihrer Nachricht und `.action` ist ein [JSONPath](https://goessner.net/articles/JsonPath/)Ausdruck. Sie können nach `request.body` einen beliebigen JSON-Pfad-Ausdruck verwenden. Denken Sie aber daran, dass das Ergebnis in Text umgewandelt wird. Wenn Ihr JSONPath Ausdruck beispielsweise ein Array mit zwei Elementen zurückgibt, wird dieses als Zeichenfolge `"[item1, item2]"` dargestellt. Aus diesem Grund ist es sinnvoll, dass Ihr Ausdruck auf einen Wert und nicht auf ein Array oder Objekt ausgewertet wird.
Sie können einfach einen statischen Wert oder auch mehrere Variablen verwenden. In der folgenden Tabelle werden Beispiele und deren im Hinblick auf die vorhergehende Nutzlast ausgewerteten Ergebnisse gezeigt.
| Ausdruck | Ausgewertetes Ergebnis | Beschreibung |
| --- | --- | --- |
| \$1request.body.action | join | Eine entpackte Variable |
| \$1\$1request.body.action\$1 | join | Eine verpackte Variable |
| \$1\$1request.body.service\$1/\$1\$1request.body.action\$1 | chat/join | Mehrere Variablen mit statischen Werten |
| \$1\$1request.body.action\$1-\$1\$1request.body.invalidPath\$1 | join- | Wenn der nicht gefunden JSONPath wird, wird die Variable als „“ aufgelöst. |
| action | action | Statischer Wert |
| \$1\$1default | \$1default | Statischer Wert |
Das ausgewertete Ergebnis wird zum Auffinden der Route verwendet. Wenn eine Route mit einem übereinstimmenden Routenschlüssel vorhanden ist, wird die Route zur Verarbeitung der Nachricht ausgewählt. Wenn keine passende Route gefunden wird, versucht API Gateway, die `$default`-Route zu finden, falls verfügbar. Wenn die `$default`-Route nicht definiert ist, gibt API Gateway einen Fehler zurück.
## Routen für eine WebSocket API in API Gateway einrichten
Wenn Sie zum ersten Mal eine neue WebSocket API erstellen, gibt es drei vordefinierte Routen: `$connect``$disconnect`, und`$default`. Sie können sie mithilfe der Konsole, der API oder erstellen AWS CLI. Auf Wunsch können Sie benutzerdefinierte Routen erstellen. Weitere Informationen finden Sie unter [Überblick über WebSocket APIs in API Gateway](apigateway-websocket-api-overview.md).
**Anmerkung**
In der CLI ist es möglich, Routen vor oder nach dem Erstellen von Integrationen zu erstellen. Auch können Sie dieselbe Integration für mehrere Routen wiederverwenden.
### Route mit der API Gateway-Konsole erstellen
**So erstellen Sie eine Route über die API Gateway-Konsole:**
1. Melden Sie sich bei der API Gateway-Konsole an, wählen Sie die API und wählen Sie **Routes (Routen)**.
1. Wählen Sie **Create route** (Route erstellen) aus.
1. Geben Sie bei **Route key** (Routenschlüssel) den Schlüsselnamen ein. Sie können die vordefinierten Routen (`$connect`, `$disconnect` und `$default`) oder eine benutzerdefinierte Route erstellen.
**Anmerkung**
Wenn Sie eine benutzerdefinierte Route erstellen, verwenden Sie nicht das `$`-Präfix im Routenschlüsselnamen. Dieses Präfix ist für vordefinierte Routen reserviert.
1. Wählen und konfigurieren Sie den Integrationstyp für die Route. Weitere Informationen finden Sie unter [Richten Sie mit der WebSocket API Gateway-Konsole eine API-Integrationsanfrage ein](apigateway-websocket-api-integration-requests.md#apigateway-websocket-api-integration-request-using-console).
### Erstellen Sie eine Route mit dem AWS CLI
Der folgende [create-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route.html)-Befehl erstellt eine Route:
```
aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default
```
Die Ausgabe sieht wie folgt aus:
```
{
"ApiKeyRequired": false,
"AuthorizationType": "NONE",
"RouteKey": "$default",
"RouteId": "1122334"
}
```
### Angeben der Routenanforderungs-Einstellungen für `$connect`
Wenn Sie die `$connect`-Route für Ihre API einrichten, sind die folgenden optionalen Einstellungen verfügbar, um die Autorisierung für Ihre API zu ermöglichen. Weitere Informationen finden Sie unter [Die Route `$connect`](apigateway-websocket-api-route-keys-connect-disconnect.md#apigateway-websocket-api-routes-about-connect).
+ **Authorization (Autorisierung)**: Wenn keine Autorisierung erforderlich ist, können Sie `NONE` angeben. Geben Sie andernfalls Folgendes ein:
+ `AWS_IAM`um den Zugriff auf Ihre API mithilfe von AWS Standard-IAM-Richtlinien zu kontrollieren.
+ `CUSTOM`, um die Autorisierung für eine API durch Angabe einer zuvor von Ihnen erstellten Lambda-Genehmigerfunktion zu implementieren. Der Autorisierer kann sich in Ihrem eigenen AWS Konto oder einem anderen Konto befinden. AWS Weitere Informationen über Lambda-Genehmiger finden Sie unter [API Gateway-Lambda-Genehmiger verwenden](apigateway-use-lambda-authorizer.md).
**Anmerkung**
In der API Gateway-Konsole ist die Einstellung `CUSTOM` erst sichtbar, nachdem Sie eine Genehmigerfunktion wie unter [Lambda-Genehmiger konfigurieren (Konsole)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console) beschrieben eingerichtet haben.
**Wichtig**
Die Einstellung von **Authorization (Autorisierung)** wird auf die gesamte API angewendet, nicht nur auf die `$connect`-Route. Die `$connect`-Route schützt die übrigen Routen, da sie für jede Verbindung aufgerufen wird.
+ **API-Schlüssel erforderlich**: Sie können für die `$connect`-Route einer API optional einen API-Schlüssel verlangen. Sie können API-Schlüssel zusammen mit Nutzungsplänen verwenden, um den Zugriff auf Ihre zu kontrollieren und zu verfolgen. APIs Weitere Informationen finden Sie unter [Nutzungspläne und API-Schlüssel für REST APIs in API Gateway](api-gateway-api-usage-plans.md).
### `$connect`-Routenanforderung über die API Gateway-Konsole einrichten
So richten Sie die `$connect` Routenanforderung für eine WebSocket API mithilfe der API-Gateway-Konsole ein:
1. Melden Sie sich bei der API Gateway-Konsole an, wählen Sie die API und wählen Sie **Routes (Routen)**.
1. Wählen Sie unter **Routes** (Routen) `$connect` aus oder erstellen Sie eine `$connect`-Route, indem Sie wie folgt vorgehen [Route mit der API Gateway-Konsole erstellen](#apigateway-websocket-api-route-using-console).
1. Wählen Sie im Abschnitt **Route request settings** (Einstellungen der Routenanforderung) die Option **Edit** (Bearbeiten) aus.
1. Wählen Sie für **Authorization** (Autorisierung) einen Autorisierungstyp aus.
1. Um eine API für die `$connect`-Route anzufordern, wählen Sie **Require API key** (API-Schlüssel erforderlich) aus.
1. Wählen Sie **Änderungen speichern ** aus.
# Richten Sie Routenantworten für WebSocket APIs in API Gateway ein
WebSocket Routen können für bidirektionale oder unidirektionale Kommunikation konfiguriert werden. API-Gateway übergibt die Backend-Antwort nicht über die Routenantwort, es sei denn, Sie haben eine Routenantwort eingerichtet.
**Anmerkung**
Sie können nur die `$default` Routenantwort für definieren. WebSocket APIs Sie können eine Integrationsantwort verwenden, um die Antwort von einem Backend-Service zu manipulieren. Weitere Informationen finden Sie unter [Übersicht über Integrationsantworten](apigateway-websocket-api-integration-responses.md#apigateway-websocket-api-integration-response-overview).
Sie können Routenantworten und Antwortauswahlausdrücke mithilfe der API Gateway Gateway-Konsole oder des AWS CLI oder eines AWS SDK konfigurieren.
Weitere Informationen über Routenantwort-Auswahlausdrücke finden Sie unter [Routenantwort-Auswahlausdrücke](apigateway-websocket-api-selection-expressions.md#apigateway-websocket-api-route-response-selection-expressions).
**Topics**
+ [Routenantwort mit der API Gateway-Konsole einrichten](#apigateway-websocket-api-route-response-using-console)
+ [Richten Sie eine Routenantwort ein, indem Sie AWS CLI](#apigateway-websocket-api-route-response-using-awscli)
## Routenantwort mit der API Gateway-Konsole einrichten
Nachdem Sie eine WebSocket API erstellt und eine Proxy-Lambda-Funktion an die Standardroute angehängt haben, können Sie die Routenantwort mit der API Gateway Gateway-Konsole einrichten:
1. Melden Sie sich bei der API Gateway Gateway-Konsole an und wählen Sie eine WebSocket API mit einer Proxy-Lambda-Funktionsintegration auf der `$default` Route aus.
1. Wählen Sie unter **Routes** (Routen) die `$default`-Route aus.
1. Wählen Sie **Enable two-way communication** (Bidirektionale Kommunikation aktivieren).
1. Klicken Sie auf **Deploy API**.
1. Stellen Sie Ihre API für eine Stufe bereit.
Stellen Sie mit dem folgenden [wscat](https://www.npmjs.com/package/wscat)-Befehl eine Verbindung mit Ihrer API her. Mehr über `wscat` erfahren Sie unter [Wird verwendet`wscat`, um eine Verbindung zu einer WebSocket API herzustellen und Nachrichten an diese zu senden](apigateway-how-to-call-websocket-api-wscat.md).
```
wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test
```
Drücken Sie die Eingabetaste, um die Standardroute aufzurufen. Der Hauptteil Ihrer Lambda-Funktion sollte zurückgegeben werden.
## Richten Sie eine Routenantwort ein, indem Sie AWS CLI
Der folgende [create-route-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route-response.html)Befehl erstellt eine Routenantwort für die `$default` Route. Sie können die API-ID und Routing-ID identifizieren, indem Sie die Befehle [get-apis](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-apis.html) und [get-routes](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-routes.html) verwenden.
```
aws apigatewayv2 create-route-response \
--api-id aabbccddee \
--route-id 1122334 \
--route-response-key '$default'
```
Die Ausgabe sieht wie folgt aus:
```
{
"RouteResponseId": "abcdef",
"RouteResponseKey": "$default"
}
```
# Richten Sie eine `$connect` Route ein, für die ein WebSocket Unterprotokoll erforderlich ist
Clients können das `Sec-WebSocket-Protocol` Feld verwenden, um während der Verbindung zu Ihrer WebSocket API ein [WebSocket Unterprotokoll](https://datatracker.ietf.org/doc/html/rfc6455#page-12) anzufordern. Sie können eine Integration für die `$connect`-Route einrichten, um Verbindungen nur zuzulassen, wenn ein Client ein von Ihrer API unterstütztes Unterprotokoll anfordert.
Die folgende Lambda-Beispielfunktion gibt den `Sec-WebSocket-Protocol`-Header an Clients zurück. Die Funktion stellt nur dann eine Verbindung zu Ihrer API her, wenn der Client das `myprotocol`-Unterprotokoll angibt.
Eine CloudFormation Vorlage, die diese Beispiel-API- und Lambda-Proxyintegration erstellt, finden Sie unter [samples/ws-subprotocol.zip](samples/ws-subprotocol.zip).
```
export const handler = async (event) => {
if (event.headers != undefined) {
const headers = toLowerCaseProperties(event.headers);
if (headers['sec-websocket-protocol'] != undefined) {
const subprotocolHeader = headers['sec-websocket-protocol'];
const subprotocols = subprotocolHeader.split(',');
if (subprotocols.indexOf('myprotocol') >= 0) {
const response = {
statusCode: 200,
headers: {
"Sec-WebSocket-Protocol" : "myprotocol"
}
};
return response;
}
}
}
const response = {
statusCode: 400
};
return response;
};
function toLowerCaseProperties(obj) {
var wrapper = {};
for (var key in obj) {
wrapper[key.toLowerCase()] = obj[key];
}
return wrapper;
}
```
Sie können [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat) verwenden, um zu testen, ob Ihre API Verbindungen nur zulässt, wenn ein Client ein von Ihrer API unterstütztes Unterprotokoll anfordert. Die folgenden Befehle verwenden das `-s`-Flag, um während der Verbindung Unterprotokolle anzugeben.
Mit dem folgenden Befehl wird versucht, eine Verbindung mit einem nicht unterstützten Unterprotokoll herzustellen. Da der Client das `chat1`-Unterprotokoll angegeben hat, gibt die Lambda-Integration einen 400-Fehler zurück und die Verbindung ist nicht erfolgreich.
```
wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1
error: Unexpected server response: 400
```
Der folgende Befehl enthält ein unterstütztes Unterprotokoll in der Verbindungsanforderung. Die Lambda-Integration ermöglicht die Verbindung.
```
wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1,myprotocol
connected (press CTRL+C to quit)
```
Weitere Informationen zum Aufrufen WebSocket APIs finden Sie unter. [Aufrufen WebSocket APIs](apigateway-how-to-call-websocket-api.md)
# Steuern und verwalten Sie den Zugriff WebSocket APIs auf das API Gateway
API Gateway unterstützt mehrere Mechanismen zur Steuerung und Verwaltung des Zugriffs auf Ihre WebSocket API.
Sie können die folgenden Mechanismen für die Authentifizierung und Autorisierung verwenden:
+ ** AWS Standard-IAM-Rollen und -Richtlinien** bieten flexible und robuste Zugriffskontrollen. Mithilfe von IAM-Rollen und -Richtlinien können Sie steuern, wer Ihre APIs Rollen erstellen und verwalten darf und wer sie aufrufen kann. Weitere Informationen finden Sie unter [Steuern Sie den Zugriff auf WebSocket APIs mit IAM-Autorisierung](apigateway-websocket-control-access-iam.md).
+ **IAM-Tags** können zusammen mit IAM-Richtlinien verwendet werden, um den Zugriff zu steuern. Weitere Informationen finden Sie unter [Tags zur Steuerung des Zugriffs auf API Gateway-REST-API-Ressourcen verwenden](apigateway-tagging-iam-policy.md).
+ **Lambda-Autorisierer** sind Lambda-Funktionen, die den Zugriff auf kontrollieren. APIs Weitere Informationen finden Sie unter [Steuern Sie den Zugriff WebSocket APIs mit AWS Lambda REQUEST-Autorisierern](apigateway-websocket-api-lambda-auth.md).
Um Ihre Sicherheitslage zu verbessern, empfehlen wir Ihnen, auf allen Ihren Routen einen Autorisierer für die `$connect` Route zu konfigurieren. WebSocket APIs Dies kann erforderlich sein, um verschiedene Compliance-Rahmenwerke einzuhalten. Weitere Informationen finden Sie unter [Amazon-API-Gateway-Steuerelemente](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) im *Benutzerhandbuch für AWS Security Hub *.
**Topics**
+ [Steuern Sie den Zugriff auf WebSocket APIs mit IAM-Autorisierung](apigateway-websocket-control-access-iam.md)
+ [Steuern Sie den Zugriff WebSocket APIs mit AWS Lambda REQUEST-Autorisierern](apigateway-websocket-api-lambda-auth.md)
# Steuern Sie den Zugriff auf WebSocket APIs mit IAM-Autorisierung
Die IAM-Autorisierung in WebSocket APIs ähnelt der für [REST APIs](api-gateway-control-access-using-iam-policies-to-invoke-api.md), mit den folgenden Ausnahmen:
+ Die Aktion `execute-api` unterstützt `ManageConnections` zusätzlich zu vorhandenen Aktionen (`Invoke`, `InvalidateCache`). `ManageConnections` steuert den Zugriff auf die API @connections.
+ WebSocket Routen verwenden ein anderes ARN-Format:
```
arn:aws:execute-api:region:account-id:api-id/stage-name/route-key
```
+ Die `@connections` API verwendet dasselbe ARN-Format wie REST APIs:
```
arn:aws:execute-api:region:account-id:api-id/stage-name/POST/@connections
```
**Wichtig**
Wenn Sie die [IAM-Autorisierung](#apigateway-websocket-control-access-iam) verwenden, müssen Sie Anforderungen mit [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html) signieren.
Sie könnten z. B. die folgende Richtlinie für den Client einrichten. Dieses Beispiel ermöglicht allen Benutzern das Senden einer Nachricht (`Invoke`) für alle Routen, außer für eine geheime Route in der Stufe `prod`, und hindert alle Benutzer am Senden einer Nachricht zurück an verbundene Clients (`ManageConnections`) für alle Stufen.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/prod/*"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/prod/secret"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:ManageConnections"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/*"
]
}
]
}
```
------
# Steuern Sie den Zugriff WebSocket APIs mit AWS Lambda REQUEST-Autorisierern
Eine Lambda-Autorisierungsfunktion in WebSocket APIs ähnelt der für [REST APIs](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create), mit den folgenden Ausnahmen:
+ Sie können für die `$connect`-Route nur eine Lambda-Genehmiger-Funktion verwenden.
+ Sie können keine Pfadvariablen (`event.pathParameters`) verwenden, da der Pfad fest ist.
+ `event.methodArn` unterscheidet sich von seinem REST API-Äquivalent, da es über keine HTTP-Methode verfügt. Im Fall von `$connect` endet `methodArn` mit `"$connect"`:
```
arn:aws:execute-api:region:account-id:api-id/stage-name/$connect
```
+ Die Kontextvariablen in unterscheiden `event.requestContext` sich von denen für REST. APIs
Das folgende Beispiel zeigt eine Eingabe für einen `REQUEST` Autorisierer für eine WebSocket API:
```
{
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/default/$connect",
"headers": {
"Connection": "upgrade",
"content-length": "0",
"HeaderAuth1": "headerValue1",
"Host": "abcdef123.execute-api.us-east-1.amazonaws.com",
"Sec-WebSocket-Extensions": "permessage-deflate; client_max_window_bits",
"Sec-WebSocket-Key": "...",
"Sec-WebSocket-Version": "13",
"Upgrade": "websocket",
"X-Amzn-Trace-Id": "...",
"X-Forwarded-For": "...",
"X-Forwarded-Port": "443",
"X-Forwarded-Proto": "https"
},
"multiValueHeaders": {
"Connection": [
"upgrade"
],
"content-length": [
"0"
],
"HeaderAuth1": [
"headerValue1"
],
"Host": [
"abcdef123.execute-api.us-east-1.amazonaws.com"
],
"Sec-WebSocket-Extensions": [
"permessage-deflate; client_max_window_bits"
],
"Sec-WebSocket-Key": [
"..."
],
"Sec-WebSocket-Version": [
"13"
],
"Upgrade": [
"websocket"
],
"X-Amzn-Trace-Id": [
"..."
],
"X-Forwarded-For": [
"..."
],
"X-Forwarded-Port": [
"443"
],
"X-Forwarded-Proto": [
"https"
]
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"multiValueQueryStringParameters": {
"QueryString1": [
"queryValue1"
]
},
"stageVariables": {},
"requestContext": {
"routeKey": "$connect",
"eventType": "CONNECT",
"extendedRequestId": "...",
"requestTime": "19/Jan/2023:21:13:26 +0000",
"messageDirection": "IN",
"stage": "default",
"connectedAt": 1674162806344,
"requestTimeEpoch": 1674162806345,
"identity": {
"sourceIp": "..."
},
"requestId": "...",
"domainName": "abcdef123.execute-api.us-east-1.amazonaws.com",
"connectionId": "...",
"apiId": "abcdef123"
}
}
```
Die folgende Lambda-Autorisierungsfunktion ist eine WebSocket Version der Lambda-Autorisierungsfunktion für REST in: APIs [Weitere Beispiele für Lambda-Genehmigerfunktionen](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create)
------
#### [ Node.js ]
```
// A simple REQUEST authorizer example to demonstrate how to use request
// parameters to allow or deny a request. In this example, a request is
// authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter
// in the request context match the specified values of
// of 'headerValue1' and 'queryValue1' respectively.
export const handler = function(event, context, callback) {
console.log('Received event:', JSON.stringify(event, null, 2));
// Retrieve request parameters from the Lambda function input:
var headers = event.headers;
var queryStringParameters = event.queryStringParameters;
var stageVariables = event.stageVariables;
var requestContext = event.requestContext;
// Parse the input for the parameter values
var tmp = event.methodArn.split(':');
var apiGatewayArnTmp = tmp[5].split('/');
var awsAccountId = tmp[4];
var region = tmp[3];
var ApiId = apiGatewayArnTmp[0];
var stage = apiGatewayArnTmp[1];
var route = apiGatewayArnTmp[2];
// Perform authorization to return the Allow policy for correct parameters and
// the 'Unauthorized' error, otherwise.
var authResponse = {};
var condition = {};
condition.IpAddress = {};
if (headers.HeaderAuth1 === "headerValue1"
&& queryStringParameters.QueryString1 === "queryValue1") {
callback(null, generateAllow('me', event.methodArn));
} else {
callback(null, generateDeny('me', event.methodArn));
}
}
// Helper function to generate an IAM policy
var generatePolicy = function(principalId, effect, resource) {
// Required output:
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17 '; // default version
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke'; // default action
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}
var generateAllow = function(principalId, resource) {
return generatePolicy(principalId, 'Allow', resource);
}
var generateDeny = function(principalId, resource) {
return generatePolicy(principalId, 'Deny', resource);
}
```
------
#### [ Python ]
```
# A simple REQUEST authorizer example to demonstrate how to use request
# parameters to allow or deny a request. In this example, a request is
# authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter
# in the request context match the specified values of
# of 'headerValue1' and 'queryValue1' respectively.
import json
def lambda_handler(event, context):
print(event)
# Retrieve request parameters from the Lambda function input:
headers = event['headers']
queryStringParameters = event['queryStringParameters']
stageVariables = event['stageVariables']
requestContext = event['requestContext']
# Parse the input for the parameter values
tmp = event['methodArn'].split(':')
apiGatewayArnTmp = tmp[5].split('/')
awsAccountId = tmp[4]
region = tmp[3]
ApiId = apiGatewayArnTmp[0]
stage = apiGatewayArnTmp[1]
route = apiGatewayArnTmp[2]
# Perform authorization to return the Allow policy for correct parameters
# and the 'Unauthorized' error, otherwise.
authResponse = {}
condition = {}
condition['IpAddress'] = {}
if (headers['HeaderAuth1'] ==
"headerValue1" and queryStringParameters["QueryString1"] == "queryValue1"):
response = generateAllow('me', event['methodArn'])
print('authorized')
return json.loads(response)
else:
response = generateDeny('me', event['methodArn'])
print('unauthorized')
return json.loads(response)
# Help function to generate IAM policy
def generatePolicy(principalId, effect, resource):
authResponse = {}
authResponse['principalId'] = principalId
if (effect and resource):
policyDocument = {}
policyDocument['Version'] = '2012-10-17 '
policyDocument['Statement'] = []
statementOne = {}
statementOne['Action'] = 'execute-api:Invoke'
statementOne['Effect'] = effect
statementOne['Resource'] = resource
policyDocument['Statement'] = [statementOne]
authResponse['policyDocument'] = policyDocument
authResponse['context'] = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": True
}
authResponse_JSON = json.dumps(authResponse)
return authResponse_JSON
def generateAllow(principalId, resource):
return generatePolicy(principalId, 'Allow', resource)
def generateDeny(principalId, resource):
return generatePolicy(principalId, 'Deny', resource)
```
------
[Gehen Sie genauso vor wie bei REST, um die vorherige Lambda-Funktion als `REQUEST` Autorisierungsfunktion für eine WebSocket API zu konfigurieren. APIs](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console)
Um die `$connect`-Route für die Verwendung dieses Lambda-Genehmigers in der Konsole zu konfigurieren, wählen Sie die `$connect`-Route oder erstellen diese. Wählen Sie im Abschnitt **Route request settings** (Einstellungen der Routenanforderung) die Option **Edit** (Bearbeiten) aus. Wählen Sie im Dropdown-Menü **Authorization** (Autorisierung) Ihren Autorisierer aus und wählen Sie dann **Save changes** (Änderungen speichern) aus.
Zum Testen des Genehmigers müssen Sie eine neue Verbindung erstellen. Wenn der Genehmiger in `$connect` geändert wird, hat dies keine Auswirkungen auf den bereits verbundenen Client. Wenn Sie eine Verbindung zu Ihrer WebSocket API herstellen, müssen Sie Werte für alle konfigurierten Identitätsquellen angeben. Beispielsweise können Sie eine Verbindung durch Senden einer gültigen Abfragezeichenfolge und eines gültigen Headers unter Verwendung von `wscat` wie im folgenden Beispiel herstellen:
```
wscat -c 'wss://myapi.execute-api.us-east-1.amazonaws.com/beta?QueryString1=queryValue1' -H HeaderAuth1:headerValue1
```
Bei dem Versuch, ohne einen gültigen Identitätswert eine Verbindung herzustellen, erhalten Sie eine `401`-Antwort:
```
wscat -c wss://myapi.execute-api.us-east-1.amazonaws.com/beta
error: Unexpected server response: 401
```
# Integrationen für das WebSocket APIs API Gateway
Nach dem Einrichten einer API-Route müssen Sie diese in einen Endpunkt im Backend integrieren. Ein Backend-Endpunkt wird auch als Integrationsendpunkt bezeichnet und kann eine Lambda-Funktion, ein HTTP-Endpunkt oder eine AWS Serviceaktion sein. Die API-Integration beinhaltet eine Integrationsanforderung und eine Integrationsantwort.
In diesem Abschnitt erfahren Sie, wie Sie Integrationsanfragen und Integrationsantworten für Ihre WebSocket API einrichten.
**Topics**
+ [Richten Sie eine WebSocket API-Integrationsanfrage in API Gateway ein](apigateway-websocket-api-integration-requests.md)
+ [Richten Sie eine WebSocket API-Integrationsantwort in API Gateway ein](apigateway-websocket-api-integration-responses.md)
# Richten Sie eine WebSocket API-Integrationsanfrage in API Gateway ein
Das Einrichten einer Integrationsanforderung umfasst die folgenden Schritte:
+ Auswählen eines Routenschlüssels zum Integrieren im Backend.
+ Angabe des aufzurufenden Backend-Endpunkts. WebSocket APIs unterstützt die folgenden Integrationstypen:
+ `AWS_PROXY`
+ `AWS`
+ `HTTP_PROXY`
+ `HTTP`
+ `MOCK`
Weitere Informationen zu Integrationstypen finden Sie [IntegrationType](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)in der API Gateway V2 REST API.
+ Konfigurieren, wie die Routenanforderungsdaten bei Bedarf in Integrationsanforderungsdaten konvertiert werden, durch Angabe einer oder mehrerer Anforderungsvorlagen.
## Richten Sie mit der WebSocket API Gateway-Konsole eine API-Integrationsanfrage ein
**So fügen Sie mithilfe der API-Gateway-Konsole eine Integrationsanfrage zu einer Route in einer WebSocket API hinzu**
1. Melden Sie sich bei der API Gateway-Konsole an, wählen Sie die API und wählen Sie **Routes (Routen)**.
1. Wählen Sie unter **Routes (Routen)** die Route aus.
1. Wählen Sie die Registerkarte **Integration request** (Integrationsanforderung) und dann im Abschnitt **Integration request settings** (Einstellungen für Integrationsanforderungen) die Option **Edit** (Bearbeiten) aus.
1. Wählen Sie für **Integration type** (Integrationstyp) eine der folgenden Optionen:
+ Wählen Sie die **Lambda-Funktion** nur, wenn Ihre API in eine AWS Lambda Funktion integriert wird, die Sie bereits in diesem Konto oder in einem anderen Konto erstellt haben.
**Um eine neue Lambda-Funktion in zu erstellen AWS Lambda, eine Ressourcenberechtigung für die Lambda-Funktion festzulegen oder andere Lambda-Serviceaktionen auszuführen, wählen Sie AWS stattdessen Service.**
+ Wählen Sie **HTTP**, wenn Ihre API in einen vorhandenen HTTP-Endpunkt integriert wird. Weitere Informationen finden Sie unter [HTTP-Integrationen für REST APIs in API Gateway](setup-http-integrations.md).
+ Wählen Sie **Mock**, wenn Sie API-Antworten direkt von API Gateway generieren möchten, ohne dass ein Integrations-Backend erforderlich ist. Weitere Informationen finden Sie unter [Scheinintegrationen für REST APIs in API Gateway](how-to-mock-integration.md).
+ Wählen Sie **AWS Service**, wenn Ihre API in einen Dienst integriert werden soll. AWS
+ Wählen Sie **VPC Link** (VPC-Link), wenn Ihre API einen `VpcLink` als privaten Integrations-Endpunkt verwenden wird. Weitere Informationen finden Sie unter [Richten Sie eine private Integration ein](set-up-private-integration.md).
1. Wenn Sie **Lambda Function** (Lambda-Funktion) wählen, gehen Sie wie folgt vor:
1. Markieren Sie unter **Use Lambda Proxy integration** (Lambda-Proxy-Integration verwenden) das Kontrollkästchen, wenn Sie die [Lambda-Proxy-Integration](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy) oder die [kontoübergreifende Lambda-Proxy-Integration](apigateway-cross-account-lambda-integrations.md) verwenden möchten.
1. Geben Sie für **Lambda Function** (Lambda-Funktion) die Funktion auf eine der folgenden Arten an:
+ Wenn sich Ihre Lambda-Funktion in demselben Konto befindet, geben Sie den Funktionsnamen ein und wählen Sie dann die Funktion aus der Dropdown-Liste aus.
**Anmerkung**
Der Funktionsname kann optional seinen Alias oder seine Versionsangabe, wie in `HelloWorld`, `HelloWorld:1` oder `HelloWorld:alpha`, enthalten.
+ Wenn sich die Funktion in einem anderen Konto befindet, geben Sie den ARN für die Funktion ein.
1. Wenn Sie den Timeout-Standardwert von 29 Sekunden verwenden möchten, lassen Sie das Kontrollkästchen **Default timeout** (Standardzeitüberschreitung) aktiviert. Wenn Sie einen benutzerdefinierten Zeitüberschreitungswert festlegen möchten, wählen Sie **Default timeout** (Standardzeitüberschreitung) aus und geben Sie einen Zeitüberschreitungswert zwischen `50` und `29000` Millisekunden ein.
1. Befolgen Sie bei Wahl von **HTTP** die Anweisungen in Schritt 4 von [API-Integrationsanfrage über die API Gateway-Konsole einrichten](how-to-method-settings-console.md).
1. Befolgen Sie bei Wahl von **Mock (Pseudo)** die Anweisungen unter dem Schritt **Request Templates (Vorlagen anfordern)**.
1. Befolgen Sie bei Wahl von **AWS -Service** die Anweisungen in Schritt 6 von [API-Integrationsanfrage über die API Gateway-Konsole einrichten](how-to-method-settings-console.md).
1. Wenn Sie **VPC Link** (VPC-Link) ausgewählt haben, gehen Sie wie folgt vor:
1. Markieren Sie für **VPC proxy integration** (Proxy-Integration verwenden) das Kontrollkästchen, wenn Anforderungen über einen Proxy an Ihren `VPCLink`-Endpunkt gesendet werden sollen.
1. Wählen Sie als **HTTP method** die HTTP-Methode aus, die am ehesten der Methode im HTTP-Backend entspricht.
1. Wählen Sie in der Dropdownliste **VPC link** (VPC-Link) einen VPC-Link aus. Sie können `[Use Stage Variables]` auswählen und **\$1\$1stageVariables.vpcLinkId\$1** in das Textfeld unter der Liste eingeben.
Sie können die `vpcLinkId`-Stufenvariable nach der Bereitstellung der API für eine Stufe definieren und ihren Wert auf die ID des `VpcLink` festlegen.
1. Geben Sie als **Endpunkt-URL** die URL des HTTP-Backends ein, das von dieser Integration verwendet werden soll.
1. Wenn Sie die Standardzeitüberschreitung von 29 Sekunden verwenden möchten, lassen Sie das Kontrollkästchen **Default timeout** (Standardzeitüberschreitung) aktiviert. Wenn Sie einen benutzerdefinierten Zeitüberschreitungswert festlegen möchten, wählen Sie **Default timeout** (Standardzeitüberschreitung) aus und geben Sie einen Zeitüberschreitungswert zwischen `50` und `29000` Millisekunden ein.
1. Wählen Sie **Änderungen speichern ** aus.
1. Führen Sie unter **Request Templates** (Vorlagen anfordern) die folgenden Schritte durch:
1. Um einen **Template selection expression** (Vorlagen-Auswahlausdruck) einzugeben, wählen Sie unter **Request templates** (Vorlagen anfordern) die Option **Edit** (Bearbeiten).
1. Geben Sie einen **Template selection expression** (Vorlagen-Auswahlausdruck) ein. Verwenden Sie einen Ausdruck, nach dem API Gateway in der Nachrichtennutzlast sucht. Wenn er gefunden wird, wird er ausgewertet. Das Ergebnis ist ein Vorlagen-Schlüsselwert zur Auswahl der Datenzuweisungsvorlage, die auf die Daten in der Nachrichtennutzlast anzuwenden ist. Die Datenzuweisungsvorlage erstellen Sie im nächsten Schritt. Wählen Sie **Edit** (Bearbeiten) aus, um Ihre Änderungen zu speichern.
1. Wählen Sie **Create template** (Vorlage erstellen), um die Datenzuweisungsvorlage zu erstellen. Geben Sie für **Template key** (Vorlagenschlüssel) einen Vorlagenschlüsselwert zur Auswahl der Datenzuweisungsvorlage ein, die auf die Daten in der Nachrichtennutzlast anzuwenden ist. Definieren Sie anschließend eine Zuweisungsvorlage. Wählen Sie **Create template (Vorlage erstellen)** aus.
Weitere Informationen zu Vorlagen-Auswahlausdrücken finden Sie unter [Vorlagen-Auswahlausdrücke](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions).
## Richten Sie eine Integrationsanfrage ein, indem Sie AWS CLI
Sie können eine Integrationsanfrage für eine Route in einer WebSocket API einrichten, indem Sie AWS CLI wie im folgenden Beispiel vorgehen, wodurch eine Scheinintegration erstellt wird:
1. Erstellen Sie eine Datei mit dem Namen `integration-params.json` und dem folgenden Inhalt:
```
{"PassthroughBehavior": "WHEN_NO_MATCH", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "RequestTemplates": {"application/json": "{\"statusCode\":200}"}, "IntegrationType": "MOCK"}
```
1. Verwenden Sie den folgenden [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html)-Befehl, um die Mock-Integration zu erstellen.
```
aws apigatewayv2 --region us-east-1 create-integration --api-id aabbccddee --cli-input-json file://integration-params.json
```
Die Ausgabe sieht wie folgt aus:
```
{
"PassthroughBehavior": "WHEN_NO_MATCH",
"TimeoutInMillis": 29000,
"ConnectionType": "INTERNET",
"IntegrationResponseSelectionExpression": "${response.statuscode}",
"RequestTemplates": {
"application/json": "{\"statusCode\":200}"
},
"IntegrationId": "0abcdef",
"IntegrationType": "MOCK"
}
```
Alternativ können Sie eine Integrationsanfrage für eine Proxyintegration einrichten, indem Sie den verwenden AWS CLI.
1. Erstellen Sie eine Lambda-Funktion in der Lambda-Konsole und geben Sie ihr eine grundlegende Lambda-Ausführungsrolle.
1. Verwenden Sie den folgenden [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html)–Befehl, um eine Integration zu erstellen.
```
aws apigatewayv2 create-integration --api-id aabbccddee --integration-type AWS_PROXY --integration-method POST --integration-uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations
```
Die Ausgabe sieht wie folgt aus:
```
{
"PassthroughBehavior": "WHEN_NO_MATCH",
"IntegrationMethod": "POST",
"TimeoutInMillis": 29000,
"ConnectionType": "INTERNET",
"IntegrationUri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations",
"IntegrationId": "abcdefg",
"IntegrationType": "AWS_PROXY"
}
```
## Eingabeformat einer Lambda-Funktion für die Proxyintegration für WebSocket APIs
Bei der Lambda-Proxy-Integration ordnet API Gateway die gesamte Client-Anforderung dem `event`-Eingabeparameter der Backend-Lambda-Funktion zu. Im folgenden Beispiel sehen Sie die Struktur des Eingabeereignisses der `$connect`-Route und des Eingabeereignisses der `$disconnect`-Route, die das API Gateway an eine Lambda-Proxy-Integration sendet.
------
#### [ Input from the \$1connect route ]
```
{
headers: {
Host: 'abcd123.execute-api.us-east-1.amazonaws.com',
'Sec-WebSocket-Extensions': 'permessage-deflate; client_max_window_bits',
'Sec-WebSocket-Key': '...',
'Sec-WebSocket-Version': '13',
'X-Amzn-Trace-Id': '...',
'X-Forwarded-For': '192.0.2.1',
'X-Forwarded-Port': '443',
'X-Forwarded-Proto': 'https'
},
multiValueHeaders: {
Host: [ 'abcd123.execute-api.us-east-1.amazonaws.com' ],
'Sec-WebSocket-Extensions': [ 'permessage-deflate; client_max_window_bits' ],
'Sec-WebSocket-Key': [ '...' ],
'Sec-WebSocket-Version': [ '13' ],
'X-Amzn-Trace-Id': [ '...' ],
'X-Forwarded-For': [ '192.0.2.1' ],
'X-Forwarded-Port': [ '443' ],
'X-Forwarded-Proto': [ 'https' ]
},
requestContext: {
routeKey: '$connect',
eventType: 'CONNECT',
extendedRequestId: 'ABCD1234=',
requestTime: '09/Feb/2024:18:11:43 +0000',
messageDirection: 'IN',
stage: 'prod',
connectedAt: 1707502303419,
requestTimeEpoch: 1707502303420,
identity: { sourceIp: '192.0.2.1' },
requestId: 'ABCD1234=',
domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com',
connectionId: 'AAAA1234=',
apiId: 'abcd1234'
},
isBase64Encoded: false
}
```
------
#### [ Input from the \$1disconnect route ]
```
{
headers: {
Host: 'abcd1234.execute-api.us-east-1.amazonaws.com',
'x-api-key': '',
'X-Forwarded-For': '',
'x-restapi': ''
},
multiValueHeaders: {
Host: [ 'abcd1234.execute-api.us-east-1.amazonaws.com' ],
'x-api-key': [ '' ],
'X-Forwarded-For': [ '' ],
'x-restapi': [ '' ]
},
requestContext: {
routeKey: '$disconnect',
disconnectStatusCode: 1005,
eventType: 'DISCONNECT',
extendedRequestId: 'ABCD1234=',
requestTime: '09/Feb/2024:18:23:28 +0000',
messageDirection: 'IN',
disconnectReason: 'Client-side close frame status not set',
stage: 'prod',
connectedAt: 1707503007396,
requestTimeEpoch: 1707503008941,
identity: { sourceIp: '192.0.2.1' },
requestId: 'ABCD1234=',
domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com',
connectionId: 'AAAA1234=',
apiId: 'abcd1234'
},
isBase64Encoded: false
}
```
------
# Richten Sie eine WebSocket API-Integrationsantwort in API Gateway ein
Der folgende Abschnitt bietet einen kurzen Überblick über Integrationsantworten für WebSocket API und wie eine Integrationsantwort für eine WebSocket API eingerichtet wird.
**Topics**
+ [Übersicht über Integrationsantworten](#apigateway-websocket-api-integration-response-overview)
+ [Integrationsantworten für bidirektionale Kommunikation](#apigateway-websocket-api-integration-response-for-two-way-communication)
+ [Integrationsantwort mit der API Gateway-Konsole einrichten](#apigateway-websocket-api-integration-response-using-console)
+ [Richten Sie eine Integrationsantwort mit dem ein AWS CLI](#apigateway-websocket-api-integration-response-using-awscli)
## Übersicht über Integrationsantworten
Die Integrationsantwort von API Gateway ist eine Möglichkeit, die Antwort von einem Backend-Service zu modellieren und zu manipulieren. Es gibt einige Unterschiede bei der Einrichtung einer REST-API und einer WebSocket API-Integrationsantwort, aber konzeptionell ist das Verhalten dasselbe.
WebSocket Routen können für bidirektionale oder unidirektionale Kommunikation konfiguriert werden.
+ Wenn eine Route für bidirektionale Kommunikation konfiguriert ist, können Sie mit einer Integrationsantwort Transformationen für die zurückgegebene Nachrichtennutzlast konfigurieren, ähnlich wie bei Integrationsantworten für REST. APIs
+ Wenn eine Route für unidirektionale Kommunikation konfiguriert ist, wird unabhängig von der Konfiguration der Integrationsantwort nach der Verarbeitung der Nachricht keine Antwort über den WebSocket Kanal zurückgegeben.
API Gateway übergibt die Backend-Antwort nicht über die Routenantwort, es sei denn, Sie richten eine Routenantwort ein. Weitere Informationen zum Einrichten einer Routenreaktion finden Sie unter [Richten Sie Routenantworten für WebSocket APIs in API Gateway ein](apigateway-websocket-api-route-response.md).
## Integrationsantworten für bidirektionale Kommunikation
Integrationen lassen sich in *Proxy*-Integrationen und *Nicht-Proxy*-Integrationen unterteilen.
**Wichtig**
Bei *Proxy-Integrationen* gibt API Gateway automatisch die Backend-Ausgabe als vollständigen Payload an den Aufrufer weiter. Es gibt keine Integrationsantwort.
Bei *Nicht-Proxy-Integrationen* müssen Sie mindestens eine Integrationsantwort einrichten:
+ Im Idealfall sollte eine Ihrer Integrationsantworten als Catch-all-Methode dienen, wenn keine explizite Wahl vorgenommen werden kann. Dieser Standardfall wird durch Festlegen des Integrationsantwort-Schlüssels dargestell `$default`.
+ In allen anderen Fällen fungiert der Integrationsantwort-Schlüssel als regulärer Ausdruck. Er sollte dem Format folge `"/expression/"`.
Bei Nicht-Proxy-HTTP-Integrationen:
+ API Gateway versucht, den HTTP-Statuscode der Backend-Antwort zuzuordnen. Der Integrationsantwort-Schlüssel fungiert in diesem Fall als regulärer Ausdruck. Wenn keine Übereinstimmung gefunden wird, dann wird `$default` als Integrationsantwort gewählt.
+ Der Vorlagen-Auswahlausdruck funktioniert wie oben beschrieben identisch. Zum Beispiel:
+ `/2\d\d/`: Erfolgreiche Antworten empfangen und transformieren
+ `/4\d\d/`: Fehler (ungültige Anforderung) empfangen und transformieren
+ `$default`: Alle unerwarteten Antworten empfangen und transformieren
Weitere Informationen zu Vorlagen-Auswahlausdrücken finden Sie unter [Vorlagen-Auswahlausdrücke](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions).
## Integrationsantwort mit der API Gateway-Konsole einrichten
So richten Sie mithilfe der API-Gateway-Konsole eine Antwort zur Routenintegration für eine WebSocket API ein:
1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway).
1. Wählen Sie Ihre WebSocket API und wählen Sie Ihre Route.
1. Wählen Sie die Registerkarte **Integration request** (Integrationsanforderung) und dann im Abschnitt **Integration request settings** (Einstellungen für Integrationsanforderungen) die Option **Create integration response** (Integrationsantwort erstellen) aus.
1. Geben Sie für **Antwortschlüssel** einen Wert ein, der nach Auswertung des Ausdrucks der Antwortauswahl im Antwortschlüssel der ausgehenden Nachricht zu finden ist. Sie können beispielsweise **/4\$1d\$1d/** eingeben, um Anforderungsfehler zu empfangen und umzuwandeln, oder Sie können **\$1default** eingeben, um alle Antworten zu empfangen und umzuwandeln, die dem Ausdruck für die Vorlagenauswahl entsprechen.
1. Geben Sie unter **Template selection expression** (Ausdruck für die Vorlagenauswahl) einen Auswahlausdruck ein, um die ausgehende Nachricht auszuwerten.
1. Wählen Sie **Create response** (Antwort erstellen) aus.
1. Sie können auch eine Zuordnungsvorlage definieren, um Transformationen Ihrer Payload für zurückgegebene Nachrichten zu konfigurieren. Wählen Sie **Create template (Vorlage erstellen)** aus.
1. Geben Sie einen Schlüsselnamen ein. Wenn Sie den Standardausdruck für die Vorlagenauswahl auswählen, geben Sie **\$1\$1default** ein.
1. Geben Sie unter **Response template** (Antwortvorlage) Ihre Zuordnungsvorlage in den Code-Editor ein.
1. Wählen Sie **Create template (Vorlage erstellen)** aus.
1. Wählen Sie **Deploy API** (API bereitstellen) aus, um Ihre API bereitzustellen.
Stellen Sie mit dem folgenden [wscat](https://www.npmjs.com/package/wscat)-Befehl eine Verbindung mit Ihrer API her. Mehr über `wscat` erfahren Sie unter [Wird verwendet`wscat`, um eine Verbindung zu einer WebSocket API herzustellen und Nachrichten an diese zu senden](apigateway-how-to-call-websocket-api-wscat.md).
```
wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test
```
Wenn Sie Ihre Route aufrufen, sollte die Payload der zurückgegebenen Nachricht zurückgegeben werden.
## Richten Sie eine Integrationsantwort mit dem ein AWS CLI
Der folgende [create-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration-response.html)Befehl erstellt eine `$default` Integrationsantwort:
```
aws apigatewayv2 create-integration-response \
--api-id vaz7da96z6 \
--integration-id a1b2c3 \
--integration-response-key '$default'
```
# Validierung für WebSocket APIs im API Gateway anfordern
Sie können API Gateway so konfigurieren, dass die Validierung einer Routenanforderung durchgeführt wird, bevor Sie mit der Integrationsanforderung fortfahren. Wenn die Validierung fehlschlägt, schlägt API Gateway die Anfrage fehl, ohne Ihr Backend aufzurufen, sendet eine Gateway-Antwort „Bad Request Body“ an den Client und veröffentlicht die Validierungsergebnisse in CloudWatch Logs. Die Verwendung der Validierung auf diese Weise reduziert unnötige Aufrufe an Ihr API-Backend.
## Modell-Auswahlausdrücke
Sie können einen Modell-Auswahlausdruck verwenden, um Anforderungen innerhalb derselben Route dynamisch zu validieren. Die Modellvalidierung erfolgt, wenn Sie einen Modell-Auswahlausdruck für Proxy- oder Nicht-Proxy-Integrationen bereitstellen. Möglicherweise müssen Sie das `$default`-Modell als Fallback definieren, wenn kein passendes Modell gefunden wird. Wenn kein übereinstimmendes Modell vorhanden ist und `$default` nicht definiert ist, schlägt die Validierung fehl. Der Auswahlausdruck ähnelt `Route.ModelSelectionExpression` und wertet den Schlüssel für `Route.RequestModels` aus.
Wenn Sie eine Route für eine WebSocket API definieren, können Sie optional einen *Modellauswahlausdruck* angeben. Dieser Ausdruck wird zur Auswahl des Modells ausgewertet, das bei Eingang einer Anforderung für die Textvalidierung verwendet werden soll. Der Ausdruck wird auf einen der Einträge in den einer Route ausgewertet [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels).
Ein Modell wird als [JSON-Schema](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) ausgedrückt und beschreibt die Datenstruktur des Anforderungstextes. Die Beschaffenheit dieses Auswahlausdrucks ermöglicht Ihnen, dynamisch das Modell auszuwählen, über das zur Laufzeit für eine bestimmte Route validiert werden soll. Weitere Informationen, wie Sie ein Modell erstellen können, finden Sie unter [Datenmodelle für REST APIs](models-mappings-models.md).
## Einrichten der grundlegenden Anforderungsvalidierung über die API-Gateway-Konsole
Im folgenden Beispiel wird gezeigt, wie Sie die Anforderungsvalidierung auf einer Route einrichten.
Zuerst erstellen Sie ein Modell und dann eine Route. Als Nächstes konfigurieren Sie die Anforderungsvalidierung für die Route, die Sie gerade erstellt haben. Abschließend stellen Sie Ihre API bereit und testen sie. Um dieses Tutorial abzuschließen, benötigen Sie eine WebSocket API `$request.body.action` als Routenauswahlausdruck und einen Integrationsendpunkt für Ihre neue Route.
Sie benötigen außerdem `wscat`, um eine Verbindung zu Ihrer API herzustellen. Weitere Informationen finden Sie unter [Wird verwendet`wscat`, um eine Verbindung zu einer WebSocket API herzustellen und Nachrichten an diese zu senden](apigateway-how-to-call-websocket-api-wscat.md).
**So erstellen Sie ein Modell**
1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway).
1. Wählen Sie eine API aus. WebSocket
1. Klicken Sie im Navigationsbereich auf **Models** (Modelle).
1. Wählen Sie **Modell erstellen** aus.
1. Geben Sie unter **Name** **emailModel** ein.
1. Geben Sie für **Content type** (Inhaltstyp) **application/json** ein.
1. Geben Sie für **Modellschema** Folgendes ein:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type" : "object",
"required" : [ "address"],
"properties" : {
"address": {
"type": "string"
}
}
}
```
Für dieses Modell muss die Anfrage eine E-Mail-Adresse enthalten.
1. Wählen Sie **Speichern**.
In diesem Schritt erstellen Sie eine Route für Ihre WebSocket API.
**So erstellen Sie eine Route**
1. Klicken Sie im Hauptnavigationsbereich auf **Routen**.
1. Wählen Sie **Create route (Route erstellen)** aus.
1. Geben Sie in **Route key** (Routenschlüssel) **sendMessage** ein.
1. Wählen Sie einen Integrationstyp und geben Sie einen Integrationsendpunkt an. Weitere Informationen finden Sie unter [Integrationen für das WebSocket APIs API Gateway](apigateway-websocket-api-integrations.md).
1. Wählen Sie **Create route (Route erstellen)** aus.
In diesem Schritt richten Sie die Anforderungsvalidierung für die `sendMessage`-Route ein.
**Einrichten der Anforderungsvalidierung**
1. Klicken Sie auf der Registerkarte **Routenanforderung** unter **Routenanforderungseinstellungen** auf **Bearbeiten**.
1. Geben Sie unter **Modellauswahlausdruck** **\$1\$1request.body.messageType\$1** ein.
API Gateway verwendet die `messageType`-Eigenschaft zur Validierung der eingehenden Anforderung.
1. Klicken Sie auf **Anforderungsmodell hinzufügen**.
1. Geben Sie für **Modellschlüssel** **email** ein.
1. Wählen Sie unter **Modell** die Option **emailModel** aus.
API Gateway validiert eingehende Nachrichten mithilfe der `messageType`-Eigenschaft, die anhand dieses Modells auf `email` gesetzt ist.
**Anmerkung**
Wenn API Gateway den Modellauswahlausdruck nicht mit einem Modellschlüssel abgleichen kann, wird das `$default`-Modell ausgewählt. Wenn kein `$default`-Modell vorhanden ist, schlägt die Validierung fehl. Für die Produktion empfehlen wir APIs, dass Sie ein `$default` Modell erstellen.
1. Wählen Sie **Änderungen speichern ** aus.
In diesem Schritt stellen Sie Ihre API bereit und testen sie.
**Bereitstellen und testen Ihrer API**
1. Klicken Sie auf **Deploy API**.
1. Wählen Sie die gewünschte Stufe aus der Dropdown-Liste aus oder geben Sie den Namen einer neuen Stufe ein.
1. Wählen Sie **Bereitstellen**.
1. Klicken Sie im Hauptnavigationsbereich auf **Stufen**.
1. Kopieren Sie die WebSocket URL Ihrer API. Die URL sollte wie `wss://abcdef123.execute-api.us-east-2.amazonaws.com/production` aussehen.
1. Öffnen Sie ein neues Terminal. Führen Sie den Befehl **wscat** mit den folgenden Parametern aus.
```
wscat -c wss://abcdef123.execute-api.us-west-2.amazonaws.com/production
```
```
Connected (press CTRL+C to quit)
```
1. Testen Sie Ihre API mit dem folgenden Befehl.
```
{"action": "sendMessage", "messageType": "email"}
```
```
{"message": "Invalid request body", "connectionId":"ABCD1=234", "requestId":"EFGH="}
```
Die Anforderung schlägt in API Gateway fehl.
Verwenden Sie den folgenden Befehl, um eine gültige Anforderung an Ihre API zu senden.
```
{"action": "sendMessage", "messageType": "email", "address": "mary_major@example.com"}
```
# Datentransformationen für WebSocket APIs im API Gateway
In API Gateway kann die Methodenanforderung einer WebSocket API eine Nutzlast in einem anderen Format als die entsprechende Nutzlast der Integrationsanfrage annehmen, wie es im Backend erforderlich ist. Das Backend wiederum kann eine Integrationsantwortnutzlast zurückgeben, die nicht der Methodenantwortnutzlast entspricht, die das Frontend erwartet.
In Amazon API Gateway können Sie Zuweisungsvorlagen verwenden, um die Nutzdaten einer Methodenanforderung der entsprechenden Integrationsanforderung zuzuordnen bzw. die Nutzdaten einer Integrationsanforderung der entsprechenden Methodenantwort zuzuordnen. Sie erstellen eine Zuweisungsvorlage und geben einen Vorlagen-Auswahlausdruck an, um zu bestimmen, welche Vorlage für die erforderlichen Datentransformationen verwendet werden soll.
Sie können Datenzuordnungen verwenden, um Daten aus einer [Routenanforderung](api-gateway-basic-concept.md#apigateway-definition-route-request) einer Backend-Integration zuzuordnen. Weitere Informationen hierzu finden Sie unter [Datenzuordnung für WebSocket APIs in API Gateway einrichten](websocket-api-data-mapping.md).
## Zuweisungsvorlagen und Modelle
[Eine *Mapping-Vorlage* ist ein in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) ausgedrücktes Skript, das mithilfe von Ausdrücken auf die Nutzlast angewendet wird. JSONPath ](https://goessner.net/articles/JsonPath/) Weitere Informationen über API Gateway-Zuordnungsvorlagen finden Sie unter [Zuordnen von Vorlagentransformationen für REST APIs in API Gateway](models-mappings.md).
Die Nutzlast kann ein dem [JSON-Schema Entwurf 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) entsprechendes *Datenmodell* umfassen. Sie müssen kein Modell definieren, um eine Zuweisungsvorlage zu erstellen. Ein Modell kann Ihnen jedoch bei der Erstellung einer Vorlage helfen, da API Gateway einen Vorlagenentwurf auf der Grundlage eines bereitgestellten Modells generiert. Weitere Informationen über API Gateway-Modelle finden Sie unter [Datenmodelle für REST APIs](models-mappings-models.md).
## Vorlagen-Auswahlausdrücke
[Um eine Payload mit einer Mapping-Vorlage zu transformieren, geben Sie in einer [Integrationsanfrage oder Integrationsantwort](apigateway-websocket-api-integration-requests.md) einen Ausdruck für die WebSocket API-Vorlagenauswahl an.](apigateway-websocket-api-integration-responses.md) Durch Auswerten dieses Ausdrucks wird die Eingabe- oder Ausgabevorlage (falls vorhanden) bestimmt, die zum Transformieren des Anforderungstexts in den Integrationsanforderungstext (über eine Eingabevorlage) oder des Integrationsantworttext in den Routenantworttext (über eine Ausgabevorlage) verwendet werden soll.
`Integration.TemplateSelectionExpression` unterstützt `${request.body.jsonPath}` und statische Werte.
`IntegrationResponse.TemplateSelectionExpression` unterstützt `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}` und statische Werte.
## Integrationsantwort-Auswahlausdrücke
Wenn Sie [eine Integrationsantwort für eine WebSocket API einrichten](apigateway-websocket-api-integration-responses.md), können Sie optional einen Auswahlausdruck für eine Integrationsantwort angeben. Dieser Ausdruck bestimmt, welche `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)` ausgewählt werden sollte, wenn eine Integration zurückgegeben wird. Der Wert dieses Ausdrucks wird zurzeit durch API Gateway eingeschränkt, wie nachfolgend definiert. Beachten Sie, dass dieser Ausdruck nur für *Nicht-Proxy-Integrationen* relevant ist. Eine Proxy-Integration übergibt die Antwortnutzlast einfach ohne Modellierung oder Modifikation an die aufrufende Methode zurück.
Im Gegensatz zu den anderen vorhergehenden Auswahlausdrücken unterstützt dieser Ausdruck derzeit ein *Musterabgleich*-Format. Der Ausdruck sollte in Schrägstriche verpackt werden.
Derzeit ist der Wert je nach fixier `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)`:
+ Für Lambda-basierte Integrationen lautet er `$integration.response.body.errorMessage`.
+ Für `HTTP`- und `MOCK`-Integrationen ist dies `$integration.response.statuscode`.
+ Für `HTTP_PROXY` und `AWS_PROXY` wird der Ausdruck nicht verwendet, da Sie anfordern, dass die Nutzlast über die aufrufende Methode übergeben wird.
# Datenzuordnung für WebSocket APIs in API Gateway einrichten
Mit der *Datenzuordnung* können Sie Daten aus einer [Routenanforderung](api-gateway-basic-concept.md#apigateway-definition-route-request) einer Backend-Integration zuordnen.
**Anmerkung**
Die Datenzuordnung für wird in der WebSocket APIs nicht unterstützt AWS-Managementkonsole. Sie müssen das AWS CLI, oder ein SDK verwenden AWS CloudFormation, um die Datenzuordnung zu konfigurieren.
**Topics**
+ [Zuordnen von Routenanforderungsdaten zu Integrationsanforderungsparametern](#websocket-mapping-request-parameters)
+ [Beispiele](#websocket-data-mapping-examples)
## Zuordnen von Routenanforderungsdaten zu Integrationsanforderungsparametern
Integrationsanforderungsparameter können aus beliebigen definierten Routenanforderungsparametern, dem Anforderungstext [`context` oder ](api-gateway-mapping-template-reference.md#context-variable-reference) [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference)-Variablen und statischen Werten zugeordnet werden.
In der folgenden Tabelle sehen Sie Datenzuordnungsausdrücke für Integrationsanfragen. In der Tabelle ist *`PARAM_NAME`* der Name eines Routenanforderungsparameters des angegebenen Parametertyps. Es muss mit dem regulären Ausdruck übereinstimmen`'^[a-zA-Z0-9._$-]+$]'`. *JSONPath\$1EXPRESSION*ist ein JSONPath Ausdruck für ein JSON-Feld des Hauptteils der Anfrage.
| Zugewiesene Datenquelle | Mapping-Ausdruck |
| --- | --- |
| Anforderungsabfragezeichenfolge (wird nur für die \$1connect-Route unterstützt) | route.request.querystring.PARAM\$1NAME |
| Anforderungs-Header (wird nur für die \$1connect-Route unterstützt) | route.request.header.PARAM\$1NAME |
| Abfragezeichenfolge mit mehreren Werten (nur für die \$1connect-Route unterstützt) | route.request.multivaluequerystring.PARAM\$1NAME |
| Anforderungsheader mit mehreren Werten (nur für die \$1connect-Route unterstützt) | route.request.multivalueheader.PARAM\$1NAME |
| Anforderungstext | route.request.body.JSONPath\$1EXPRESSION |
| Stufenvariablen | stageVariables.VARIABLE\$1NAME |
| Kontextvariablen | context.VARIABLE\$1NAME, wobei die Variable zu den [unterstützten Kontextvariablen](api-gateway-mapping-template-reference.md#context-variable-reference) gehören muss. |
| Statischer Wert | 'STATIC\$1VALUE'. Das STATIC\$1VALUE ist ein Zeichenkettenliteral und muss in einfache Anführungszeichen eingeschlossen werden. |
Achten Sie beim Erstellen einer Datenzuordnung auf das AWS CLI richtige Format für die Verwendung von Literalen mit Zeichenfolgen in. AWS CLI Weitere Informationen finden Sie unter [Verwenden von Zeichenfolgen mit Anführungszeichen in der AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) im *Benutzerhandbuch zur AWS Command Line Interface *.
## Beispiele
In den folgenden AWS CLI Beispielen werden Datenzuordnungen konfiguriert. Eine CloudFormation Beispielvorlage finden Sie unter. [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip)
### Zuordnen der ConnectionID eines Clients zu einem Header in einer Integrationsanforderung
Der folgende [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html)-Befehl weist die `connectionId` eines Clients dem `connectionId`-Header in der Anfrage an eine Backend-Integration zu:
```
aws apigatewayv2 update-integration \
--integration-id abc123 \
--api-id a1b2c3d4 \
--request-parameters 'integration.request.header.connectionId'='context.connectionId'
```
### Zuordnen eines Abfragezeichenfolgenparameters zu einem Header in einer Integrationsanforderung
Das folgende Beispiel weist einen `authToken`-Abfragezeichenfolgenparameter dem `authToken`-Header in der Integrationsanforderung zu.
1. Verwenden Sie den folgenden [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html)-Befehl, um den `authToken`-Abfragezeichenfolgenparameter zu den Anforderungsparametern der Route hinzuzufügen.
```
aws apigatewayv2 update-route --route-id 0abcdef \
--api-id a1b2c3d4 \
--request-parameters '{"route.request.querystring.authToken": {"Required": false}}'
```
1. Verwenden Sie den folgenden [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html)-Befehl, um den Abfragezeichenfolgenparameter dem `authToken`-Header in der Anfrage an die Backend-Integration zuzuweisen.
```
aws apigatewayv2 update-integration \
--integration-id abc123 \
--api-id a1b2c3d4 \
--request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken'
```
1. (Optional) Gehen Sie bei Bedarf wie folgt vor, [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html)um den `authToken` Abfragezeichenfolgenparameter aus den Anforderungsparametern der Route zu löschen.
```
aws apigatewayv2 delete-route-request-parameter \
--route-id 0abcdef \
--api-id a1b2c3d4 \
--request-parameter-key 'route.request.querystring.authToken'
```
# WebSocket Referenz zur API-Zuordnungsvorlage für API Gateway
In diesem Abschnitt werden die Variablen zusammengefasst, die derzeit WebSocket APIs in API Gateway unterstützt werden.
| Parameter | Beschreibung |
| --- | --- |
| \$1context.connectionId | Eine eindeutige ID für die Verbindung, die für einen Rückruf an den Client verwendet werden kann. |
| \$1context.connectedAt | Die [Epoch](https://en.wikipedia.org/wiki/Unix_time)-formatierte Verbindungszeit. |
| \$1context.domainName | Ein Domainname für die WebSocket API. Dies kann für einen Rückruf an den Client (anstelle eines hardcodierten Wertes) verwendet werden. |
| \$1context.eventType | Der Ereignistyp: `CONNECT`, `MESSAGE` oder `DISCONNECT`. |
| \$1context.messageId | Eine eindeutige serverseitige ID für eine Nachricht. Nur verfügbar, wenn der `$context.eventType` `MESSAGE` ist. |
| \$1context.routeKey | Der ausgewählte Routenschlüssel. |
| \$1context.requestId | Entspricht `$context.extendedRequestId`. |
| \$1context.extendedRequestId | Eine automatisch generierte ID für den API-Aufruf, die weitere nützliche Informationen für das Debugging/die Fehlerbehebung enthält. |
| \$1context.apiId | Die ID, die API Gateway Ihrer API zuweist. |
| \$1context.authorizer.principalId | Die ID des Prinzipalbenutzer, die dem vom Client gesendeten und von einer Lambda-Funktion eines API Gateway-Lambda-Genehmigers (früher "benutzerdefinierter Genehmiger") zurückgegebenen Token zugeordnet ist. |
| \$1context.authorizer.property | Der in einer Zeichenfolge umgewandelte Wert des angegebenen Schlüssel-Wert-Paares der `context`-Zuordnung, der von einer API Gateway Lambda-Genehmigerfunktion zurückgegeben wird. Angenommen, der Genehmiger gibt folgende `context`-Zuweisung zurück: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} Dann gibt der Aufruf von `$context.authorizer.key` die Zeichenfolge `"value"` zurück, der Aufruf von `$context.authorizer.numKey` gibt die Zeichenfolge `"1"` zurück und der Aufruf von `$context.authorizer.boolKey` gibt den Wert `"true"` zurück. |
| \$1context.error.messageString | Die Wert von \$1context.error.message in Anführungszeichen, d. h. "\$1context.error.message". |
| \$1context.error.validationErrorString | Eine Zeichenfolge mit einer detaillierten Validierungs-Fehlermeldung. |
| \$1context.identity.accountId | Die der Anfrage zugeordnete AWS Konto-ID. |
| \$1context.identity.apiKey | Der API-Besitzerschlüssel, der der schlüsselfähigen API-Anforderung zugewiesen ist. |
| \$1context.identity.apiKeyId | Die API-Schlüssel-ID, die der schlüsselfähigen API-Anforderung zugewiesen ist |
| \$1context.identity.caller | Die Prinzipal-ID des Aufrufers, von dem die Anforderung stammt. |
| \$1context.identity.cognitoAuthenticationProvider | Eine durch Komma getrennte Liste aller Amazon-Cognito-Authentifizierungsanbieter, die vom anfordernden Aufrufer verwendet werden. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. Zum Beispiel für eine Identität aus einem Amazon Cognito-Benutzerpool, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Weitere Informationen zu verfügbaren Amazon-Cognito-Authentifizierungsanbietern finden Sie unter [Verbundidentitäten verwenden](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) im *Amazon-Cognito-Entwicklerhandbuch*. |
| \$1context.identity.cognitoAuthenticationType | Der Amazon Cognito-Authentifizierungstyp des Aufrufers, der den Anfrage erstellt hat. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. Mögliche Werte sind `authenticated` für authentifizierte Identitäten und `unauthenticated` für nicht authentifizierte Identitäten. |
| \$1context.identity.cognitoIdentityId | Die Amazon Cognito Identitäts-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. |
| \$1context.identity.cognitoIdentityPoolId | Die Amazon Cognito Identitätspool-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. |
| \$1context.identity.sourceIp | Die Quell-IP-Adresse der TCP-Verbindung, von der die Anforderung an API Gateway gesendet wird. |
| \$1context.identity.user | Die Prinzipal-ID des Benutzers, von dem die Anforderung stammt. |
| \$1context.identity.userAgent | Der Benutzeragent des API-Aufrufers. |
| \$1context.identity.userArn | Der ARN (Amazon Resource Name) des tatsächlichen Benutzers nach der Authentifizierung. |
| \$1context.requestTime | Die Anforderungszeit im [CLF](https://httpd.apache.org/docs/current/logs.html#common)-Format (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | Die Anforderungszeit im [Epoch](https://en.wikipedia.org/wiki/Unix_time)-Format in Millisekunden. |
| \$1context.stage | Die Bereitstellungsstufe des API-Aufrufs (z. B. "Beta" oder "Prod"). |
| \$1context.status | Der Antwortstatus. |
| \$1input.body | Gibt die Raw-Nutzlast als Zeichenfolge zurück. |
| \$1input.json(x) | Diese Funktion wertet einen JSONPath Ausdruck aus und gibt die Ergebnisse als JSON-Zeichenfolge zurück. Beispielsweise gibt `$input.json('$.pets')` eine JSON-Zeichenfolge zurück, die die "Pets"-Struktur abbildet. Weitere Informationen zu JSONPath, finden Sie unter [JSONPath](https://goessner.net/articles/JsonPath/)oder [JSONPath für Java](https://github.com/json-path/JsonPath). |
| \$1input.path(x) | Nimmt einen JSONPath Ausdruck string (`x`) und gibt eine JSON-Objektdarstellung des Ergebnisses zurück. Dies ermöglicht einen nativen Zugriff auf Elemente der Nutzlast in [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) und deren Bearbeitung. Beispiel: Der Ausdruck `$input.path('$.pets')` könnte das folgende Objekt zurückgeben: [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').count()` gibt `"3"` zurück. Weitere Informationen zu JSONPath Java finden Sie unter [JSONPath](http://goessner.net/articles/JsonPath/)oder [JSONPath für Java](https://github.com/jayway/JsonPath). |
| \$1stageVariables. | **steht für einen Stufenvariablennamen. |
| \$1stageVariables[''] | **steht für einen beliebigen Stufenvariablennamen. |
| \$1\$1stageVariables['']\$1 | **steht für einen beliebigen Stufenvariablennamen. |
| \$1util.escapeJavaScript() | Escapiert die Zeichen in einer Zeichenfolge mithilfe von JavaScript Zeichenfolgenregeln. Mit dieser Funktion werden alle einfachen Anführungszeichen (`'`) durch Escape-Zeichen (`\'`) geschützt. Allerdings sind diese durch Escape-Zeichen geschützten einfachen Anführungszeichen in JSON nicht zulässig. Sofern die Ausgabe dieser Funktion in einer JSON-Eigenschaft verwendet werden soll, müssen alle einfachen Anführungszeichen, die durch Escape-Zeichen geschützt sind (`\'`), wieder in reguläre einfache Anführungszeichen (`'`) geändert werden. Das wird im folgenden Beispiel veranschaulicht: $util.escapeJavaScript(data).replaceAll("\\'","'") |
| \$1util.parseJson() | Erhält das "stringify"-JSON-Objekt und gibt eine Objektdarstellung des Ergebnisses zurück. Mit dem Ergebnis dieser Funktion können Sie Elemente der Nutzlast, die in Apache Velocity Template Language (VTL) sind, aufrufen und bearbeiten. Angenommen, Sie haben folgende Nutzlast: {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} Und verwenden die folgende Mapping-Vorlage: #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Dann erhalten Sie die folgende Ausgabe: {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | Konvertiert eine Zeichenfolge in das Format „application/x-www-form-urlencoded“. |
| \$1util.urlDecode() | Dekodiert eine Zeichenfolge „application/x-www-form-urlencoded“. |
| \$1util.base64Encode() | Codiert die Daten in eine base64-verschlüsselte Zeichenfolge. |
| \$1util.base64Decode() | Decodiert die Daten einer base64-verschlüsselten Zeichenfolge. |
# Binäre Medientypen für WebSocket-APIs in API Gateway
API Gateway-WebSocket-APIs unterstützen derzeit keine binären Frames in Payloads von eingehenden Nachrichten. Wenn eine Client-Anwendung einen Binär-Frame sendet, weist API Gateway diesen zurück und trennt die Verbindung zum Client mit dem Code 1003.
Es gibt eine Problemumgehung für dieses Verhalten. Wenn der Client textcodierte binäre Daten (z. B. base64) als Text-Frame sendet, können Sie für die `contentHandlingStrategy`-Eigenschaft der Integration `CONVERT_TO_BINARY` festlegen, um die Nutzlast von einer base64-codierten Zeichenfolge in eine binäre Zeichenfolge zu konvertieren.
Damit für eine binäre Nutzlast in Nicht-Proxy-Integrationen eine Routenantwort zurückgegeben wird, können Sie für die `contentHandlingStrategy`-Eigenschaft der Integrationsantwort `CONVERT_TO_TEXT` festlegen, um die Nutzlast von einer binären in eine base64-codierte Zeichenfolge zu konvertieren.
# Aufrufen WebSocket APIs
Nachdem Sie Ihre WebSocket API bereitgestellt haben, können Client-Anwendungen eine Verbindung zu ihr herstellen und Nachrichten an sie senden — und Ihr Back-End-Dienst kann Nachrichten an verbundene Client-Anwendungen senden:
+ Sie können `wscat` damit eine Verbindung zu Ihrer WebSocket API herstellen und Nachrichten an sie senden, um das Verhalten von Clients zu simulieren. Siehe [Wird verwendet`wscat`, um eine Verbindung zu einer WebSocket API herzustellen und Nachrichten an diese zu senden](apigateway-how-to-call-websocket-api-wscat.md).
+ Sie können die @connections-API aus Ihrem Backend-Service verwenden, um eine Rückrufnachricht an einen verbundenen Client zu senden, Verbindungsinformationen anzufordern oder die Clientverbindung zu trennen. Siehe [Verwenden der `@connections`-Befehle in Ihrem Backend-Service](apigateway-how-to-call-websocket-api-connections.md).
+ Eine Client-Anwendung kann ihre eigene WebSocket Bibliothek verwenden, um Ihre WebSocket API aufzurufen.
# Wird verwendet`wscat`, um eine Verbindung zu einer WebSocket API herzustellen und Nachrichten an diese zu senden
Das `[wscat](https://www.npmjs.com/package/wscat)` Hilfsprogramm ist ein praktisches Tool zum Testen einer WebSocket API, die Sie in API Gateway erstellt und bereitgestellt haben. Sie können `wscat` wie folgt installieren und verwenden:
1. `wscat`Von [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat) herunterladen.
1. Installieren Sie `wscat` mit dem folgenden Befehl:
```
npm install -g wscat
```
1. Um eine Verbindung mit Ihrer API herzustellen, führen Sie wie im folgenden Beispiel gezeigt den Befehl `wscat` aus. Beachten Sie, dass in diesem Beispiel davon ausgegangen wird, dass die `Authorization`-Einstellung `NONE` lautet.
```
wscat -c wss://aabbccddee.execute-api.us-east-1.amazonaws.com/test/
```
Sie müssen `aabbccddee` durch die tatsächliche API-ID ersetzen, die in der API-Gateway-Konsole angezeigt oder vom AWS CLI -Befehl [https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) zurückgegeben wird.
Wenn sich Ihre API in einer anderen Region als `us-east-1` befindet, müssen Sie diese außerdem durch die korrekte Region ersetzen.
1. Zum Testen Ihrer API geben Sie eine Nachricht ähnlich der folgenden ein, während Sie noch verbunden sind:
```
{"{jsonpath-expression}":"{route-key}"}
```
wo *\$1jsonpath-expression\$1* ist ein JSONPath Ausdruck und *\$1route-key\$1* ein Routenschlüssel für die API. Beispiel:
```
{"action":"action1"}
{"message":"test response body"}
```
Weitere Informationen zu JSONPath, finden Sie unter [JSONPath](https://goessner.net/articles/JsonPath/)oder [JSONPath für Java](https://github.com/json-path/JsonPath).
1. Um die Verbindung mit der API zu trennen, geben Sie ei `ctrl-C`.
# Verwenden der `@connections`-Befehle in Ihrem Backend-Service
Ihr Back-End-Dienst kann die folgenden WebSocket HTTP-Verbindungsanfragen verwenden, um eine Rückrufnachricht an einen verbundenen Client zu senden, Verbindungsinformationen abzurufen oder die Verbindung zum Client zu trennen.
**Wichtig**
Da für diese Anfragen die [IAM-Autorisierung](apigateway-websocket-control-access-iam.md) erforderlich ist, müssen Sie sich mit [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html) anmelden. Dazu können Sie die API Gateway-Verwaltungs-API verwenden. Weitere Informationen finden Sie unter [ApiGatewayManagementApi](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigatewaymanagementapi.html).
Im folgenden Befehl müssen Sie ihn durch die tatsächliche API-ID `{api-id}` ersetzen, die in der API Gateway Gateway-Konsole angezeigt oder vom Befehl AWS CLI [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) zurückgegeben wird. Die Verbindung muss hergestellt werden, bevor Sie diesen Befehl ausführen können.
Um eine Rückrufnachricht zum Client zu senden, verwenden Sie Folgendes:
```
POST https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Sie können diese Anforderung mithilfe von `[Postman](https://www.postman.com/)` oder durch Aufruf von `[awscurl](https://github.com/okigan/awscurl)` wie im folgenden Beispiel testen:
```
awscurl --service execute-api -X POST -d "hello world" https://{prefix}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Sie müssen den Befehl wie im folgenden Beispiel URL-codieren:
```
awscurl --service execute-api -X POST -d "hello world" https://aabbccddee.execute-api.us-east-1.amazonaws.com/prod/%40connections/R0oXAdfD0kwCH6w%3D
```
Zum Abrufen des neuesten Verbindungsstatus des Clients verwenden Sie:
```
GET https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Zum Trennen der Verbindung mit dem Client verwenden Sie:
```
DELETE https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Sie können mittels der `$context`-Variablen in Ihrer Integration eine Rückruf-URL dynamisch erstellen. Wenn Sie zum Beispiel die Lambda-Proxy-Integration mit einer `Node.js`-Lambda-Funktion verwenden, können Sie die URL wie folgt aufbauen und eine Nachricht an einen verbundenen Client senden:
```
import {
ApiGatewayManagementApiClient,
PostToConnectionCommand,
} from "@aws-sdk/client-apigatewaymanagementapi";
export const handler = async (event) => {
const domain = event.requestContext.domainName;
const stage = event.requestContext.stage;
const connectionId = event.requestContext.connectionId;
const callbackUrl = `https://${domain}/${stage}`;
const client = new ApiGatewayManagementApiClient({ endpoint: callbackUrl });
const requestParams = {
ConnectionId: connectionId,
Data: "Hello!",
};
const command = new PostToConnectionCommand(requestParams);
try {
await client.send(command);
} catch (error) {
console.log(error);
}
return {
statusCode: 200,
};
};
```
Wenn Sie einen benutzerdefinierten Domainnamen für Ihre WebSocket API verwenden, entfernen Sie die `stage` Variable aus Ihrem Funktionscode.
Wenn Sie eine Rückrufnachricht senden, muss Ihre Lambda-Funktion über die Berechtigung verfügen, die API-Gateway-Management-API aufzurufen. Möglicherweise erhalten Sie eine Fehlermeldung mit dem Inhalt `GoneException`, wenn Sie eine Nachricht veröffentlichen, bevor die Verbindung hergestellt wurde oder nachdem der Client die Verbindung getrennt hat.
# WebSocket-APIs für Kundenaufrufe veröffentlichen
Das einfache Erstellen und Entwickeln einer API Gateway-API macht sie nicht automatisch für Ihre Benutzer aufrufbar. Um sie aufrufbar zu machen, müssen Sie Ihre API in einer Stufe bereitstellen. Darüber hinaus können Sie die URL anpassen, die Ihre Benutzer für den Zugriff auf Ihre API verwenden. Sie können ihr eine Domäne zuweisen, die mit Ihrer Marke übereinstimmt oder einprägsamer ist als die Standard-URL für Ihre API.
In diesem Abschnitt erfahren Sie, wie Sie Ihre API bereitstellen und die URL anpassen, die Sie Benutzern für den Zugriff zur Verfügung stellen.
**Anmerkung**
Um die Sicherheit Ihrer API-Gateway-APIs zu erhöhen, ist die `execute-api.{region}.amazonaws.com`-Domain in der [Public Suffix List (PSL](https://publicsuffix.org/)) registriert. Aus Sicherheitsgründen empfehlen wir Ihnen, Cookies mit einem `__Host-`-Präfix zu verwenden, falls Sie jemals sensible Cookies im Standard-Domain-Namen für Ihre API-Gateway-APIs einrichten müssen. Diese Vorgehensweise hilft Ihnen dabei, Ihre Domain vor CSRF-Versuchen (Cross-Site Request Forgery Attempts, Anforderungsfälschung zwischen Websites) zu schützen. Weitere Informationen finden Sie auf der [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes)-Seite im Mozilla Developer Network.
**Topics**
+ [Stufen für WebSocket APIs im API Gateway erstellen](websocket-api-stages.md)
+ [WebSocket APIs In API Gateway bereitstellen](apigateway-set-up-websocket-deployment.md)
+ [Sicherheitsrichtlinie für WebSocket APIs in API Gateway](websocket-api-ciphers.md)
+ [Benutzerdefinierte Domainnamen für WebSocket-APIs in API Gateway](websocket-api-custom-domain-names.md)
# Stufen für WebSocket APIs im API Gateway erstellen
Eine API-Stufe ist ein logischer Verweis auf einen Lebenszyklusstatus Ihrer API (z. B. `dev`, `prod`, `beta` oder `v2`). API-Stufen werden durch ihre API-ID und den Stufennamen identifiziert und sind in der URL enthalten, die Sie zum Aufrufen der API verwenden. Jede Stufe ist ein benannter Verweis auf eine Bereitstellung der API und wird für Clientanwendungen zum Aufrufen zur Verfügung gestellt.
Eine Bereitstellung ist ein Snapshot Ihrer API-Konfiguration. Nachdem Sie eine API in einer Phase bereitgestellt haben, kann sie von Clients aufgerufen werden. Sie müssen eine API bereitstellen, damit Änderungen wirksam werden.
## Stufenvariablen
Stufenvariablen sind Schlüssel-Wert-Paare, die Sie für eine Phase einer WebSocket API definieren können. Sie weisen dasselbe Verhalten auf wie Umgebungsvariablen und können für die API-Einrichtung verwendet werden.
Sie können beispielsweise eine Stufenvariable definieren und dann ihren Wert als HTTP-Endpunkt für eine HTTP-Proxy-Integration festlegen. Später können Sie den Endpunkt mithilfe des zugeordneten Stufenvariablennamens referenzieren. Auf diese Weise können Sie in jeder Stufe dieselbe API-Einrichtung mit einem anderen Endpunkt verwenden. In ähnlicher Weise können Sie Stufenvariablen verwenden, um für jede Phase Ihrer API eine andere AWS Lambda Funktionsintegration anzugeben.
**Anmerkung**
Stage-Variablen sind nicht dazu gedacht, für sensible Daten wie Anmeldeinformationen verwendet zu werden. Verwenden Sie einen AWS Lambda Autorisierer, um sensible Daten an Integrationen weiterzugeben. Sie können sensible Daten an Integrationen in der Ausgabe des Lambda-Genehmigers übergeben. Weitere Informationen hierzu finden Sie unter [Antwortformat des Lambda-Genehmigers](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response).
### Beispiele
Wenn Sie eine Stufenvariable zum Anpassen des HTTP-Integrationsendpunkts verwenden möchten, müssen Sie zunächst den Namen und den Wert der Stufenvariablen (z. B. `url`) mit dem Wert `example.com` festlegen. Richten Sie als Nächstes eine HTTP-Proxy-Integration ein. Anstatt die URL des Endpunkts einzugeben, können Sie API Gateway anweisen, den Wert der Stufenvariablen zu verwenden, **http://\$1\$1stageVariables.url\$1**. Dieser Wert weist API Gateway an, Ihre Stufenvariable `${}` zur Laufzeit abhängig von der Stufe Ihrer API zu ersetzen.
Sie können auf ähnliche Weise auf Stufenvariablen verweisen, um einen Lambda-Funktionsnamen oder einen AWS Rollen-ARN anzugeben.
Wenn Sie einen Lambda-Funktionsnamen als Stufenvariablenwert angeben, müssen Sie die Berechtigungen für die Lambda-Funktion manuell konfigurieren. Der folgende [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html)-Befehl fügt die erforderlichen Berechtigungen hinzu:
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
## API Gateway Stufenvariablenreferenz
### HTTP-Integration URIs
Sie können eine Stufenvariable als Teil einer HTTP-Integrations-URI verwenden, wie in den folgenden Beispielen gezeigt.
+ Eine vollständige URI ohne Protokoll – `http://${stageVariables.}`
+ Eine vollständige Domäne – `http://${stageVariables.}/resource/operation`
+ Eine Unterdomäne – `http://${stageVariables.}.example.com/resource/operation`
+ Ein Pfad – `http://example.com/${stageVariables.}/bar`
+ Eine Abfragezeichenfolge – `http://example.com/foo?q=${stageVariables.}`
### Lambda-Funktionen
Sie können eine Stufenvariable anstelle eines Lambda-Funktionsnamens oder Alias verwenden, wie in den folgenden Beispielen gezeigt.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**Anmerkung**
Um eine Stufenvariable für eine Lambda-Funktion zu verwenden, muss sich die Funktion im selben Konto wie die API befinden. Stufenvariablen unterstützen keine kontoübergreifenden Lambda-Funktionen.
### AWS Anmeldeinformationen für die Integration
Sie können eine Stage-Variable als Teil eines ARN mit AWS Benutzer- oder Rollenanmeldedaten verwenden, wie im folgenden Beispiel gezeigt.
+ `arn:aws:iam:::${stageVariables.}`
# WebSocket APIs In API Gateway bereitstellen
Nachdem Sie Ihre WebSocket API erstellt haben, müssen Sie sie bereitstellen, damit Ihre Benutzer sie aufrufen können.
Zum Bereitstellen einer API erstellen Sie eine [API-Bereitstellung](api-gateway-basic-concept.md#apigateway-definition-api-deployment) und verknüpfen sie mit einer [Stufe](api-gateway-basic-concept.md#apigateway-definition-api-stage). Jede Stufe ist ein Snapshot der API und wird für Client-Apps zum Aufrufen verfügbar gemacht.
**Wichtig**
Eine API muss nach jeder Aktualisierung erneut bereitgestellt werden. Alle Änderungen außer an Stufeneinstellungen erfordern eine erneute Bereitstellung, einschließlich Änderungen an den folgenden Ressourcen:
Routen
Integrationen
Genehmiger
APIs sind standardmäßig auf 10 Stufen begrenzt. Wir empfehlen, bereits verwendete Stufen für Ihre Bereitstellungen wiederzuverwenden.
Um eine bereitgestellte WebSocket API aufzurufen, sendet der Client eine Nachricht an die URL der API. Die URL wird anhand des Hostnamens und der Stufennummer der API bestimmt.
**Anmerkung**
API Gateway unterstützt Nutzlasten bis zu 128 KB mit einer maximalen Framegröße von 32 KB. Sie müssen Nachrichten, die 32 KB überschreiten, in mehrere Frames aufteilen, die jeweils 32 KB oder kleiner sind.
Unter Verwendung des Standard-Domainnamens der API hat die URL (zum Beispiel) einer WebSocket API in einer bestimmten Phase (`{stageName}`) das folgende Format:
```
wss://{api-id}.execute-api.{region}.amazonaws.com/{stageName}
```
Um die URL der WebSocket API benutzerfreundlicher zu gestalten, können Sie einen benutzerdefinierten Domainnamen (z. B.`api.example.com`) erstellen, der den Standard-Hostnamen der API ersetzt. Der Konfigurationsprozess ist derselbe wie für REST APIs. Weitere Informationen finden Sie unter [Benutzerdefinierter Domainname für öffentliches REST APIs in API Gateway](how-to-custom-domains.md).
Stufen ermöglichen eine robuste Versionskontrolle Ihrer API. Sie können beispielsweise eine API für eine `test`- und eine `prod`-Stufe bereitstellen und die `test`-Stufe als Test-Build und die `prod`-Stufe als stabilen Build verwenden. Nachdem die Aktualisierungen den Test bestanden haben, können Sie die `test`-Stufe auf `prod` hochstufen. Die Hochstufung kann durch die erneute Bereitstellung der API für die `prod`-Stufe erfolgen. Weitere Informationen zu Stufen finden Sie unter [Einrichten einer Stufe für eine REST-API in API Gateway](set-up-stages.md).
**Topics**
+ [Erstellen Sie eine WebSocket API-Bereitstellung mit dem AWS CLI](#apigateway-create-websocket-deployment-using-awscli)
+ [Erstellen Sie eine WebSocket API-Bereitstellung mit der API Gateway Gateway-Konsole](#apigateway-create-websocket-deployment-using-console)
## Erstellen Sie eine WebSocket API-Bereitstellung mit dem AWS CLI
Der Befehl [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) erstellt eine Bereitstellung:
```
aws apigatewayv2 --region us-east-1 create-deployment --api-id aabbccddee
```
Die Ausgabe sieht wie folgt aus:
```
{
"DeploymentId": "fedcba",
"DeploymentStatus": "DEPLOYED",
"CreatedDate": "2018-11-15T06:49:09Z"
}
```
Die bereitgestellte API kann erst aufgerufen werden, wenn Sie die Bereitstellung einer Stufe zugeordnet haben. Sie können eine neue Stufe erstellen oder eine Stufe wiederverwenden, die Sie zuvor erstellt haben.
Der folgende [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-stage.html)-Befehl erstellt eine neue Stufe und verknüpft diese mit der Bereitstellung.
```
aws apigatewayv2 --region us-east-1 create-stage --api-id aabbccddee --deployment-id fedcba --stage-name test
```
Die Ausgabe sollte wie folgt aussehen:
```
{
"StageName": "test",
"CreatedDate": "2018-11-15T06:50:28Z",
"DeploymentId": "fedcba",
"DefaultRouteSettings": {
"MetricsEnabled": false,
"ThrottlingBurstLimit": 5000,
"DataTraceEnabled": false,
"ThrottlingRateLimit": 10000.0
},
"LastUpdatedDate": "2018-11-15T06:50:28Z",
"StageVariables": {},
"RouteSettings": {}
}
```
Sie können eine vorhandene Phase auch wiederverwenden, indem Sie die `deploymentId` Eigenschaft der Phase mit der neu erstellten Bereitstellungs-ID (*deployment-id*) aktualisieren. Der folgende [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html)-Befehl aktualisiert die Bereitstellungs-ID der Stufe:
```
aws apigatewayv2 update-stage --region region \
--api-id api-id \
--stage-name stage-name \
--deployment-id deployment-id
```
## Erstellen Sie eine WebSocket API-Bereitstellung mit der API Gateway Gateway-Konsole
So verwenden Sie die API Gateway Gateway-Konsole, um eine Bereitstellung für eine WebSocket API zu erstellen:
1. Melden Sie sich bei der API Gateway-Konsole an und wählen Sie die API aus.
1. Klicken Sie auf **Deploy API**.
1. Wählen Sie die gewünschte Stufe aus der Dropdown-Liste aus oder geben Sie den Namen einer neuen Stufe ein.
# Sicherheitsrichtlinie für WebSocket APIs in API Gateway
API Gateway setzt eine Sicherheitsrichtlinie von `TLS_1_2` für alle WebSocket API-Endpunkte durch.
Eine *Sicherheitsrichtlinie* ist eine vordefinierte Kombination aus einer TLS-Mindestversion und Verschlüsselungsverfahren, die von Amazon API Gateway bereitgestellt wird. Das TLS-Protokoll behandelt Netzwerksicherheitsprobleme wie Manipulationen und Abhören zwischen einem Client und einem Server. Wenn Ihre Clients über die benutzerdefinierte Domäne einen TLS-Handshake mit Ihrer API ausführen, erzwingt die Sicherheitsrichtlinie die TLS-Version und die Verschlüsselungssuite-Optionen, die von Ihren Clients verwendet werden können. Diese Sicherheitsrichtlinie akzeptiert TLS 1.2- und TLS 1.3-Verkehr und weist TLS 1.0-Verkehr zurück.
## Unterstützte TLS-Protokolle und Chiffren für WebSocket APIs
In der folgenden Tabelle werden die unterstützten TLS-Protokolle für beschrieben. WebSocket APIs
| **TLS-Protokolle** | **TLS\$11\$12-Sicherheitsrichtlinie** |
| --- | --- |
| TLSv13. | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| TLSv12. | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
In der folgenden Tabelle werden die TLS-Verschlüsselungen beschrieben, die für die Sicherheitsrichtlinie TLS 1\$12 für verfügbar sind. WebSocket APIs
| **TLS-Verschlüsselungsverfahren** | **TLS\$11\$12-Sicherheitsrichtlinie** |
| --- | --- |
| TLS\$1AES\$1128\$1GCM\$1 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| TLS\$1AES\$1256\$1GCM\$1 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| TLS\$1 \$1 CHACHA20 POLY1305 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| ECDHE-ECDSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| ECDHE-RSA- AES128 -GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| ECDHE-ECDSA- AES128 - SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| ECDHE-RSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| ECDHE-ECDSA- -GCM AES256 - SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| ECDHE-RSA- AES256 -GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| ECDHE-ECDSA- AES256 - SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| ECDHE-RSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| AES128-GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| AES256-GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/success_icon.svg) Ja |
## OpenSSL- und RFC-Verschlüsselungsnamen
OpenSSL und IETF RFC 5246 verwenden unterschiedliche Namen für die gleichen Verschlüsselungsverfahren. Eine Liste der Namen der Verschlüsselungsverfahren finden Sie unter [OpenSSL- und RFC-Verschlüsselungsnamen](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names).
## Informationen zu REST APIs und HTTP APIs
Weitere Informationen zu REST APIs und HTTP APIs finden Sie unter [Wählen Sie eine Sicherheitsrichtlinie für Ihre benutzerdefinierte Domain in API Gateway](apigateway-custom-domain-tls-version.md) und[Sicherheitsrichtlinie für HTTP APIs in API Gateway](http-api-ciphers.md).
# 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 Domainnamen mit Platzhalter](http-api-custom-domain-names.md#http-wildcard-custom-domain-names).
## 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](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) 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](https://tools.ietf.org/html/rfc1035#section-2.3.4)-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](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) 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 [Standardkontingent](limits.md)zu ü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 [Variablen für Datentransformationen für API Gateway](api-gateway-mapping-template-reference.md).
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](https://console.aws.amazon.com/support/home#/) 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 [Bereiten Sie Zertifikate vor in AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Dann erstellen Sie einen regionalen benutzerdefinierten Domainnamen. Weitere Informationen finden Sie unter [Einrichten eines regionalen benutzerdefinierten Domainnamens in API Gateway](apigateway-regional-api-custom-domain-create.md).
# API-Stufen einem benutzerdefinierten Domainnamen für WebSocket-APIs zuweisen
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 `wss://api.example.com/orders` abbilden.
Bevor Sie eine API-Zuweisung 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).
## Einschränkungen
+ In einer API-Zuweisung müssen sich der benutzerdefinierte Domainname und die zugeordneten 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.
+ Sie können WebSocket-APIs nicht demselben benutzerdefinierten Domainnamen wie dem einer HTTP-API oder REST-API zuweisen.
+ Wenn Sie mehrstufige API-Zuweisungen erstellen, konvertiert API Gateway alle Header-Namen in Kleinbuchstaben.
## 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 [Einrichten eines regionalen benutzerdefinierten Domainnamens in API Gateway](apigateway-regional-api-custom-domain-create.md).
------
#### [ AWS-Managementkonsole ]
**So erstellen Sie eine API-Zuweisung**
1. Melden Sie sich bei der API-Gateway-Konsole unter [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) an.
1. Wählen Sie **benutzerdefinierte Domain-Namen** aus.
1. Wählen Sie einen benutzerdefinierten Domain-Namen aus, den Sie bereits erstellt haben.
1. Wählen Sie **API-Mappings** aus.
1. Wählen Sie **API-Zuweisungen konfigurieren** aus.
1. Wählen Sie **Neue Zuweisung hinzufügen** aus.
1. Geben Sie eine **API**, eine **Phase** und optional einen **Pfad** ein.
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` an die angegebene API und Phase.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1 \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
Mit dem folgenden CloudFormation-Beispiel wird ein API-Mapping erstellt.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'v1'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# IP-Adresstypen für benutzerdefinierte Domainnamen für WebSocket-APIs
Wenn Sie einen benutzerdefinierten Domainnamen erstellen, geben Sie den Typ der IP-Adressen an, die Ihre Domain aufrufen können. Sie können IPv4 auswählen, um IPv4-Adressen für den Aufruf Ihrer Domain zuzulassen, oder Dualstack, um sowohl IPv4- als auch IPv6-Adressen für den Aufruf zuzulassen. Wir empfehlen, den IP-Adresstyp auf Dualstack zu setzen, um Engpässe im IP-Adressraum zu vermeiden und Ihre Sicherheitsposition zu verbessern. Weitere Informationen zu den Vorteilen eines Dualstack-IP-Adresstyps finden Sie unter [IPv6 in AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Überlegungen zu IP-Adresstypen
Die folgenden Überlegungen können Ihre Verwendung von IP-Adresstypen beeinflussen.
+ Der Standard-IP-Adresstyp für benutzerdefinierte Domainnamen in API Gateway ist IPv4.
+ Ihr benutzerdefinierter Domainname muss nicht denselben IP-Adresstyp für alle darauf zugewiesenen APIs haben. Wenn Sie Ihren Standard-API-Endpunkt deaktivieren, kann dies die Art und Weise beeinflussen, wie Aufrufer Ihre API aufrufen können.
## Ändern des IP-Adresstyps eines benutzerdefinierten Domainnamens
Sie können den IP-Adresstyp ändern, indem Sie die Endpunktkonfiguration des Domainnamens aktualisieren. Dies kann über die AWS-Managementkonsole, die AWS CLI, CloudFormation oder ein AWS SDK erfolgen.
------
#### [ AWS-Managementkonsole ]
**So ändern Sie den IP-Adresstyp eines benutzerdefinierten Domainnamens**
1. Melden Sie sich bei der API Gateway-Konsole unter [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) an.
1. Wählen Sie einen öffentlichen benutzerdefinierten Domainnamen aus.
1. Wählen Sie **Endpunktkonfiguration** aus.
1. Wählen Sie unter „IP-Adresstyp“ entweder **IPv4** oder **Dualstack** aus.
1. Wählen Sie **Speichern** aus.
------
#### [ AWS CLI ]
Der folgende [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)-Befehl aktualisiert eine API, sodass sie den IP-Adresstyp „Dualstack“ aufweist:
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
Die Ausgabe sieht wie folgt aus:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# Deaktivieren Sie den Standardendpunkt für WebSocket APIs
Standardmäßig können Clients Ihre API mithilfe des `execute-api`-Endpunkts aufrufen, den API Gateway für Ihre API generiert. Um sicherzustellen, dass Kunden nur über einen benutzerdefinierten Domänennamen auf Ihre API zugreifen können, deaktivieren Sie den standardmäßigen `execute-api`-Endpunkt. Wenn Sie den Standardendpunkt deaktivieren, wirkt sich dies auf alle Stufen einer API aus.
Das folgende Verfahren zeigt, wie Sie den Standardendpunkt für eine WebSocket API deaktivieren.
------
#### [ AWS-Managementkonsole ]
1. Melden Sie sich bei der API Gateway Gateway-Konsole unter [https://console.aws.amazon.com/apigatewayan](https://console.aws.amazon.com/apigateway).
1. Wählen Sie eine API aus. WebSocket
1. Wählen Sie **API-Einstellungen** aus.
1. Klicken Sie unter **API-Details** auf **Bearbeiten**.
1. Wählen Sie unter **Standardendpunkt** die Option **Inaktiv** aus.
1. Wählen Sie **Änderungen speichern ** aus.
1. Klicken Sie im Navigationsbereich auf **Routen**.
1. Klicken Sie auf **Bereitstellen** und stellen Sie Ihre API erneut bereit oder erstellen Sie eine neue Stufe, in der die Änderung wirksam werden soll.
------
#### [ AWS CLI ]
Der folgende [update-api-Befehl deaktiviert den Standardendpunkt für eine API](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html): WebSocket
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
Nachdem Sie den Standardendpunkt deaktiviert haben, müssen Sie Ihre API bereitstellen, damit die Änderung wirksam wird.
Der folgende AWS CLI Befehl erstellt eine Bereitstellung.
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# Schützen Sie Ihr WebSocket APIs internes API Gateway
API Gateway bietet eine Reihe von Möglichkeiten, Ihre API vor bestimmten Bedrohungen zu schützen, wie böswillige Benutzer oder Spitzen im Datenverkehr. Sie können Ihre API mit Strategien wie dem Generieren von SSL-Zertifikaten oder dem Festlegen von Drosselungszielen schützen. Weitere Informationen über das Generieren von Zertifikaten finden Sie unter [Erstellen und Konfigurieren eines SSL-Zertifikats für die Backend-Authentifizierung in API Gateway](getting-started-client-side-ssl-authentication.md). Der Rest dieses Abschnitts behandelt das Festlegen von Drosselungszielen.
Sie können die Drosselung für Sie konfigurieren, um sie davor APIs zu schützen, von zu vielen Anfragen überfordert zu werden. Drosselungen werden mit bestem Bemühen angewendet und sollten als Ziele und nicht als garantierte Anforderungsobergrenzen betrachtet werden.
API Gateway drosselt Anfragen an Ihre API mit dem Token-Bucket-Algorithmus, wobei ein Token für eine Anforderung gilt. Insbesondere untersucht API Gateway die Rate und die Anzahl der eingereichten Anfragen für alle APIs in Ihrem Konto pro Region. Im Token-Bucket-Algorithmus kann ein Burst ein vordefiniertes Überlaufen dieser Grenzwerte ermöglichen, aber andere Faktoren können auch dazu führen, dass Grenzwerte in einigen Fällen überlaufen werden.
Wenn Anfrageeinreichungen die Steady-State-Anfragerate und Steigerungs-Limits überschreiten, drosselt API Gateway Anfragen. Kunden erhalten möglicherweise `429 Too Many Requests` Fehlerantworten an dieser Stelle. Bei der Erfassung solcher Ausnahmen kann der Client die fehlgeschlagenen Anforderungen in einer Weise erneut einreichen, die raten-begrenzend ist.
Als API-Entwickler können Sie die Zielgrenzwerte für einzelne API-Phasen oder -Routen festlegen, um die Gesamtleistung APIs in Ihrem Konto zu verbessern.
## Drosselung auf Kontoebene pro Region
Standardmäßig begrenzt API Gateway die Steady-State-Anfragen pro Sekunde (RPS) APIs innerhalb eines AWS Kontos pro Region. Außerdem wird der Burst (d. h. die maximale Bucket-Größe) für alle APIs innerhalb eines AWS Kontos pro Region begrenzt. In API Gateway entspricht das Burst-Limit der maximalen Target-Anzahl gleichzeitiger Anfragen, die API Gateway vor Rückgabe von `429 Too Many Requests`-Fehlerantworten ausführt. Weitere Informationen zu Drosselungskontingenten finden Sie unter [Kontingente für Amazon API Gateway](limits.md).
Die Limits pro Konto gelten für alle APIs Konten in einer bestimmten Region. Das Ratenlimit auf Kontoebene kann auf Anfrage erhöht werden. Höhere Limits sind möglich, was kürzere Timeouts und geringere Payloads zur Folge hat. APIs Um eine Steigerung der Ablehnungslimits auf Kontoebene pro Region anzufordern, wenden Sie sich an das [AWS Supportcenter](https://console.aws.amazon.com/support/home#/). Weitere Informationen finden Sie unter [Kontingente für Amazon API Gateway](limits.md). Beachten Sie, dass diese Limits nicht höher als die Drosselungsgrenzen sein können. AWS
## Drosselung auf Routenebene
Sie können die Drosselung auf Routenebene festlegen, um die Anforderungs-Drosselungslimits auf Kontoebene für eine bestimmte Stufe oder für individuelle Routen in Ihrer API zu überschreiben. Die Standardgrenzen für die Routendrosselung können die Ratenlimits auf Kontoebene nicht überschreiten.
Sie können die Drosselung auf Routenebene konfigurieren, indem Sie die verwende AWS CLI. Der folgende [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html)-Befehl konfiguriert die benutzerdefinierte Drosselung für die angegebene Stufe und Route einer API.
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"messages":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# WebSocket-APIs in API Gateway überwachen
Sie können CloudWatch-Metriken und CloudWatch Logs zur Überwachung von WebSocket-APIs verwenden. Durch die Kombination von Protokollen und Metriken können Sie Fehler protokollieren und die Leistung Ihrer API überwachen.
**Anmerkung**
API Gateway generiert in den folgenden Fällen möglicherweise keine Protokolle und Metriken:
413 Request Entity Too Large-Fehler
Übermäßige 429 Too Many Requests-Fehler
Fehler der Serie 400 von Anfragen, die an eine benutzerdefinierte Domäne gesendet wurden, die keine API-Zuordnung hat
Fehler der Serie 500, die durch interne Ausfälle verursacht werden
**Topics**
+ [Überwachen Sie die WebSocket API-Ausführung mit CloudWatch Metriken](apigateway-websocket-api-logging.md)
+ [Konfigurieren Sie die Protokollierung für WebSocket APIs im API Gateway](websocket-api-logging.md)
# Überwachen Sie die WebSocket API-Ausführung mit CloudWatch Metriken
Sie können [ CloudWatchAmazon-Metriken](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) zur Überwachung verwenden WebSocket APIs. Die Konfiguration ähnelt der für REST verwendeten APIs. Weitere Informationen finden Sie unter [Überwachen Sie die REST-API-Ausführung mit CloudWatch Amazon-Metriken](monitoring-cloudwatch.md).
Die folgenden Metriken werden unterstützt für WebSocket APIs:
| Metrik | Description |
| --- | --- |
| ConnectCount | Die Anzahl der Nachrichten, die an die \$1connect-Routenintegration gesendet werden. |
| MessageCount | Die Anzahl der Nachrichten, die entweder vom oder an den Client an die WebSocket API gesendet wurden. |
| IntegrationError | Die Anzahl der Anforderungen, die eine 4XX/5XX-Antwort von der Integration zurückgeben. |
| ClientError | Die Anzahl der Anfragen, auf die eine 4XX-Antwort von API Gateway zurückgegeben wird, bevor die Integration aufgerufen wird. |
| ExecutionError | Fehler beim Aufrufen der Integration. |
| IntegrationLatency | Der Zeitunterschied zwischen dem Senden der Anfragen durch API Gateway an die Integration und dem Eingang der Antwort der Integration bei API Gateway. Wird für Rückrufe und Pseudo-Integrationen ausgeblendet. |
Sie können die Dimensionen in der folgenden Tabelle verwenden, um API Gateway-Metriken zu filtern.
| Dimension | Description |
| --- | --- |
| ApiId | Filtert API Gateway-Metriken für eine API mit der angegebenen API-ID. |
| ApiId, Phase | Filtert API Gateway-Metriken für eine API-Stufe mit der angegebenen API-ID und Stufen-ID. |
| ApiId, Methode, Ressource, Phase | Filtert API-Gateway-Metriken für eine API-Methode mit der angegebenen API-ID, Stufen-ID, dem Ressourcenpfad und der Routen-ID. API Gateway sendet diese Metriken nur, wenn Sie detaillierte CloudWatch Metriken explizit aktiviert haben. Sie können dies tun, indem Sie die [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html)Aktion der API Gateway V2 REST-API aufrufen, auf die die `detailedMetricsEnabled` Eigenschaft aktualisiert `true` werden soll. Alternativ können Sie den AWS CLI Befehl [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) aufrufen, um die `DetailedMetricsEnabled` Eigenschaft auf zu aktualisieren. `true` Durch die Aktivierung dieser Metriken wird Ihr Konto mit zusätzlichen Gebühren belastet. Preisinformationen finden Sie unter [ CloudWatchAmazon-Preise](https://aws.amazon.com/cloudwatch/pricing/). |
# Konfigurieren Sie die Protokollierung für WebSocket APIs im API Gateway
Sie können die Protokollierung aktivieren, um CloudWatch Protokolle in Logs zu schreiben. Es gibt zwei Arten der API-Anmeldung CloudWatch: Ausführungsprotokollierung und Zugriffsprotokollierung. Bei der Ausführungsprotokollierung verwaltet API Gateway die CloudWatch Protokolle. Der Prozess umfasst das Erstellen von Protokollgruppen und -Streams sowie die Meldung der Anforderungen und Antworten jedes Aufrufers an Protokoll-Streams.
Zur Verbesserung Ihrer Sicherheitslage empfehlen wir Ihnen, die Ausführungsprotokollierung auf der `ERROR`- oder `INFO`-Ebene zu verwenden. Dies kann erforderlich sein, um verschiedene Compliance-Rahmenwerke einzuhalten. Weitere Informationen finden Sie unter [Amazon-API-Gateway-Steuerelemente](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) im *Benutzerhandbuch für AWS Security Hub *.
In der Zugriffsprotokollierung protokollieren Sie, als API-Entwickler, wer auf Ihre API zugegriffen hat und wie der Aufrufer auf die API zugegriffen hat. Erstellen Sie eine eigene Protokollgruppe oder wählen Sie eine vorhandene Protokollgruppe aus, die von API Gateway verwaltet werden kann. Um die Zugriffsdetails anzugeben, wählen Sie `$context`-Variablen (ausgedrückt in einem Format Ihrer Wahl) und eine Protokollgruppe als Ziel aus.
Anweisungen zum Einrichten der CloudWatch Protokollierung finden Sie unter[CloudWatch API-Protokollierung mit der API Gateway Gateway-Konsole einrichten](set-up-logging.md#set-up-access-logging-using-console).
Wenn Sie das **Log Format (Protokollformat)** angeben, können Sie wählen, welche Kontextvariablen protokolliert werden sollen. Die folgenden Variablen werden unterstützt.
| Parameter | Beschreibung |
| --- | --- |
| \$1context.apiId | Die ID, die API Gateway Ihrer API zuweist. |
| \$1context.authorize.error | Die Autorisierungsfehlermeldung. |
| \$1context.authorize.latency | Die Autorisierungslatenz in ms |
| \$1context.authorize.status | Der Statuscode, der von einem Autorisierungsversuch zurückgegeben wurde. |
| \$1context.authorizer.error | Die von einem Genehmiger zurückgegebene Fehlermeldung. |
| \$1context.authorizer.integrationLatency | Die Lambda-Genehmiger-Latenzzeit in ms. |
| \$1context.authorizer.integrationStatus | Der von einem Lambda-Genehmiger zurückgegebene Statuscode. |
| \$1context.authorizer.latency | Der Genehmiger-Latenz in ms. |
| \$1context.authorizer.requestId | Die Anforderungs-ID des AWS Endpunkts. |
| \$1context.authorizer.status | Der von einem Genehmiger zurückgegebene Statuscode. |
| \$1context.authorizer.principalId | Die ID des Prinzipalbenutzers, die mit dem vom Client gesendeten und von einer Lambda-Genehmiger-Lambda-Funktion des API Gateways zurückgegebenen Token verknüpft ist. (Ein Lambda-Genehmiger wurde früher als benutzerdefinierter Genehmiger bezeichnet). |
| \$1context.authorizer.property | Der in einer Zeichenfolge umgewandelte Wert des angegebenen Schlüssel-Wert-Paares der `context`-Zuordnung, der von einer API Gateway Lambda-Genehmigerfunktion zurückgegeben wird. Angenommen, der Genehmiger gibt folgende `context`-Zuweisung zurück: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} Dann gibt der Aufruf von `$context.authorizer.key` die Zeichenfolge `"value"` zurück, der Aufruf von `$context.authorizer.numKey` gibt die Zeichenfolge `"1"` zurück und der Aufruf von `$context.authorizer.boolKey` gibt den Wert `"true"` zurück. |
| \$1context.authenticate.error | Die von einem Authentifizierungsversuch zurückgegebene Fehlermeldung. |
| \$1context.authenticate.latency | Die Authentifizierungslatenz in ms |
| \$1context.authenticate.status | Der Statuscode, der von einem Authentifizierungsversuch zurückgegeben wurde. |
| \$1context.connectedAt | Die [Epoch](https://en.wikipedia.org/wiki/Unix_time)-formatierte Verbindungszeit. |
| \$1context.connectionId | Eine eindeutige ID für die Verbindung, die für einen Rückruf an den Client verwendet werden kann. |
| \$1context.domainName | Ein Domainname für die WebSocket API. Dies kann für einen Rückruf an den Client (anstelle eines hardcodierten Wertes) verwendet werden. |
| \$1context.error.message | Eine Zeichenfolge, die eine API Gateway-Fehlermeldung enthält. |
| \$1context.error.messageString | Die Wert von \$1context.error.message in Anführungszeichen, d. h. "\$1context.error.message". |
| \$1context.error.responseType | Der Fehler-Antworttyp. |
| \$1context.error.validationErrorString | Eine Zeichenfolge, die eine detaillierte Validierungsfehlermeldung enthält. |
| \$1context.eventType | Der Ereignistyp: `CONNECT`, `MESSAGE` oder `DISCONNECT`. |
| \$1context.extendedRequestId | Äquivalent mit \$1context.requestId. |
| \$1context.identity.accountId | Die der Anfrage zugeordnete AWS Konto-ID. |
| \$1context.identity.apiKey | Der API-Besitzerschlüssel, der der schlüsselfähigen API-Anforderung zugewiesen ist. |
| \$1context.identity.apiKeyId | Die API-Schlüssel-ID, die der schlüsselfähigen API-Anforderung zugewiesen ist |
| \$1context.identity.caller | Die Hauptkennung des Aufrufers, der die Anforderung signiert hat. Wird für Routen unterstützt, die die IAM-Autorisierung verwenden. |
| \$1context.identity.cognitoAuthenticationProvider | Eine durch Komma getrennte Liste aller Amazon-Cognito-Authentifizierungsanbieter, die vom anfordernden Aufrufer verwendet werden. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. Zum Beispiel für eine Identität aus einem Amazon Cognito-Benutzerpool, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Weitere Informationen zu verfügbaren Amazon-Cognito-Authentifizierungsanbietern finden Sie unter [Verbundidentitäten verwenden](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) im *Amazon-Cognito-Entwicklerhandbuch*. |
| \$1context.identity.cognitoAuthenticationType | Der Amazon Cognito-Authentifizierungstyp des Aufrufers, der den Anfrage erstellt hat. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. Mögliche Werte sind `authenticated` für authentifizierte Identitäten und `unauthenticated` für nicht authentifizierte Identitäten. |
| \$1context.identity.cognitoIdentityId | Die Amazon Cognito Identitäts-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. |
| \$1context.identity.cognitoIdentityPoolId | Die Amazon Cognito Identitätspool-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. |
| \$1context.identity.principalOrgId | Die [AWS -Organisations-ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). Wird für Routen unterstützt, die die IAM-Autorisierung verwenden. |
| \$1context.identity.sourceIp | Die Quell-IP-Adresse der TCP-Verbindung, von der die Anforderung an API Gateway gesendet wird. |
| \$1context.identity.user | Die Hauptkennung des Benutzers, der für den Ressourcenzugriff autorisiert wird. Wird für Routen unterstützt, die die IAM-Autorisierung verwenden. |
| \$1context.identity.userAgent | Der Benutzeragent des API-Aufrufers. |
| \$1context.identity.userArn | Der ARN (Amazon Resource Name) des tatsächlichen Benutzers nach der Authentifizierung. |
| \$1context.integration.error | Die von einer Integration zurückgegebene Fehlermeldung. |
| \$1context.integration.integrationStatus | Bei der Lambda-Proxyintegration wurde der Statuscode vom Lambda-Funktionscode zurückgegeben AWS Lambda, nicht vom Backend-Funktionscode. |
| \$1context.integration.latency | Die Integrationslatenz in Millisekunden. Äquivalent mit \$1context.integrationLatency. |
| \$1context.integration.requestId | Die AWS Anforderungs-ID des Endpunkts. Äquivalent mit \$1context.awsEndpointRequestId. |
| \$1context.integration.status | Der von einer Integration zurückgegebene Statuscode. Bei Lambda-Proxy-Integrationen ist dies der Statuscode, der von Ihrem Lambda-Funktionscode zurückgegeben wird. Äquivalent mit \$1context.integrationStatus. |
| \$1context.integrationLatency | Die Integrationslatenz in ms, nur für die Zugriffsprotokollierung verfügbar. |
| \$1context.messageId | Eine eindeutige serverseitige ID für eine Nachricht. Nur verfügbar, wenn der `$context.eventType` `MESSAGE` ist. |
| \$1context.requestId | Entspricht `$context.extendedRequestId`. |
| \$1context.requestTime | Die Anforderungszeit im [CLF](https://httpd.apache.org/docs/current/logs.html#common)-Format (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | Die Anforderungszeit im [Epoch](https://en.wikipedia.org/wiki/Unix_time)-Format in Millisekunden. |
| \$1context.routeKey | Der ausgewählte Routenschlüssel. |
| \$1context.stage | Die Bereitstellungsstufe des API-Aufrufs (z. B. "beta" oder "prod"). |
| \$1context.status | Der Antwortstatus. |
| \$1context.waf.error | Die Fehlermeldung wurde von zurückgegeben AWS WAF. |
| \$1context.waf.latency | Die AWS WAF Latenz in ms. |
| \$1context.waf.status | Der Statuscode wurde von zurückgegeben AWS WAF. |
Beispiele für einige häufig verwendete Zugriffsprotokollformate werden in der API Gateway-Konsole dargestellt und wie folgt aufgeführt.
+ `CLF` ([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp $context.identity.caller \
$context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
$context.status $context.requestId
```
Die Fortsetzungszeichen (`\`) sind als visuelle Hilfe gedacht. Das Protokollformat muss eine einzelne Zeile sein. Sie können am Ende des Protokollformats ein Zeilenumbruchzeichen (`\n`) hinzufügen, um am Ende jedes Protokolleintrags einen Zeilenumbruch einzuschließen.
+ `JSON`:
```
{
"requestId":"$context.requestId", \
"ip": "$context.identity.sourceIp", \
"caller":"$context.identity.caller", \
"user":"$context.identity.user", \
"requestTime":"$context.requestTime", \
"eventType":"$context.eventType", \
"routeKey":"$context.routeKey", \
"status":"$context.status", \
"connectionId":"$context.connectionId"
}
```
Die Fortsetzungszeichen (`\`) sind als visuelle Hilfe gedacht. Das Protokollformat muss eine einzelne Zeile sein. Sie können am Ende des Protokollformats ein Zeilenumbruchzeichen (`\n`) hinzufügen, um am Ende jedes Protokolleintrags einen Zeilenumbruch einzuschließen.
+ `XML`:
```
\
$context.identity.sourceIp \
$context.identity.caller \
$context.identity.user \
$context.requestTime \
$context.eventType \
$context.routeKey \
$context.status \
$context.connectionId \
```
Die Fortsetzungszeichen (`\`) sind als visuelle Hilfe gedacht. Das Protokollformat muss eine einzelne Zeile sein. Sie können am Ende des Protokollformats ein Zeilenumbruchzeichen (`\n`) hinzufügen, um am Ende jedes Protokolleintrags einen Zeilenumbruch einzuschließen.
+ `CSV` (durch Komma getrennte Werte):
```
$context.identity.sourceIp,$context.identity.caller, \
$context.identity.user,$context.requestTime,$context.eventType, \
$context.routeKey,$context.connectionId,$context.status, \
$context.requestId
```
Die Fortsetzungszeichen (`\`) sind als visuelle Hilfe gedacht. Das Protokollformat muss eine einzelne Zeile sein. Sie können am Ende des Protokollformats ein Zeilenumbruchzeichen (`\n`) hinzufügen, um am Ende jedes Protokolleintrags einen Zeilenumbruch einzuschließen.