# Transformaciones de datos para las API de WebSocket en API Gateway En API Gateway, una solicitud de método de API de WebSocket puede aceptar una carga en un formato diferente del de la carga de la solicitud de integración, según requiera el backend. Del mismo modo, el backend puede devolver una carga de respuesta de integración diferente de la carga de respuesta del método que espera el frontend. API Gateway le permite utilizar transformaciones de plantillas de asignación para asignar la carga útil de una solicitud de método a la solicitud de integración correspondiente y de una respuesta de integración a la respuesta de método correspondiente. Cree una plantilla de asignación y especifique una expresión de selección de plantilla para determinar qué plantilla se utilizará para realizar las transformaciones de datos necesarias. Puede utilizar asignaciones de datos para asignar datos de una [solicitud de ruta](api-gateway-basic-concept.md#apigateway-definition-route-request) a una integración con backend. Para obtener más información, consulte [Configuración de asignación de datos para las API de WebSocket en API Gateway](websocket-api-data-mapping.md). ## Plantillas y modelos de asignación Una *plantilla de asignación* es un script expresado en [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) que se aplica a la carga mediante [expresiones JSONPath](https://goessner.net/articles/JsonPath/). Para obtener más información acerca de las plantillas de mapeo de API Gateway, consulte [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md). La carga puede tener un *modelo de datos* de acuerdo con el [esquema JSON, borrador 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04). No tiene que definir un modelo para crear una plantilla de asignación. Sin embargo, un modelo puede ayudarle a crear una plantilla porque API Gateway genera un esquema de plantilla basado en un modelo proporcionado. Para obtener más información acerca de los modelos de API Gateway, consulte [Modelos de datos para las API de REST](models-mappings-models.md). ## Expresiones de selección de plantilla Para transformar una carga con una plantilla de mapeo, especifique una expresión de selección de plantilla de API de WebSocket en una [solicitud de integración](apigateway-websocket-api-integration-requests.md) o [respuesta de integración](apigateway-websocket-api-integration-responses.md). Esta expresión se evalúa para determinar la plantilla de entrada o de salida (si procede) que se va a utilizar para transformar ya sea el cuerpo de la solicitud en el cuerpo de la solicitud de integración (a través de una plantilla de entrada) o el cuerpo de la respuesta de integración en el cuerpo de la respuesta de ruta (a través de una plantilla de salida). `Integration.TemplateSelectionExpression` admite `${request.body.jsonPath}` y valores estáticos. `IntegrationResponse.TemplateSelectionExpression` admite `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}` y valores estáticos. ## Expresiones de selección de respuesta de integración Al [configurar una respuesta de integración](apigateway-websocket-api-integration-responses.md) para una API de WebSocket, puede especificar si lo desea una expresión de selección de respuesta de integración. Esta expresión determina qué valor de `[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)` debe seleccionarse cuando regresa una integración. El valor de esta expresión se encuentra actualmente restringido por API Gateway, tal y como se define a continuación. Tenga en cuenta que esta expresión solo se aplica a las *integraciones que no sean de proxy*; una integración de proxy simplemente transfiere la carga de respuesta de vuelta al intermediario sin realizar ningún modelado ni modificación. A diferencia del resto de expresiones de selección precedentes, actualmente esta expresión admite un formato de *coincidencia de patrones*. La expresión debe encerrarse entre barras inclinadas. Actualmente, el valor es fijo en función de la propiedad `[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)`: + Para integraciones basadas en Lambda, es `$integration.response.body.errorMessage`. + En las integraciones `HTTP` y `MOCK`, es `$integration.response.statuscode`. + En `HTTP_PROXY` y `AWS_PROXY`, la expresión no se utiliza, ya que se está solicitando que la carga pase hacia el intermediario. # Configuración de asignación de datos para las API de WebSocket en API Gateway La *asignación de datos* le permite asignar datos de una [solicitud de ruta](api-gateway-basic-concept.md#apigateway-definition-route-request) a una integración del backend. **nota** El mapeo de datos para las API de WebSocket no se admite en Consola de administración de AWS. Debe utilizar la AWS CLI, AWS CloudFormation o un SDK para configurar la asignación de datos. **Topics** + [Asignar datos de solicitud de ruta a parámetros de solicitud de integración](#websocket-mapping-request-parameters) + [Ejemplos](#websocket-data-mapping-examples) ## Asignar datos de solicitud de ruta a parámetros de solicitud de integración Los parámetros de solicitud de integración se pueden asignar desde cualquier parámetro de solicitud de ruta definido, el cuerpo de la solicitud, variables [`context` o ](api-gateway-mapping-template-reference.md#context-variable-reference) [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) y valores estáticos. En la siguiente tabla se muestran las expresiones de asignación de datos de las solicitudes de integración. En la tabla, *`PARAM_NAME`* es el nombre de un parámetro de solicitud de ruta del tipo de parámetro especificado. Debe coincidir con la expresión regular `'^[a-zA-Z0-9._$-]+$]'`. *JSONPath\$1expression* es una expresión JSONPath para un campo JSON del cuerpo de la solicitud. | Origen de datos asignado | Expresión de asignación | | --- | --- | | Cadena de consulta de solicitud (compatible solo con la ruta \$1connect) | route.request.querystring.PARAM\$1NAME | | Encabezado de solicitud (compatible solo con la ruta \$1connect) | route.request.header.PARAM\$1NAME | | Cadena de consulta de solicitud de varios valores (compatible solo con la ruta \$1connect) | route.request.multivaluequerystring.PARAM\$1NAME | | Encabezado de solicitud de varios valores (solo compatible con la ruta \$1connect) | route.request.multivalueheader.PARAM\$1NAME | | Cuerpo de la solicitud | route.request.body.JSONPath\$1EXPRESSION | | Variables de etapa | stageVariables.VARIABLE\$1NAME | | Variables de contexto | context.VARIABLE\$1NAME que debe ser alguna de las [variables de contexto admitidas](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valor estático | 'STATIC\$1VALUE'. STATIC\$1VALUE es un literal de cadena que se debe incluir entre comillas simples. | Al crear una asignación de datos, mediante la AWS CLI asegúrese de seguir el formato correcto para usar literales con cadenas en la AWS CLI. Para obtener más información, consulte [Uso de entrecomillado y literales con cadenas en la AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) de la *Guía del usuario de AWS Command Line Interface*. ## Ejemplos En los siguientes ejemplos de la AWS CLI se configuran asignaciones de datos. Para obtener una plantilla de CloudFormation, consulte [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip). ### Asignar el connectionId de un cliente a un encabezado en una solicitud de integración El siguiente comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) permite asignar el `connectionId` de un cliente a un encabezado `connectionId` en la solicitud a una integración de backend: ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.connectionId'='context.connectionId' ``` ### Asignar un parámetro de cadena de consulta a un encabezado en una solicitud de integración En el siguiente ejemplo, se asigna un parámetro de cadena de consulta `authToken` a un encabezado `authToken` en la solicitud de integración. 1. Utilice el siguiente comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) para agregar el parámetro de cadena de consulta `authToken` a los parámetros de solicitud de ruta. ``` aws apigatewayv2 update-route --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameters '{"route.request.querystring.authToken": {"Required": false}}' ``` 1. Utilice el siguiente comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) para asignar el parámetro de cadena de consulta al encabezado `authToken` en la solicitud a la integración de backend. ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken' ``` 1. (Opcional) Si es necesario, utilice el siguiente comando [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html) para eliminar el parámetro de cadena de consulta `authToken` de los parámetros de solicitud de ruta. ``` aws apigatewayv2 delete-route-request-parameter \ --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameter-key 'route.request.querystring.authToken' ``` # Referencia de la plantilla de asignación de la API de WebSocket para API Gateway En esta sección se resume el conjunto de variables compatibles actualmente con las API de WebSocket en API Gateway. | Parámetro | Descripción | | --- | --- | | \$1context.connectionId | Identificador único para la conexión que se puede utilizar para realizar una devolución de llamada al cliente. | | \$1context.connectedAt | Hora de la conexión en [formato de tiempo Unix](https://en.wikipedia.org/wiki/Unix_time). | | \$1context.domainName | Nombre de dominio para la API de WebSocket. Se puede utilizar para realizar una devolución de llamada al cliente (en lugar de un valor de código rígido). | | \$1context.eventType | El tipo de evento: `CONNECT`, `MESSAGE` o `DISCONNECT`. | | \$1context.messageId | Un ID único del lado del servidor para un mensaje. Solo está disponible si `$context.eventType` es `MESSAGE`. | | \$1context.routeKey | La clave de ruta seleccionada. | | \$1context.requestId | Igual que `$context.extendedRequestId`. | | \$1context.extendedRequestId | Un ID generado de forma automática para la llamada a la API, que contiene más información útil para la depuración o la resolución de problemas. | | \$1context.apiId | El identificador que API Gateway asigna a su API. | | \$1context.authorizer.principalId | La identificación de usuario principal asociada con el token enviado por el cliente y devuelto de una función de Lambda del autorizador de Lambda de API Gateway (que anteriormente se denominaba “autorizador personalizado”). | | \$1context.authorizer.property | El valor en forma de cadena del par clave-valor especificado de la asignación `context` que devuelve la función de Lambda del autorizador de Lambda de API Gateway. Por ejemplo, si el autorizador devuelve la siguiente asignación de `context`: 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
la llamada a `$context.authorizer.key` devuelve la cadena `"value"`, la llamada a `$context.authorizer.numKey` devuelve la cadena `"1"` y la llamada a `$context.authorizer.boolKey` devuelve la cadena `"true"`. | | \$1context.error.messageString | El valor entrecomillado de \$1context.error.message, es decir, "\$1context.error.message". | | \$1context.error.validationErrorString | Una cadena que contiene un mensaje de error de validación detallado. | | \$1context.identity.accountId | El ID de cuenta de AWS asociado con la solicitud. | | \$1context.identity.apiKey | Clave del propietario de API asociada a la solicitud de API habilitada para claves. | | \$1context.identity.apiKeyId | ID de clave de API asociado a la solicitud de API habilitada para claves | | \$1context.identity.caller | El identificador principal del intermediario que realiza la solicitud. | | \$1context.identity.cognitoAuthenticationProvider | Una lista separada por comas de todos los proveedores de autenticación de Amazon Cognito utilizados por el intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. Por ejemplo, para una identidad de un grupo de usuarios de Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Consulte [Uso de las identidades federadas](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) en la *Guía para desarrolladores de Amazon Cognito* para obtener información sobre los proveedores de autenticación de Amazon Cognito disponibles. | | \$1context.identity.cognitoAuthenticationType | El tipo de autenticación de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. Los valores posibles incluyen `authenticated` para identidades autenticadas y `unauthenticated` para identidades no autenticadas. | | \$1context.identity.cognitoIdentityId | El ID de identidad de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. | | \$1context.identity.cognitoIdentityPoolId | El ID del grupo de identidades de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. | | \$1context.identity.sourceIp | La dirección IP de origen de la conexión TCP inmediata que realiza la solicitud al punto de enlace de API Gateway. | | \$1context.identity.user | El identificador principal del usuario que realiza la solicitud. | | \$1context.identity.userAgent | El agente de usuario del intermediario de la API. | | \$1context.identity.userArn | El Nombre de recurso de Amazon (ARN) del usuario identificado después de la autenticación. | | \$1context.requestTime | Hora de la solicitud en formato [CLF](https://httpd.apache.org/docs/current/logs.html#common)-(dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | Hora de la solicitud en formato [Epoch](https://en.wikipedia.org/wiki/Unix_time) en milisegundos. | | \$1context.stage | La etapa de implementación de la llamada a la API (por ejemplo, Beta o Prod). | | \$1context.status | Estado de la respuesta. | | \$1input.body | Devuelve la carga bruta como una cadena. | | \$1input.json(x) | Esta función evalúa una expresión JSONPath y devuelve los resultados como una cadena JSON. Por ejemplo, `$input.json('$.pets')` devolverá una cadena JSON que representa la estructura de "pets" (mascotas). Para obtener más información acerca de JSONPath, consulte [JSONPath](https://goessner.net/articles/JsonPath/) o [JSONPath for Java](https://github.com/json-path/JsonPath). | | \$1input.path(x) | Toma una cadena de expresión JSONPath (`x`) y devuelve una representación del resultado en forma de objeto JSON. Esto le permite tener acceso y manipular los elementos de la carga de forma nativa en [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Por ejemplo, si la expresión `$input.path('$.pets')` devuelve un objeto como este: 
[
  { 
    "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()` devolvería `"3"`. Para obtener más información acerca de JSONPath, consulte [JSONPath](http://goessner.net/articles/JsonPath/) o [JSONPath for Java](https://github.com/jayway/JsonPath). | | \$1stageVariables. | ** representa un nombre de variable de etapa. | | \$1stageVariables[''] | ** representa cualquier nombre de variable de etapa. | | \$1\$1stageVariables['']\$1 | ** representa cualquier nombre de variable de etapa. | | \$1util.escapeJavaScript() | Aplica caracteres de escape a los caracteres de una cadena usando reglas de cadena de JavaScript. Esta función convertirá todas las comillas simples (`'`) en caracteres de escape (`\'`). Sin embargo, JSON no admite comillas simples con caracteres de escape. Por lo tanto, cuando la salida de esta función se utiliza en una propiedad de JSON, debe convertir todas las comillas simples con caracteres de escape (`\'`) en comillas simples normales (`'`). Esto se muestra en el siguiente ejemplo: 
 $util.escapeJavaScript(data).replaceAll("\\'","'")
| | \$1util.parseJson() | Toma un elemento JSON en forma de cadena y devuelve una representación del resultado en forma de objeto. Puede utilizar el resultado de esta función para tener acceso y manipular los elementos de la carga de forma nativa en Apache Velocity Template Language (VTL). Por ejemplo, si tiene la siguiente carga: 
{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}
y usa la siguiente plantilla de asignación 
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Obtendrá el siguiente resultado: 
{
   "errorMessageObjKey2ArrVal" : 1
}
| | \$1util.urlEncode() | Convierte una cadena en formato "application/x-www-form-urlencoded". | | \$1util.urlDecode() | Descodifica una cadena "application/x-www-form-urlencoded". | | \$1util.base64Encode() | Codifica los datos en una cadena codificada en base64. | | \$1util.base64Decode() | Descodifica los datos de una cadena codificada en base64. |