Referência de mapeamento de dados de resposta e de solicitação de API do Amazon API Gateway - Amazon API Gateway

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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 Amazon API Gateway.

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, PARAM_NAME é o nome de um parâmetro de solicitação de método de tipo de parâmetro especificado. Deve corresponder à expressão regular '^[a-zA-Z0-9._$-]+$]'. Ele deve ter sido definido antes de poder ser referenciado. JSONPath_EXPRESSION é uma expressão JSONPath para um campo JSON do corpo de uma solicitação ou resposta.

nota

O prefixo "$" é omitido nesta sintaxe.

Expressões de mapeamento de dados de solicitações de integração
Fonte de dados mapeada Expressão de mapeamento
Caminho de solicitação de método method.request.path.PARAM_NAME
String de consulta da solicitação de método method.request.querystring.PARAM_NAME
String de consulta de solicitação do método de vários valores method.request.multivaluequerystring.PARAM_NAME
Cabeçalho da solicitação de método method.request.header.PARAM_NAME
Cabeçalho de solicitação de método de vários valores method.request.multivalueheader.PARAM_NAME
Corpo de solicitação de método method.request.body
Corpo da solicitação de método (JsonPath) method.request.body.JSONPath_EXPRESSION.
Variáveis de estágio stageVariables.VARIABLE_NAME
Variáveis de contexto context.VARIABLE_NAME que deve ser uma das variáveis de contexto com suporte.
Valor estático 'STATIC_VALUE'. 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, denominado integrationPathParam

  • 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, denominada integrationQueryParam

... "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. A tabela a seguir mostra as expressões de mapeamento para um corpo de solicitação de método e seus campos JSON.

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.

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.PARAM_NAME
Cabeçalho da resposta de integração integration.response.multivalueheader.PARAM_NAME
Corpo da resposta de integração integration.response.body
Corpo de resposta de integração (JsonPath) integration.response.body.JSONPath_EXPRESSION
Variável de estágio stageVariables.VARIABLE_NAME
Variável de contexto context.VARIABLE_NAME que deve ser uma das variáveis de contexto com suporte.
Valor estático 'STATIC_VALUE'. 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) para processar modelos de mapeamento de corpo para a solicitação de integração e a resposta de integração. Os modelos de mapeamento convertem cargas de solicitação de método nas cargas de solicitação de integração correspondentes e convertem corpos de resposta de integração em corpos de resposta de método.

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 mapear a carga de uma solicitação de método para a solicitação de integração correspondente ou para mapear a carga de uma resposta de integração para a resposta de método correspondente.

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.