Configurar integrações de proxy HTTP no API Gateway Configurar integrações personalizadas HTTP

Integrações de HTTP para APIs REST no API Gateway

Você pode integrar um método de API com um endpoint HTTP usando a integração de proxy ou a integração personalizada HTTP.

O API Gateway oferece suporte às seguintes portas endpoint: 80, 443 e 1024-65535.

Com a integração de proxy, a configuração é simples. Você só precisa definir o método HTTP e o URI de endpoint HTTP de acordo com os requisitos de backend, se você não estiver preocupado com a codificação de conteúdo nem o armazenamento em cache.

Com a integração personalizada, a configuração é mais complexa. Além das etapas de configuração da integração de proxy, você precisa especificar como os dados da solicitação de entrada serão mapeados para a solicitação de integração e como os dados da resposta de integração resultante serão mapeados para a resposta do método.

Tópicos

Configurar integrações de proxy HTTP no API Gateway
Configurar integrações personalizadas HTTP no API Gateway

Configurar integrações de proxy HTTP no API Gateway

Para configurar um recurso de proxy com o tipo de integração de proxy HTTP, crie um recurso de API com um parâmetro de caminho voraz (por exemplo, /parent/{proxy+}) e integre esse recurso a um endpoint de backend HTTP (por exemplo, https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}) no método ANY. O parâmetro de caminho voraz deve estar no final do caminho do recurso.

Como no caso de um recurso não proxy, é possível configurar um recurso de proxy com a integração de proxy HTTP usando o console do API Gateway, importando um arquivo de definição do OpenAPI ou chamando diretamente a API REST do API Gateway. Para obter instruções detalhadas sobre como usar o console do API Gateway para configurar um recurso de proxy com a integração HTTP, consulte Tutorial: Crie uma API REST com uma integração de proxy de HTTP.

O seguinte arquivo de definição do OpenAPI mostra um exemplo de uma API com um recurso de proxy que está integrado ao site PetStore.

OpenAPI 3.0


{
   "openapi": "3.0.0",
   "info": {
      "version": "2016-09-12T23:19:28Z",
      "title": "PetStoreWithProxyResource"
   },
   "paths": {
      "/{proxy+}": {
         "x-amazon-apigateway-any-method": {
            "parameters": [
               {
                  "name": "proxy",
                  "in": "path",
                  "required": true,
                  "schema": {
                     "type": "string"
                  }
               }
            ],
            "responses": {},
            "x-amazon-apigateway-integration": {
               "responses": {
                  "default": {
                     "statusCode": "200"
                  }
               },
               "requestParameters": {
                  "integration.request.path.proxy": "method.request.path.proxy"
               },
               "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
               "passthroughBehavior": "when_no_match",
               "httpMethod": "ANY",
               "cacheNamespace": "rbftud",
               "cacheKeyParameters": [
                  "method.request.path.proxy"
               ],
               "type": "http_proxy"
            }
         }
      }
   },
   "servers": [
      {
         "url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}",
         "variables": {
            "basePath": {
              "default": "/test"
            }
         }
      }
   ]
}

OpenAPI 2.0


{
  "swagger": "2.0",
  "info": {
    "version": "2016-09-12T23:19:28Z",
    "title": "PetStoreWithProxyResource"
  },
  "host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com",
  "basePath": "/test",
  "schemes": [
    "https"
  ],
  "paths": {
    "/{proxy+}": {
      "x-amazon-apigateway-any-method": {
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "proxy",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {},
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "requestParameters": {
            "integration.request.path.proxy": "method.request.path.proxy"
          },
          "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "ANY",
          "cacheNamespace": "rbftud",
          "cacheKeyParameters": [
            "method.request.path.proxy"
          ],
          "type": "http_proxy"
        }
      }
    }
  }
}

Neste exemplo, uma chave de cache é declarada no parâmetro de caminho method.request.path.proxy do recurso de proxy. Esta é a configuração padrão quando você cria a API usando o console do API Gateway. O caminho base da API (/test, correspondente a um estágio) é mapeado para a página PetStore do site (/petstore). A solicitação de integração única espelha o site PetStore inteiro usando a variável de caminho voraz da API e o método genérico ANY. Os exemplos a seguir ilustram esse espelhamento.

Defina ANY como GET e {proxy+} como pets

Solicitação de método iniciada no front-end:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
```
Solicitação de integração enviada ao backend:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
```
As instâncias de tempo de execução do método ANY e o recurso de proxy são ambos válidos. A chamada retorna uma resposta 200 OK com a carga que contém o primeiro lote de animais de estimação, conforme retornado do back-end.
Defina ANY como GET e {proxy+} como pets?type=dog
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1
```
Solicitação de integração enviada ao backend:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1
```
As instâncias de tempo de execução do método ANY e o recurso de proxy são ambos válidos. A chamada retorna uma resposta 200 OK com a carga que contém o primeiro lote de cães especificados, conforme retornado do back-end.
Defina ANY como GET e {proxy+} como pets/{petId}

Solicitação de método iniciada no front-end:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1
```
Solicitação de integração enviada ao backend:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1
```
As instâncias de tempo de execução do método ANY e o recurso de proxy são ambos válidos. A chamada retorna uma resposta 200 OK com a carga que contém o animal de estimação especificado, conforme retornado do back-end.

Defina ANY como POST e {proxy+} como pets

Solicitação de método iniciada no front-end:


POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
Content-Type: application/json
Content-Length: ...

{
  "type" : "dog",
  "price" : 1001.00
}

Solicitação de integração enviada ao backend:


POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
Content-Type: application/json
Content-Length: ...

{
  "type" : "dog",
  "price" : 1001.00
}

As instâncias de tempo de execução do método ANY e o recurso de proxy são ambos válidos. A chamada retorna uma resposta 200 OK com a carga que contém o animal de estimação recém-criado, conforme retornado do back-end.

Defina ANY como GET e {proxy+} como pets/cat

Solicitação de método iniciada no front-end:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat
```
Solicitação de integração enviada ao backend:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat
```
A instância de runtime do caminho do recurso de proxy não corresponde a um endpoint de backend, e a solicitação resultante é inválida. Como resultado, uma resposta 400 Bad Request é retornada com a seguinte mensagem de erro.
```
{
  "errors": [
    {
      "key": "Pet2.type",
      "message": "Missing required field"
    },
    {
      "key": "Pet2.price",
      "message": "Missing required field"
    }
  ]
}
```
Defina ANY como GET e {proxy+} como null

Solicitação de método iniciada no front-end:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test
```
Solicitação de integração enviada ao backend:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
O recurso direcionado é o pai do recurso de proxy, mas a instância de tempo de execução do método ANY não está definida na API nesse recurso. Como resultado, essa solicitação GET retorna uma resposta 403 Forbidden com a mensagem de erro Missing Authentication Token retornada pelo API Gateway. Se a API expõe o método ANY ou GET no recurso pai, (/), a chamada retorna uma resposta 404 Not Found com a mensagem Cannot GET /petstore conforme retornada do backend.

Para qualquer solicitação de cliente, se a URL do endpoint de destino for inválida ou se o verbo HTTP for válido, mas não tiver suporte, o back-end retornará uma resposta 404 Not Found. Para um método HTTP sem suporte, uma resposta 403 Forbidden é retornada.

Configurar integrações personalizadas HTTP no API Gateway

Com a integração personalizada HTTP, você tem mais controle de quais dados transmitir entre um método de API e uma integração de API e como transmitir os dados. Isso é feito pelo mapeamento de dados.

Como parte da configuração da solicitação do método, defina a propriedade requestParameters em um recurso Method. Isso declara quais parâmetros da solicitação do método, que são provisionados pelo cliente, devem ser mapeados para os parâmetros da solicitação de integração ou para as propriedades do corpo aplicáveis antes de serem enviados para o backend. Depois, como parte da configuração da solicitação de integração, defina a propriedade requestParameters no recurso Integration correspondente para especificar os mapeamentos entre parâmetros. Você também define a propriedade requestTemplates para especificar modelos de mapeamento, um para cada tipo de conteúdo com suporte. Os modelos de mapeamento mapeiam o corpo ou os parâmetros da solicitação do método ao corpo da solicitação da integração.

De forma similar, como parte da configuração da resposta do método, você define a propriedade responseParameters no recurso MethodResponse. Isso declara quais parâmetros de resposta do método, a serem enviados ao cliente, devem ser mapeados dos parâmetros da resposta de integração ou de determinadas propriedades do corpo aplicáveis que foram retornadas do backend. Depois, como parte da configuração da resposta de integração, defina a propriedade responseParameters no recurso IntegrationResponse correspondente para especificar os mapeamentos entre parâmetros. Você também define o mapa responseTemplates para especificar modelos de mapeamento, um para cada tipo de conteúdo com suporte. Os modelos de mapeamento mapeiam os parâmetros da resposta de integração ou as propriedades do corpo da resposta de integração ao corpo da resposta do método.

Para obter mais informações sobre como configurar modelos de mapeamento, consulte Transformações de dados para APIs REST no API Gateway.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Manipular erros do Lambda no API Gateway

Integração privada