Configurazione di integrazioni proxy HTTP in API Gateway Configurazione di integrazioni personalizzate di HTTP

Integrazioni HTTP per le API REST in API Gateway

Puoi integrare un metodo API con un endpoint HTTP tramite l'integrazione proxy di HTTP o l'integrazione personalizzata di HTTP.

API Gateway supporta le seguenti porte dell'endpoint: 80, 443 e 1024-65535.

Con l'integrazione proxy la configurazione è semplice. Devi solo impostare il metodo HTTP e l'URI dell'endpoint HTTP, in base ai requisiti del back-end, se non sei interessato alla codifica o al caching dei contenuti.

Con l'integrazione personalizzata la configurazione è più complessa. Oltre alla procedura di configurazione dell'integrazione proxy, devi specificare come verranno mappati i dati della richiesta in ingresso alla richiesta di integrazione e i dati della risposta di integrazione risultante alla risposta del metodo.

Argomenti

Configurazione di integrazioni proxy HTTP in API Gateway
Configurazione di integrazioni personalizzate HTTP in API Gateway

Configurazione di integrazioni proxy HTTP in API Gateway

Per configurare una risorsa proxy con il tipo di integrazione proxy HTTP, crea una risorsa API con un parametro di percorso greedy, ad esempio /parent/{proxy+}, e integra la risorsa con un endpoint di back-end HTTP, ad esempio https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}, nel metodo ANY. Il parametro di percorso greedy deve trovarsi alla fine del percorso della risorsa.

Come per una risorsa non proxy, puoi configurare una risorsa proxy con l'integrazione proxy HTTP usando la console API Gateway, importando un file di definizione OpenAPI o chiamando direttamente l'API REST di API Gateway. Per istruzioni dettagliate sull'uso della console API Gateway per configurare una risorsa proxy con l'integrazione HTTP, consulta Tutorial: creare un'API REST con un'integrazione proxy HTTP.

Il seguente file di definizione OpenAPI mostra un esempio di API con una risorsa proxy integrata con il PetStoresito Web.

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"
        }
      }
    }
  }
}

In questo esempio, viene dichiarata una chiave cache nel parametro del percorso method.request.path.proxy della risorsa proxy. Questa è l'impostazione predefinita quando crei l'API tramite la console API Gateway. Il percorso di base dell'API (/testcorrispondente a una fase) è mappato alla PetStore pagina del sito Web (/petstore). La singola richiesta di integrazione rispecchia l'intero PetStore sito Web utilizzando la variabile greedy path dell'API e il metodo ANY catch-all. Negli esempi seguenti viene illustrato questo mirroring.

Imposta ANY come GET e {proxy+} come pets

Richiesta di metodo iniziata dal front-end:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
```
Richiesta di integrazione inviata al back-end:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
```
Le istanze run-time del metodo ANY e le risorse proxy sono entrambe valide. La chiamata restituisce una risposta 200 OK con il payload contenente il primo batch di animali, nel modo in cui viene restituito dal back-end.
Imposta ANY come GET e {proxy+} come pets?type=dog
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1
```
Richiesta di integrazione inviata al back-end:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1
```
Le istanze run-time del metodo ANY e le risorse proxy sono entrambe valide. La chiamata restituisce una risposta 200 OK con il payload contenente il primo batch di cani specifici, nel modo in cui viene restituito dal back-end.
Imposta ANY come GET e {proxy+} come pets/{petId}

Richiesta di metodo iniziata dal front-end:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1
```
Richiesta di integrazione inviata al back-end:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1
```
Le istanze run-time del metodo ANY e le risorse proxy sono entrambe valide. La chiamata restituisce una risposta 200 OK con il payload contenente l'animale specificato, nel modo in cui viene restituito dal back-end.

Imposta ANY come POST e {proxy+} come pets

Richiesta di metodo iniziata dal 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
}

Richiesta di integrazione inviata al back-end:


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

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

Le istanze run-time del metodo ANY e le risorse proxy sono entrambe valide. La chiamata restituisce una risposta 200 OK con il payload contenente il nuovo animale creato, nel modo in cui viene restituito dal back-end.

Imposta ANY come GET e {proxy+} come pets/cat

Richiesta di metodo iniziata dal front-end:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat
```
Richiesta di integrazione inviata al back-end:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat
```
L'istanza run-time del percorso della risorsa del proxy non corrisponde all'endpoint di un back-end e la relativa richiesta non è valida. Di conseguenza, viene restituita una risposta 400 Bad Request con il seguente messaggio di errore.
```
{
  "errors": [
    {
      "key": "Pet2.type",
      "message": "Missing required field"
    },
    {
      "key": "Pet2.price",
      "message": "Missing required field"
    }
  ]
}
```
Imposta ANY come GET e {proxy+} come null

Richiesta di metodo iniziata dal front-end:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test
```
Richiesta di integrazione inviata al back-end:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
La risorsa di destinazione è il padre della risorsa del proxy, ma l'istanza run-time del metodo ANY non è definita nell'API di quella risorsa. Di conseguenza, la richiesta GET restituisce una risposta 403 Forbidden con il messaggio di errore Missing Authentication Token restituito da API Gateway. Se l'API espone il metodo ANY o GET alla risorsa padre (/), la chiamata restituisce una risposta 404 Not Found con il messaggio Cannot GET /petstore restituito dal back-end.

Per qualsiasi richiesta del client, se l'URL dell'endpoint di destinazione non è valido o il verbo HTTP è valido ma non è supportato, il back-end restituisce una risposta 404 Not Found. Per un metodo HTTP non supportato, viene restituita una risposta 403 Forbidden.

Configurazione di integrazioni personalizzate HTTP in API Gateway

Con l'integrazione HTTP personalizzata, hai più controllo su quali dati passare tra un metodo API e un'integrazione API e su come passarli. Puoi fare questo utilizzando le mappature dei dati.

Come parte della configurazione della richiesta del metodo, imposti la proprietà requestParameters su una risorsa Method. Questo dichiara quali parametri della richiesta di metodo, forniti dal client, devono essere mappati ai parametri di richiesta di integrazione o alle proprietà del corpo applicabili prima di essere inviati al back-end. Quindi, come parte della configurazione della richiesta di integrazione, impostate la proprietà RequestParameters sulla risorsa di integrazione corrispondente per specificare le parameter-to-parameter mappature. Imposti inoltre la proprietà requestTemplates per specificare i modelli di mappatura, uno per ogni tipo di contenuto supportato. I modelli di mappatura mappano i parametri della richiesta di metodo, o il corpo, al corpo della richiesta di integrazione.

Analogamente, come parte della configurazione della risposta del metodo, impostate la proprietà ResponseParameters sulla risorsa. MethodResponse Questo dichiara quali parametri della risposta di metodo, da inviare al client, devono essere mappati dai parametri della risposta di integrazione o da alcune proprietà del corpo applicabili restituite dal back-end. Quindi, come parte della configurazione della risposta di integrazione, impostate la proprietà ResponseParameters sulla risorsa IntegrationResponsecorrispondente per specificare le mappature. parameter-to-parameter Imposti inoltre la mappa responseTemplates per specificare i modelli di mappatura, uno per ogni tipo di contenuto supportato. I modelli di mappatura mappano i parametri della risposta di integrazione, o le proprietà del corpo della risposta di integrazione, al corpo della risposta del metodo.

Per ulteriori informazioni sulla configurazione dei modelli di mappatura, consulta Trasformazioni dei dati per REST APIs in Gateway API.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Gestione degli errori Lambda in API Gateway

Integrazione privata