Variabili per la registrazione dei log degli accessi per Gateway API - Amazon API Gateway

Variabili per la registrazione dei log degli accessi per Gateway API

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, è possibile utilizzare le seguenti variabili $context con distinzione tra maiuscole e minuscole.

Per l’elenco di tutte le variabili di riferimento per le trasformazioni dei dati, consultare Variabili per le trasformazioni dei dati per Gateway API.

Parametro Descrizione
$context.accountId

L'ID dell'account AWS del proprietario dell'API.
$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.claims.property

Proprietà delle richieste restituite dal pool di utenti di Amazon Cognito dopo che l'intermediario del metodo viene autenticato correttamente. Per ulteriori informazioni, consulta Controllo degli accessi alle REST API utilizzando pool di utenti di Amazon Cognito come sistema di autorizzazione.

Nota

La chiamata di $context.authorizer.claims restituisce null.
$context.authorizer.error Il messaggio di errore restituito da un'autorizzazione.
$context.authorizer.integrationLatency Latenza di integrazione del sistema di autorizzazione 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.principalId

Identificazione dell'utente dell'entità principale associata al token inviata dal client e restituita da un'autorizzazione Lambda in API Gateway (precedentemente noto come autorizzazione ad hoc). Per ulteriori informazioni, consulta Uso di autorizzazioni Lambda di API Gateway.
$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".

Per property, l'unico carattere speciale supportato è il trattino basso (_).

Per ulteriori informazioni, consulta Uso di autorizzazioni Lambda di API Gateway.
$context.authorizer.requestId ID richiesta dell'endpoint AWS.
$context.authorizer.status Il codice di stato restituito da un'autorizzazione.
$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.awsEndpointRequestId

ID richiesta dell'endpoint AWS.
$context.customDomain.basePathMatched

Il percorso per una mappatura API a cui corrisponde una richiesta in ingresso. Applicabile quando un client utilizza un nome di dominio personalizzato per accedere a un'API. Ad esempio, se un client invia una richiesta a https://api.example.com/v1/orders/1234 e la richiesta corrisponde alla mappatura API con il percorso v1/orders, il valore è v1/orders. Per ulteriori informazioni, consulta Utilizzo delle mappature API per connettere le fasi API a un nome di dominio personalizzato per REST API.
$context.customDomain.routingRuleIdMatched

La regola di routing a cui corrisponde una richiesta in ingresso. Applicabile quando un client utilizza un nome di dominio personalizzato per accedere a un'API. Per ulteriori informazioni, consulta Regole di routing per connettere le fasi API a un nome di dominio personalizzato per REST API.
$context.deploymentId

ID dell'implementazione API.
$context.domainName

Nome di dominio completo usato per richiamare l'API. Deve essere lo stesso dell'intestazione Host in ingresso.
$context.domainPrefix

Prima etichetta di $context.domainName.
$context.endpointType

Il tipo di endpoint dell'API.
$context.error.message

Stringa contenente un messaggio di errore di API Gateway. Questa variabile può essere usata solo per semplici sostituzioni di variabili in un modello di mappatura del corpo GatewayResponse, che non viene elaborato dal motore Velocity Template Language e nella registrazione degli accessi. Per ulteriori informazioni, consultare Monitoraggio dell'esecuzione dell'API WebSocket con le metriche CloudWatch e Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori.
$context.error.messageString Valore $context.error.message tra virgolette, ovvero "$context.error.message".
$context.error.responseType

Tipo di GatewayResponse. Questa variabile può essere usata solo per semplici sostituzioni di variabili in un modello di mappatura del corpo GatewayResponse, che non viene elaborato dal motore Velocity Template Language e nella registrazione degli accessi. Per ulteriori informazioni, consultare Monitoraggio dell'esecuzione dell'API WebSocket con le metriche CloudWatch e Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori.
$context.error.validationErrorString

Stringa contenente un messaggio dettagliato di errore di convalida.
$context.extendedRequestId ID esteso generato da API Gateway e assegnato alla richiesta API. L’ID della richiesta esteso contiene ulteriori informazioni utili per il debug e la risoluzione dei problemi.
$context.httpMethod

Metodo HTTP usato. I valori validi sono: DELETE, GET, HEAD, OPTIONS, PATCH, POST e PUT.
$context.identity.accountId

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

Per i metodi API che richiedono una chiave API, questa variabile è la chiave API associata alla richiesta del metodo. Per i metodi che non richiedono una chiave API, questa variabile è null. Per ulteriori informazioni, consulta Piani di utilizzo e chiavi API per REST API in Gateway API.
$context.identity.apiKeyId ID chiave API associato a una richiesta API che richiede una chiave API.
$context.identity.caller

Identificatore dell'entità principale dell'intermediario che ha firmato la richiesta. Supportato per risorse 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.
$context.identity.sourceIp

L'indirizzo IP di origine della connessione TCP immediata da cui proviene la richiesta all'endpoint di Gateway API.
$context.identity.clientCert.clientCertPem

Certificato client codificato PEM che il client ha presentato durante l'autenticazione TLS reciproca. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce.
$context.identity.clientCert.subjectDN

Nome distinto dell'oggetto del certificato presentato da un client. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce.
$context.identity.clientCert.issuerDN

Nome distinto dell'approvatore del certificato presentato da un cliente. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce.
$context.identity.clientCert.serialNumber

Il numero di serie del certificato. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce.
$context.identity.clientCert.validity.notBefore

La data prima della quale il certificato non è valido. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce.
$context.identity.clientCert.validity.notAfter

La data dopo la quale il certificato non è valido. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce.
$context.identity.vpcId

L'ID VPC del VPC da cui proviene la richiesta all'endpoint Gateway API.
$context.identity.vpceId

L'ID endpoint VPC dell'endpoint VPC da cui proviene la richiesta all'endpoint Gateway API. Presente solo quando si dispone di un'API privata.
$context.identity.user

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

Intestazione User-Agent del chiamante API.
$context.identity.userArn

Amazon Resource Name (ARN) dell'utente valido identificato dopo l'autenticazione. Per ulteriori informazioni, consulta https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html.
$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.
$context.integrationLatency Latenza di integrazione in ms.
$context.integrationStatus Per l'integrazione proxy Lambda, questo parametro rappresenta il codice di stato restituito da AWS Lambda, non dal codice della funzione Lambda di back-end.
$context.isCanaryRequest

Restituisce true se la richiesta era indirizzata al canary e false se la richiesta non era indirizzata al canary. Presente solo quando è abilitato un canary.
$context.path Percorso della richiesta. Ad esempio, per un URL di richiesta non proxy https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child, il valore di $context.path è /{stage}/root/child.
$context.protocol Protocollo della richiesta, ad esempi, HTTP/1.1.
Nota

Le API di API Gateway possono accettare richieste HTTP/2, ma API Gateway invia le richieste alle integrazioni di backend utilizzando HTTP/1.1. Di conseguenza, il protocollo di richiesta viene registrato come HTTP/1.1 anche se un client invia una richiesta che utilizza HTTP/2.
$context.requestId

L'ID della richiesta. I client possono sovrascrivere questo ID di richiesta. Utilizza $context.extendedRequestId per un ID di richiesta univoco generato da API Gateway.
$context.requestOverride.header.header_name

Sovrascrittura intestazione della richiesta. Se definito, questo parametro contiene le intestazioni da utilizzare al posto delle intestazioni HTTP che sono definite nel riquadro Integration Request (Richiesta di integrazione). Per ulteriori informazioni, consulta Sostituzione dei parametri della richiesta e della risposta e dei codici di stato per REST API in Gateway API.
$context.requestOverride.path.path_name

Sovrascrittura percorso della richiesta. Se definito, questo parametro contiene il percorso della richiesta da utilizzare al posto dei parametri di percorso URL che sono definiti nel riquadro Integration Request (Richiesta di integrazione). Per ulteriori informazioni, consulta Sostituzione dei parametri della richiesta e della risposta e dei codici di stato per REST API in Gateway API.
$context.requestOverride.querystring.querystring_name

Sovrascrittura stringa di query della richiesta. Se definito, questo parametro contiene la stringa di query della richiesta da utilizzare al posto dei URL Query String Parameters (Parametri stringa di query URL) che sono definiti nel riquadro Integration Request (Richiesta di integrazione). Per ulteriori informazioni, consulta Sostituzione dei parametri della richiesta e della risposta e dei codici di stato per REST API in Gateway API.
$context.responseLatency Latenza della risposta in ms.
$context.responseLength Lunghezza del payload della risposta in byte.
$context.responseOverride.header.header_name Sovrascrittura intestazione della risposta. Se definito, questo parametro contiene l'intestazione da restituire al posto della Response header (Intestazione di risposta) che è definita come la Default mapping (mappatura predefinita) nel riquadro Integration Response (Risposta integrazione). Per ulteriori informazioni, consulta Sostituzione dei parametri della richiesta e della risposta e dei codici di stato per REST API in Gateway API.
$context.responseOverride.status Sovrascrittura codice di stato della risposta. Se definito, questo parametro contiene il codice di stato da restituire al posto di Method response status (Stato risposta metodo) che è definito come la Default mapping (Mappatura predefinita) nel riquadro Integration Response (Risposta integrazione). Per ulteriori informazioni, consulta Sostituzione dei parametri della richiesta e della risposta e dei codici di stato per REST API in Gateway API.
$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.resourceId

Identificatore assegnato da API Gateway alla risorsa.
$context.resourcePath

Percorso della risorsa. Ad esempio, per l'URI della richiesta non proxy di https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child, il valore di $context.resourcePath è /root/child. Per ulteriori informazioni, consulta Tutorial: creazione di una REST API con un'integrazione non proxy HTTP.

$context.stage

La fase di distribuzione della richiesta API (ad esempio Beta o Prod).
$context.status Stato della risposta del metodo.
$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.
$context.xrayTraceId

L'ID della traccia di X-Ray. Per ulteriori informazioni, consulta Configurazione di AWS X-Ray con REST API di Gateway API.
$context.wafResponseCode

La risposta ricevuta da AWS WAF: WAF_ALLOW o WAF_BLOCK. Non verrà impostata se la fase non è associata a un ACL Web. Per ulteriori informazioni, consulta Utilizzo di AWS WAF per proteggere le REST API in Gateway API.
$context.webaclArn

ARN completo della lista di controllo accessi Web usata per stabilire se consentire o bloccare la richiesta. Non verrà impostata se la fase non è associata a un ACL Web. Per ulteriori informazioni, consulta Utilizzo di AWS WAF per proteggere le REST API in Gateway API.