Methodenanfrage in API Gateway einrichten

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.

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.

Zum Einrichten einer Methodenanforderung müssen nach dem Erstellen einer RestApiRessource die folgenden Aufgaben ausgeführt werden:

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 {api-id} steht der für die API-ID, 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.

Bei der PetStore Beispiel-API 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.

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 dem folgenden Befehl get-resources werden alle Ressourcen einer API abgerufen:

aws apigateway get-resources --rest-api-id apiId

Für die PetStore Beispiel-API sieht die Ausgabe 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 übergeordnete Ressource ausgewählt haben, verwenden Sie den folgenden Befehl, um eine untergeordnete Ressource hinzuzufügen:

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

Um beispielsweise Tiernahrung zum Verkauf auf der PetStore Website hinzuzufügen, verwenden Sie den folgenden Befehl:

aws apigateway create-resource --rest-api-id a1b2c3 \
    --parent-id svzr2028x8 \
    --path-part food

Die Ausgabe sieht wie folgt aus:

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

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

Wenn das Geschäft wächst, kann der PetStore Eigentümer beschließen, Lebensmittel, Spielzeug und andere Artikel für Haustiere 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 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. Sie können eine beliebige Zeichenfolge für den Parameternamen Greedy Path verwenden.

Der folgende Befehl create-resource erstellt eine Proxyressource unter dem Root (): /{proxy+}

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

Die Ausgabe sieht wie folgt aus:

{
    "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 Proxyressource kann auch auf alle anderen (vorhandenen oder to-be-added) Ressourcen verweisen /food/{type}/{item}/toys/{type}/{item}, wie, 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. 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.

Die folgende Tabelle zeigt, wie API Gateway Anfragen an die folgenden Ressourcen für die prod Phase einer API weiterleitet.

ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog

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 Befehl put-method erstellt eine Methodenanforderung für das ANY Verb, wobei IAM-Berechtigungen verwendet werden, um seinen Zugriff zu kontrollieren.

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

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. Der folgende Put-Method-Befehl erstellt eine Methode mit einem erforderlichen Pfadparameter:

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id rjkmth \
    --http-method GET \
    --authorization-type "NONE" \
    --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 und einen optionalen Header-Parameter von type verwendetage, können Sie sie mit dem folgenden Put-Method-Befehl deklarieren:

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method GET \
    --authorization-type "NONE" \
    --request-parameters method.request.querystring.type=false,method.request.header.age=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.age":false}'

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

GET /pets?type=dog

Und der Kunde kann Hunde, die Welpen sind, wie folgt abfragen:

GET /pets?type=dog
age:puppy

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 für Methodenanfragen 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 der PetStore Beispiel-API festzulegen, können Sie den folgenden Befehl put-method verwenden:

aws apigateway put-method \
    --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method POST \
    --authorization-type "NONE" \
    --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 aus anderen Ländern AWS-Konto können die API-Methoden nur aufrufen, wenn sie eine Rolle innerhalb des API-Besitzers AWS-Konto übernehmen dürfen und über die erforderlichen Berechtigungen verfügen, um die Aktion aufzurufen. execute-api:Invoke Weitere Informationen zu kontoübergreifenden Berechtigungen finden Sie unter Verwenden von IAM-Rollen.

Sie können ein AWS SDK oder einen REST-API-Client wie Postman verwenden AWS CLI, der Signature Version 4 (Sigv4) -Signaturen 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 einen Request-Validator erstellen. Der folgende create-request-validatorBefehl erstellt einen nur für den Hauptteil bestimmten Anforderungsvalidator.

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

Die Ausgabe sieht wie folgt aus:

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

Sie können diesen Anforderungsvalidator verwenden, um die Anforderungsvalidierung als Teil der Einrichtung der Methodenanforderung zu verwenden. Der folgende Befehl put-method erstellt eine Methodenanforderung, bei der der Hauptteil der eingehenden Anfrage mit dem übereinstimmt PetModel und zwei Anforderungsparameter hat, die nicht erforderlich sind:

aws apigateway put-method \
    --rest-api-id 7zw9uyk9kl \
    --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 einen Anforderungsparameter in die Anforderungsvalidierung einzubeziehen, müssen Sie true für den Anforderungsvalidator auf und den spezifischen Anforderungsparameter im Befehl auf true festlegen. validateRequestParameters put-method