Methodenanfrage in API Gateway einrichten

Das Einrichten einer Methodenanforderung beinhaltet die Durchführung folgender Aufgaben nach der Erstellung einer RestApi-Ressource:

Sie können diese Aufgaben mithilfe der folgenden Methoden durchführen:

Einrichten von API-Ressourcen

In einer API Gateway-API setzen Sie adressierbare Ressourcen als eine API-Ressourcen-Entitätsstruktur ein, mit der Stammressource (/) oben in der Hierarchie. Die Stammressource bezieht sich auf die Basis-URL der API, die aus dem API-Endpunkt und einem Stufennamen besteht. In der API Gateway-Konsole wird diese Basis-URI als Invoke URI (Aufruf-URI) bezeichnet und im Stage-Editor der API angezeigt, nachdem die API bereitgestellt wurde.

Der API-Endpunkt kann ein Standard-Host-Name oder ein benutzerdefinierter Domänenname sein. Der Standard-Host-Name hat das folgende Format:

{api-id}.execute-api.{region}.amazonaws.com

In diesem Format stellt der {api-id} die API-ID dar, die von API Gateway generiert wird. Die {region}-Variable stellt die AWS-Region (z. B. us-east-1) dar, die Sie bei der Erstellung der API auswählen. Ein benutzerdefinierter Domänenname ist jeder benutzerfreundliche Name in einer gültigen Internetdomäne. Wenn Sie beispielsweise eine Internetdomäne von example.com registriert haben, ist alles von *.example.com ein gültiger benutzerdefinierter Domänenname. Weitere Informationen finden Sie unter Erstellen eines benutzerdefinierten Domänenname.

Für die PetStore-Beispiel-API stellt die Stammressource (/) den PetStore bereit. Die /pets-Ressource stellt die Sammlung von Haustieren, die im PetStore verfügbar sind, dar. Die /pets/{petId} stellt ein einzelnes Haustier einer bestimmten ID (petId) dar. Der Pfadparameter von {petId} ist Teil der Anforderungsparameter.

Zum Konfigurieren einer API-Ressource wählen Sie eine vorhandene Ressource als übergeordnetes Element aus und erstellen anschließend unter dieser die untergeordnete Ressource. Sie beginnen mit der Stammressource als übergeordnetes Element, fügen diesem eine Ressource hinzu, fügen eine andere Ressource dieser untergeordneten Ressource als neues übergeordnetes Element und so weiter der übergeordneten ID hinzu. Anschließend fügen Sie die benannte Ressource dem übergeordneten Element hinzu.

Mit AWS CLI können Sie den Befehl get-resources aufrufen, um herauszufinden, welche Ressourcen einer API zur Verfügung stehen:

aws apigateway get-resources --rest-api-id <apiId> \
                             --region <region>

Das Ergebnis ist eine Liste der aktuell verfügbaren Ressourcen der API. Für unsere PetStore-Beispiel-API sieht diese Liste wie folgt aus:

{
    "items": [
        {
            "path": "/pets", 
            "resourceMethods": {
                "GET": {}
            }, 
            "id": "6sxz2j", 
            "pathPart": "pets", 
            "parentId": "svzr2028x8"
        }, 
        {
            "path": "/pets/{petId}", 
            "resourceMethods": {
                "GET": {}
            }, 
            "id": "rjkmth", 
            "pathPart": "{petId}", 
            "parentId": "6sxz2j"
        }, 
        {
            "path": "/", 
            "id": "svzr2028x8"
        }
    ]
}

Jedes Element listet die ID der Ressource (id) und, mit Ausnahme der Stammressource, das unmittelbar übergeordnete Element (parentId) sowie den Ressourcennamen (pathPart). Die Stammressource ist dahingehend besonders, dass sie über kein übergeordnetes Element verfügt. Nachdem Sie eine Ressource als übergeordnetes Element auswählt haben, rufen Sie den folgenden Befehl auf, um eine untergeordnete Ressource hinzuzufügen.

aws apigateway create-resource --rest-api-id <apiId> \
                             --region <region> \
                             --parent-id <parentId> \
                             --path-part <resourceName>

Um beispielsweise der PetStore-Website Haustierfutter zum Verkauf hinzuzufügen, fügen Sie eine food-Ressource dem Stammverzeichnis (/) hinzu, indem Sie path-part auf food und parent-id auf svzr2028x8 setzen. Das Ergebnis sollte wie folgt aussehen:

{
    "path": "/food", 
    "pathPart": "food", 
    "id": "xdsvhp", 
    "parentId": "svzr2028x8"
}

Verwenden Sie eine Proxy-Ressource zur Optimierung der API-Einrichtung

Bei wachsendem Unternehmen könnte der PetStore-Eigentümer sich dazu entscheiden, Futter, Spielzeug und andere Haustierartikel zum Verkauf hinzuzufügen. Um dies zu unterstützen, können Sie /food, /toys und andere Ressourcen unter der Stammressource hinzufügen. Unter jeder Verkaufskategorie möchten Sie möglicherweise auch weitere Ressourcen hinzufügen, wie /food/{type}/{item}, /toys/{type}/{item} usw. Dies kann sehr zeitaufwändig werden. Wenn Sie sich dazu entscheiden, eine mittlere Schicht {subtype} den Ressourcenpfaden hinzuzufügen, um die Pfadhierarchie in /food/{type}/{subtype}/{item}, /toys/{type}/{subtype}/{item}usw. zu ändern, könnten die Änderungen zu Fehlern bei der vorhandenen API-Einrichtung führen. Um dies zu vermeiden, können Sie ein API Gateway-Proxy-Ressource verwenden, um einen Satz von API-Ressourcen auf einmal bereitzustellen.

API Gateway definiert eine Proxy-Ressource als Platzhalter für eine Ressource, die bei der Übertragung der Anfrage angegeben wird. Eine Proxy-Ressource wird durch einen speziellen Pfadparameter {proxy+} ausgedrückt, häufig auch als gieriger Pfadparameter bezeichnet. Das +-Zeichen gibt an, welche untergeordneten Ressourcen ihm angehängt werden. Der Platzhalter /parent/{proxy+} steht für jede Ressource, die mit dem Pfadmuster /parent/* übereinstimmt. Der Name des gierigen Pfadparameters, proxy, kann auf die gleichen Art und Weise wie der Name eines regulären Pfadparameters durch eine andere Zeichenfolge ersetzt werden.

Mithilfe der AWS CLI können Sie den folgenden Befehl aufrufen, um eine Proxy-Ressource unter dem Stammverzeichnis (/{proxy+}) einzurichten:

aws apigateway create-resource --rest-api-id <apiId> \
                             --region <region> \
                             --parent-id <rootResourceId> \
                             --path-part {proxy+}

Das Ergebnis sollte wie folgt aussehen:

{
    "path": "/{proxy+}", 
    "pathPart": "{proxy+}", 
    "id": "234jdr", 
    "parentId": "svzr2028x8"
}

Für das PetStore-API-Beispiel können Sie /{proxy+} verwenden, um die /pets und /pets/{petId} darzustellen. Diese Proxy-Ressource kann auch jede andere (vorhandene oder hinzuzufügende) Ressource wie /food/{type}/{item}, /toys/{type}/{item} usw. oder /food/{type}/{subtype}/{item}, /toys/{type}/{subtype}/{item} usw. referenzieren. Die Backend-Developer bestimmt die Ressourcenhierarchie und der Client-Developer ist dafür verantwortlich, sie zu verstehen. API Gateway übergibt einfach alles, was der Client an das Backend übermittelt hat.

Eine API kann über mehr als eine Proxy-Ressource verfügen. Beispielsweise sind die folgenden Proxy-Ressourcen innerhalb einer API erlaubt, vorausgesetzt /parent/{proxy+} ist nicht dieselbe übergeordnete Ressource wie /parent/{child}/{proxy+}.

/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}

Wenn eine Proxy-Ressource über gleichwertige Nicht-Proxy-Elemente verfügt, werden die gleichwertigen Ressourcen von der Darstellung der Proxy-Ressource ausgeschlossen. Bei den vorherigen Beispielen bezieht sich /{proxy+} auf alle Ressourcen unter der Stammressource mit Ausnahme der /parent[/*]-Ressourcen. Mit anderen Worten, eine Methodenanforderung für eine bestimmte Ressource hat Vorrang vor einer ähnlichen Methodenanforderung für eine generische Ressource auf derselben Ebene der Ressourcenhierarchie.

Eine Proxy-Ressource kann über keine untergeordnete Ressource verfügen. Jede API-Ressource nach {proxy+} ist überflüssig und zweideutig. Die folgenden Proxy-Ressourcen sind nicht innerhalb einer API erlaubt.

/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}

Einrichten einer HTTP-Methode

Eine API-Methodenanforderung wird durch die API Gateway-Methode-Ressource gekapselt. Um die Methodenanforderung einzurichten, müssen Sie zuerst die Method-Ressource instanziieren und mindestens eine HTTP-Methode und einen Autorisierungstyp für die Methode festlegen.

API Gateway ist eng mit der Proxy-Ressource verbunden und unterstützt die HTTP-API-Methode ANY. Diese ANY-Methode entspricht der HTTP-Methode, die zur Laufzeit bereitgestellt wird. Sie gibt Ihnen die Möglichkeit, eine einzige API-Methodeneinrichtung für die unterstützten HTTP-Methoden DELETE, GET, HEAD, OPTIONS, PATCH, POST und PUT zu verwenden.

Sie können die ANY-Methode auch auf einer Nicht-Proxy-Ressource einrichten. Durch die Kombination der ANY-Methode mit einer Proxy-Ressource erhalten Sie eine einzige API-Methodeneinrichtung für alle unterstützten HTTP-Methoden gegen alle Ressourcen einer API. Darüber hinaus kann sich das Backend weiterentwickeln, ohne die vorhandene API-Einrichtung zu stören.

Berücksichtigen Sie vor dem Einrichten einer API-Methode, wer die Methode aufrufen kann. Legen Sie den Autorisierungstyp entsprechend Ihres Plans fest. Für einen offenen Zugriff setzen Sie ihn auf NONE. Zur Nutzung von IAM-Berechtigungen setzen Sie den Autorisierungstyp auf AWS_IAM. Um eine Lambda-Genehmiger-Funktion zu verwenden, setzen Sie diese Eigenschaft auf CUSTOM. Um einen Amazon Cognito-Benutzerpool zu verwenden, setzen Sie den Autorisierungstyp auf COGNITO_USER_POOLS.

Der folgende AWS CLI-Befehl zeigt die Erstellung einer Methodenanforderung des ANY-Verbs für eine bestimmte Ressource (6sxz2j) mithilfe der IAM-Berechtigungen, um ihren Zugriff zu steuern.

aws apigateway put-method --rest-api-id vaz7da96z6 \
       --resource-id 6sxz2j \
       --http-method ANY \
       --authorization-type AWS_IAM \
       --region us-west-2

Informationen zur Erstellung einer API-Methodenanforderung mit einem anderen Autorisierungstyp finden Sie unter Einrichten der Autorisierung der Methodenanforderung.

Einrichten von Methodenanforderungs-Parametern

Methodenanforderungs-Parameter sind eine Möglichkeit für einen Client, Eingabedaten oder Ausführungskontext bereitzustellen, damit die Methodenanforderung abgeschlossen werden kann. Ein Methodenparameter kann ein Pfadparameter, ein Header oder ein Abfragezeichenfolge-Parameter sein. Im Rahmen der Methodenanforderungseinrichtung müssen Sie die erforderlichen Anforderungsparameter deklarieren, um sie dem Client zur Verfügung zu stellen. Für eine Nicht-Proxy-Integration können Sie diese Anforderungsparameter in ein Formular umwandeln, das mit der Backend-Anforderung kompatibel ist.

Zum Beispiel ist für die GET /pets/{petId}-Methodenanforderung die {petId}-Pfadvariable ein erforderlicher Anforderungsparameter. Sie können diesen Pfadparameter beim Aufrufen des Befehls AWS CLI der put-method deklarieren. Dies kann wie folgt dargestellt werden:

aws apigateway put-method --rest-api-id vaz7da96z6 \
       --resource-id rjkmth \
       --http-method GET \
       --authorization-type "NONE" \
       --region us-west-2 \
       --request-parameters method.request.path.petId=true

Wenn ein Parameter nicht erforderlich ist, können Sie ihn auf false in request-parameters setzen. Wenn beispielsweise die GET /pets-Methode den optionalen Abfragezeichenfolge-Parameter type und den optionalen Header-Parameter breed verwendet, können Sie diese mithilfe des folgenden CLI-Befehls deklarieren, vorausgesetzt, dass die /pets-Ressourcen-id 6sxz2j lautet:

aws apigateway put-method --rest-api-id vaz7da96z6 \
       --resource-id 6sxz2j \
       --http-method GET \
       --authorization-type "NONE" \
       --region us-west-2 \
       --request-parameters method.request.querystring.type=false,method.request.header.breed=false

Anstelle dieser Kurzform können Sie eine JSON-Zeichenfolge verwenden, um den request-parameters-Wert zu setzen:

'{"method.request.querystring.type":false,"method.request.header.breed":false}'

Mit dieser Einrichtung kann der Client die Haustiere nach Typ abfragen:

GET /pets?type=dog

Und der Client kann Hunde der Rasse Pudel wie folgt abfragen:

GET /pets?type=dog
breed:poodle

Weitere Informationen, wie Methodenanforderungs-Parameter den Integrationsanforderungs-Parametern zugewiesen werden, finden Sie unter Integrationen für REST-APIs in API Gateway.

Einrichten eines Methodenanforderungsmodells

Für eine API-Methode, die Eingabedaten in eine Nutzlast übernehmen kann, können Sie ein Modell verwenden. Ein Modell wird in einem JSON-Schema Entwurf 4 ausgedrückt und beschreibt die Datenstruktur des Anforderungstexts. Mit einem Modell kann ein Client festlegen, wie eine Methodenanforderungsnutzlast als Eingabe erstellt wird. Noch wichtiger ist, dass API Gateway das Modell verwendet, um eine Anfrage zu validieren, ein SDK zu generieren und eine Mapping-Vorlage für die Einrichtung der Integration in der API Gateway-Konsole zu initialisieren. Informationen zum Erstellen eines Modells finden Sie unter Grundlegendes zu Datenmodellen.

Je nach Inhaltstypen, kann eine Methodenutzlast über unterschiedliche Formate verfügen. Ein Modell wird für den Medientyp der angewendeten Nutzlast indiziert. API Gateway verwendet den Content-Type Anforderungsheader, um den Inhaltstyp zu bestimmen. Um Modelle der Methodenanforderung einzurichten, fügen Sie Schlüssel-Wert-Paare im Format "<media-type>":"<model-name>" der requestModels-Map hinzu, wenn Sie den AWS CLI-Befehl put-method aufrufen.

Um das gleiche Modell unabhängig vom Inhaltstyp zu verwenden, geben Sie es $default als Schlüssel an.

Um beispielsweise ein Modell für die JSON-Nutzlast der POST /pets-Methodenanforderung der PetStore-Beispiel-API festzulegen, können Sie den folgenden AWS CLI-Befehl aufrufen:

aws apigateway put-method \
       --rest-api-id vaz7da96z6 \
       --resource-id 6sxz2j \
       --http-method POST \
       --authorization-type "NONE" \
       --region us-west-2 \
       --request-models '{"application/json":"petModel"}'

Hier ist petModel der name-Eigenschaftswert einer Model-Ressource, die ein Haustier beschreibt. Die tatsächliche Schemadefinition wird als JSON-Zeichenfolgenwert der schema-Eigenschaft der Model-Ressource ausgedrückt.

In einem Java oder anderen stark typisierten SDK der API werden die Eingabedaten in die petModel-Klasse umgewandelt, die von der Schemadefinition abgeleitet sind. Mit dem Anforderungsmodell werden die Eingabedaten in dem generierten SDK in die Empty-Klasse umgewandelt, die von dem Standard-Empty-Modell abgeleitet wird. In diesem Fall kann der Client nicht die richtige Datenklasse instanziieren, um die benötigte Ausgabe bereitzustellen.

Einrichten der Autorisierung der Methodenanforderung

Um zu steuern, wer die API-Methode aufrufen kann, können Sie den Autorisierungstyp für die Methode konfigurieren. Sie können diesen Typ verwenden, um einen der unterstützten Genehmiger einzusetzen, einschließlich IAM-Rollen und -Richtlinien (AWS_IAM), einen Amazon Cognito-Benutzerpool (COGNITO_USER_POOLS) oder einen Lambda-Genehmiger (CUSTOM).

Um IAM-Berechtigungen für die Autorisierung des Zugriffs auf die API-Methode zu verwenden, setzen Sie die authorization-type-Eingabeeigenschaft auf AWS_IAM. Wenn Sie diese Option festlegen, verifiziert API Gateway die Signatur des Aufrufers in der Anfrage basierend auf den Anmeldeinformationen des Aufrufers. Wenn der bestätigte Benutzer über die Berechtigung zum Aufrufen der Methode verfügt, akzeptiert sie die Anforderung. Andernfalls lehnt sie die Anforderung ab und der Aufrufer erhält die Fehlerantwort „Unbefugt“. Der Aufruf der Methode ist nicht erfolgreich, es sei denn, der Aufrufer hat die Berechtigung, die API-Methode aufzurufen. Die folgende IAM-Richtlinie gewährt dem Aufrufer die Berechtigung, alle darin API-Methoden aufzurufen, die im gleichen AWS-Konto erstellt wurden:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": "arn:aws:execute-api:*:*:*"
        }
    ]
}

Weitere Informationen finden Sie unter Zugriffskontrolle für eine API mit IAM-Berechtigungen.

Derzeit können Sie diese Richtlinie nur Benutzern, Gruppen und Rollen innerhalb des AWS-Konto des API-Besitzers gewähren. Benutzer von einem anderen AWS-Konto können die API-Methoden nur aufrufen, wenn sie berechtigt sind, innerhalb des AWS-Konto des API-Besitzers nur den erforderlichen Berechtigungen zum Aufrufen der execute-api:Invoke-Aktion eine Rolle zu übernehmen. Weitere Informationen zu kontoübergreifenden Berechtigungen finden Sie unter Verwenden von IAM-Rollen.

Sie können AWS CLI, ein AWS-SDK oder einen REST-API-Client (z. B. Postman) verwenden, der die Signierung mit Signature Version 4 (SigV4) implementiert.

Um einen Lambda-Genehmiger für die Autorisierung des Zugriffs auf die API-Methode zu verwenden, setzen Sie die authorization-type-Eingabeeigenschaft auf CUSTOM und die authorizer-id-Eingabeeigenschaft auf den id-Eigenschaftswert eines Lambda-Genehmigers, der bereits vorhanden ist. Der referenzierte Lambda-Genehmiger kann vom Typ TOKEN oder REQUEST sein. Informationen zur Erstellung eines Lambda-Genehmigers finden Sie unter API Gateway-Lambda-Genehmiger verwenden.

Um einen Amazon Cognito-Benutzerpool für die Autorisierung des Zugriffs auf die API-Methode zu verwenden, setzen Sie die authorization-type-Eingabeeigenschaft auf COGNITO_USER_POOLS und die authorizer-id-Eingabeeigenschaft auf den id-Eigenschaftswert des COGNITO_USER_POOLS-Genehmigers, der bereits vorhanden ist. Informationen über die Erstellung eines Genehmigers für einen Amazon Cognito-Benutzerpool finden Sie unter In der Rolle „Genehmiger“ den Zugriff auf REST-APIs mithilfe von Amazon-Cognito-Benutzerpools steuern.

Einrichten einer Validierung der Methodenanforderung

Sie können die Anforderungsvalidierung beim Einrichten einer API-Methodenanforderung aktivieren. Sie müssen zuerst eine Anforderungsvalidierung erstellen:

aws apigateway create-request-validator \
    --rest-api-id 7zw9uyk9kl \
    --name bodyOnlyValidator \
    --validate-request-body  \
    --no-validate-request-parameters

Dieser CLI-Befehl erstellt eine Nur-Text-Anforderungsvalidierung. Die Beispielausgabe lautet wie folgt:

{
    "validateRequestParameters": false, 
    "validateRequestBody": true, 
    "id": "jgpyy6", 
    "name": "bodyOnlyValidator"
}

Mit dieser Anforderungsvalidierung können Sie Anforderungsvalidierung als Teil der Einrichtung der Methodenanforderung aktivieren:

aws apigateway put-method \
    --rest-api-id 7zw9uyk9kl 
    --region us-west-2 
    --resource-id xdsvhp 
    --http-method PUT 
    --authorization-type "NONE" 
    --request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' 
    --request-models '{"application/json":"petModel"}'
    --request-validator-id jgpyy6

Um in einer Anforderungsvalidierung aufgenommen zu werden, muss ein Anforderungsparameter als erforderlich deklariert werden. Wenn der Abfragezeichenfolge-Parameter für die Seite in einer Anforderungsvalidierung verwendet wird, muss die request-parameters-Map des vorangehenden Beispiels als '{"method.request.querystring.type": false, "method.request.querystring.page":true}' festgelegt werden.