Plantilla de mapeo de API Gateway y referencia de la variable de registro de acceso

Modo de enfoque

Plantilla de mapeo de API Gateway y referencia de la variable de registro de acceso - Amazon API Gateway

Variables $context para modelos de datos, autorizadores, plantillas de mapeo y registro de acceso de CloudWatch Ejemplo de plantilla de variable $context Variables $context solo para registro de acceso Variables $input Ejemplos de plantilla de variable $input $stageVariables Variables $util

Esta sección contiene información de referencia para las variables y funciones que Amazon API Gateway define para su uso con modelos de datos, autorizadores, plantillas de mapeo y el registro de acceso de CloudWatch. Para obtener información detallada acerca de cómo utilizar estas variables y funciones, consulte Plantillas de asignación para las API de REST. Para obtener más información sobre Velocity Template Language, consulte la referencia de VTL.

Temas

Variables $context para modelos de datos, autorizadores, plantillas de mapeo y registro de acceso de CloudWatch
Ejemplo de plantilla de variable $context
Variables $context solo para registro de acceso
Variables $input
Ejemplos de plantilla de variable $input
$stageVariables
Variables $util

nota

Para las variables $method y $integration, consulte Referencia de mapeo de datos de solicitud y respuesta de API de Amazon API Gateway.

Variables `$context` para modelos de datos, autorizadores, plantillas de mapeo y registro de acceso de CloudWatch

Es posible utilizar las siguientes variables $context para modelos de datos, autorizadores, plantillas de mapeo y registro de acceso de CloudWatch. API Gateway podría agregar variables de contexto adicionales.

Para las variables $context que solo se pueden usar en el registro de acceso de CloudWatch, consulte Variables $context solo para registro de acceso.

Parámetro	Descripción
`$context.accountId`	El ID de cuenta de AWS del propietario de la API.
`$context.apiId`	El identificador que API Gateway asigna a su API.
`$context.authorizer.claims.property`	Una propiedad de las notificaciones devueltas por el grupo de usuarios de Amazon Cognito una vez que se ha autenticado correctamente al intermediario del método. Para obtener más información, consulte Control del acceso a las API de REST con grupos de usuarios de Amazon Cognito como autorizador. nota La llamada a `$context.authorizer.claims` devuelve null.
`$context.authorizer.principalId`	La identificación de usuario principal asociada con el token enviado por el cliente y devuelto por el autorizador de Lambda de API Gateway (que anteriormente se denominaba autorizador personalizado). Para obtener más información, consulte Uso de autorizadores Lambda de API Gateway.
`$context.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"`. En el caso de la `propiedad`, el único carácter especial admitido es el carácter `(_)` de subrayado. Para obtener más información, consulte Uso de autorizadores Lambda de API Gateway.
`$context.awsEndpointRequestId`	El ID de solicitud del punto de enlace de AWS.
`$context.deploymentId`	El ID de la implementación de la API.
`$context.domainName`	El nombre de dominio completo que se utiliza para invocar la API. Este debe ser el mismo que el encabezado `Host` entrante.
`$context.domainPrefix`	La primera etiqueta del `$context.domainName`.
`$context.error.message`	Una cadena que contiene un mensaje de error de API Gateway. Esta variable solo se puede usar para una sustitución sencilla de variables en una plantilla de mapeo de cuerpo GatewayResponse, que no procesa el motor de Velocity Template Language, y en el registro de acceso. Para obtener más información, consulte Supervisión de la ejecución de la API de WebSocket con métricas de CloudWatch y Configuración de respuestas de gateway para personalizar respuestas de errores.
`$context.error.messageString`	El valor entrecomillado de `$context.error.message`, es decir, `"$context.error.message"`.
`$context.error.responseType`	Un tipo de GatewayResponse. Esta variable solo se puede usar para una sustitución sencilla de variables en una plantilla de mapeo de cuerpo GatewayResponse, que no procesa el motor de Velocity Template Language, y en el registro de acceso. Para obtener más información, consulte Supervisión de la ejecución de la API de WebSocket con métricas de CloudWatch y Configuración de respuestas de gateway para personalizar respuestas de errores.
`$context.error.validationErrorString`	Una cadena que contiene un mensaje de error de validación detallado.
`$context.extendedRequestId`	El ID ampliado que API Gateway genera y asigna a la solicitud de API. El ID de solicitud ampliado contiene información útil para la depuración y la resolución de problemas.
`$context.httpMethod`	El método HTTP utilizado. Los valores válidos son: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` y `PUT`.
`$context.identity.accountId`	El ID de cuenta de AWS asociado con la solicitud.
`$context.identity.apiKey`	Para los métodos de API que necesitan una clave de API, esta variable es la clave de API asociada a la solicitud del método. Para métodos que no requieren una clave de API, esta variable corresponde a valores null. Para obtener más información, consulte Planes de uso y clave de API para las API de REST en API Gateway.
`$context.identity.apiKeyId`	El ID de clave de API asociado a una solicitud de API que requiere una clave de API.
`$context.identity.caller`	El identificador principal del intermediario que firmó la solicitud. Compatible con recursos que utilizan la autorización de IAM.
`$context.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 en la Guía para desarrolladores de Amazon Cognito para obtener información sobre los proveedores de autenticación de Amazon Cognito disponibles.
`$context.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.
`$context.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.
`$context.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.
`$context.identity.principalOrgId`	El ID de organización de AWS.
`$context.identity.sourceIp`	La dirección IP de origen de la conexión TCP inmediata que realiza la solicitud al punto de conexión de API Gateway.
`$context.identity.clientCert.clientCertPem`	El certificado de cliente codificado en PEM que el cliente presentó durante la autenticación TLS mutua. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua.
`$context.identity.clientCert.subjectDN`	Nombre distintivo del asunto del certificado que presenta un cliente. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua.
`$context.identity.clientCert.issuerDN`	Nombre distintivo del emisor del certificado que presenta un cliente. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua.
`$context.identity.clientCert.serialNumber`	Número de serie del certificado. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua.
`$context.identity.clientCert.validity.notBefore`	Fecha antes de la cual el certificado no es válido. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua.
`$context.identity.clientCert.validity.notAfter`	Fecha después de la cual el certificado no es válido. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua.
`$context.identity.vpcId`	El ID de VPC de la VPC que realiza la solicitud al punto de conexión de API Gateway.
`$context.identity.vpceId`	El ID de punto de conexión de VPC del punto de conexión de VPC que realiza la solicitud al punto de conexión de API Gateway. Está presente solo cuando tiene una API privada.
`$context.identity.user`	El identificador principal del usuario que se autorizará a acceder al recurso. Compatible con recursos que utilizan la autorización de IAM.
`$context.identity.userAgent`	El encabezado `User-Agent` del intermediario de la API.
`$context.identity.userArn`	El Nombre de recurso de Amazon (ARN) del usuario identificado después de la autenticación. Para obtener más información, consulte https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html.
`$context.isCanaryRequest`	Devuelve `true` si la solicitud se dirigió al canario y `false` si no se dirigió al canario. Está presente solo cuando tiene un canario activado.
`$context.path`	Ruta de acceso de la solicitud. Por ejemplo, en el caso del URL de una solicitud que no es de proxy `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, el valor de `$context.path` es `/{stage}/root/child`.
`$context.protocol`	Protocolo de la solicitud; por ejemplo, `HTTP/1.1`. nota Las API de API Gateway pueden aceptar solicitudes HTTP/2, pero API Gateway envía solicitudes a las integraciones de backend mediante HTTP/1.1. Como resultado, el protocolo de solicitud se registra como HTTP/1.1 incluso si un cliente envía una solicitud que usa HTTP/2.
`$context.requestId`	ID de la solicitud. Los clientes pueden anular este ID de solicitud. Utilice `$context.extendedRequestId` para un ID de solicitud único que genera API Gateway.
`$context.requestOverride.header.header_name`	La invalidación del encabezado de solicitud. Si este parámetro se define, contiene los encabezados que se utilizarán en lugar de los HTTP Headers (Encabezados HTTP) que se definen en el panel Integration Request (Solicitud de integración). Para obtener más información, consulte Uso de una plantilla de mapeo para invalidar códigos de estado y parámetros de solicitud y de respuesta de una API.
`$context.requestOverride.path.path_name`	La invalidación de la ruta de acceso de la solicitud. Si este parámetro se define, contiene la ruta de acceso de la solicitud que se utilizará en lugar de los URL Path Parameters (Parámetros de ruta URL) que se definen en el panel Integration Request (Solicitud de integración). Para obtener más información, consulte Uso de una plantilla de mapeo para invalidar códigos de estado y parámetros de solicitud y de respuesta de una API.
`$context.requestOverride.querystring.querystring_name`	La invalidación de la cadena de consulta de solicitud. Si este parámetro se define, contiene las cadenas de consulta de solicitud que se utilizarán en lugar de los URL Query String Parameters (Parámetros de cadena de consulta URL) que se definen en el panel Integration Request (Solicitud de integración). Para obtener más información, consulte Uso de una plantilla de mapeo para invalidar códigos de estado y parámetros de solicitud y de respuesta de una API.
`$context.responseOverride.header.header_name`	La invalidación del encabezado de respuesta. Si este parámetro se define, contiene el encabezado que se devolverá en lugar del Response header (Encabezado de respuesta) que se define como Default mapping (Asignación predeterminada) en el panel Integration Response (Respuesta de integración). Para obtener más información, consulte Uso de una plantilla de mapeo para invalidar códigos de estado y parámetros de solicitud y de respuesta de una API.
`$context.responseOverride.status`	La invalidación del código de estado de respuesta. Si este parámetro se define, contiene el código de estado que se devolverá en lugar del Method response status (Estado de respuesta de método) que se define como Default mapping (Asignación predeterminada) en el panel Integration Response (Respuesta de integración). Para obtener más información, consulte Uso de una plantilla de mapeo para invalidar códigos de estado y parámetros de solicitud y de respuesta de una API.
`$context.requestTime`	Hora de la solicitud en formato CLF-(`dd/MMM/yyyy:HH:mm:ss +-hhmm`).
`$context.requestTimeEpoch`	Hora de la solicitud en formato Epoch en milisegundos.
`$context.resourceId`	El identificador que API Gateway asigna a su recurso.
`$context.resourcePath`	La ruta a su recurso. Por ejemplo, en el caso del URI de una solicitud que no es de proxy `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, el valor de `$context.resourcePath` es `/root/child`. Para obtener más información, consulte Tutorial: Creación de una API de REST con integración no de proxy HTTP.
`$context.stage`	La etapa de implementación de la solicitud de la API (por ejemplo, `Beta` o `Prod`).
`$context.wafResponseCode`	La respuesta recibida desde AWS WAF: `WAF_ALLOW` o `WAF_BLOCK`. No se establecerá si la etapa no está asociada a una ACL web. Para obtener más información, consulte Uso de AWS WAF para proteger sus API de REST en API Gateway.
`$context.webaclArn`	El ARN completo de la ACL web que se utiliza para decidir si se debe permitir o bloquear la solicitud. No se establecerá si la etapa no está asociada a una ACL web. Para obtener más información, consulte Uso de AWS WAF para proteger sus API de REST en API Gateway.

Ejemplo de plantilla de variable `$context`

Es posible que desee utilizar variables $context en una plantilla de mapeo si su método de API transfiere datos estructurados a un backend que requiere que los datos estén en un formato determinado.

El siguiente ejemplo muestra una plantilla de asignación que mapea variables $context de entrada a las variables de backend con nombres ligeramente diferentes en una carga de la solicitud de integración:

nota

Una de las variables es una clave de API. En este ejemplo se supone que el método requiere una clave de API.


{
    "stage" : "$context.stage",
    "request_id" : "$context.requestId",
    "api_id" : "$context.apiId",
    "resource_path" : "$context.resourcePath",
    "resource_id" : "$context.resourceId",
    "http_method" : "$context.httpMethod",
    "source_ip" : "$context.identity.sourceIp",
    "user-agent" : "$context.identity.userAgent",
    "account_id" : "$context.identity.accountId",
    "api_key" : "$context.identity.apiKey",
    "caller" : "$context.identity.caller",
    "user" : "$context.identity.user",
    "user_arn" : "$context.identity.userArn"
}

La salida de esta plantilla de asignación debe tener el siguiente aspecto:


{
  stage: 'prod',
  request_id: 'abcdefg-000-000-0000-abcdefg',
  api_id: 'abcd1234',
  resource_path: '/',
  resource_id: 'efg567',
  http_method: 'GET',
  source_ip: '192.0.2.1',
  user-agent: 'curl/7.84.0',
  account_id: '111122223333',
  api_key: 'MyTestKey',
  caller: 'ABCD-0000-12345',
  user: 'ABCD-0000-12345',
  user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}

Variables `$context` solo para registro de acceso

Las siguientes variables $context solo están disponibles para el registro de acceso. Para obtener más información, consulte Configuración del registro de CloudWatch para las API de REST en API Gateway. (Para las API de WebSocket, consulte Supervisión de la ejecución de la API de WebSocket con métricas de CloudWatch.)

Parámetro	Descripción
`$context.authorize.error`	El mensaje de error de autorización.
`$context.authorize.latency`	La latencia de autorización en ms.
`$context.authorize.status`	El código de estado devuelto por un intento de autorización.
`$context.authorizer.error`	El mensaje de error devuelto por un autorizador.
`$context.authorizer.integrationLatency`	La latencia de integración del autorizador en ms.
`$context.authorizer.integrationStatus`	El código de estado que devuelve un autorizador de Lambda.
`$context.authorizer.latency`	La latencia del autorizador en ms.
`$context.authorizer.requestId`	El ID de solicitud del punto de enlace de AWS.
`$context.authorizer.status`	El código de estado devuelto por un autorizador.
`$context.authenticate.error`	El mensaje de error devuelto por un intento de autorización.
`$context.authenticate.latency`	La latencia de autenticación en ms.
`$context.authenticate.status`	El código de estado devuelto por un intento de autenticación.
`$context.customDomain.basePathMatched`	La ruta de un mapeo de la API con la que coincidió una solicitud entrante. Aplicable cuando un cliente utiliza un nombre de dominio personalizado para acceder a una API. Por ejemplo, si un cliente envía una solicitud a `https://api.example.com/v1/orders/1234` y la solicitud empareja el mapeo de la API con la ruta `v1/orders`, el valor es `v1/orders`. Para obtener más información, consulte Asignación de etapas de API a un nombre de dominio personalizado para las API de REST.
`$context.endpointType`	El tipo del punto de conexión de la API.
`$context.integration.error`	El mensaje de error devuelto por una integración.
`$context.integration.integrationStatus`	Para la integración de proxy de Lambda, el código de estado que devuelve AWS Lambda, en lugar del código de función de Lambda del backend.
`$context.integration.latency`	La latencia de integración en ms. Es igual que `$context.integrationLatency`.
`$context.integration.requestId`	El ID de solicitud del punto de enlace de AWS. Es igual que `$context.awsEndpointRequestId`.
`$context.integration.status`	El código de estado devuelto por una integración. Para integraciones de proxy de Lambda, este es el código de estado que devuelve su código de la función de Lambda.
`$context.integrationLatency`	La latencia de integración en ms.
`$context.integrationStatus`	Para la integración de proxy de Lambda, este parámetro representa el código de estado que devuelve AWS Lambda, en lugar del código de función de Lambda del backend.
`$context.responseLatency`	La latencia de respuesta en ms.
`$context.responseLength`	La duración de la carga de respuesta en bytes.
`$context.status`	El estado de respuesta de método.
`$context.waf.error`	El mensaje de error devuelto por AWS WAF.
`$context.waf.latency`	La latencia de AWS WAF en ms.
`$context.waf.status`	El código de estado devuelto por AWS WAF.
`$context.xrayTraceId`	La ID de rastreo para el rastro de X-Ray. Para obtener más información, consulte Configuración de AWS X-Ray con las API de REST de API Gateway.

Variables `$input`

La variable $input representa la carga de solicitud de método y los parámetros que va a procesar la plantilla de asignación. Ofrece las siguientes funciones:

Variable y función	Descripción
`$input.body`	Devuelve la carga de solicitud bruta como una cadena. Puede utilizar `$input.body` para conservar números enteros de punto flotante, como `10.00`.
`$input.json(x)`	Esta función evalúa una expresión JSONPath y devuelve los resultados como una cadena JSON. Por ejemplo, `$input.json('$.pets')` devuelve una cadena JSON que representa la estructura de `pets` (mascotas). Para obtener más información acerca de JSONPath, consulte JSONPath o JSONPath for Java.
`$input.params()`	Devuelve una asignación de todos los parámetros de solicitud. Recomendamos que se utilice `$util.escapeJavaScript` para sanear el resultado a fin de evitar un posible ataque de inyección. Para un control total del saneamiento de solicitudes, utilice una integración de proxy sin plantilla y gestione dicho saneamiento en su integración.
`$input.params(x)`	Devuelve el valor de un parámetro de solicitud de método de la ruta, cadena de consulta o valor de encabezado (buscado en este orden) dada una cadena de nombre de parámetro `x`. Recomendamos que se utilice `$util.escapeJavaScript` para sanear el parámetro a fin de evitar un posible ataque de inyección. Para un control total del saneamiento de parámetros, utilice una integración de proxy sin plantilla y gestione dicho saneamiento en su integración.
`$input.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). 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').size()` devolvería `"3"`. Para obtener más información acerca de JSONPath, consulte JSONPath o JSONPath for Java.

Ejemplos de plantilla de variable `$input`

En los siguientes ejemplos se muestra cómo usar las variables de $input en las plantillas de asignación. Puede usar una integración simulada o una integración que no sea de proxy de Lambda que devuelva el evento de entrada a API Gateway para probar estos ejemplos.

Ejemplo de plantilla de mapeo de parámetros

El siguiente ejemplo pasa todos los parámetros de solicitud, como path, querystring y header, a través del punto de conexión de integración mediante una carga de JSON:


#set($allParams = $input.params())
{
  "params" : {
    #foreach($type in $allParams.keySet())
    #set($params = $allParams.get($type))
    "$type" : {
      #foreach($paramName in $params.keySet())
      "$paramName" : "$util.escapeJavaScript($params.get($paramName))"
      #if($foreach.hasNext),#end
      #end
    }
    #if($foreach.hasNext),#end
    #end
  }
}

Para una solicitud que incluye los siguientes parámetros de entrada:

Un parámetro de ruta denominado myparam
Parámetros de cadenas de consulta querystring1=value1,value2&querystring2=value3
Encabezados "header1" : "value1", "header2" : "value2", "header3" : "value3".

La salida de esta plantilla de asignación debe tener el siguiente aspecto:


{
  "params" : {
        "path" : {
            "path" : "myparam"
                }
    ,        "querystring" : {
            "querystring1" : "value1,value2"
      ,            "querystring2" : "value3"
                }
    ,        "header" : {
            "header3" : "value3"
      ,            "header2" : "value2"
      ,            "header1" : "value1"
                }
          }
}

Ejemplo de plantilla de asignación JSON

Es posible que desee utilizar la variable $input para obtener las cadenas de consulta y el cuerpo de la solicitud con o sin el uso de modelos. Es posible que también desee obtener el parámetro y la carga o una subsección de la carga. Los siguientes tres ejemplos muestran cómo hacer esto.

El siguiente ejemplo utiliza una plantilla de asignación para obtener una subsección de la carga. En este ejemplo, se obtiene el parámetro de entrada name y, a continuación, todo el cuerpo de POST:


{
    "name" : "$input.params('name')",
    "body" : $input.json('$') 
}

Para una solicitud que incluye los parámetros de cadena de consulta name=Bella&type=dog y el cuerpo siguiente:


{
    "Price" : "249.99",
    "Age": "6"
}

La salida de esta plantilla de asignación debe tener el siguiente aspecto:


{
    "name" : "Bella",
    "body" : {"Price":"249.99","Age":"6"}
}

Si la entrada JSON contiene caracteres sin escape que no puede analizar JavaScript, es posible que API Gateway devuelva una respuesta 400. Aplique $util.escapeJavaScript($input.json('$')) para asegurarse de que la entrada JSON se pueda analizar correctamente.

El ejemplo anterior con $util.escapeJavaScript($input.json('$')) se aplica de la siguiente manera:


{
    "name" : "$input.params('name')",
    "body" : $util.escapeJavaScript($input.json('$'))
}

En este caso, la salida de esta plantilla de asignación debe tener el siguiente aspecto:


{
    "name" : "Bella",
    "body": {\"Price\":\"249.99\",\"Age\":\"6\"}
}

Ejemplo de expresiones JSONPath

El siguiente ejemplo muestra cómo pasar una expresión JSONPath al método json(). También puede leer una subsección del objeto del cuerpo de la solicitud mediante el uso de un punto, ., para especificar una propiedad:


{
    "name" : "$input.params('name')",
    "body" : $input.json('$.Age')  
}

Para una solicitud que incluye los parámetros de cadena de consulta name=Bella&type=dog y el cuerpo siguiente:


{
    "Price" : "249.99",
    "Age": "6"
}

La salida de esta plantilla de asignación debe tener el siguiente aspecto:


{
    "name" : "Bella",
    "body" : "6"
}

Si una carga de solicitud de método contiene caracteres sin escape que no puede analizar JavaScript, es posible que API Gateway devuelva una respuesta 400. Aplique $util.escapeJavaScript() para asegurarse de que la entrada JSON se pueda analizar correctamente.

El ejemplo anterior con $util.escapeJavaScript($input.json('$.Age')) se aplica de la siguiente manera:


{
    "name" : "$input.params('name')",
    "body" : "$util.escapeJavaScript($input.json('$.Age'))" 
}

En este caso, la salida de esta plantilla de asignación debe tener el siguiente aspecto:


{
    "name" : "Bella",
    "body": "\"6\""
}

Ejemplo de solicitud y respuesta

El siguiente ejemplo utiliza $input.params(), $input.path() y $input.json() para un recurso con la ruta /things/{id}:


{
    "id" : "$input.params('id')",
    "count" : "$input.path('$.things').size()",
    "things" : $input.json('$.things')"
}

Para una solicitud que incluye el parámetros de ruta 123 y el cuerpo siguiente:


{
      "things": {
            "1": {},
            "2": {},
            "3": {}
      }
}

La salida de esta plantilla de asignación debe tener el siguiente aspecto:


{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}

El ejemplo anterior con $util.escapeJavaScript($input.json('$.things')) se aplica de la siguiente manera:


{
     "id" : "$input.params('id')",
     "count" : "$input.path('$.things').size()",
     "things" : "$util.escapeJavaScript($input.json('$.things'))"
}

La salida de esta plantilla de asignación debe tener el siguiente aspecto:


{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}

Para obtener más ejemplos de asignación, consulte Plantillas de asignación para las API de REST.

`$stageVariables`

Las variables de etapa se pueden utilizar en plantillas de asignación y asignación de parámetros como marcadores de posición en los ARN y las direcciones URL que se utilizan en las integraciones de método. Para obtener más información, consulte Uso de variables de etapa para una API de REST en API Gateway.

Sintaxis	Descripción
`$stageVariables.<variable_name>`, `$stageVariables['<variable_name>']` o `${stageVariables['<variable_name>']}`	`<variable_name>` representa un nombre de variable de etapa.

Variables `$util`

La variable $util contiene funciones de utilidad para su uso en plantillas de asignación.

nota

A menos que se especifique lo contrario, el conjunto de caracteres predeterminado es UTF-8.

Función	Descripción
`$util.escapeJavaScript()`	Aplica caracteres de escape a los caracteres de una cadena usando reglas de cadena de JavaScript. nota 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: `"input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"`
`$util.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 }`
`$util.urlEncode()`	Convierte una cadena en formato "application/x-www-form-urlencoded".
`$util.urlDecode()`	Descodifica una cadena "application/x-www-form-urlencoded".
`$util.base64Encode()`	Codifica los datos en una cadena codificada en base64.
`$util.base64Decode()`	Descodifica los datos de una cadena codificada en base64.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Comportamientos del acceso directo a la integración

Respuestas de gateway

En esta página

Seleccione sus preferencias de cookies

Personalizar preferencias de cookies

Esenciales

De rendimiento

Funcionales

De publicidad

No se pueden guardar las preferencias de cookies

Plantilla de mapeo de API Gateway y referencia de la variable de registro de acceso

Temas

nota

Variables `$context` para modelos de datos, autorizadores, plantillas de mapeo y registro de acceso de CloudWatch

nota

nota

Ejemplo de plantilla de variable `$context`

nota

Variables `$context` solo para registro de acceso

Variables `$input`

Ejemplos de plantilla de variable `$input`

Ejemplo de plantilla de mapeo de parámetros

Ejemplo de plantilla de asignación JSON

Ejemplo de expresiones JSONPath

Ejemplo de solicitud y respuesta

`$stageVariables`

Variables `$util`

nota

nota

En esta página

Related resources

¿Le ha servido de ayuda esta página?

Related resources

Tema siguiente:

Tema anterior:

¿Necesita ayuda?