Tutorial: Erstellen Sie eine REST-API als Amazon S3 S3-Proxy - Amazon API Gateway

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Tutorial: Erstellen Sie eine REST-API als Amazon S3 S3-Proxy

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:

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 Entwickeln Sie REST-APIs mit OpenAPI in API Gateway.

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.

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.

Um die Ausführungsrolle AWS für den Service-Proxy zu erstellen
  1. Melden Sie sich bei der an AWS Management Console 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 Dienst aus, wählen Sie dann API Gateway aus und wählen Sie Erlaubt API Gateway, Logs in Logs zu CloudWatch übertragen.

  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

Sie verwenden die Root (/) -Ressource der API als Container für die Amazon S3 S3-Buckets eines authentifizierten Aufrufers. Sie erstellen auch Item Ressourcen Folder und, um einen bestimmten Amazon S3 S3-Bucket bzw. ein bestimmtes Amazon S3 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 Weise, in der AWS-Region Sie Ihren Amazon S3 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:

    Erstellen einer API in API Gateway als Amazon S3-Proxy

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 den Ort aus AWS-Region, AWS-Region an dem Sie Ihren Amazon S3 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 Einstellungen für Methodenanfragen aus.

    Sie verwenden die Einstellungen für Methodenanfragen, um zu steuern, wer diese Methode Ihrer API aufrufen kann.

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

    Deklarieren von Methodenantworttypen
  13. 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.

Damit Ihre API erfolgreiche Antworten und Ausnahmen ordnungsgemäß an den Aufrufer zurückgibt, deklarieren Sie die Antworten 200, 400 und 500 in Method Response. Sie verwenden die Standardzuordnung für 200 Antworten, sodass Backend-Antworten mit dem hier nicht deklarierten Statuscode als 200 Antworten an den Aufrufer 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 Standardmethodenantwort von API Gateway eine JSON-Nutzlast zurückgibt, müssen Sie den Wert des Backend-Header-Parameters Content-Type dem Frontend-Gegenstück zuordnen. 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 möchten Sie dem Client auch andere Header-Parameter wie Datum und Inhaltslänge anzeigen.

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:

    Zuweisen von Integrationsantwort-Headern zu Methodenantwort-Headern
  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 Erstellen.

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

Es hat sich bewährt, die API zu testen, die Sie 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:

    Testen des GET-Bucket-Ergebnisses für API-Stammressource

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

Um mit einem Amazon S3 S3-Bucket zu arbeiten, machen Sie die GET Methode für die Ressource/{folder} verfügbar, um Objekte in einem Bucket aufzulisten. 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 den Ort aus AWS-Region, AWS-Region an dem Sie Ihren Amazon S3 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.

  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.

    Testen der GET-Methode zur Erstellung eines Amazon-S3-Bucket.

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 den Ort aus AWS-Region, AWS-Region an dem Sie Ihren Amazon S3 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.

    Testen der GET-Methode zur Erstellung eines Amazon-S3-Bucket.

    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 bei den APIs binaryMediaTypes. 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.