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

Sie können Ihre HTTP-API mithilfe erstklassiger Integrationen in AWS Dienste integrieren. 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. 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 Tabelle unten sind die unterstützten Anforderungsparameter der Zuordnung beschrieben.

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	$kontext. variableName	Der Wert einer unterstützten Kontextvariablen.
Stufenvariable	$stageVariablen. 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 Gateway-Berechtigungen zum Aufrufen der AWS Serviceaktion gewährt, mit der Sie die Integration durchführen. 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 Serviceaktion aus, z. B. SQS-SendMessage konfigurieren Sie die Anforderungsparameter, und stellen Sie eine Rolle bereit, die API Gateway 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.

Der folgende Befehl create-integration erstellt eine Integration, die eine Amazon SQS 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 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-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"