Grundlegende Aufgaben einer API-Integrationsanforderung

Eine Integrationsanforderung ist eine HTTP-Anfrage, die API Gateway an das Backend sendet. Dabei werden die vom Client gesendeten Anfragedaten übergeben und gegebenenfalls umgewandelt. Die HTTP-Methode (oder Verb) und URI der Integrationsanforderung werden vom Backend, also dem Integrationsendpunkt, vorgegeben. Sie können, müssen aber nicht identisch mit der HTTP-Methode und URI der Methodenanforderung übereinstimmen.

Wenn eine Lambda-Funktion eine Datei zurückgibt, die von Amazon S3 abgerufen wurde, können Sie diesen Vorgang beispielsweise intuitiv als GET-Methodenanfrage für den Client bereitstellen, obwohl die entsprechende Integrationsanfrage festlegt, dass eine POST-Anfrage zum Aufruf der Lambda-Funktion verwendet wird. Bei einem HTTP-Endpunkt ist es wahrscheinlich, dass für die Methodenanforderung und die entsprechende Integrationsanforderung dasselbe HTTP-Verb verwendet wird. Dies ist jedoch nicht erforderlich. Sie können die folgende Methodenanforderung integrieren:

GET /{var}?query=value
Host: api.domain.net

Mit der folgenden Integrationsanforderung:

POST /
Host: service.domain.com
Content-Type: application/json
Content-Length: ...

{
   path: "{var}'s value",
   type: "value"
}

Als API-Entwickler können Sie beliebige HTTP-Verben und URIs für eine Methodenanforderung verwenden, die Ihre Anforderungen erfüllt. Dabei müssen jedoch die Anforderungen des Integrationsendpunkts erfüllt werden. Wenn die Methodenanforderungsdaten sich von den Daten der Integrationsanforderung unterscheiden, können Sie den Unterschied dadurch ausgleichen, dass Sie das Mapping der Methodenanforderungsdaten zu den Integrationsanforderungsdaten angeben.

In den vorherigen Beispielen werden die Werte für die Pfadvariable ({var}) und den Abfrageparameter (query) der GET-Methodenanforderung in Werte der Nutzlasteigenschaften der Integrationsanforderung path und type zugeordnet. Auch der Header und Inhalt der Anforderungsdaten können zugeordnet werden. Diese werden in Mappings von Anfrage- und Antwortdaten über die API Gateway-Konsole einrichten beschrieben.

Beim Einrichten der HTTP- oder HTTP-Proxy-Integrationsanforderung weisen Sie die URL des Backend-HTTP-Endpunkts als URI-Wert der Integrationsanforderung zu. In der PetStore-API hat die Methodenanforderung zum Abrufen einer Seite mit Haustieren beispielsweise die folgende Integrationsanforderungs-URI:

http://petstore-demo-endpoint.execute-api.com/petstore/pets

Beim Einrichten der Lambda- oder Lambda-Proxy-Integration weisen Sie den Amazon-Ressourcennamen (ARN) für den Aufruf der Lambda-Funktion als URI-Wert der Integrationsanforderung zu. Der ARN hat das folgende Format:

arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations

Der Teil nach arn:aws:apigateway:api-region:lambda:path/ (/2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations) ist der REST-API-URI-Pfad der Lambda-Aufruf-Aktion. Wenn Sie die API Gateway-Konsole zum Einrichten der Lambda-Integration verwenden, erstellt API Gateway den ARN und weist ihn der Integrations-URI zu, nachdem Sie aufgefordert wurden, den lambda-function-name aus einer Region auszuwählen.

Beim Einrichten der Integrationsanforderung mit einer anderen AWS-Service-Aktion ist die Integrationsanforderungs-URI ähnlich wie bei der Integration in die Lambda-Invoke-Aktion auch ein ARN. Für die Integration in die GetBucket-Aktion von Amazon S3 ist die Integrationsanforderungs-URI beispielsweise ein ARN im folgenden Format:

arn:aws:apigateway:api-region:s3:path/{bucket}

Die Integrationsanforderungs-URI entspricht der Pfadkonvention zur Festlegung der Aktion, wobei {bucket} der Platzhalter für einen Bucket-Namen ist. Alternativ können Sie auf eine AWS-Service-Aktion auch per Name verweisen. Mit dem Aktionsnamen sieht die Integrationsanforderungs-URI für die GetBucket-Aktion für Amazon S3 wie folgt aus:

arn:aws:apigateway:api-region:s3:action/GetBucket

In der aktionsbasierten Integrationsanforderungs-URI muss der Bucket-Name ({bucket}) im Inhalt der Integrationsanforderung ({ Bucket: "{bucket}" }) im Eingabeformat der GetBucket-Aktion festgelegt werden.

Für AWS-Integrationen müssen Sie außerdem Anmeldeinformationen konfigurieren, damit API Gateway die integrierten Aktionen aufrufen kann. Sie können eine neue IAM-Rolle erstellen oder eine vorhandene IAM-Rolle auswählen, mit der API Gateway die Aktion aufruft, und dann die Rolle mit ihrem ARN angeben. Hier ein Beispiel für diesen ARN:

arn:aws:iam::account-id:role/iam-role-name

Die IAM-Rolle muss eine Richtlinie enthalten, in der die Berechtigung für die auszuführende Aktion gewährt wird. Außerdem muss API Gateway (in der Vertrauensbeziehung der Rolle) als vertrauenswürdige Entität deklariert sein, um die Rolle übernehmen zu können. Solche Berechtigungen können für die Aktion selbst gewährt werden. Sie werden als ressourcenbasierte Berechtigungen bezeichnet. Für die Lambda-Integration können Sie die Lambda-Aktion addPermission aufrufen, um die ressourcenbasierten Berechtigungen festzulegen, und dann credentials in der API Gateway-Integrationsanforderung auf Null festlegen.

Wir haben die Grundlagen der Integrationseinrichtung besprochen. Die erweiterten Einstellungen umfassen die Möglichkeit des Mapping der Methodenanforderungsdaten zu den Integrationsanforderungsdaten. Nachdem wir die grundlegende Einrichtung für eine Integrationsantwort behandelt haben, decken wir fortgeschrittene Themen in Mappings von Anfrage- und Antwortdaten über die API Gateway-Konsole einrichten ab, wo auch die Übergabe von Nutzlasten und der Umgang mit Verschlüsselungen behandelt werden.