Erstellen Sie AWS Serviceintegrationen für HTTP APIs in Gateway API

Sie können Ihre AWS Dienste HTTP API mithilfe erstklassiger Integrationen integrieren. Eine erstklassige Integration verbindet eine HTTP API Route mit einem AWS DienstAPI. Wenn ein Client eine Route aufruft, die durch eine erstklassige Integration unterstützt wird, ruft API Gateway einen AWS Dienst API für Sie auf. Sie können beispielsweise erstklassige Integrationen verwenden, um eine Nachricht an eine Amazon Simple Queue Service-Warteschlange zu senden oder eine AWS Step Functions Zustandsmaschine 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.

In der folgenden Tabelle werden die unterstützten Parameter für Zuordnungsanforderungen beschrieben.

Typ	Beispiel	Hinweise
Header-Wert	$request.header.name	Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden. APIGateway kombiniert beispielsweise mehrere Header-Werte mit Kommas. "header1": "value1,value2"
Abfragezeichenfolgenwert	$request.querystring.name	Abfragezeichenfolgennamen unterscheiden zwischen Groß- und Kleinschreibung. APIGateway kombiniert beispielsweise mehrere Werte mit Kommas. "querystring1": "Value1,Value2"
Path-Parameter	$request.path.name	Der Wert eines Pfadparameters in der Anforderung. Wenn die Route beispielsweise lautet/pets/{petId}, können Sie den petId Parameter aus der Anfrage wie folgt zuordnen $request.path.petId.
Übergeben des Anforderungstexts	$request.body	APIDas Gateway leitet den gesamten Anfragetext weiter.
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, kürzt API Gateway den Anforderungstext auf 100 KB und wendet dann den Auswahlausdruck an. Um Payloads mit mehr als 100 KB zu senden, geben Sie an $request.body.
Kontextvariable	$context.variableName	Der Wert einer unterstützten Kontextvariablen.
Stufenvariable	$stageVariables.variableName	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 Dienstaktion gewährt, in die Sie integrieren. Weitere Informationen finden Sie unter Erstellen einer Rolle für einen AWS -Service.

Um eine erstklassige Integration zu erstellen, wählen Sie eine unterstützte AWS Dienstaktion aus, z. B. SQS-SendMessage konfigurieren Sie die Anforderungsparameter und geben Sie eine Rolle an, die API Gateway Berechtigungen zum Aufrufen des integrierten AWS Dienstes gewährt. API Je nach Integration-Subtyp sind unterschiedliche Anforderungsparameter erforderlich. Weitere Informationen hierzu finden Sie unter Integration-Subtypreferenz.

Der folgende AWS CLI Befehl erstellt eine Integration, die eine SQS Amazon-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 Sie eine erstklassige Integration mit AWS CloudFormation

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

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 die Berechtigungen zum Aufrufen der Aktion gewährt. PutEvents

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"