HTTP-Proxy-Integrationen in API Gateway einrichten Einrichten von benutzerdefinierten HTTP-Integrationen

HTTP-Integrationen in API Gateway einrichten

Sie können eine API-Methode mit einem HTTP-Endpunkt mithilfe der HTTP-Proxy-Integration oder der benutzerdefinierten HTTP-Integration integrieren.

API Gateway unterstützt die folgenden Endpunkt-Ports: 80, 443 und 1024-65535.

Mit der Proxy-Integration ist die Einrichtung einfach. Sie müssen nur die HTTP-Methode und die HTTP-Endpunkt-URI entsprechend der Backend-Anforderungen festlegen, wenn Sie sich nicht mit der Codierung oder dem Caching von Inhalten befassen.

Mit der benutzerdefinierten Integration ist die Einrichtung komplexer. Zusätzlich zu den Einrichtungsschritten der Proxy-Integration müssen Sie angeben, wie die eingehenden Anforderungsdaten der Integrationsanforderung und die resultierenden Integrationsantwortdaten der Methodenantwort zugeordnet werden.

Themen

HTTP-Proxy-Integrationen in API Gateway einrichten
Benutzerdefinierte HTTP-API-Integrationen in API Gateway einrichten

HTTP-Proxy-Integrationen in API Gateway einrichten

Erstellen Sie zum Einrichten einer Proxy-Ressource mit dem HTTP-Proxy-Integrationstyp eine API-Ressource mit einem gierigen Pfadparameter (zum Beispiel /parent/{proxy+}) und integrieren Sie diese Ressource mit einem HTTP-Backend-Endpunkt (zum Beispiel https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}) in die Methode ANY. Der gierige Pfadparameter muss am Ende des Ressourcenpfads stehen.

Wie bei einer Nicht-Proxy-Ressource können Sie eine Proxy-Ressource mit der HTTP-Proxy-Integration einrichten, indem Sie die API Gateway-Konsole verwenden, eine OpenAPI-Definitionsdatei importieren oder die API Gateway-REST-API direkt aufrufen. Detaillierte Anweisungen für die Verwendung der API Gateway-Konsole zur Konfiguration einer Proxy-Ressource mit der HTTP-API-Integration finden Sie unter Tutorial: REST-API mit HTTP-Proxy-Integration erstellen.

Die folgende OpenAPI-Definitionsdatei zeigt ein Beispiel für eine API mit einer Proxyressource, die mit der PetStore-Website integriert ist.

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 diesem Beispiel wird ein Cache-Schlüssel für den Pfadparameter method.request.path.proxy der Proxy-Ressource deklariert. Dies ist die Standardeinstellung, wenn Sie die API mit der API Gateway-Konsole erstellen. Der Basispfad der API (/test, entsprechend einer Stufe) wird der Seite "PetStore" (/petstore) der Website zugeordnet. Die einzelne Integrationsanforderung spiegelt die gesamte "PetStore"-Website mithilfe der gierigen Pfadvariable der API und der Catch-all-Methode ANY. Die folgenden Beispiele veranschaulichen diese Spiegelung.

Festlegen von ANY als GET und {proxy+} als pets

Vom Frontend initiierte Methodenanforderung:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
```
An das Backend gesendete Integrationsanforderung:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
```
Die Laufzeitinstanzen der Methode ANY und der Proxy-Ressource sind beide gültig. Der Aufruf gibt eine Antwort 200 OK mit der Nutzlast zurück, die den ersten Batch Haustiere enthält, wie vom Backend zurückgegeben.
Festlegen von ANY als GET und {proxy+} als pets?type=dog
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1
```
An das Backend gesendete Integrationsanforderung:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1
```
Die Laufzeitinstanzen der Methode ANY und der Proxy-Ressource sind beide gültig. Der Aufruf gibt eine Antwort 200 OK mit der Nutzlast zurück, die den ersten Batch der angegebenen Hunde enthält, wie vom Backend zurückgegeben.
Festlegen von ANY als GET und {proxy+} als pets/{petId}

Vom Frontend initiierte Methodenanforderung:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1
```
An das Backend gesendete Integrationsanforderung:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1
```
Die Laufzeitinstanzen der Methode ANY und der Proxy-Ressource sind beide gültig. Der Aufruf gibt eine Antwort 200 OK mit der Nutzlast zurück, die das angegebene Haustier enthält, wie vom Backend zurückgegeben.

Festlegen von ANY als POST und {proxy+} als pets

Vom Frontend initiierte Methodenanforderung:


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
}

An das Backend gesendete Integrationsanforderung:


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

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

Die Laufzeitinstanzen der Methode ANY und der Proxy-Ressource sind beide gültig. Der Aufruf gibt eine Antwort 200 OK mit der Nutzlast zurück, die das neu erstellte Haustier enthält, wie vom Backend zurückgegeben.

Festlegen von ANY als GET und {proxy+} als pets/cat

Vom Frontend initiierte Methodenanforderung:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat
```
An das Backend gesendete Integrationsanforderung:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat
```
Die Laufzeit-Instance des Proxy-Ressourcenpfads entspricht keinem Backend-Endpunkt und die resultierende Anforderung ist ungültig. Dies hat zur Folge, dass eine Antwort 400 Bad Request mit der folgenden Fehlermeldung zurückgegeben wird.
```
{
  "errors": [
    {
      "key": "Pet2.type",
      "message": "Missing required field"
    },
    {
      "key": "Pet2.price",
      "message": "Missing required field"
    }
  ]
}
```
Festlegen von ANY als GET und {proxy+} als null

Vom Frontend initiierte Methodenanforderung:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test
```
An das Backend gesendete Integrationsanforderung:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
Die Zielressource ist der Proxy-Ressource übergeordnet, aber die Laufzeit-Instance der Methode ANY ist in der API auf dieser Ressource nicht definiert. Infolgedessen gibt diese GET-Anfrage eine 403 Forbidden-Antwort mit der Missing Authentication Token-Fehlermeldung zurück, die von API Gateway zurückgegeben wird. Wenn die API die Methode ANY oder GET in der übergeordneten Ressource (/) verfügbar macht, gibt der Aufruf eine Antwort 404 Not Found mit der Meldung Cannot GET /petstore zurück, wie vom Backend zurückgegeben.

Wenn die URL des Zielendpunkts ungültig ist oder das HTTP-Verb gültig ist, aber nicht unterstützt wird, gibt das Backend für jede Clientanforderung die Antwort 404 Not Found zurück. Bei einer nicht unterstützten HTTP-Methode wird eine Antwort 403 Forbidden zurückgegeben.

Benutzerdefinierte HTTP-API-Integrationen in API Gateway einrichten

Mit der benutzerdefinierten HTTP-Integration haben Sie mehr Kontrolle darüber, welche Daten zwischen einer API-Methode und einer API-Integration übertragen werden sollen und wie Sie diese übertragen. Dies können Sie mithilfe von Daten-Mappings tun.

Als Teil der Einrichtung der Methodenanforderung legen Sie die requestParameters-Eigenschaft für eine Method-Ressource fest. Dies gibt an, welche Methodenanforderungsparameter, die von dem Client bereitgestellt werden, den Integrationsanforderungsparametern oder den geltenden Textkörpereigenschaften zugeordnet werden sollen, bevor sie an den Backend versendet werden. Legen Sie dann als Teil der Einrichtung der Integrationsanforderung die requestParameters-Eigenschaft für die entsprechende Integration-Ressource fest, um die Parameter-zu-Parameter-Mappings anzugeben. Sie legen auch die requestTemplates-Eigenschaft fest, um die Mapping-Vorlagen anzugeben, eine für jeden unterstützten Inhaltstyp. Die Mapping-Vorlagen weisen Methodenanforderungsparameter oder Textkörper dem Anforderungstextkörper der Integration zu.

Ebenso legen Sie als Teil der Einrichtung der Methodenantwort die responseParameters-Eigenschaft für eine MethodResponse-Ressource fest. Dies gibt an, welche Methodenantwortparameter, die an den Client gesendet werden sollen, von den Integrationsantwortparametern oder bestimmten geltenden Textkörpereigenschaften zugeordnet werden sollen, die vom Backend zurückgegeben wurden. Legen Sie dann als Teil der Einrichtung der Integrationsantwort die responseParameters-Eigenschaft für die entsprechende IntegrationResponse-Ressource fest, um die Parameter-zu-Parameter-Mappings anzugeben. Sie legen auch die responseTemplates-Zuordnung fest, um die Mapping-Vorlagen anzugeben, eine für jeden unterstützten Inhaltstyp. Die Mapping-Vorlagen weisen Methodenantwortparameter oder Textkörpereigenschaften der Integrationsantwort dem Antworttextkörper der Methode zu.

Weitere Hinweise zum Einrichten von Mapping-Vorlagen finden Sie unter Datentransformationen für REST-APIs einrichten.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Lambda-Fehler in API Gateway behandeln

Private Integration