Protokollierung für WebSocket-APIs in API Gateway konfigurieren

Sie können die Protokollierung aktivieren, um Protokolle in CloudWatch Logs zu schreiben. Es gibt zwei Arten der API-Protokollierung in CloudWatch: Ausführungsprotokollierung und Zugriffsprotokollierung. In der Ausführungsprotokollierung verwaltet API Gateway die CloudWatch Logs. 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 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 Einrichten der CloudWatch-API-Protokollierung über die API Gateway-Konsole.

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
`$context.apiId`	Die ID, die API Gateway Ihrer API zuweist.
`$context.authorize.error`	Die Autorisierungsfehlermeldung.
`$context.authorize.latency`	Die Autorisierungslatenz in ms
`$context.authorize.status`	Der Statuscode, der von einem Autorisierungsversuch zurückgegeben wurde.
`$context.authorizer.error`	Die von einem Genehmiger zurückgegebene Fehlermeldung.
`$context.authorizer.integrationLatency`	Die Lambda-Genehmiger-Latenzzeit in ms.
`$context.authorizer.integrationStatus`	Der von einem Lambda-Genehmiger zurückgegebene Statuscode.
`$context.authorizer.latency`	Der Genehmiger-Latenz in ms.
`$context.authorizer.requestId`	Die Anforderungs-ID des AWS-Endpunkts.
`$context.authorizer.status`	Der von einem Genehmiger zurückgegebene Statuscode.
`$context.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).
`$context.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.
`$context.authenticate.error`	Die von einem Authentifizierungsversuch zurückgegebene Fehlermeldung.
`$context.authenticate.latency`	Die Authentifizierungslatenz in ms
`$context.authenticate.status`	Der Statuscode, der von einem Authentifizierungsversuch zurückgegeben wurde.
`$context.connectedAt`	Die Epoch-formatierte Verbindungszeit.
`$context.connectionId`	Eine eindeutige ID für die Verbindung, die für einen Rückruf an den Client verwendet werden kann.
`$context.domainName`	Ein Domänenname für die WebSocket-API. Dies kann für einen Rückruf an den Client (anstelle eines hardcodierten Wertes) verwendet werden.
`$context.error.message`	Eine Zeichenfolge, die eine API Gateway-Fehlermeldung enthält.
`$context.error.messageString`	Die Wert von `$context.error.message` in Anführungszeichen, d. h. `"$context.error.message"`.
`$context.error.responseType`	Der Fehler-Antworttyp.
`$context.error.validationErrorString`	Eine Zeichenfolge, die eine detaillierte Validierungsfehlermeldung enthält.
`$context.eventType`	Der Ereignistyp: `CONNECT`, `MESSAGE` oder `DISCONNECT`.
`$context.extendedRequestId`	Äquivalent mit `$context.requestId`.
`$context.identity.accountId`	Die AWS-Konto-ID der Anforderung.
`$context.identity.apiKey`	Der API-Besitzerschlüssel, der der schlüsselfähigen API-Anforderung zugewiesen ist.
`$context.identity.apiKeyId`	Die API-Schlüssel-ID, die der schlüsselfähigen API-Anforderung zugewiesen ist
`$context.identity.caller`	Die Hauptkennung des Aufrufers, der die Anforderung signiert hat. Wird für Routen unterstützt, die die IAM-Autorisierung verwenden.
`$context.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 im Amazon-Cognito-Entwicklerhandbuch.
`$context.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.
`$context.identity.cognitoIdentityId`	Die Amazon Cognito Identitäts-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde.
`$context.identity.cognitoIdentityPoolId`	Die Amazon Cognito Identitätspool-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde.
`$context.identity.principalOrgId`	Die AWS-Organisations-ID. Wird für Routen unterstützt, die die IAM-Autorisierung verwenden.
`$context.identity.sourceIp`	Die Quell-IP-Adresse der TCP-Verbindung, von der die Anforderung an API Gateway gesendet wird.
`$context.identity.user`	Die Hauptkennung des Benutzers, der für den Ressourcenzugriff autorisiert wird. Wird für Routen unterstützt, die die IAM-Autorisierung verwenden.
`$context.identity.userAgent`	Der Benutzeragent des API-Aufrufers.
`$context.identity.userArn`	Der ARN (Amazon Resource Name) des tatsächlichen Benutzers nach der Authentifizierung.
`$context.integration.error`	Die von einer Integration zurückgegebene Fehlermeldung.
`$context.integration.integrationStatus`	Für die Lambda-Proxy-Integration wird der Statuscode von AWS Lambda zurückgegeben, nicht der Backend-Lambda-Funktionscode.
`$context.integration.latency`	Die Integrationslatenz in Millisekunden. Äquivalent mit `$context.integrationLatency`.
`$context.integration.requestId`	Die Anforderungs-ID des AWS-Endpunkts. Äquivalent mit `$context.awsEndpointRequestId`.
`$context.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 `$context.integrationStatus`.
`$context.integrationLatency`	Die Integrationslatenz in ms, nur für die Zugriffsprotokollierung verfügbar.
`$context.messageId`	Eine eindeutige serverseitige ID für eine Nachricht. Nur verfügbar, wenn der `$context.eventType` `MESSAGE` ist.
`$context.requestId`	Entspricht `$context.extendedRequestId`.
`$context.requestTime`	Die Anforderungszeit im CLF-Format (`dd/MMM/yyyy:HH:mm:ss +-hhmm`).
`$context.requestTimeEpoch`	Die Anforderungszeit im Epoch-Format in Millisekunden.
`$context.routeKey`	Der ausgewählte Routenschlüssel.
`$context.stage`	Die Bereitstellungsstufe des API-Aufrufs (z. B. "beta" oder "prod").
`$context.status`	Der Antwortstatus.
`$context.waf.error`	Die von AWS WAF zurückgegebene Fehlermeldung.
`$context.waf.latency`	Die AWS WAF-Latenz in ms.
`$context.waf.status`	Der von AWS WAF zurückgegebene Statuscode.

Beispiele für einige häufig verwendete Zugriffsprotokollformate werden in der API Gateway-Konsole dargestellt und wie folgt aufgeführt.

CLF (Common Log Format):
```
$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:


<request id="$context.requestId"> \
 <ip>$context.identity.sourceIp</ip> \
 <caller>$context.identity.caller</caller> \
 <user>$context.identity.user</user> \
 <requestTime>$context.requestTime</requestTime> \
 <eventType>$context.eventType</eventType> \
 <routeKey>$context.routeKey</routeKey> \
 <status>$context.status</status> \
 <connectionId>$context.connectionId</connectionId> \
</request>

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.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Metriken

API Gateway-ARNs