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 API Gateway para las API de REST en API Gateway.
Temas
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,
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 PARAM_NAME
'^[a-zA-Z0-9._$-]+$]'
. Debe haberse definido para que se pueda hacer referencia a él.
es una expresión JSONPath para un campo JSON del cuerpo de una solicitud o respuesta.JSONPath_EXPRESSION
nota
El prefijo "$"
se omite en esta sintaxis.
Origen de datos asignado |
Expresión de asignación |
---|---|
Ruta de solicitud de método | method.request.path. |
Cadena de consulta de solicitud de método | method.request.querystring. |
Cadena de consulta de solicitud de método multivalor | method.request.multivaluequerystring. |
Encabezado de solicitud de método | method.request.header. |
Encabezado de solicitud de método multivalor | method.request.multivalueheader. |
Cuerpo de solicitud de método | method.request.body |
Cuerpo de solicitud de método (JsonPath) | method.request.body. . |
Variables de etapa | stageVariables. |
Variables de contexto | context. que debe ser alguna de las variables de contexto admitidas. |
Valor estático | : 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, llamadointegrationPathParam
-
la cadena de consulta de la solicitud de método multivalor, llamada
methodRequestQueryParam
, a la cadena de consulta de la solicitud de integración, llamadaintegrationQueryParam
... "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
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. En la siguiente tabla se describen las 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. |
Encabezado de respuesta de integración | integration.response.multivalueheader. |
Cuerpo de respuesta de integración | integration.response.body |
Cuerpo de respuesta de integración (JsonPath) | integration.response.body. |
Variable de etapa | stageVariables. |
Variable de contexto | context. que debe ser alguna de las variables de contexto admitidas. |
Valor estático | : 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)
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 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.