Referencia de mapeo de datos de solicitud y respuesta de API de Amazon API Gateway

En esta sección, se explica cómo configurar la asignación de los datos de solicitud del método de una API, incluidos otros datos almacenados en las variables context, stage, o util, a los parámetros de solicitud de integración correspondientes y de los datos de respuesta de integración, incluidos los demás datos, a los parámetros de respuesta del método. Los datos de la solicitud de método incluyen parámetros de solicitud (ruta, cadena de consulta, encabezados) y el cuerpo. Los datos de la respuesta de integración incluyen parámetros de respuesta (encabezados) y el cuerpo. Para obtener más información sobre el uso de las variables de etapa, consulte Referencia de variables de etapa de Amazon API Gateway.

Temas

• Asignar datos de solicitud de método a parámetros de solicitud de integración
• Asignar datos de respuesta de integración a encabezados de respuesta de método
• Asignar cargas de solicitud y respuesta entre método e integración
• Comportamientos del acceso directo a la integración

Asignar datos de solicitud de método a parámetros de solicitud de integración

Los parámetros de solicitud de integración, en forma de variables de ruta, cadenas de consulta o encabezados, se pueden asignar desde cualquier parámetro de solicitud de método definido y la carga.

En la tabla siguiente, PARAM_NAME es el nombre de un parámetro de solicitud de método del tipo de parámetro especificado. Debe coincidir con la expresión regular '^[a-zA-Z0-9._$-]+$]'. Debe haberse definido para que se pueda hacer referencia a él. JSONPath_EXPRESSION es una expresión JSONPath para un campo JSON del cuerpo de una solicitud o respuesta.

nota

El prefijo "$" se omite en esta sintaxis.

Expresiones de asignación de datos de solicitud de integración
Origen de datos asignado	Expresión de asignación
Ruta de solicitud de método	method.request.path.PARAM_NAME
Cadena de consulta de solicitud de método	method.request.querystring.PARAM_NAME
Cadena de consulta de solicitud de método multivalor	method.request.multivaluequerystring.PARAM_NAME
Encabezado de solicitud de método	method.request.header.PARAM_NAME
Encabezado de solicitud de método multivalor	method.request.multivalueheader.PARAM_NAME
Cuerpo de solicitud de método	method.request.body
Cuerpo de la solicitud del método () JsonPath	method.request.body.JSONPath_EXPRESSION.
Variables de etapa	stageVariables.VARIABLE_NAME
Variables de contexto	context.VARIABLE_NAME que debe ser alguna de las variables de contexto admitidas.
Valor estático	'STATIC_VALUE': el STATIC_VALUE es una cadena de literales que se debe colocar entre comillas simples.

ejemplo Mapeos de parámetro de solicitud de método en OpenAPI

En el siguiente ejemplo se muestra un fragmento de código de OpenAPI que asigna:

• el encabezado de la solicitud de método, llamado methodRequestHeaderParam, al parámetro de ruta de la solicitud de integración, llamado integrationPathParam

• la cadena de consulta de la solicitud de método multivalor, llamada methodRequestQueryParam, a la cadena de consulta de la solicitud de integración, llamada integrationQueryParam

...
"requestParameters" : {
            
    "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam",        
    "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam"
            
}
...
                
            

Los parámetros de solicitud de integración también se pueden asignar desde campos del cuerpo de la solicitud JSON mediante una expresión JSONPath. En la siguiente tabla se muestran las expresiones de asignación de un cuerpo de solicitud de método y sus campos JSON.

ejemplo Mapeo desde el cuerpo de solicitud de método en OpenAPI

El siguiente ejemplo muestra un fragmento de OpenAPI que asigna 1) el cuerpo de solicitud de método al encabezado de solicitud de integración, denominado body-header, y 2) un campo JSON del cuerpo, expresado por una expresión JSON (petstore.pets[0].name, sin el prefijo $.).

...
"requestParameters" : {
            
    "integration.request.header.body-header" : "method.request.body",
    "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name",
            
}
...
                
            

Asignar datos de respuesta de integración a encabezados de respuesta de método

Los parámetros de encabezado de respuesta de método se pueden asignar desde cualquier encabezado de respuesta de integración o cuerpo de respuesta de integración, variables $context o valores estáticos.

Expresiones de asignación de encabezado de respuesta de método
Origen de datos asignado	Expresión de asignación
Encabezado de respuesta de integración	integration.response.header.PARAM_NAME
Encabezado de respuesta de integración	integration.response.multivalueheader.PARAM_NAME
Cuerpo de respuesta de integración	integration.response.body
Cuerpo de respuesta de integración (JsonPath)	integration.response.body.JSONPath_EXPRESSION
Variable de etapa	stageVariables.VARIABLE_NAME
Variable de contexto	context.VARIABLE_NAME que debe ser alguna de las variables de contexto admitidas.
Valor estático	'STATIC_VALUE': el STATIC_VALUE es una cadena de literales que se debe colocar entre comillas simples.

ejemplo Mapeo de datos desde una respuesta de integración en OpenAPI

El siguiente ejemplo muestra un fragmento de OpenAPI que asigna 1) el campo JSONPath redirect.url de la respuesta de integración al encabezado location de la respuesta de solicitud; y 2) el encabezado x-app-id de la respuesta de integración al encabezado id de la respuesta de método.

...
"responseParameters" : {
            
    "method.response.header.location" : "integration.response.body.redirect.url",
    "method.response.header.id" : "integration.response.header.x-app-id",
    "method.response.header.items" : "integration.response.multivalueheader.item",
            
}
...
                
            

Asignar cargas de solicitud y respuesta entre método e integración

API Gateway utiliza el motor Velocity Template Language (VTL) para procesar las plantillas de mapeo de cuerpo para la solicitud de integración y la respuesta de integración. Las plantillas de asignación traducen las cargas de solicitud de método en las cargas de solicitud de integración correspondientes y los cuerpos de respuesta de integración en los cuerpos de respuesta de método.

Las plantillas de VTL usan expresiones JSONPath, otros parámetros como los contextos de llamada y las variables de etapa, y funciones de utilidad para procesar los datos JSON.

Si se define un modelo para describir la estructura de datos de una carga, API Gateway puede utilizar el modelo para generar una plantilla de mapeo básica para una solicitud de integración o una respuesta de integración. Puede utilizar la plantilla básica como ayuda para personalizar y ampliar el script VTL de asignación. Sin embargo, puede crear una plantilla de asignación desde cero sin definir un modelo para la estructura de datos de la carga.

Seleccionar una plantilla de asignación VTL

API Gateway utiliza la siguiente lógica para seleccionar una plantilla de mapeo, en Velocidad Template Language (VTL), para asignar la carga desde una solicitud de método a la solicitud de integración correspondiente o para asignar la carga desde una respuesta de integración a la respuesta de método correspondiente.

Para una carga de solicitud, API Gateway utiliza el valor del encabezado Content-Type de la solicitud como la clave para seleccionar la plantilla de mapeo para la carga de la solicitud. Para una carga de respuesta, API Gateway utiliza el valor del encabezado Accept de la solicitud entrante como la clave para seleccionar la plantilla de mapeo.

Cuando el encabezado Content-Type no está presente en la solicitud, API Gateway presupone que el valor predeterminado es application/json. Para dicha solicitud, API Gateway utiliza application/json como la clave predeterminada para seleccionar la plantilla de mapeo, si se define una. Cuando ninguna plantilla coincide con esta clave, API Gateway transfiere la carga sin mapear si la propiedad passthroughBehavior está establecida en WHEN_NO_MATCH o WHEN_NO_TEMPLATES.

Cuando no se especifica el encabezado Accept en la solicitud, API Gateway presupone que el valor predeterminado es application/json. En este caso, API Gateway selecciona una plantilla de mapeo de application/json para asignar la carga de la respuesta. Si no se define ninguna plantilla para application/json, API Gateway selecciona la primera plantilla existente y la utiliza como la opción predeterminada para asignar la carga de la respuesta. Del mismo modo, API Gateway utiliza la primera plantilla existente cuando el valor del encabezado Accept especificado no coincide con ninguna clave de plantilla existente. Si no se define ninguna plantilla, API Gateway simplemente transfiere la carga de la respuesta sin asignar.

Suponga, por ejemplo, que una API tiene una plantilla application/json definida para una carga de solicitud y una plantilla application/xml definida para la carga de la respuesta. Si el cliente configura los encabezados "Content-Type : application/json"y "Accept : application/xml" en la solicitud, las cargas de la solicitud y la respuesta se procesarán con las plantillas de asignación correspondientes. Si el encabezado Accept:application/xml no está presente, la plantilla de asignación application/xml se usará para asignar la carga de la respuesta. Para devolver la carga de la respuesta sin asignar en su lugar, debe configurar una plantilla vacía para application/json.

Solo se utiliza el tipo MIME de los encabezados Accept y Content-Type cuando se selecciona una plantilla de asignación. Por ejemplo, un encabezado "Content-Type: application/json; charset=UTF-8" tendrá una plantilla de solicitud con la clave application/json seleccionada.