Referência de mapeamento de dados de resposta e de solicitação de API do Amazon API Gateway
Esta seção explica como configurar mapeamentos de dados com base nos dados da solicitação de método de uma API, incluindo outros dados armazenados em variáveis context, stage ou util para os parâmetros de solicitação de integração correspondentes e com base nos dados de uma resposta de integração, incluindo os outros dados, para os parâmetros de resposta de método. Os dados de solicitação do método incluem parâmetros de solicitação (caminho, string de consulta, cabeçalhos) e o corpo. Os dados de resposta de integração incluem parâmetros de resposta (cabeçalhos) e o corpo. Para obter mais informações sobre o uso de variáveis de estágio, consulte Referência de variáveis de estágio do API Gateway para APIs REST no API Gateway.
Tópicos
Mapear dados de solicitação de método para parâmetros de solicitação de integração
Parâmetros de solicitação de integração, no formato de variáveis de caminho, strings de consulta ou cabeçalhos, podem ser mapeados a partir de qualquer parâmetro de solicitação de método definido e da carga.
Na tabela a seguir,
é o nome de um parâmetro de solicitação de método de tipo de parâmetro especificado. Deve corresponder à expressão regular PARAM_NAME
'^[a-zA-Z0-9._$-]+$]'
. Ele deve ter sido definido antes de poder ser referenciado.
é uma expressão JSONPath para um campo JSON do corpo de uma solicitação ou resposta.JSONPath_EXPRESSION
nota
O prefixo "$"
é omitido nesta sintaxe.
Fonte de dados mapeada |
Expressão de mapeamento |
---|---|
Caminho de solicitação de método | method.request.path. |
String de consulta da solicitação de método | method.request.querystring. |
String de consulta de solicitação do método de vários valores | method.request.multivaluequerystring. |
Cabeçalho da solicitação de método | method.request.header. |
Cabeçalho de solicitação de método de vários valores | method.request.multivalueheader. |
Corpo de solicitação de método | method.request.body |
Corpo de solicitação de método (JsonPath) | method.request.body. . |
Variáveis de estágio | stageVariables. |
Variáveis de contexto | context. que deve ser uma das variáveis de contexto com suporte. |
Valor estático | . STATIC_VALUE é um literal de string e deve estar entre aspas simples. |
exemplo Mapeamentos do parâmetro de solicitação de método no OpenAPI
O exemplo a seguir mostra um trecho do OpenAPI que mapeia:
-
o cabeçalho da solicitação de método, denominado
methodRequestHeaderParam
, no parâmetro do caminho de solicitação de integração, denominadointegrationPathParam
-
a string de consulta da solicitação de método de vários valores, denominada
methodRequestQueryParam
, na string de consulta da solicitação de integração, denominadaintegrationQueryParam
... "requestParameters" : { "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam", "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam" } ...
Parâmetros de solicitação de integração também podem ser mapeados a partir de campos no corpo da solicitação JSON usando uma expressão JSONPath
exemplo Mapeamento do corpo da solicitação de método no OpenAPI
O exemplo a seguir mostra um trecho do OpenAPI que mapeia 1) o corpo da solicitação de método para o cabeçalho da solicitação de integração, denominado body-header
, e 2) um campo JSON do corpo, conforme expresso por uma expressão JSON (petstore.pets[0].name
, sem o prefixo $.
).
... "requestParameters" : { "integration.request.header.body-header" : "method.request.body", "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name", } ...
Mapear dados de resposta de integração para cabeçalhos de resposta de método
Parâmetros de cabeçalho de resposta de método podem ser mapeados a partir de qualquer cabeçalho de resposta de integração ou corpo de resposta de integração, variáveis $context
ou valores estáticos. A tabela a seguir descreve as expressões de mapeamento do cabeçalho de resposta do método.
Fonte de dados mapeada | Expressão de mapeamento |
---|---|
Cabeçalho da resposta de integração | integration.response.header. |
Cabeçalho da resposta de integração | integration.response.multivalueheader. |
Corpo da resposta de integração | integration.response.body |
Corpo da resposta de integração (JsonPath) | integration.response.body. |
Variável de estágio | stageVariables. |
Variável de contexto | context. que deve ser uma das variáveis de contexto com suporte. |
Valor estático | . STATIC_VALUE é um literal de string e deve estar entre aspas simples. |
exemplo Mapeamento de dados a partir da resposta de integração no OpenAPI
O exemplo a seguir mostra um trecho do OpenAPI que mapeia 1) o campo JSONPath redirect.url
da resposta de integração para o cabeçalho location
da resposta de solicitação e 2) o cabeçalho x-app-id
da resposta de integração para o cabeçalho id
da resposta 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", } ...
Mapear cargas de solicitação e resposta entre método e integração
O API Gateway usa o mecanismo Velocity Template Language (VTL)
Os modelos VTL usam expressões JSONPath, outros parâmetros, como contextos de chamada e variáveis de estágio e funções de utilitário para processar os dados JSON.
Se um modelo estiver definido para descrever a estrutura de dados de uma carga, o API Gateway poderá usá-lo para gerar um esqueleto de modelo de mapeamento para uma solicitação de integração ou resposta de integração. Você pode usar esse esqueleto de modelo como ajuda para personalizar e expandir o script de mapeamento VTL. No entanto, é possível criar um modelo de mapeamento do zero, sem definir um modelo para a estrutura de dados da carga.
Selecionar um modelo de mapeamento VTL
O API Gateway usa a seguinte lógica para selecionar um modelo de mapeamento, no Velocity Template Language (VTL)
Para uma carga de solicitação, o API Gateway usa o valor do cabeçalho Content-Type
da solicitação como chave para selecionar o modelo de mapeamento para a carga de solicitação. Para uma carga de resposta, o API Gateway usa o valor do cabeçalho Accept
da solicitação de entrada como chave para selecionar o modelo de mapeamento.
Quando o cabeçalho Content-Type
está ausente na solicitação, o API Gateway pressupõe que o valor padrão seja application/json
. Para tal solicitação, o API Gateway usa application/json
como chave padrão para selecionar o modelo de mapeamento, se um estiver definido. Quando nenhum modelo corresponde a essa chave, o API Gateway transmitirá a carga não mapeada se a propriedade passthroughBehavior estiver definida como WHEN_NO_MATCH
ou WHEN_NO_TEMPLATES
.
Quando o cabeçalho Accept
não está especificado na solicitação, o API Gateway pressupõe que o valor padrão seja application/json
. Nesse caso, o API Gateway seleciona um modelo de mapeamento existente para application/json
com o objetivo de mapear a carga de resposta. Se nenhum modelo estiver definido para application/json
, o API Gateway selecionará o primeiro modelo existente e o usará como padrão para mapear a carga de resposta. Da mesma forma, o API Gateway usa o primeiro modelo existente quando o valor do cabeçalho Accept
especificado não corresponde a nenhuma chave de modelo existente. Se nenhum modelo estiver definido, o API Gateway simplesmente transmitirá a carga da resposta não mapeada.
Por exemplo, suponha que uma API tenha um modelo application/json
definido para uma carga de solicitação e tenha um modelo application/xml
definido para a carga de resposta. Se o cliente definir os cabeçalhos "Content-Type :
application/json"
e "Accept : application/xml"
na solicitação, ambas as cargas de solicitação e resposta serão processadas com os modelos de mapeamento correspondentes. Se o cabeçalho Accept:application/xml
estiver ausente, o modelo de mapeamento application/xml
será usado para mapear a carga de resposta. Em vez disso, para retornar a carga de resposta não mapeada, você deve configurar um modelo vazio para application/json
.
Apenas o tipo MIME é usado nos cabeçalhos Accept
e Content-Type
ao selecionar um modelo de mapeamento. Por exemplo, um cabeçalho de "Content-Type: application/json; charset=UTF-8"
terá um modelo de solicitação com a chave application/json
selecionada.