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

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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

En esta sección se proporciona información de referencia sobre las variables y funciones que Amazon API Gateway define para su uso con modelos de datos, autorizadores, plantillas de mapeo y registros de CloudWatch acceso. Para obtener información detallada acerca de cómo utilizar estas variables y funciones, consulte Comprensión de las plantillas de mapeo. Para obtener más información sobre Velocity Template Language, consulte la referencia de VTL.

nota

$contextVariables para los modelos de datos, los autorizadores, las plantillas de mapeo y CloudWatch el registro de acceso

Las siguientes $context variables se pueden usar en los modelos de datos, los autorizadores, las plantillas de mapeo y el registro de CloudWatch acceso.

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

Parámetro Descripción
$context.accountId

El ID de AWS cuenta 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 una 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".

Para obtener más información, consulte Uso de autorizadores Lambda de API Gateway.

$context.awsEndpointRequestId

El ID de solicitud del AWS punto final.

$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 utilizar para la sustitución simple de variables en una plantilla de GatewayResponsemapeo corporal, que no es procesada por el motor del lenguaje de plantillas Velocity, y en el registro de acceso. Para obtener más información, consulte Monitoreo 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 utilizar para la sustitución simple de variables en una plantilla de GatewayResponsemapeo corporal, que no es procesada por el motor del lenguaje de plantillas Velocity, ni en el registro de acceso. Para obtener más información, consulte Monitoreo 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 AWS de cuenta asociado a 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 Creación y uso de planes de uso con claves de API.

$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 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 más información.

$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 enlace 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.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.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: Desarrollo de una API de REST con integración HTTP no de proxy.

$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.

$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.

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

Tenga en cuenta que una de las variables es una clave de API. En este ejemplo se supone que el método cuenta con "require API key" (exigir clave de API) habilitado.

{ "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" }

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 una API de REST en API Gateway. (Para obtener WebSocket información sobre las API, consulteMonitoreo 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 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 identificador de solicitud del AWS punto final.
$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 Trabajar con mapeos de la API para las API REST.

$context.integration.error El mensaje de error devuelto por una integración.
$context.integration.integrationStatus Para la integración del proxy de Lambda, el código de estado se devuelve desde AWS Lambda, no desde el código de la función Lambda del backend.
$context.integration.latency La latencia de integración en ms. Es igual que $context.integrationLatency.
$context.integration.requestId El identificador de AWS solicitud del punto final. 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 del proxy de Lambda, este parámetro representa el código de estado devuelto desde AWS Lambda, no desde el código de la función 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 desde. AWS WAF
$context.waf.latency La AWS WAF latencia en ms.
$context.waf.status El código de estado devuelto desde 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 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. Proporciona cuatro funciones:

Variable y función Descripción
$input.body

Devuelve la carga de solicitud bruta como una cadena.

$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').count() devolvería "3".

Para obtener más información acerca de JSONPath, consulte JSONPath o JSONPath for Java.

Ejemplos de plantilla de variable $input

Ejemplo de plantilla de mapeo de parámetros

El siguiente ejemplo de asignación de parámetros pasa todos los parámetros, incluidos los parámetros path, querystring y header, a través del punto de enlace de integración mediante una carga 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 } }

De hecho, esta plantilla de mapeo muestra todos los parámetros de solicitud de la carga tal y como se describe a continuación:

{ "params" : { "path" : { "path_name" : "path_value", ... } "header" : { "header_name" : "header_value", ... } "querystring" : { "querystring_name" : "querystring_value", ... } } }

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 bien una subsección de la carga, en su función de Lambda. El siguiente ejemplo muestra cómo hacerlo.

Plantilla de mapeo JSON de ejemplo con $input

El siguiente ejemplo muestra cómo utilizar una asignación para leer un nombre de la cadena de consulta y después incluir todo el cuerpo de POST en un elemento:

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

Si la entrada JSON contiene caracteres sin escape que no se puedan analizar JavaScript, es posible que se devuelva una respuesta de 400. Si aplica $util.escapeJavaScript($input.json('$')) arriba se asegurará de que la entrada JSON se pueda analizar correctamente.

Plantilla de mapeo de ejemplo con $input

El siguiente ejemplo muestra cómo pasar una expresión JSONPath al método json(). También puede leer una propiedad específica del objeto del cuerpo de la solicitud utilizando un punto (.), seguido del nombre de la propiedad:

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

Si la carga útil de una solicitud de método contiene caracteres sin escape que no se pueden analizar JavaScript, es posible que obtengas una respuesta. 400 En este caso, debe llamar a la función $util.escapeJavaScript() en la plantilla de mapeo, tal y como se muestra a continuación:

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

Solicitud y respuesta de ejemplo con $input

A continuación se muestra un ejemplo que utiliza las tres funciones:

Request template: (Plantilla de solicitud:)

Resource: /things/{id} With input template: { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : "$util.escapeJavaScript($input.json('$.things'))" } POST /things/abc { "things" : { "1" : {}, "2" : {}, "3" : {} } }

Respuesta:

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

Para obtener más ejemplos de asignación, consulte Comprensión de las plantillas de mapeo.

$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 Configuración de variables de etapa para una implementación de una API de REST.

Sintaxis Descripción
$stageVariables.<variable_name>

<variable_name> representa un nombre de variable de etapa.

$stageVariables['<variable_name>']

<variable_name> representa cualquier nombre de variable de etapa.

${stageVariables['<variable_name>']}

<variable_name> representa cualquier 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()

Escapa de los caracteres de una cadena mediante reglas de cadenas. 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 al formato «application/x-www-form-urlencoded».

$util.urlDecode()

Decodifica 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.