Tutorial: Erstellen einer REST-API als Amazon S3-Proxy in API Gateway

Dieser Abschnitt zeigt anhand eines Beispiels die Verwendung einer REST-API in API Gateway als Amazon S3-Proxy und beschreibt das Erstellen und Konfigurieren einer REST-API zur Bereitstellung der folgenden Amazon S3-Operationen:

• Bereitstellung von GET bei der Stammressource der API, um alle Amazon S3-Buckets eines Aufrufers aufzulisten.

• Bereitstellung von GET bei einer Folder-Ressource, um eine Liste aller Objekte in einem Amazon S3-Bucket anzuzeigen.

• Bereitstellung von GET bei einer Folder/Item-Ressource, um ein Objekt von einem Amazon S3-Bucket anzuzeigen oder herunterzuladen.

Unter Umständen sollten Sie die Beispiel-API wie in OpenAPI-Definitionen der Beispiel-API als Amazon-S3-Proxy gezeigt als Amazon-S3-Proxy importieren. Dieses Beispiel enthält weitere exponierte Methoden. Anweisung zum Importieren einer API mithilfe der OpenAPI-Definition finden Sie unter Konfigurieren einer REST-API mit OpenAPI.

Anmerkung

Um Ihre API Gateway-API in Amazon S3 zu integrieren, müssen Sie eine Region auswählen, in der sowohl die API Gateway- als auch die Amazon S3-Services verfügbar sind. Informationen zur Verfügbarkeit der Regionen finden Sie unter Amazon API Gateway-Endpunkte und -Kontingente.

Themen

• Einrichten von IAM-Berechtigungen für die API, um Amazon S3-Aktionen aufzurufen
• Erstellen von API-Ressourcen zum Darstellen von Amazon S3-Ressourcen
• Bereitstellen einer API-Methode zur Auflistung der Amazon S3-Buckets des Aufrufers
• Bereitstellen von API-Methoden, um auf einen Amazon S3-Bucket zuzugreifen
• Bereitstellen von API-Methoden für den Zugriff auf ein Amazon S3-Objekt in einem Bucket
• OpenAPI-Definitionen der Beispiel-API als Amazon-S3-Proxy
• Aufrufen der API mit einem REST-API-Client

Einrichten von IAM-Berechtigungen für die API, um Amazon S3-Aktionen aufzurufen

Einer IAM-Rolle müssen geeignete IAM-Richtlinien zugeordnet sein, damit die API erforderliche Amazon-S3-Aktionen aufrufen kann.

Erstellen der Ausführungsrolle für den AWS-Service-Proxy

1. Melden Sie sich bei der AWS Management Console an, und öffnen Sie die IAM-Konsole unter https://console.aws.amazon.com/iam/.

2. Wählen Sie Roles.

3. Wählen Sie Rolle erstellen aus.

4. Wählen Sie unter Typ der vertrauenswürdigen Entität auswählen die Option AWS-Service und anschließend API Gateway und Erlaubt API Gateway, Protokolle an CloudWatch Logs zu senden aus.

5. Klicken Sie auf Weiter und dann erneut auf Weiter.

6. Geben Sie für Role name (Rollenname) den Namen APIGatewayS3ProxyPolicy ein und klicken Sie auf Create role (Rolle erstellen).

7. Wählen Sie in der Liste Roles die Rolle aus, die Sie gerade erstellt haben. Möglicherweise müssen Sie scrollen oder die Rolle über die Suchleiste finden.

8. Wählen Sie für die ausgewählte Rolle die Registerkarte Berechtigungen hinzufügen aus.

9. Wählen Sie in der Dropdown-Liste Berechtigungen anfügen aus.

10. Geben Sie im Suchfeld AmazonS3FullAccess ein und wählen Sie Berechtigungen hinzufügen aus.

    Anmerkung

    Dieses Tutorial verwendet der Einfachheit halber eine verwaltete Richtlinie. Als Best Practice sollten Sie Ihre eigene IAM-Richtlinie erstellen, um die erforderlichen Mindestberechtigungen zu gewähren.

11. Notieren Sie sich den neu erstellten Rollen-ARN, Sie werden ihn später brauchen.

Erstellen von API-Ressourcen zum Darstellen von Amazon S3-Ressourcen

Wir verwenden die Stammressource (/) der API als Container des Amazon S3-Buckets eines authentifizierten Aufrufers. Außerdem erstellen wir die Ressourcen Folder und Item, um einen bestimmten Amazon S3-Bucket bzw. ein bestimmtes Amazon S3-Objekt darzustellen. Der Ordnername und der Objektschlüssel werden vom Aufrufer in Form von Pfadparametern als Teil einer Anforderungs-URL angegeben.

Anmerkung

Beim Zugriff auf Objekte, deren Objektschlüssel / oder andere Sonderzeichen enthält, müssen diese Zeichen URL-kodiert sein. Beispielsweise sollte test/test.txt zu test%2Ftest.txt kodiert werden.

So erstellen Sie eine API-Ressource, die die Amazon S3-Servicefunktionen bereitstellt

1. Erstellen Sie in derselben AWS-Region, in der Sie Ihren Amazon-S3-Bucket erstellt haben, eine API mit dem Namen myS3. Die Stammressource dieser API (/) stellt den Amazon S3-Service dar. In diesem Schritt erstellen Sie zwei zusätzliche Ressourcen: /{folder} und /{item}.

2. Wählen Sie die Stammressource für die API aus und klicken Sie dann auf Ressource erstellen.

3. Die Proxy-Ressource bleibt ausgeschaltet.

4. Wählen Sie für Ressourcenpfad / aus.

5. Geben Sie für Resource name (Ressourcenname) {folder} ein.

6. CORS (Cross Origin Resource Sharing) bleibt unmarkiert.

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

8. Wählen Sie die /{folder}-Ressource aus und klicken Sie dann auf Ressource erstellen.

9. Wiederholen Sie die Schritte oben, um eine untergeordnete Ressource für /{folder} mit dem Namen {item} zu erstellen.

   Die endgültige API sollte wie folgt aussehen:

   

Bereitstellen einer API-Methode zur Auflistung der Amazon S3-Buckets des Aufrufers

Um die Liste der Amazon S3-Buckets des Aufrufers zu erhalten, muss die Aktion GET Service in Amazon S3 aufgerufen werden. Erstellen Sie die GET-Methode in der Stammressource der API (/). Konfigurieren Sie die GET-Methode für die Integration in Amazon S3 wie folgt.

So erstellen und initialisieren Sie die GET /-Methode der API

1. Wählen Sie die /-Ressource aus und klicken Sie dann auf Methode erstellen.

2. Wählen Sie als Methodentyp GET aus.

3. Für Integrationstyp wählen Sie AWS-Service aus.

4. Wählen Sie für AWS-Region die AWS-Region aus, wo Sie Ihren Amazon-S3-Bucket erstellt haben.

5. Wählen Sie für AWS-Service Amazon Simple Storage Service aus.

6. Lassen Sie die AWS-Subdomain leer.

7. Für HTTP-Methode wählen Sie GET aus.

8. Wählen Sie für Aktionstyp Pfadüberschreibung verwenden aus. Wenn der Pfad überschrieben wird, leitet API Gateway die Client-Anfrage an Amazon S3 als die entsprechende Amazon S3-REST-API-Path-Style-Anfrage weiter, worin eine Amazon S3-Ressource durch den Ressourcen-Pfad des s3-host-name/bucket/key-Musters ausgedrückt wird. API Gateway legt den s3-host-name fest und gibt den Client, der in bucket und key spezifiziert ist, vom Client an Amazon S3 weiter.

9. Geben Sie für Pfadüberschreibung / ein.

10. Geben Sie für Ausführungsrolle den Rollen-ARN für APIGatewayS3ProxyPolicy ein.

11. Wählen Sie Methode erstellen aus.

Mit dieser Einrichtung wird die Frontend-Anforderung GET https://your-api-host/stage/ in das GET https://your-s3-host/ am Backend integriert.

Anmerkung

Nach der ersten Einrichtung können Sie diese Einstellungen auf der Seite Integration Request der Methode ändern.

Um zu kontrollieren, wer diese Methode unserer API aufrufen kann, aktivieren wir das Autorisierungs-Flag und setzen es auf AWS_IAM.

So aktivieren Sie IAM, um den Zugriff auf die GET-Methode zu kontrollieren

1. Wählen Sie auf der Registerkarte Methodenanfrage unter Methodenanfrage-Einstellungen die Option Bearbeiten aus.

2. Wählen Sie im Dropdown-Menü AWS_IAM für Autorisierung aus.

   

3. Wählen Sie Speichern.

Damit unsere API erfolgreiche Antworten und Ausnahmen ordnungsgemäß an den Aufrufer zurückgibt, deklarieren wir die 200, 400 und 500 Antworten in Method Response. Wir verwenden die Standard-Zuweisung für 200-Antworten, so dass hier nicht deklarierte Backend-Antworten des Statuscodes an den Aufrufer als 200-Antworten zurückgegeben werden.

Deklarieren der Antworttypen für die GET /-Methode

1. Klicken Sie auf der Registerkarte Methodenantwort unter Antwort 200 auf Bearbeiten.

2. Klicken Sie auf Header hinzufügen und gehen Sie wie folgt vor:

   1. Für Header-Name geben Sie Content-Type ein.

   2. Wählen Sie Add header.

   Wiederholen Sie diese Schritte, um einen Timestamp-Header und einen Content-Length-Header zu erstellen.

3. Wählen Sie Speichern.

4. Klicken Sie auf der Registerkarte Methodenantwort unter Methodenantworten auf Antwort erstellen.

5. Geben Sie als HTTP-Statuscode 400 ein.

   Für diese Antwort legen Sie keine Header fest.

6. Wählen Sie Speichern.

7. Wiederholen Sie die folgenden Schritte, um die Antwort 500 zu erstellen.

   Für diese Antwort legen Sie keine Header fest.

Da die erfolgreiche Integrationsantwort von Amazon S3 die Bucket-Liste als XML-Nutzlast zurückgibt und die standardmäßige Methodenantwort von API Gateway eine JSON-Nutzlast zurückgibt, müssen wir den Parameterwert des Backend-Content-Type-Headers seinem Frontend-Gegenstück zuweisen. Andernfalls erhält der Client application/json als Content-Type, wenn der Antworttext eigentlich eine XML-Zeichenfolge ist. Das folgende Verfahren zeigt, wie diese Einrichtung erfolgt. Darüber hinaus wollen wir dem Client auch andere Header-Parameter anzeigen, beispielsweise Datum und Content-Length.

So richten Sie Antwort-Header-Zuordnungen für die GET-Methode ein

1. Klicken Sie auf der Registerkarte Integrationsantwort unter Standard - Antwort auf Bearbeiten.

2. Geben Sie für den Header Content-Length den Wert integration.response.header.Content-Length als Zuordnungswert ein.

3. Geben Sie für den Header Content-Type den Wert integration.response.header.Content-Type als Zuordnungswert ein.

4. Geben Sie für den Header Timestamp den Wert integration.response.header.Date als Zuordnungswert ein.

5. Wählen Sie Speichern. Das Ergebnis sollte in etwa wie folgt aussehen:

   

6. Klicken Sie auf der Registerkarte Integrationsantwort unter Integrationsantworten auf Antwort erstellen.

7. Machen Sie für HTTP status regex (HTTP-Status-RegEx) den Eintrag 4\d{2}. Dadurch werden alle 4xx-HTTP-Antwortstatuscodes der Methodenantwort zugeordnet.

8. Wählen Sie für Statuscode der Methodenantwort 400 aus.

9. Wählen Sie Create (Erstellen) aus.

10. Wiederholen Sie die folgenden Schritte, um eine Integrationsantwort für die 500-Methodenantwort zu erstellen. Machen Sie für HTTP status regex (HTTP-Status-RegEx) den Eintrag 5\d{2}.

Testen wir zunächst die API, die wir bisher konfiguriert haben.

So testen Sie die GET /-Methode

1. Wählen Sie die Registerkarte Test. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen.

2. Wählen Sie Test aus. Das Ergebnis sollte wie in der folgenden Abbildung aussehen:

   

Bereitstellen von API-Methoden, um auf einen Amazon S3-Bucket zuzugreifen

Um mit einem zu arbeiten, stellen wir Die GET Methode in der /{folder}-Ressource zum Auflisten von Objekten in einem Bucket muss exponiert werden, damit sie in einem Amazon-S3-Bucket arbeiten kann. Die Anweisungen sind ähnlich wie diejenigen, die unter beschrieben sin Bereitstellen einer API-Methode zur Auflistung der Amazon S3-Buckets des Aufrufers. Sie können die Beispiel-API hier für weitere Methoden importieren, OpenAPI-Definitionen der Beispiel-API als Amazon-S3-Proxy.

Exponieren der GET-Methoden in einer Ordnerressource

1. Wählen Sie die /{folder}-Ressource aus und klicken Sie dann auf Methode erstellen.

2. Wählen Sie als Methodentyp GET aus.

3. Für Integrationstyp wählen Sie AWS-Service aus.

4. Wählen Sie für AWS-Region die AWS-Region aus, wo Sie Ihren Amazon-S3-Bucket erstellt haben.

5. Wählen Sie für AWS-Service Amazon Simple Storage Service aus.

6. Lassen Sie die AWS-Subdomain leer.

7. Für HTTP-Methode wählen Sie GET aus.

8. Wählen Sie für Aktionstyp Pfadüberschreibung verwenden aus.

9. Geben Sie für Pfadüberschreibung {bucket} ein.

10. Geben Sie für Ausführungsrolle den Rollen-ARN für APIGatewayS3ProxyPolicy ein.

11. Wählen Sie Methode erstellen aus.

Der {folder}-Pfadparameter wird in der Amazon-S3-Endpunkt-URL festgelegt. Der {folder}-Pfadparameter der Methodenanforderung muss dem {bucket}-Pfadparameter der Integrationsanforderung zugeordnet werden.

Zuordnen von {folder} zu {bucket}

1. Klicken Sie auf der Registerkarte Integrationsanfrage unter Einstellungen für Integrationsanfragen auf Bearbeiten.

2. Wählen Sie URL-Pfadparameter aus und klicken Sie dann auf Pfadparameter hinzufügen.

3. Geben Sie unter Name bucket ein.

4. Geben Sie für Zugeordnet von method.request.path.folder ein. Die Konfiguration sollte ähnlich wie folgt aussehen:

   

5. Wählen Sie Speichern.

Als Nächstes testen Sie Ihre API.

Testen der /{folder} GET-Methode

1. Wählen Sie die Registerkarte Test. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen.

2. Geben Sie den Namen Ihres Buckets unter Pfad für Ordner ein.

3. Wählen Sie Test aus.

   Das Testergebnis wird eine Liste der Objekte in Ihrem Bucket enthalten.

   

Bereitstellen von API-Methoden für den Zugriff auf ein Amazon S3-Objekt in einem Bucket

Amazon S3 unterstützt GET-, DELETE-, HEAD-, OPTIONS-, POST- und PUT-Aktionen für den Zugriff auf und die Verwaltung von Objekte(n) in einem bestimmten Bucket. In diesem Tutorial exponieren Sie eine GET-Methode für die {folder}/{item}-Ressource, um eine Abbildung aus einem Bucket abzurufen. Weitere Nutzungsbeispiele der {folder}/{item} Ressource finden Sie in der Beispiel-API, OpenAPI-Definitionen der Beispiel-API als Amazon-S3-Proxy.

Exponieren der GET-Methode in einer item-Ressource

1. Wählen Sie die /{item}-Ressource aus und klicken Sie dann auf Methode erstellen.

2. Wählen Sie als Methodentyp GET aus.

3. Für Integrationstyp wählen Sie AWS-Service aus.

4. Wählen Sie für AWS-Region die AWS-Region aus, wo Sie Ihren Amazon-S3-Bucket erstellt haben.

5. Wählen Sie für AWS-Service Amazon Simple Storage Service aus.

6. Lassen Sie die AWS-Subdomain leer.

7. Für HTTP-Methode wählen Sie GET aus.

8. Wählen Sie für Aktionstyp Pfadüberschreibung verwenden aus.

9. Geben Sie für Pfadüberschreibung {bucket}/{object} ein.

10. Geben Sie für Ausführungsrolle den Rollen-ARN für APIGatewayS3ProxyPolicy ein.

11. Wählen Sie Methode erstellen aus.

Die Pfadparameter {folder} und {item} werden in der Amazon-S3-Endpunkt-URL festgelegt. Der -Pfadparameter der Methodenanforderung muss dem -Pfadparameter der Integrationsanforderung zugeordnet werden.

In diesem Schritt führen Sie folgende Aufgaben aus:

• Ordnen Sie den Pfadparameter {folder} der Methodenanforderung dem Pfadparameter {bucket} der Integrationsanforderung zu.

• Ordnen Sie den Pfadparameter {item} der Methodenanforderung dem Pfadparameter {object} der Integrationsanforderung zu.

Zuordnen von {folder} zu {bucket} und {item} zu {object}

1. Klicken Sie auf der Registerkarte Integrationsanfrage unter Einstellungen für Integrationsanfragen auf Bearbeiten.

2. Klicken Sie auf URL-Pfadparameter.

3. Klicken Sie auf Pfadparameter hinzufügen.

4. Geben Sie unter Name bucket ein.

5. Geben Sie für Zugeordnet von method.request.path.folder ein.

6. Klicken Sie auf Pfadparameter hinzufügen.

7. Geben Sie unter Name object ein.

8. Geben Sie für Zugeordnet von method.request.path.item ein.

9. Wählen Sie Speichern.

Testen der /{folder}/{object} GET-Methode

1. Wählen Sie die Registerkarte Test. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen.

2. Geben Sie den Namen Ihres Buckets unter Pfad für Ordner ein.

3. Geben Sie unter Pfad, Element den Namen eines Elements ein.

4. Wählen Sie Test aus.

   Der Antworttext enthält den Inhalt des Elements.

   

   Die Anforderung gibt den Klartext („Hello world“) als Inhalt der angegebenen Datei (test.txt) in dem entsprechenden Amazon-S3-Bucket (DOC-EXAMPLE-BUCKET) zurück.

Um Binärdateien, die in API Gateway als irgendetwas anderes als utf-8-codierter JSON-Inhalt betrachtet werden, herunter- oder hochzuladen, sind zusätzliche API-Einstellungen erforderlich. Dies kann wie folgt beschrieben werden:

Herunterladen oder Hochladen von Binärdateien von S3

1. Registrieren Sie die Medientypen der betroffenen Datei in den binaryMediaTypes des API. Sie können Sie von der Konsole aus erledigen:

   1. Wählen Sie API-Einstellungen für die API aus.

   2. Klicken Sie unter Binäre Medientypen auf Medientypen verwalten.

   3. Klicken Sie auf Binären Medientyp hinzufügen und geben Sie dann den erforderlichen Medientyp ein, z. B. image/png.

   4. Wählen Sie zum Speichern der Einstellung Save Changes (Änderungen speichern) aus.

2. Fügen Sie den Header Content-Type (zum Hochladen) und/oder Accept (zum Herunterladen) zur Methodenanfrage hinzu, um den Client aufzufordern, den erforderlichen binären Medientyp anzugeben, und weisen Sie sie der Integrationsanfrage zu.

3. Setzen Sie Content Handling in der Integrationsanfrage auf Passthrough (für das Hochladen), und in einer Integrationsantwort (für das Herunterladen). Stellen Sie sicher, dass keine Mapping-Vorlage für den betroffenen Inhaltstyp definiert ist. Weitere Informationen finden Sie unter Integrations-Pass-Through-Verhalten und Auswählen einer VTL-Mapping-Vorlage.

Die maximale Größe der Nutzlast ist 10 MB. Siehe API Gateway-Kontingente für die Konfiguration und Ausführung einer REST-API.

Stellen Sie sicher, dass für Dateien in Amazon S3 die richtigen Inhaltstypen als Metadaten der Dateien hinzugefügt wurden. Bei streamfähigen Medieninhalten muss den Metadaten möglicherweise auch Content-Disposition:inline hinzugefügt werden.

Weitere Informationen zur Unterstützung von Binärdateien in API Gateway finden Sie in Inhaltstypkonvertierungen in API Gateway.