Plantilla de mapeo de API Gateway y referencia de la variable de registro de acceso
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 Trabajo con modelos y plantillas de asignación.
Temas
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.
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. |
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. La llamada a |
$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. |
El valor en forma de cadena del par clave-valor especificado de la asignación
la llamada a 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.domainName |
El nombre de dominio completo que se utiliza para invocar la API. Este debe ser el mismo que el encabezado |
$context.domainPrefix |
La primera etiqueta del |
$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 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 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 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: |
$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 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, 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 |
$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 |
|
$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 |
$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 . 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.requestOverride.header. |
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. |
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. |
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. |
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 CLFdd/MMM/yyyy:HH:mm:ss
+-hhmm ). |
$context.requestTimeEpoch |
Hora de la solicitud en formato Epoch |
$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 |
$context.stage |
La etapa de implementación de la solicitud de la API (por ejemplo, |
$context.wafResponseCode |
La respuesta recibida desde AWS WAF: |
$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
Puede utilizar variables $context
en una plantilla de asignación 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:
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 las API de WebSocket, consulte Monitoreo 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 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 |
$context.integration.error |
El mensaje de error devuelto por una integración. Es igual que $context.integrationErrorMessage . |
$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. Es igual que $context.integrationStatus . |
$context.integrationErrorMessage |
Una cadena que contiene un mensaje de error de integración. |
$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 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, Para obtener más información acerca de JSONPath, consulte JSONPath |
$input.params() |
Devuelve una asignación de todos los parámetros de solicitud. Recomendamos que se utilice |
$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 |
$input.path(x) |
Toma una cadena de expresión JSONPath ( Por ejemplo, si la expresión
Para obtener más información acerca de JSONPath, consulte JSONPath |
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", ... } } }
Tal vez 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 puede analizar JavaScript, es posible que se devuelva una respuesta 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 una carga de solicitud de método contiene caracteres sin escape que no puede analizar JavaScript, es posible que obtenga la 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" : {} } }
Response: (Respuesta:)
{ "id": "abc", "count": "3", "things": { "1": {}, "2": {}, "3": {} } }
Para obtener más ejemplos de asignación, consulte Trabajo con modelos y plantillas de asignación.
$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. |
|
$stageVariables[' |
|
${stageVariables[' |
|
Variables $util
La variable $util
contiene funciones de utilidad para su uso en plantillas de asignación.
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. Esta función convertirá todas las comillas simples (
|
$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:
y usa la siguiente plantilla de asignación
Obtendrá el siguiente resultado:
|
$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. |