Configurazione della registrazione dei log per le API WebSocket in Gateway API - Amazon API Gateway

Configurazione della registrazione dei log per le API WebSocket in Gateway API

Puoi abilitare la registrazione per scrivere i log in CloudWatch Logs. Esistono sono due tipi di log delle API in CloudWatch: log delle operazioni di esecuzione e log delle operazioni di accesso. Nei log delle operazioni di esecuzione, l'API Gateway gestisce i CloudWatch Logs. Il processo include la creazione di gruppi e flussi di log e la segnalazione ai flussi di log delle richieste e delle risposte dell'intermediario.

Nella registrazione degli accessi, in qualità di sviluppatore dell'API puoi registrare chi ha avuto accesso alla tua API e in che modo l'intermediario ha avuto accesso all'API. Puoi creare un gruppo di log personalizzato o sceglierne uno esistente che potrebbe essere gestito da API Gateway. Per specificare i dettagli di accesso, seleziona variabili $context (espresse in un formato a scelta) e scegli un gruppo di log come destinazione.

Per istruzioni sull'impostazione della registrazione CloudWatch, consulta Configurazione della registrazione dei log delle API di CloudWatch utilizzando la console API Gateway.

Quando specifichi il Log Format (Formato di log), puoi scegliere quali variabili di contesto registrare. Sono supportate le seguenti variabili.

Parametro Descrizione
$context.apiId

Identificatore assegnato da API Gateway all'API.
$context.authorize.error Il messaggio di errore di autorizzazione.
$context.authorize.latency La latenza di autorizzazione in ms.
$context.authorize.status Il codice di stato restituito da un tentativo di autorizzazione.
$context.authorizer.error Il messaggio di errore restituito da un'autorizzazione.
$context.authorizer.integrationLatency La latenza del provider di autorizzazioni Lambda in ms.
$context.authorizer.integrationStatus Il codice di stato restituito da un'autorizzazione Lambda.
$context.authorizer.latency La latenza di autorizzazione in ms.
$context.authorizer.requestId ID richiesta dell'endpoint AWS.
$context.authorizer.status Il codice di stato restituito da un'autorizzazione.
$context.authorizer.principalId

Identificazione dell'utente principale associata al token inviato dal client e restituita da una funzione Lambda del provider di autorizzazioni di Lambda API Gateway. (Un provider di autorizzazioni Lambda in precedenza noto come autorizzazioni ad hoc).
$context.authorizer.property

Valore in formato stringa della coppia chiave/valore specificata della mappa context restituita da una funzione delle autorizzazioni Lambda di API Gateway. Ad esempio, se le autorizzazioni restituiscono la mappa context seguente: 

"context" : {
                            "key": "value",
                            "numKey": 1,
                            "boolKey": true
                            }

la chiamata di $context.authorizer.key restituisce la stringa "value", la chiamata di $context.authorizer.numKey restituisce la stringa "1" e la chiamata di $context.authorizer.boolKey restituisce la stringa "true".
$context.authenticate.error Il messaggio di errore restituito da un tentativo di autenticazione.
$context.authenticate.latency La latenza di autenticazione in ms.
$context.authenticate.status Il codice di stato restituito da un tentativo di autenticazione.
$context.connectedAt

L'ora della connessione in formato Epoch.
$context.connectionId

Un ID univoco per la connessione, che può essere utilizzato per effettuare un callback al client.
$context.domainName

Un nome di dominio per l'API WebSocket. Può essere utilizzato per effettuare un callback al client (invece di un valore codificato).
$context.error.message

Una stringa contenente un messaggio di errore API Gateway.
$context.error.messageString Valore $context.error.message tra virgolette, ovvero "$context.error.message".
$context.error.responseType

Il tipo di risposta di errore.
$context.error.validationErrorString

Stringa contenente un messaggio di errore di convalida dettagliato.
$context.eventType

Il tipo di evento: CONNECT, MESSAGE o DISCONNECT.
$context.extendedRequestId Equivalente a $context.requestId.
$context.identity.accountId

ID account AWS associato alla richiesta.
$context.identity.apiKey

Chiave del proprietario dell'API associata alla richiesta API abilitata dalla chiave.
$context.identity.apiKeyId ID chiave API associato alla richiesta API abilitata dalla chiave
$context.identity.caller

Identificatore dell'entità principale dell'intermediario che ha firmato la richiesta. Supportato per route che utilizzano l'autorizzazione IAM.
$context.identity.cognitoAuthenticationProvider

Un elenco separato da virgole con tutti i provider di autenticazione Amazon Cognito utilizzati dal chiamante che effettua la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito.

Ad esempio, per un'identità di un pool di utenti Amazon Cognito, cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim

Per informazioni sui provider di autenticazione Amazon Cognito disponibili, consulta Using Federated Identities nella Guida per gli sviluppatori di Amazon Cognito.
$context.identity.cognitoAuthenticationType

Tipo di autenticazione Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. I valori possibili includono authenticated per le identità autenticate e unauthenticated per le identità non autenticate.
$context.identity.cognitoIdentityId

ID identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito.
$context.identity.cognitoIdentityPoolId

ID pool di identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito.
$context.identity.principalOrgId

L'ID organizzazione AWS. Supportato per route che utilizzano l'autorizzazione IAM.
$context.identity.sourceIp

Indirizzo IP di origine della connessione TCP da cui proviene la richiesta ad API Gateway.
$context.identity.user

Identificatore dell'entità principale dell'utente che sarà autorizzato per l'accesso alle risorse. Supportato per route che utilizzano l'autorizzazione IAM.
$context.identity.userAgent

Agente utente del chiamante API.
$context.identity.userArn

Amazon Resource Name (ARN) dell'utente valido identificato dopo l'autenticazione.
$context.integration.error Il messaggio di errore restituito da un'integrazione.
$context.integration.integrationStatus Per l'integrazione proxy Lambda, il codice di stato restituito da AWS Lambda, non dal codice della funzione Lambda back-end.
$context.integration.latency Latenza di integrazione in ms. Equivalente a $context.integrationLatency.
$context.integration.requestId ID richiesta dell'endpoint AWS. Equivalente a $context.awsEndpointRequestId.
$context.integration.status Il codice di stato restituito da un'integrazione. Per le integrazioni proxy Lambda, questo è il codice di stato restituito dal codice della funzione Lambda. Equivalente a $context.integrationStatus.
$context.integrationLatency La latenza di integrazione in millisecondi, disponibile solo per il log di accesso.
$context.messageId

Un ID univoco sul lato server per un messaggio. Disponibile solo quando $context.eventType è MESSAGE.
$context.requestId

Come $context.extendedRequestId.
$context.requestTime Ora della richiesta in formato CLF (dd/MMM/yyyy:HH:mm:ss +-hhmm).
$context.requestTimeEpoch L'ora della richiesta in formato epoca (Unix epoch) in millisecondi.
$context.routeKey

La chiave di instradamento selezionata.
$context.stage

Fase di distribuzione della chiamata API, ad esempio, beta o di produzione.
$context.status

Lo stato della risposta.
$context.waf.error Il messaggio di errore restituito da AWS WAF.
$context.waf.latency La latenza AWS WAF in ms.
$context.waf.status Il codice di stato restituito da AWS WAF.

Esempi di alcuni formati di log delle operazioni di accesso utilizzati con maggiore frequenza sono mostrati nella console API Gateway ed elencati qui di seguito.

  • 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

    I caratteri di continuazione (\) sono intesi come un aiuto visivo. Il formato del registro deve essere una singola riga. È possibile aggiungere un carattere di nuova riga (\n) alla fine del formato di registro per includere una nuova riga alla fine di ogni voce di registro.

  • 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"
}

    I caratteri di continuazione (\) sono intesi come un aiuto visivo. Il formato del registro deve essere una singola riga. È possibile aggiungere un carattere di nuova riga (\n) alla fine del formato di registro per includere una nuova riga alla fine di ogni voce di registro.

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

    I caratteri di continuazione (\) sono intesi come un aiuto visivo. Il formato del registro deve essere una singola riga. È possibile aggiungere un carattere di nuova riga (\n) alla fine del formato di registro per includere una nuova riga alla fine di ogni voce di registro.

  • CSV (valori separati da virgola):

    $context.identity.sourceIp,$context.identity.caller, \
$context.identity.user,$context.requestTime,$context.eventType, \
$context.routeKey,$context.connectionId,$context.status, \
$context.requestId

    I caratteri di continuazione (\) sono intesi come un aiuto visivo. Il formato del registro deve essere una singola riga. È possibile aggiungere un carattere di nuova riga (\n) alla fine del formato di registro per includere una nuova riga alla fine di ogni voce di registro.