Protokollierung für eine WebSocket API konfigurieren

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.

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.

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 Domainname 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 der Anfrage zugeordnete AWS Konto-ID.
$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 der Amazon Cognito-Authentifizierungsanbieter, die vom Aufrufer, der die Anfrage stellt, 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 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	Bei der Lambda-Proxyintegration wurde der Statuscode vom Lambda-Funktionscode zurückgegeben AWS Lambda, nicht vom Backend-Funktionscode.
$context.integration.latency	Die Integrationslatenz in Millisekunden. Äquivalent mit $context.integrationLatency.
$context.integration.requestId	Die AWS Anforderungs-ID des 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 Fehlermeldung wurde von zurückgegeben AWS WAF.
$context.waf.latency	Die AWS WAF Latenz in ms.
$context.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):

  $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>

  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.