Usar um modelo de mapeamento para substituir parâmetros de solicitação e resposta e códigos de status de uma API

Os modelos padrão de mapeamento de parâmetros e códigos de resposta do API Gateway permitem mapear parâmetros one-to-one e mapear uma família de códigos de status de resposta de integração (combinados por uma expressão regular) em um único código de status de resposta. As substituições de modelos de mapeamento oferecem a flexibilidade de realizar mapeamentos de many-to-one parâmetros; substituir parâmetros após a aplicação dos mapeamentos padrão do API Gateway; mapear condicionalmente parâmetros com base no conteúdo do corpo ou em outros valores de parâmetros; criar programaticamente novos parâmetros dinamicamente; e substituir códigos de status retornados pelo seu endpoint de integração. Qualquer tipo de parâmetro de solicitação, cabeçalho de resposta ou código de status de resposta pode ser substituído.

A seguir encontram-se exemplos de uso de substituições por meio de modelo de mapeamento:

• Criar um novo cabeçalho (ou substituir um cabeçalho existente) como uma concatenação de dois parâmetros

• Substituir o código de resposta para um código de êxito ou falha com base no conteúdo do corpo

• Remapear condicionalmente um parâmetro com base em seu conteúdo ou no conteúdo de algum outro parâmetro

• Iterar o conteúdo de um corpo json e remapear pares de chave/valor para cabeçalhos ou strings de consulta

Para criar uma substituição por meio de modelo de mapeamento, use uma ou mais das seguintes $context variáveis em um modelo de mapeamento:

Modelo de mapeamento do corpo da solicitação	Modelo de mapeamento do corpo da resposta
$context.requestOverride.header.header_name	$context.responseOverride.header.header_name
$context.requestOverride.path.path_name	$context.responseOverride.status
$context.requestOverride.querystring.querystring_name

nota

Não é possível usar substituições por meio de modelo de mapeamento com endpoints de integração de proxy, os quais não têm mapeamentos de dados. Para mais informações sobre integração, consulte Escolher um tipo de integração de API do API Gateway.

Importante

As substituições são feitas no final. Uma substituição só pode ser aplicada a um parâmetro por vez. A tentativa de substituir o mesmo parâmetro várias vezes gerará respostas 5XX do Amazon API Gateway. Se você tiver de substituir o mesmo parâmetro várias vezes em todo o modelo, é recomendável criar uma variável e aplicar a substituição no final do modelo. Observe que o modelo é aplicado somente depois que todo o modelo é analisado. Consulte Tutorial: como substituir parâmetros e cabeçalhos de solicitação de uma API com o console do API Gateway.

Os tutoriais a seguir mostram como criar e testar uma substituição por meio de modelo de mapeamento no console do API Gateway. Esses tutoriais usam a API de PetStore amostra como ponto de partida. Ambos os tutoriais presumem que você já criou a API de PetStore amostra.

Tutorial: como substituir o código de status de resposta de uma API com o console do API Gateway

Para recuperar um animal de estimação usando a API de PetStore amostra, você usa a solicitação do método de API deGET /pets/{petId}, onde {petId} é um parâmetro de caminho que pode receber um número em tempo de execução.

Neste tutorial, você vai substituir esse código de resposta do método GET criando um modelo de mapeamento que mapeia $context.responseOverride.status para 400 quando é detectada uma condição de erro.

1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

2. Em APIs, escolha a PetStore API e, em seguida, escolha Recursos.

3. Na árvore Recursos, selecione o método GET em /{petId}.

4. Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

5. Em petId, insira -1 e, depois, selecione Testar.

   Nos resultados, você verá dois fatores:

   Primeiro, o corpo da resposta indica um out-of-range erro:

   {
     "errors": [
       {
         "key": "GetPetRequest.petId",
         "message": "The value is out of range."
       }
     ]
   }

   Segundo, a última linha na caixa Log termina com: Method completed with status: 200.

6. Na guia Resposta de integração, em Padrão - Resposta, selecione Editar.

7. Selecione Modelos de mapeamento.

8. Escolha Add mapping template (Adicionar modelo de mapeamento).

9. Em Tipo de conteúdo, insira application/json.

10. Em Corpo do modelo, insira o seguinte:

    #set($inputRoot = $input.path('$'))
    $input.json("$")
    #if($inputRoot.toString().contains("error"))
    #set($context.responseOverride.status = 400)
    #end

11. Escolha Salvar.

12. Selecione a guia Testar.

13. Em petId, insira -1.

14. Nos resultados, o Corpo da Resposta indica um out-of-range erro:

    {
      "errors": [
        {
          "key": "GetPetRequest.petId",
          "message": "The value is out of range."
        }
      ]
    }

    Entretanto, a última linha na caixa Logs agora termina com: Method completed with status: 400.

Tutorial: como substituir parâmetros e cabeçalhos de solicitação de uma API com o console do API Gateway

Neste tutorial, você vai substituir o código do cabeçalho da solicitação do método GET criando um modelo de mapeamento que é mapeia $context.requestOverride.header.header_name para um novo cabeçalho que associa dois outros cabeçalhos.

1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

2. Em APIs, escolha a PetStore API.

3. Na árvore Recursos, selecione o método GET em /pet.

4. Na guia Solicitação de método, em Configurações de solicitação de método, selecione Editar.

5. Selecione Cabeçalhos de solicitação HTTP e, depois, Adicionar cabeçalho.

6. Em Nome, digite header1.

7. Selecione Adicionar cabeçalho e, depois, crie um segundo cabeçalho chamado header2.

8. Escolha Salvar.

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

10. Em Passagem do corpo da solicitação, selecione Quando não há modelos definidos (recomendado).

11. Selecione Modelos de mapeamento e, depois, faça o seguinte:

    1. Escolha Add mapping template (Adicionar modelo de mapeamento).

    2. Em Tipo de conteúdo, insira application/json.

    3. Em Corpo do modelo, insira o seguinte:

       #set($header1Override = "foo")
       #set($header3Value = "$input.params('header1')$input.params('header2')")
       $input.json("$")
       #set($context.requestOverride.header.header3 = $header3Value)
       #set($context.requestOverride.header.header1 = $header1Override)
       #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])

12. Escolha Salvar.

13. Selecione a guia Testar.

14. Em Headers (Cabeçalhos) para {pets}, copie o seguinte código:

    header1:header1Val
    header2:header2Val

15. Escolha Test (Testar).

    No Log, você deve ver uma entrada com este texto:

    Endpoint request headers: {header3=header1Valheader2Val, 
    header2=header2Val, header1=foo, x-amzn-apigateway-api-id=<api-id>,
    Accept=application/json, multivalueheader=foo,header1Valheader2Val}

Exemplos: como substituir parâmetros e cabeçalhos de solicitação de uma API com a CLI do API Gateway

O seguinte exemplo de CLI mostra como usar o comando put-integration para substituir um código de resposta:

aws apigateway put-integration --rest-api-id <API_ID> --resource-id <PATH_TO_RESOURCE_ID> --http-method <METHOD> 
            --type <INTEGRATION_TYPE> --request-templates <REQUEST_TEMPLATE_MAP>

onde <REQUEST_TEMPLATE_MAP> é um mapa do tipo de conteúdo para uma string do modelo a ser aplicado. A estrutura do mapa é como a seguir:

Content_type1=template_string,Content_type2=template_string

ou, na sintaxe JSON:

{"content_type1": "template_string"
...}

O seguinte exemplo mostra como usar o comando put-integration-response para substituir o código de resposta de uma API:

aws apigateway put-integration-response --rest-api-id <API_ID> --resource-id <PATH_TO_RESOURCE_ID> --http-method <METHOD> 
            --status-code <STATUS_CODE> --response-templates <RESPONSE_TEMPLATE_MAP>

onde <RESPONSE_TEMPLATE_MAP> tem o mesmo formato que <REQUEST_TEMPLATE_MAP> acima.

Exemplo: substituir os parâmetros e cabeçalhos de solicitação de uma API usando o SDK para JavaScript

O seguinte exemplo de mostra como usar o comando put-integration para substituir um código de resposta:

Solicitação:

var params = {
  httpMethod: 'STRING_VALUE', /* required */
  resourceId: 'STRING_VALUE', /* required */
  restApiId: 'STRING_VALUE', /* required */
  type: HTTP | AWS | MOCK | HTTP_PROXY | AWS_PROXY, /* required */
  requestTemplates: {
    '<Content_type>': 'TEMPLATE_STRING',
    /* '<String>': ... */
  },
};
apigateway.putIntegration(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Resposta:

var params = {
  httpMethod: 'STRING_VALUE', /* required */
  resourceId: 'STRING_VALUE', /* required */
  restApiId: 'STRING_VALUE', /* required */
  statusCode: 'STRING_VALUE', /* required */
  responseTemplates: {
    '<Content_type>': 'TEMPLATE_STRING',
    /* '<String>': ... */
  },
};
apigateway.putIntegrationResponse(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});