Variabili per le trasformazioni dei dati per Gateway API - Amazon API Gateway
Variabili di contesto per le trasformazioni dei datiVariabili inputVariabili di faseVariabili util

Variabili per le trasformazioni dei dati per Gateway API

Quando si crea una mappatura dei parametri, è possibile utilizzare le variabili di contesto come origine dati. Per creare le trasformazioni di modelli di mappatura, è possibile utilizzare variabili di contesto, input e util negli script scritti in Velocity Template Language (VTL). Per modelli di mappatura di esempio che utilizzano queste variabili di riferimento, consultare Esempi di utilizzo di variabili per trasformazioni dei modelli di mappatura per Gateway API.

Per l’elenco delle variabili di riferimento per la registrazione degli accessi, consultare Variabili per la registrazione dei log degli accessi per Gateway API.

Variabili di contesto per le trasformazioni dei dati

È possibile utilizzare le seguenti variabili $context con distinzione tra maiuscole e minuscole per le trasformazioni dei dati.

Parametro Descrizione
$context.accountId

L'ID dell'account AWS del proprietario dell'API.
$context.apiId

Identificatore assegnato da API Gateway all'API.
$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, consultare 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.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, consultare 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, consultare Uso di autorizzazioni Lambda di API Gateway.
$context.awsEndpointRequestId

ID richiesta dell'endpoint AWS.
$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.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, consultare 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, consultare https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html.
$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, consultare 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, consultare 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, consultare Sostituzione dei parametri della richiesta e della risposta e dei codici di stato per REST API in Gateway API.
$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, consultare 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, consultare 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, consultare 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.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, consultare 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, consultare Utilizzo di AWS WAF per proteggere le REST API in Gateway API.

Variabili input

È possibile utilizzare le seguenti variabili $input con distinzione tra maiuscole e minuscole per fare riferimento ai parametri e al payload della richiesta di metodo. Sono disponibili le funzioni seguenti:

Variabile e funzione Descrizione
$input.body

Restituisce il payload della richiesta non elaborata come stringa. È possibile utilizzare $input.body per conservare interi numeri in virgola mobile, ad esempio 10.00.
$input.json(x)

Questa funzione valuta un'espressione JSONPath e restituisce i risultati come stringa JSON.

Ad esempio, $input.json('$.pets') restituisce una stringa JSON che rappresenta la struttura pets.

Per ulteriori informazioni su JSONPath, consulta la pagina relativa a JSONPath o JSONPath per Java.
$input.params()

Restituisce una mappa di tutti i parametri della richiesta. Si consiglia di utilizzare $util.escapeJavaScript per sanificare il risultato ed evitare un potenziale attacco di iniezione. Per il pieno controllo della sanificazione delle richieste, utilizzare un'integrazione proxy senza un modello e gestire la sanificazione delle richieste nell'integrazione.
$input.params(x)

Restituisce il valore di un parametro della richiesta del metodo dal percorso, dalla stringa di query o dal valore dell'intestazione (cercati in questo ordine) a partire da una stringa del nome del parametro x. Si consiglia di utilizzare $util.escapeJavaScript per sanificare il parametro ed evitare un potenziale attacco di iniezione. Per il controllo completo della sanificazione dei parametri, utilizzare un'integrazione proxy senza un modello e gestire la sanificazione delle richieste nell'integrazione.
$input.path(x)

Da una stringa di espressione JSONPath (x) restituisce una rappresentazione di oggetto JSON del risultato. In questo modo, puoi accedere agli elementi del payload e modificarli in modo nativo in Apache Velocity Template Language (VTL).

Ad esempio, se l'espressione $input.path('$.pets') restituisce un oggetto in questo modo:

[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]

$input.path('$.pets').size() restituisce "3".

Per ulteriori informazioni su JSONPath, consulta la pagina relativa a JSONPath o JSONPath per Java.

Variabili di fase

È possibile utilizzare le seguenti variabili di fase come segnaposto per ARN e URL nelle integrazioni di metodo. Per ulteriori informazioni, consultare Utilizzo delle variabili di fase per una REST API in Gateway API.

Sintassi Descrizione
$stageVariables.variable_name, $stageVariables['variable_name'] o ${stageVariables['variable_name']}

variable_name rappresenta il nome di una variabile di fase.

Variabili util

È possibile utilizzare le seguenti variabili $util con distinzione tra maiuscole e minuscole per usare le funzioni di utilità per i modelli di mappatura. Se non diversamente specificato, il set di caratteri predefinito è UTF-8.

Funzione Descrizione
$util.escapeJavaScript()

Aggiunge caratteri di escape ai caratteri in una stringa usando le regole delle stringhe JavaScript.

Nota

Questa funzione trasforma qualsiasi virgoletta singola (') in virgoletta preceduta da un carattere escape (\'). Tuttavia, le virgolette singole con escape non sono valide in JSON. Di conseguenza, quando l'output di questa funzione viene usato in una proprietà JSON, devi modificare di nuovo qualsiasi virgoletta singola con carattere escape (\') in virgoletta singola normale ('). Questo viene mostrato nell'esempio seguente: 

 "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"
$util.parseJson()

Da una stringa JSON restituisce una rappresentazione oggetto del risultato. Puoi usare il risultato di questa funzione per accedere agli elementi del payload e modificarli in modo nativo in Apache Velocity Template Language (VTL). Ad esempio, in presenza del payload seguente: 

{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}

E se usi il modello di mappatura seguente: 

#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}

Otterrai l'output seguente:

{
   "errorMessageObjKey2ArrVal" : 1
}
$util.urlEncode()

Converte una stringa nel formato "application/x-www-form-urlencoded".
$util.urlDecode()

Decodifica una stringa "application/x-www-form-urlencoded".
$util.base64Encode()

Codifica i dati in una stringa con codifica base64.
$util.base64Decode()

Decodifica i dati da una stringa con codifica base64.