Arbeiten mit AWS-Service-Integrationen für HTTP-APIs

Sie können Ihre HTTP-API in AWS-Services integrieren, indem Sie erstklassige Integrationen verwenden. Eine erstklassige Integration verbindet eine HTTP-API-Route mit einer AWS-Service-API. Wenn ein Client eine Route aufruft, die durch eine erstklassige Integration unterstützt wird, ruft API Gateway eine AWS-Service-API für Sie auf. Beispielsweise können Sie erstklassige Integrationen verwenden, um eine Nachricht an eine Amazon-Simple-Queue-Service-Warteschlange zu senden oder einen AWS Step Functions-Zustandsautomaten zu starten. Unterstützte Serviceaktionen finden Sie unter Integration-Subtypreferenz.

Mapping von Anforderungsparametern

Erstklassige Integrationen verfügen über erforderliche und optionale Parameter. Sie müssen alle erforderlichen Parameter zum Erstellen einer Integration konfigurieren. Sie können statische Werte oder Mapping-Parameter verwenden, die zur Laufzeit dynamisch ausgewertet werden. Eine vollständige Liste der unterstützten Integrationen und Parameter finden Sie unter Integration-Subtypreferenz.

Parameter-Mapping
Typ	Beispiel	Hinweise
Header-Wert	$request.header.Name	Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden. API Gateway kombiniert mehrere Headerwerte mit Kommas, z. B. "header1": "value1,value2".
Abfragezeichenfolgenwert	$request.querystring.Name	Abfragezeichenfolgennamen unterscheiden zwischen Groß- und Kleinschreibung. API Gateway kombiniert mehrere Werte mit Kommas, z. B. "querystring1": "Value1,Value2".
Path-Parameter	$request.path.Name	Der Wert eines Pfadparameters in der Anforderung. Beispiel: Wenn die Route /pets/{petId} ist, können Sie den Parameter petId aus der Anforderung mit $request.path.petid zuordnen.
Übergeben des Anforderungstexts	$request.body	API Gateway übergibt den gesamten Anforderungstext.
Anforderungstext	$request.body.Name	Ein JSON-Pfadausdruck. Rekursiver Abstieg ($request.body..name) und Filterausdrücke (?(expression)) werden nicht unterstützt. Anmerkung Wenn Sie einen JSON-Pfad angeben, schneidet API Gateway den Anfragetext auf 100 KB ab und wendet dann den Auswahlausdruck an. Um Payloads mit mehr als 100 KB zu senden, geben Sie an $request.body.
Kontextvariable	$context.Variablenname	Der Wert einer unterstützten Kontextvariablen.
Stufenvariable	$stageVariables.Variablenname	Der Wert einer Stufenvariablen.
Statischer Wert	string	Ein konstanter Wert.

Erstellen Sie einer erstklassigen Integration

Bevor Sie eine erstklassige Integration erstellen, müssen Sie eine IAM-Rolle erstellen, die API-Gateway-Berechtigungen zum Aufrufen der AWS-Serviceaktion gewährt, in die Sie integrieren. Weitere Informationen finden Sie unter Erstellen einer Rolle für einen AWS-Service.

Zum Erstellen einer erstklassigen Integration wählen Sie eine unterstützte AWS-Serviceaktion aus, z. B. SQS-SendMessage, konfigurieren Sie die Anforderungsparameter und stellen Sie eine Rolle bereit, die API Gateway Berechtigungen zum Aufrufen der integrierten AWS-Service-API gewährt. Je nach Integration-Subtyp sind unterschiedliche Anforderungsparameter erforderlich. Weitere Informationen hierzu finden Sie unter Integration-Subtypreferenz.

Mit dem folgenden AWS CLI-Befehl wird eine Integration erstellt, die eine Amazon-SQS-Nachricht sendet.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-subtype SQS-SendMessage \
    --integration-type AWS_PROXY \
    --payload-format-version 1.0 \
    --credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \
    --request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'