Arbeiten mit AWS-Service-Integrationen für HTTP-APIs - Amazon API Gateway

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.

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"}'

Erstellen einer erstklassigen Integration mithilfe von AWS CloudFormation

Das folgende Beispiel zeigt ein AWS CloudFormation-Snippet, das eine Route /{source}/{detailType} mit einer erstklassigen Integration mit Amazon EventBridge erstellt.

Der Parameter Source wird dem Pfadparameter {source}, der DetailType dem Pfadparameter {DetailType} und der Parameter Detail dem Anforderungstext zugeordnet.

Das Snippet zeigt weder den Event Bus noch die IAM-Rolle, die API-Gateway-Berechtigungen zum Aufrufen der Aktion PutEvents gewährt.

Route: Type: AWS::ApiGatewayV2::Route Properties: ApiId: !Ref HttpApi AuthorizationType: None RouteKey: 'POST /{source}/{detailType}' Target: !Join - / - - integrations - !Ref Integration Integration: Type: AWS::ApiGatewayV2::Integration Properties: ApiId: !Ref HttpApi IntegrationType: AWS_PROXY IntegrationSubtype: EventBridge-PutEvents CredentialsArn: !GetAtt EventBridgeRole.Arn RequestParameters: Source: $request.path.source DetailType: $request.path.detailType Detail: $request.body EventBusName: !GetAtt EventBus.Arn PayloadFormatVersion: "1.0"