Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Trasformazioni dei dati per API WebSocket APIs Gateway In API Gateway, la richiesta del metodo di un' WebSocket API può accettare un payload in un formato diverso dal payload della richiesta di integrazione corrispondente, come richiesto nel backend. Analogamente, il back-end potrebbe restituire un payload delle risposta di integrazione diverso dal payload della risposta di metodo, in base alle aspettative del front-end. Gateway API consente di utilizzare le trasformazioni dei modelli di mappatura per mappare il payload da una richiesta di metodo alla richiesta di integrazione corrispondente e da una risposta di integrazione alla corrispondente risposta di metodo. Si crea un modello di mappatura e si specifica un’espressione di selezione del modello per determinare quale modello utilizzare per eseguire le trasformazioni dei dati necessarie. È possibile utilizzare le mappature dei dati per mappare i dati da una [richiesta di instradamento](api-gateway-basic-concept.md#apigateway-definition-route-request) a un'integrazione back-end. Per ulteriori informazioni, consulta [Configurare la mappatura dei dati per API WebSocket APIs Gateway](websocket-api-data-mapping.md). ## Modelli di mappatura e modelli [Un *modello di mappatura* è uno script espresso in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) e applicato al payload utilizzando espressioni. JSONPath ](https://goessner.net/articles/JsonPath/) Per ulteriori informazioni sui modelli di mappatura API Gateway, consulta [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). Il payload può avere un *modello di dati* in base alla [bozza 4 dello schema JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04). Per generare un modello di mappatura, non è necessario definire un modello. Tuttavia, un modello può essere utile per crearne un altro, poiché API Gateway genera un piano di modello in base a un modello fornito. Per ulteriori informazioni sui modelli API Gateway, consulta [Modelli di dati per REST APIs](models-mappings-models.md). ## Espressioni di selezione del modello [[Per trasformare un payload con un modello di mappatura, è necessario specificare un'espressione di selezione del modello WebSocket API in una richiesta di integrazione o in una risposta di integrazione.](apigateway-websocket-api-integration-responses.md)](apigateway-websocket-api-integration-requests.md) Questa espressione viene valutata per determinare il modello di input o di output (se disponibili) da usare per trasformare il corpo della richiesta nel corpo della richiesta di integrazione (tramite un modello di input) o il corpo della risposta di integrazione nel corpo della risposta di instradamento (tramite un modello di output). `Integration.TemplateSelectionExpression` supporta `${request.body.jsonPath}` e valori statici. `IntegrationResponse.TemplateSelectionExpression` supporta `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}` e valori statici. ## Espressioni di selezione della risposta di integrazione Quando [imposti una risposta di integrazione per un'](apigateway-websocket-api-integration-responses.md) WebSocket API, puoi facoltativamente specificare un'espressione di selezione della risposta di integrazione. Questa espressione determina quale `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)` deve essere selezionata quando viene restituita un'integrazione. Il valore di questa espressione è attualmente limitato da API Gateway, come definito di seguito. Tieni presente che questa espressione è rilevante solo per le *integrazioni non proxy*; un'integrazione proxy restituisce semplicemente il payload della risposta all'intermediario senza alcuna modellazione o modifica. A differenza di altre espressioni di selezione precedenti, questa espressione supporta attualmente un formato di *corrispondenza di modelli*. L'espressione deve essere racchiusa tra barre. Attualmente il valore è fisso e dipende dal valore di `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)`: + Per le integrazioni basate su Lambda, è `$integration.response.body.errorMessage`. + Per le integrazioni `HTTP` e `MOCK`, è `$integration.response.statuscode`. + Per `HTTP_PROXY` e `AWS_PROXY`, l'espressione non viene utilizzata poiché si richiede che il payload raggiunga il chiamante. # Configurare la mappatura dei dati per API WebSocket APIs Gateway La *mappatura dei dati* consente di mappare i dati da una [richiesta di instradamento](api-gateway-basic-concept.md#apigateway-definition-route-request) a un'integrazione back-end. **Nota** La mappatura dei dati per WebSocket APIs non è supportata in. Console di gestione AWSÈ necessario utilizzare AWS CLI AWS CloudFormation, o un SDK per configurare la mappatura dei dati. **Topics** + [Come mappare i dati di richiesta di instradamento ai parametri di richiesta di integrazione](#websocket-mapping-request-parameters) + [Esempi](#websocket-data-mapping-examples) ## Come mappare i dati di richiesta di instradamento ai parametri di richiesta di integrazione I parametri della richiesta di integrazione possono essere mappati da tutti i parametri di richiesta di instradamento definiti, dal corpo della richiesta [`context` o ](api-gateway-mapping-template-reference.md#context-variable-reference) dalle variabili [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) e dai valori statici. La tabella seguente mostra le espressioni di mappatura dei dati delle richieste di integrazione. Nella tabella *`PARAM_NAME`* è il nome del parametro di una richiesta di instradamento del tipo di parametro specifico. Deve corrispondere all'espressione regolare. `'^[a-zA-Z0-9._$-]+$]'` *JSONPath\$1EXPRESSION*è un' JSONPath espressione per un campo JSON del corpo della richiesta. | Origine dati mappata | Espressione di mappatura | | --- | --- | | Stringa di query di richiesta (supportata solo per l'instradamento \$1connect) | route.request.querystring.PARAM\$1NAME | | Intestazione della richiesta (supportata solo per l'instradamento \$1connect) | route.request.header.PARAM\$1NAME | | Stringa di query della richiesta a più valori (supportata solo per l'instradamento \$1connect) | route.request.multivaluequerystring.PARAM\$1NAME | | Intestazione della richiesta a più valori (supportata solo per l'instradamento \$1connect) | route.request.multivalueheader.PARAM\$1NAME | | Corpo di richiesta | route.request.body.JSONPath\$1EXPRESSION | | Variabili di fase | stageVariables.VARIABLE\$1NAME | | Variabili di contesto | context.VARIABLE\$1NAME che deve essere una delle [variabili di contesto supportate](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valore statico | 'STATIC\$1VALUE'. La STATIC\$1VALUE è una stringa letterale e deve essere racchiusa tra virgolette singole. | Quando crei una mappatura dei dati, AWS CLI assicurati di seguire il formato corretto per utilizzare i valori letterali con stringhe in. AWS CLI Per ulteriori informazioni, consulta [Using quotation marks and literals with strings in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) nella *Guida per l’utente di AWS Command Line Interface *. ## Esempi I seguenti AWS CLI esempi configurano le mappature dei dati. Per un CloudFormation modello di esempio, vedere. [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip) ### Mappare connectionId di un client a un'intestazione in una richiesta di integrazione Il comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) seguente mappa `connectionId` di un client a un’intestazione `connectionId` nella richiesta a un’integrazione backend. ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.connectionId'='context.connectionId' ``` ### Mappatura di un parametro di stringa di query a un'intestazione in una richiesta di integrazione Il seguente esempio mappa un parametro della stringa di query `authToken` a un’intestazione `authToken` nella richiesta di integrazione. 1. Utilizza il seguente comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) per aggiungere il parametro della stringa di query `authToken` ai parametri della richiesta di instradamento. ``` aws apigatewayv2 update-route --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameters '{"route.request.querystring.authToken": {"Required": false}}' ``` 1. Utilizza il seguente comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) per mappare il parametro della stringa di query all’intestazione `authToken` nella richiesta di integrazione backend. ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken' ``` 1. (Facoltativo) Se necessario, utilizzate quanto segue [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html)per eliminare il parametro della stringa di `authToken` query dai parametri di richiesta del percorso. ``` aws apigatewayv2 delete-route-request-parameter \ --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameter-key 'route.request.querystring.authToken' ``` # WebSocket Riferimento al modello di mappatura delle API per API Gateway Questa sezione riassume l'insieme di variabili attualmente supportate WebSocket APIs in API Gateway. | Parametro | Descrizione | | --- | --- | | \$1context.connectionId | Un ID univoco per la connessione, che può essere utilizzato per effettuare un callback al client. | | \$1context.connectedAt | L'ora della connessione in formato [Epoch](https://en.wikipedia.org/wiki/Unix_time). | | \$1context.domainName | Un nome di dominio per l' WebSocket API. Può essere utilizzato per effettuare un callback al client (invece di un valore hardcoded). | | \$1context.eventType | Il tipo di evento: `CONNECT`, `MESSAGE` o `DISCONNECT`. | | \$1context.messageId | Un ID univoco sul lato server per un messaggio. Disponibile solo quando `$context.eventType` è `MESSAGE`. | | \$1context.routeKey | La chiave di instradamento selezionata. | | \$1context.requestId | Come `$context.extendedRequestId`. | | \$1context.extendedRequestId | Un ID generato automaticamente per la chiamata API, che contiene ulteriori informazioni utili per il debug/la risoluzione dei problemi. | | \$1context.apiId | Identificatore assegnato da API Gateway all'API. | | \$1context.authorizer.principalId | Identificazione dell'utente dell'entità principale associata al token inviato dal client e restituita da una funzione Lambda del provider di autorizzazioni Lambda di API Gateway (noto in precedenza come autorizzazioni ad hoc). | | \$1context.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"`. | | \$1context.error.messageString | Valore \$1context.error.message tra virgolette, ovvero "\$1context.error.message". | | \$1context.error.validationErrorString | Stringa contenente un messaggio dettagliato di errore di convalida. | | \$1context.identity.accountId | L'ID AWS dell'account associato alla richiesta. | | \$1context.identity.apiKey | Chiave del proprietario dell'API associata alla richiesta API abilitata dalla chiave. | | \$1context.identity.apiKeyId | ID chiave API associato alla richiesta API abilitata dalla chiave | | \$1context.identity.caller | Identificatore dell'entità principale del chiamante da cui proviene la richiesta. | | \$1context.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](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) nella *Guida per gli sviluppatori di Amazon Cognito*. | | \$1context.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. | | \$1context.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. | | \$1context.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. | | \$1context.identity.sourceIp | L'indirizzo IP di origine della connessione TCP immediata da cui proviene la richiesta all'endpoint di API Gateway. | | \$1context.identity.user | Identificatore dell'entità principale dell'utente da cui proviene la richiesta. | | \$1context.identity.userAgent | Agente utente della chiamata API. | | \$1context.identity.userArn | Amazon Resource Name (ARN) dell'utente valido identificato dopo l'autenticazione. | | \$1context.requestTime | Ora della richiesta in formato [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | L'ora della richiesta in formato [epoca (Unix epoch)](https://en.wikipedia.org/wiki/Unix_time) in millisecondi. | | \$1context.stage | Fase di distribuzione della chiamata API, ad esempio, beta o di produzione. | | \$1context.status | Lo stato della risposta. | | \$1input.body | Restituisce il payload non elaborato come stringa. | | \$1input.json(x) | Questa funzione valuta un' JSONPath espressione e restituisce i risultati come stringa JSON. Ad esempio, `$input.json('$.pets')` restituisce una stringa JSON che rappresenta la struttura di elementi "pet" (animali domestici). Per ulteriori informazioni su JSONPath, vedere [JSONPath](https://goessner.net/articles/JsonPath/)or [JSONPath for](https://github.com/json-path/JsonPath) Java. | | \$1input.path(x) | Accetta una stringa di JSONPath espressione (`x`) e restituisce una rappresentazione in oggetto JSON del risultato. In questo modo, puoi accedere agli elementi del payload e modificarli in modo nativo in [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). 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').count()` restituisce `"3"`. Per ulteriori informazioni su JSONPath, vedere [JSONPath](http://goessner.net/articles/JsonPath/)or [JSONPath for Java](https://github.com/jayway/JsonPath). | | \$1stageVariables. | **rappresenta il nome di una variabile di fase. | | \$1stageVariables[''] | **rappresenta qualsiasi nome di variabile di fase. | | \$1\$1stageVariables['']\$1 | **rappresenta qualsiasi nome di variabile di fase. | | \$1util.escapeJavaScript() | Sfugge ai caratteri di una stringa utilizzando le regole delle JavaScript stringhe. 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: 
 $util.escapeJavaScript(data).replaceAll("\\'","'")
| | \$1util.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
}
| | \$1util.urlEncode() | Converte una stringa nel formato «application/x-www-form-urlencoded». | | \$1util.urlDecode() | Decodifica una stringa «application/». x-www-form-urlencoded | | \$1util.base64Encode() | Codifica i dati in una stringa con codifica base64. | | \$1util.base64Decode() | Decodifica i dati da una stringa con codifica base64. |