Richten Sie eine Methodenanforderung in API Gateway ein

Das Einrichten einer Methodenanforderung umfasst das Ausführen der folgenden Aufgaben, nachdem eine RestApiRessource erstellt wurde:

1. Erstellen einer neuen API oder Auswahl einer vorhandenen API Ressourcenentität.

2. Erstellen einer API Methodenressource, bei der es sich um ein bestimmtes HTTP Verb für die neue oder gewählte Ressource handelt APIResource. Diese Aufgabe kann noch weiter in die folgenden Sub-Aufgaben unterteilt werden:

   • Eine HTTP Methode zur Methodenanforderung hinzufügen

   • Konfigurieren von Anforderungsparametern

   • Definieren eines Modells für den Anforderungstextkörper

   • Einfügen eines Autorisierungsschemas

   • Aktivieren einer Anforderungsvalidierung

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

• APIGateway-Konsole

• AWS CLI Befehle (Create-Resource und Put-Methode)

• AWS SDKFunktionen (zum Beispiel in Node.js und) createResourceputMethod

• APIGateway REST API (resource:create und method:put).

APIRessourcen einrichten

In einem API Gateway API stellen Sie adressierbare Ressourcen als Baum von Ressourcenentitäten API zur Verfügung, wobei die Stammressource (/) ganz oben in der Hierarchie steht. Die Root-Ressource ist relativ zur Basis API vonURL, die aus dem API Endpunkt und einem Staging-Namen besteht. In der API Gateway-Konsole URI wird diese Basis als Invoke bezeichnet URI und nach der Bereitstellung im Stage-Editor API von angezeigt. API

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

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

In diesem Format ist der {api-id} steht für den API Bezeichner, der von API Gateway generiert wird. Die {region} Variable steht für die AWS Region (z. B.us-east-1), die Sie bei der Erstellung der ausgewählt habenAPI. 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 das PetStore APIBeispiel macht die Root-Ressource (/) die Tierhandlung verfügbar. 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.

Um eine API Ressource einzurichten, wählen Sie eine vorhandene Ressource als übergeordnete Ressource aus und erstellen dann die untergeordnete Ressource unter dieser übergeordneten 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 get-resources Befehl aufrufen, um herauszufinden, welche Ressourcen einer verfügbar API sind:

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

Das Ergebnis ist eine Liste der aktuell verfügbaren Ressourcen vonAPI. Für unser PetStore API Beispiel 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 Tiernahrung zum Verkauf auf der PetStore Website hinzuzufügen, fügen Sie dem Stamm (/) eine food Ressource hinzu, indem Sie path-part auf food und parent-id to setzensvzr2028x8. Das Ergebnis sollte wie folgt aussehen:

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

Verwenden Sie eine Proxyressource, um die Einrichtung zu optimieren API

Wenn das Geschäft wächst, kann der PetStore Eigentümer beschließen, Lebensmittel, Spielzeug und andere Artikel, die mit Haustieren zu tun haben, zum Verkauf anzubieten. 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 beschließen, den Ressourcenpfaden eine mittlere Ebene {subtype} hinzuzufügen, um die Pfadhierarchie zu ändern usw. /food/{type}/{subtype}/{item}/toys/{type}/{subtype}/{item}, werden die Änderungen die bestehende Konfiguration API zerstören. Um dies zu vermeiden, können Sie eine API Gateway-Proxyressource verwenden, um eine Reihe von API Ressourcen gleichzeitig verfügbar zu machen.

APIGateway definiert eine Proxyressource als Platzhalter für eine Ressource, die beim Absenden der Anfrage angegeben werden muss. 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.

Mit dem rufen Sie den folgenden Befehl auf AWS CLI, um eine Proxyressource unter dem Stamm (/{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"
}

In diesem PetStore API Beispiel können Sie verwenden, /{proxy+} um /pets sowohl das als auch darzustellen/pets/{petId}. Diese Proxyressource kann auch auf alle anderen (vorhandenen oder to-be-added) Ressourcen verweisen /food/{type}/{item}/toys/{type}/{item}, z. B. auf, usw. oder /food/{type}/{subtype}/{item}/toys/{type}/{subtype}/{item}, usw. Die Backend-Developer bestimmt die Ressourcenhierarchie und der Client-Developer ist dafür verantwortlich, sie zu verstehen. APIGateway leitet einfach alles weiter, was der Client an das Backend übermittelt hat.

Ein API kann mehr als eine Proxy-Ressource haben. Beispielsweise sind die folgenden Proxyressourcen innerhalb einer zulässigAPI, vorausgesetzt, es /parent/{proxy+} handelt sich nicht um 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 danach {proxy+} ist redundant und mehrdeutig. Die folgenden Proxyressourcen sind innerhalb eines nicht zulässigAPI.

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

Richten Sie eine HTTP Methode ein

Eine API Methodenanforderung wird von der API Gateway-Methodenressource 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.

APIGateway ist eng mit der Proxyressource verknüpft und unterstützt eine HTTP Methode von. ANY Diese ANY Methode steht für jede HTTP Methode, die zur Laufzeit bereitgestellt werden soll. Sie ermöglicht es Ihnen, ein einziges API Methoden-Setup für alle unterstützten HTTP Methoden vonDELETE,GET,HEAD, OPTIONS PATCHPOST, und zu verwendenPUT.

Sie können die ANY-Methode auch auf einer Nicht-Proxy-Ressource einrichten. Wenn Sie die ANY Methode mit einer Proxyressource kombinieren, erhalten Sie ein einziges API Methoden-Setup für alle unterstützten HTTP Methoden gegen alle Ressourcen einesAPI. Darüber hinaus kann sich das Backend weiterentwickeln, ohne das bestehende API Setup zu beschädigen.

Überlegen Sie sich 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. Um IAM Berechtigungen zu verwenden, legen Sie den Autorisierungstyp auf festAWS_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, wie eine Methodenanforderung des ANY Verbs für eine angegebene Ressource (6sxz2j) erstellt wird, wobei die IAM Berechtigungen zur Steuerung des Zugriffs verwendet werden.

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

Informationen zum Erstellen einer API Methodenanforderung mit einem anderen Autorisierungstyp finden Sie unterEinrichten 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 die GET /pets Methode beispielsweise einen optionalen Abfragezeichenfolgenparameter von type und einen optionalen Header-Parameter von verwendetbreed, können Sie sie mit dem folgenden CLI Befehl deklarieren, vorausgesetzt, die /pets Ressource id lautet6sxz2j:

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 abgekürzten Form können Sie eine JSON Zeichenfolge verwenden, um den request-parameters Wert festzulegen:

'{"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.

Richten Sie ein Modell für Methodenanfragen ein

Für eine API Methode, die Eingabedaten in einer Nutzlast aufnehmen kann, können Sie ein Modell verwenden. Ein Modell wird in einem JSONSchemaentwurf 4 ausgedrückt und beschreibt die Datenstruktur des Hauptteils der Anfrage. 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 validierenSDK, eine Zuordnungsvorlage zu generieren und zu initialisieren, um die Integration in der API Gateway-Konsole einzurichten. 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. APIGateway verwendet den Content-Type Anforderungsheader, um den Inhaltstyp zu bestimmen. Um Methodenanforderungsmodelle einzurichten, fügen Sie der requestModels Map beim Aufrufen des Befehls Schlüssel-Wert-Paare des "<media-type>":"<model-name>" Formats hinzu. AWS CLI put-method

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 des PetStore Beispiels festzulegenAPI, können Sie den folgenden Befehl aufrufen: AWS CLI

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 eigentliche Schemadefinition wird als JSON Zeichenkettenwert der schemaEigenschaft der Model Ressource ausgedrückt.

In einer Java-Version oder einer anderen stark typisierten SDK Version von werden die API Eingabedaten als die aus der Schemadefinition abgeleitete petModel Klasse umgewandelt. Beim Anforderungsmodell werden die Eingabedaten in der generierten SDK Datei in die Empty Klasse umgewandelt, die vom Empty Standardmodell abgeleitet ist. 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 Autorisierer zu aktivieren, einschließlich IAM Rollen und Richtlinien (AWS_IAM), eines Amazon Cognito Cognito-Benutzerpools () oder eines Lambda-Autorisierers (COGNITO_USER_POOLS). CUSTOM

Um IAM Berechtigungen zur Autorisierung des Zugriffs auf die API Methode zu verwenden, setzen Sie die Eingabeeigenschaft auf. authorization-type AWS_IAM Wenn Sie diese Option festlegen, überprüft API Gateway die Signatur des Anrufers in der Anfrage anhand der Anmeldeinformationen des Anrufers. 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 nur erfolgreich, wenn der Aufrufer die Berechtigung hat, die Methode aufzurufen. API Die folgende IAM Richtlinie erteilt dem Aufrufer die Erlaubnis, alle API Methoden aufzurufen, die in derselben Richtlinie erstellt wurden: AWS-Konto

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

Weitere Informationen finden Sie unter Steuern Sie den Zugriff auf eine REST API mit IAM Berechtigungen.

Derzeit können Sie diese Richtlinie nur Benutzern, Gruppen und Rollen innerhalb des API AWS-Konto Besitzers gewähren. Benutzer aus einem anderen Land AWS-Konto können die API Methoden nur aufrufen, wenn sie eine Rolle innerhalb des API AWS-Konto Besitzers übernehmen dürfen und über die erforderlichen Berechtigungen verfügen, um die execute-api:Invoke Aktion aufzurufen. Informationen zu kontoübergreifenden Berechtigungen finden Sie unter IAMRollen verwenden.

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

Um einen Lambda-Autorisierer zu verwenden, um den Zugriff auf die API Methode zu autorisieren, setzen Sie die authorization-type Eingabeeigenschaft auf CUSTOM und setzen Sie die authorizer-idEingabeeigenschaft auf den idEigenschaftswert eines bereits vorhandenen Lambda-Autorisierers. Der referenzierte Lambda-Genehmiger kann vom Typ TOKEN oder REQUEST sein. Informationen zur Erstellung eines Lambda-Genehmigers finden Sie unter Verwenden Sie API Gateway Lambda-Autorisierer.

Um einen Amazon Cognito Cognito-Benutzerpool zu verwenden, um den Zugriff auf die API Methode zu autorisieren, setzen Sie die authorization-type Eingabeeigenschaft auf COGNITO_USER_POOLS und setzen Sie die authorizer-idEingabeeigenschaft auf den idEigenschaftswert des COGNITO_USER_POOLS Autorisierers, der bereits erstellt wurde. Informationen über die Erstellung eines Genehmigers für einen Amazon Cognito-Benutzerpool finden Sie unter Steuern Sie den Zugriff auf REST-APIs mithilfe von Amazon Cognito Cognito-Benutzerpools als Autorisierer.

Einrichten einer Validierung der Methodenanforderung

Sie können die Anforderungsvalidierung aktivieren, wenn Sie eine API Methodenanforderung einrichten. 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

Mit diesem CLI Befehl wird eine reine Textanforderungsvalidierung erstellt. 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.