Tutorial: REST-API mit HTTP-Proxy-Integration erstellen

Die HTTP-Proxy-Integration von ist ein einfacher, leistungsstarker und vielseitiger Mechanismus für den Aufbau einer API, mit der eine Webanwendung auf mehrere Ressourcen oder Funktionen des integrierten HTTP-Endpunktes (z. B. die gesamte Website) zugreifen kann und der eine unkomplizierte Einrichtung einer einzigen API-Methode verwendet. Bei der HTTP-Proxy-Integration leitet API Gateway die vom Client übermittelte Methodenanforderung an das Backend weiter. Diese übergebenen Anforderungsdaten umfassen die Abfrage-Header, Parameter für Abfragezeichenfolgen, die URL-Pfadvariablen und die Nutzlast. Der Backend-HTTP-Endpunkt oder Webserver analysiert die eingehenden Anforderungsdaten, um die eigene Antwort zu bestimmen. Die HTTP-Proxy-Integration sorgt dafür, dass der Client und das Backend direkt interagieren, ohne dass nach dem Einrichten der API-Methode ein Eingriff von API Gateway erfolgt. Dies gilt nicht für bekannte Probleme wie nicht unterstützte Zeichen, die in aufgeführt sin Wichtige Hinweise zu Amazon API Gateway.

Mit der umfassenden Proxy-Ressource {proxy+}und dem umfassenden ANY-Verb für die HTTP-Methode können Sie mit einer HTTP-Proxy-Integration eine API mit einer einzelnen API-Methode erstellen. Die Methode macht den gesamten Satz der öffentlich verfügbaren HTTP-Ressourcen und -Vorgänge der Website verfügbar. Wenn der Backend-Webserver mehr Ressourcen für den öffentlichen Zugriff öffnet, kann der Client diese neuen Ressourcen mit derselben API-Einrichtung nutzen. Um dies zu ermöglichen, muss der Websiteentwickler dem Cliententwickler klar kommunizieren, was die neuen Ressourcen sind und welche Vorgänge für diese Umgebungen anwendbar sind.

Als kurze Einführung zeigt die folgende Anleitung die HTTP-Proxy-Integration. In diesem Tutorial erstellen wir eine API für die Integration mit der Website PetStore über eine allgemeine Proxy-Ressource {proxy+} mithilfe der API Gateway-Konsole und erstellen den HTTP-Platzhalter ANY.

API mit HTTP-Proxy-Integration unter Verwendung der API Gateway-Konsole erstellen

Das folgende Verfahren führt Sie durch die Schritte zum Erstellen und Testen einer API mit einer Proxy-Ressource für ein HTTP-Backend unter Verwendung der API Gateway-Konsole. Das HTTP-Backend ist die PetStore-Website (http://petstore-demo-endpoint.execute-api.com/petstore/pets) von Tutorial: REST-API mit HTTP-API ohne Proxy-Integration erstellen, auf der Screenshots als visuelle Hilfsmittel zur Veranschaulichung der API Gateway-Benutzeroberflächenelemente verwendet werden. Wenn Ihnen die Verwendung der API Gateway-Konsole zur Erstellung einer API unbekannt ist, sollten Sie zuerst diesen Abschnitt lesen.

So erstellen Sie eine API mit HTTP-Proxy-Integration mit der PetStore-Website über eine Proxy-Ressource

1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

2. Wenn Sie API Gateway zum ersten Mal verwenden, sehen Sie eine Seite, die Sie mit den Funktionen des Service vertraut macht. Wählen Sie unter REST-API die Option Build (Erstellen) aus. Wenn das Popup-Fenster Create Exampe API (Beispiel-API erstellen) angezeigt wird, klicken Sie auf OK.

   Wenn Sie API Gateway nicht zum ersten Mal verwenden, wählen Sie Create API (API erstellen). Wählen Sie unter REST-API die Option Build (Erstellen) aus.

   1. Klicken Sie auf New API (Neue API).

   2. Geben Sie in API Name (API-Name) einen Namen ein.

   3. Geben Sie optional in das Feld Description (Beschreibung) eine kurze Beschreibung ein.

   4. Wählen Sie Create API (API erstellen) aus.

   Verwenden Sie in diesem Tutorial ProxyResourceForPetStore als API-Namen.

3. Um eine untergeordnete Ressource zu erstellen, wählen Sie in der Baumstruktur Resources (Ressourcen) ein übergeordnetes Ressourcenelement und anschließend Create Resource (Ressource erstellen) im Dropdown-Menü Actions (Aktionen) aus. Führen Sie anschließend im Bereich New Child Resource (Neue untergeordnete Ressource) folgende Schritte aus:

   1. Wählen Sie die Option Configure as proxy resource (Als Proxy-Ressource konfigurieren) aus, um eine Proxy-Ressource zu erstellen. Lassen Sie sie ansonsten deaktiviert.

   2. Geben Sie in das Eingabetextfeld Resource Name* (Ressourcenname*) einen Namen ein.

   3. Geben Sie einen neuen Namen ein oder verwenden Sie den Standardnamen im Eingabetextfeld Resource Path* (Ressourcenpfad*).

   4. Wählen Sie Create Resource (Ressource erstellen) aus.

   5. Wählen Sie bei Bedarf Enable API Gateway CORS (API Gateway CORS aktivieren) aus.

   Wählen Sie für dieses Tutorial Configure as proxy resource aus. Verwenden Sie für Resource Name den Standard proxy. Verwenden Sie für Resource Path /{proxy+}. Wählen Sie Enable API Gateway CORS (API Gateway CORS aktivieren).

   

4. Gehen Sie wie folgt vor, um die Methode ANY für die Integration in das HTTP-Backend einzurichten:

   1. Wählen Sie die gerade erstellte Ressource und dann im Dropdown-Menü Actions (Aktionen) die Option Create Method (Methode erstellen) aus.

   2. Wählen Sie in der Dropdown-Liste „HTTP method“ (HTTP-Methode) die Option ANY aus und klicken Sie auf das Häkchen, um die Auswahl zu speichern.

   3. Wählen Sie HTTP Proxy (HTTP-Proxy) als Integration type (Integrationstyp) aus.

   4. Geben Sie unter Endpoint URL (Endpunkt-URL) eine HTTP-Backend-Ressourcen-URL ein.

   5. Verwenden Sie für die anderen Felder die Standardeinstellungen.

   6. Klicken Sie auf Save (Speichern), um die Konfiguration der Methode ANY abzuschließen.

   Verwenden Sie für dieses Tutorial http://petstore-demo-endpoint.execute-api.com/{proxy} als Endpoint URL.

   

In der API, die wir eben erstellt haben, wird der Proxy-Ressourcen-Pfad der API von {proxy+} zum Platzhalter der Backend-Endpunkte unter http://petstore-demo-endpoint.execute-api.com/. Zum Beispiel kann dies petstore, petstore/pets und petstore/pets/{petId} sein. Die ANY-Methode dient als Platzhalter für alle unterstützten HTTP-Verben zur Laufzeit.

Testen einer API mit HTTP-Proxy-Integration

Ob eine bestimmte Clientanforderung erfolgreich ist, hängt von Folgendem ab:

• Ob das Backend den entsprechenden Backend-Endpunkt verfügbar gemacht hat und, falls dies der Fall ist, ob die erforderlichen Zugriffsberechtigungen erteilt wurden.

• Ob der Client die korrekte Eingabe bereitstellt.

Die PetStore-API verwendet hier beispielsweise nicht die /petstore-Ressource. Daher erhalten Sie eine 404 Resource Not Found-Antwort mit der Fehlermeldung Cannot GET /petstore.

Darüber hinaus muss der Client in der Lage sein, das Ausgabeformat zu verarbeiten, um das Ergebnis des Backends korrekt zu analysieren. API Gateway fungiert nicht als Vermittler zur Vereinfachung der Interaktionen zwischen dem Client und dem Backend.

So testen Sie eine API, die in die PetStore-Website mithilfe von HTTP-Proxy-Integration über die Proxy-Ressource integriert ist

1. Um die API Gateway-Konsole zum Testen des Aufrufs der API zu verwenden, gehen Sie wie folgt vor.

   1. Wählen Sie ANY bei einer Proxy-Ressource in der Resources (Ressourcen)-Baumstruktur.

   2. Wählen Sie im Bereich Method Execution (Methodenausführung) die Option Test aus.

   3. Wählen Sie in der Dropdown-Liste Method (Methode) ein vom Backend unterstütztes HTTP-Verb aus.

   4. Geben Sie unter Path (Pfad) einen spezifischen Pfad für die Proxy-Ressource ein, die den gewählten Vorgang unterstützt.

   5. Geben Sie bei Bedarf einen unterstützten Abfrageausdruck für die gewählte Operation unter der Überschrift Query Strings (Abfragezeichenfolgen) ein.

   6. Geben Sie bei Bedarf einzelne oder mehrere unterstützte Header-Ausdrücke für die gewählte Operation unter der Überschrift Headers (Header) ein.

   7. Sofern konfiguriert, legen Sie die erforderlichen Werte der Stufenvariablen für die gewählte Operation unter der Überschrift Stage Variables (Stufenvariablen) fest.

   8. Wählen Sie bei Aufforderung ggf. ein API Gateway-generiertes Client-Zertifikat unter der Überschrift Client Certificate (Client-Zertifikat ) des Vorgangs aus, um vom Backend authentifiziert zu werden.

   9. Geben Sie bei Aufforderung einen geeigneten Anforderungstext im Texteditor unter der Überschrift Request Body (Anforderungstext) ein.

   10. Wählen Sie Test aus, um das Aufrufen der Methode zu testen.

   Verwenden Sie für dieses Tutorial GET statt ANY als Method (Methode). Verwenden Sie petstore/pets als Path (Pfad) anstelle des Proxy-Ressourcen-Pfads ({proxy}) und type=fish als Query Strings (Abfragezeichenfolgen).

   

   Da die Backend-Website die GET /petstore/pets?type=fish-Anforderung unterstützt, wird eine erfolgreiche Antwort wie die folgende zurückgegeben:

   [
     {
       "id": 1,
       "type": "fish",
       "price": 249.99
     },
     {
       "id": 2,
       "type": "fish",
       "price": 124.99
     },
     {
       "id": 3,
       "type": "fish",
       "price": 0.99
     }
   ]

   Wenn Sie versuchen, GET /petstore aufzurufen, erhalten Sie eine 404-Antwort mit der Fehlermeldung Cannot GET /petstore. Der Grund hierfür ist, dass das Backend die angegebene Operation nicht unterstützt. Wenn Sie GET /petstore/pets/1 aufrufen, erhalten Sie die Antwort 200 OK mit der folgenden Nutzlast, da die Anforderung von der PetStore-Website unterstützt wird.

   {
     "id": 1,
     "type": "dog",
     "price": 249.99
   }

2. Um einen Browser zum Aufrufen einer GET-Methode auf einer bestimmten Ressource der API zu verwenden, gehen Sie wie folgt vor:

   1. Sofern noch nicht geschehen, wählen Sie für die erstellte API die Option Deploy API (API bereitstellen) im Dropdown-Menü Actions (Aktionen) aus. Befolgen Sie zur Bereitstellung der API auf einer bestimmten Stufe die Anweisungen. Notieren Sie die Invoke URL (Aufruf-URL), die auf der resultierenden Stage Editor (Stufeneditor) -Seite angezeigt wird. Dies ist die Basis-URL der API.

   2. Um eine GET-Anforderung mit einer bestimmten Ressource zu übermitteln, fügen Sie den Ressourcenpfad an, einschließlich ggf. vorhandener Abfragezeichenfolgenausdrücke für den im vorherigen Schritt abgerufenen Invoke URL (Aufruf-URL)-Wert, kopieren dann die vollständige URL in die Adressleiste eines Browsers und drücken anschließend die Eingabetaste.

   Stellen Sie für dieses Tutorial die API für eine test-Stufe bereit, hängen Sie petstore/pets?type=fish an die Invoke-URL der API an. So entsteht die URL https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/petstore/pets?type=fish.

   Das Ergebnis sollte das sein, das Sie erhalten, wenn Sie TestInvoke von der API Gateway-Konsole aus verwenden.