Configurar mapeamentos de dados de solicitação e resposta usando o console do API Gateway

Para usar o console do API Gateway para definir a solicitação/resposta de integração da API, siga estas instruções.

nota

Estas instruções supõem que você já concluiu as etapas em Configurar uma solicitação de integração de API usando o console do API Gateway.

1. No painel Recursos, escolha seu método.

2. Na guia Solicitação de integração, em Configurações de solicitação de integração, selecione Editar.

3. Escolha uma opção para Passagem do corpo da solicitação para configurar como o corpo da solicitação do método de um tipo de conteúdo não mapeado será passado pela solicitação de integração sem transformação para a função Lambda, proxy HTTP ou proxy de serviço. AWS Existem três opções:

   • Selecione Quando nenhum modelo corresponde ao cabeçalho Content-Type se desejar que o corpo da solicitação de método passe a solicitação de integração para o back-end sem transformação quando o tipo de conteúdo da solicitação de método não corresponder a nenhum dos tipos de conteúdo associados aos modelos de mapeamento, conforme definido na próxima etapa.

     nota

     Ao chamar a API do API Gateway, escolha essa opção configurando WHEN_NO_MATCH como o valor da propriedade passthroughBehavior no recurso Integração.

   • Escolha When there are no templates defined (recommended) (Quando não há modelos definidos (recomendado)) se quiser que o corpo da solicitação de método transmita a solicitação de integração ao backend sem transformação quando nenhum modelo de mapeamento estiver definido na solicitação de integração. Se um modelo for definido quando essa opção for selecionada, a solicitação de método de um tipo de conteúdo não mapeado será rejeitada com uma resposta HTTP 415 Tipo de mídia sem suporte.

     nota

     Ao chamar a API do API Gateway, escolha essa opção configurando WHEN_NO_TEMPLATE como o valor da propriedade passthroughBehavior no recurso Integração.

   • Escolha Never (Nunca) se não quiser que a solicitação de método seja transmitida quando seu tipo de conteúdo não corresponder a nenhum tipo de conteúdo associado aos modelos de mapeamento definidos na solicitação de integração ou quando nenhum modelo de mapeamento estiver definido na solicitação de integração. A solicitação de método de um tipo de conteúdo não mapeado será rejeitada com uma resposta HTTP 415 Tipo de mídia sem suporte.

     nota

     Ao chamar a API do API Gateway, escolha essa opção configurando NEVER como o valor da propriedade passthroughBehavior no recurso Integração.

   Para obter mais informações sobre os comportamentos de passagem direta de integração, consulte Comportamentos de passagem direta de integração.

4. Para um proxy HTTP ou proxy de AWS serviço, para associar um parâmetro de caminho, um parâmetro de sequência de caracteres de consulta ou um parâmetro de cabeçalho definido na solicitação de integração a um parâmetro de caminho, parâmetro de sequência de consulta ou parâmetro de cabeçalho correspondente na solicitação de método do proxy HTTP ou proxy de AWS serviço, faça o seguinte:

   1. Selecione Parâmetros de caminho de URL, Parâmetros de string de consulta de URL ou Cabeçalhos HTTP, respectivamente. Depois, selecione Adicionar caminho, Adicionar string de consulta ou Adicionar cabeçalho, respectivamente.

   2. Em Nome, digite o nome do parâmetro de caminho, parâmetro de sequência de caracteres de consulta ou parâmetro de cabeçalho no proxy HTTP ou proxy AWS de serviço.

   3. Em Mapeado de, digite o valor de mapeamento para o parâmetro de caminho, o parâmetro de string de consulta ou o parâmetro de cabeçalho. Use um dos seguintes formatos:

      • method.request.path.parameter-name para um parâmetro de caminho denominado parameter-name, como definido na página Solicitação de método.

      • method.request.querystring.parameter-name para um parâmetro de string de consulta denominado parameter-name, como definido na página Solicitação de método.

      • method.request.multivaluequerystring.parameter-name para um parâmetro de string de consulta de vários valores denominado parameter-name, como definido na página Solicitação de método.

      • method.request.header.parameter-name para um parâmetro de cabeçalho denominado parameter-name, como definido na página Solicitação de método.

        Como alternativa, você pode definir um valor de string literal (delimitado por um par de aspas simples) para um cabeçalho de integração.

      • method.request.multivalueheader.parameter-name para um parâmetro de cabeçalho de vários valores denominado parameter-name, como definido na página Solicitação de método.

   4. Para adicionar outro parâmetro, selecione o botão Adicionar.

5. Para adicionar um modelo de mapeamento, selecione Modelos de mapeamento.

6. Para definir um modelo de mapeamento para uma solicitação recebida, selecione Adicionar modelo de mapeamento. Em Tipo de conteúdo, insira um tipo de conteúdo (por exemplo, application/json). Depois, digite o modelo de mapeamento manualmente ou selecione Gerar modelo para criar um partir de um modelo. Para ter mais informações, consulte Noções básicas de modelos de mapeamento.

7. Escolha Salvar.

8. Você pode mapear uma resposta de integração no backend para uma resposta de método da API retornada ao aplicativo de chamada. Isso inclui retornar ao cliente os cabeçalhos de resposta selecionados nos cabeçalhos disponíveis no backend, transformando o formato de dados da carga da resposta do backend em um formato especificado pela API. É possível especificar esse mapeamento configurando Resposta de método e Respostas de integração.

   Para que o método receba um formato de dados de resposta personalizado com base no código de status HTTP retornado pela função Lambda, proxy HTTP ou proxy de AWS serviço, faça o seguinte:

   1. Selecione Respostas de integração. Selecione Editar em Padrão - Resposta para especificar configurações para um código de resposta 200 HTTP do método, ou selecione Criar resposta para especificar configurações para qualquer outro código de status de resposta HTTP do método.

   2. Para regex de erro Lambda (para uma função Lambda) ou regex de status HTTP (para um proxy HTTP ou proxy de AWS serviço), insira uma expressão regular para especificar quais cadeias de erro da função Lambda (para uma função Lambda) ou códigos de status de resposta HTTP (para um proxy HTTP ou proxy de serviço) mapeiam para esse mapeamento de saída. AWS Por exemplo, para mapear todos os códigos de status de resposta HTTP 2xx de um proxy HTTP para esse mapeamento de saída, digite "2\d{2}" em HTTP status regex (Regex de status HTTP). Para gerar uma mensagem de erro contendo “Solicitação inválida” de uma função do Lambda para uma resposta 400 Bad Request, digite “.*Invalid request.*” como a expressão Regex de erro do Lambda. Por outro lado, para que o Lambda gere 400 Bad Request para todas as mensagens de erro não mapeadas, digite “(\n|.)+” em Regex de erro do Lambda. Essa última expressão regular pode ser usada para a resposta de erro padrão de uma API.

      nota

      O API Gateway usa regexes de estilo padrão de Java para o mapeamento de resposta. Para obter mais informações, consulte Padrão na documentação do Oracle.

      Os padrões de erro são comparados à string inteira da propriedade errorMessage na resposta do Lambda, que é preenchida por callback(errorMessage) em Node.js ou por throw new MyException(errorMessage) em Java. Além disso, caracteres escapados têm o escape cancelado antes que a expressão regular seja aplicada.

      Se você usar “.+” como o padrão de seleção para respostas de filtro, lembre-se de que ele pode não corresponder a uma resposta que contém um caractere de nova linha (“\n”).

   3. Se habilitado, em Status de resposta de método, selecione o código de status de resposta HTTP definido na página Resposta de método.

   4. Em Mapeamentos de cabeçalho, para cada cabeçalho que você definiu para o código de status de resposta HTTP na página Resposta do método, especifique um valor de mapeamento. Em Mapping value (Valor de mapeamento), use um dos seguintes formatos:

      • integration.response.multivalueheaders.header-name onde header-name é o nome de um cabeçalho de resposta de vários valores do backend.

        Por exemplo, para retornar o cabeçalho Date da resposta do backend como um cabeçalho Timestamp da resposta de um método de API, a coluna Response header (Cabeçalho da resposta) conterá uma entrada Timestamp, e o Mapping value (Valor de mapeamento) associado deve ser definido como integration.response.multivalueheaders.Date.

      • integration.response.header.header-name onde header-name é o nome de um cabeçalho de resposta de valor único do backend.

        Por exemplo, para retornar o cabeçalho Date da resposta do backend como um cabeçalho Timestamp da resposta de um método de API, a coluna Response header (Cabeçalho da resposta) conterá uma entrada Timestamp, e o Mapping value (Valor de mapeamento) associado deve ser definido como integration.response.header.Date.

   5. Selecione Modelos de mapeamento e, depois, Adicionar modelo de mapeamento. Na caixa Tipo de conteúdo, insira o tipo de conteúdo dos dados que serão passados da função Lambda, proxy HTTP ou proxy de AWS serviço para o método. Depois, digite o modelo de mapeamento manualmente ou selecione Gerar modelo para criar um partir de um modelo. Para ter mais informações, consulte Noções básicas de modelos de mapeamento.

   6. Escolha Salvar.