Crea integrazioni AWS di servizi per HTTP APIs in API Gateway

Puoi integrare il tuo HTTP API con i AWS servizi utilizzando integrazioni di prima classe. Un'integrazione di prima classe collega un HTTP API percorso a un servizio. AWS API Quando un client richiama un percorso supportato da un'integrazione di prima classe, API Gateway richiama un servizio per te. AWS API Ad esempio, puoi utilizzare integrazioni di prima classe per inviare un messaggio a una coda di Amazon Simple Queue Service o per avviare una macchina a stati. AWS Step Functions Per le operazioni di servizio supportate, consulta Riferimento al sottotipo di integrazione.

Mappatura dei parametri delle richieste

Le integrazioni di prima classe hanno parametri obbligatori e facoltativi. È necessario configurare tutti i parametri obbligatori per creare un'integrazione. È possibile utilizzare valori statici o mappare i parametri che vengono valutati dinamicamente in fase di runtime. Per un elenco completo delle integrazioni e dei parametri supportati, consulta Riferimento al sottotipo di integrazione.

La tabella seguente descrive i parametri di richiesta di mappatura supportati.

Type	Esempio	Note
Valore intestazione	$request.header.name	I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. APIAd esempio, Gateway combina più valori di intestazione con virgole. "header1": "value1,value2"
Valore della stringa di query	$request.querystring.name	I nomi delle stringhe di query fanno distinzione tra maiuscole e minuscole. APIAd esempio, Gateway combina più valori con virgole. "querystring1": "Value1,Value2"
Parametro del percorso	$request.path.name	Il valore di un parametro del percorso nella richiesta. Ad esempio, se il percorso è/pets/{petId}, puoi mappare il petId parametro della richiesta con $request.path.petId.
Passthrough corpo richiesta	$request.body	APIIl gateway trasmette l'intero corpo della richiesta.
Corpo della richiesta	$request.body.name	Un'JSONespressione di percorso. Le espressioni di discesa ricorsiva ($request.body..name) e di filtro (?(expression)) non sono supportate. Nota Quando si specifica un JSON percorso, API Gateway tronca il corpo della richiesta a 100 KB e quindi applica l'espressione di selezione. Per inviare payload superiori a 100 KB, specificare $request.body.
Variabile di contesto	$contesto.variableName	Valore di una variabile di contesto supportata.
Variabile di fase	$stageVariables.variableName	Il valore di una variabile di fase.
Valore statico	string	Un valore costante.

Creazione di un'integrazione di prima classe

Prima di creare un'integrazione di prima classe, è necessario creare un IAM ruolo che conceda a API Gateway le autorizzazioni per richiamare l'azione di AWS servizio con cui si sta effettuando l'integrazione. Per ulteriori informazioni, consulta Creazione di un ruolo per un servizio AWS.

Per creare un'integrazione di prima classe, scegli un'azione di AWS servizio supportata, ad esempio configura i parametri di richiesta e fornisci un ruolo che conceda a API Gateway le autorizzazioni per richiamare il servizio integrato. SQS-SendMessage AWS API A seconda del sottotipo di integrazione, sono necessari diversi parametri di richiesta. Per ulteriori informazioni, consulta Riferimento al sottotipo di integrazione.

Il AWS CLI comando seguente crea un'integrazione che invia un SQS messaggio Amazon.

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

Crea un'integrazione di prima classe utilizzando AWS CloudFormation

L'esempio seguente mostra uno AWS CloudFormation snippet che crea un /{source}/{detailType} percorso con un'integrazione di prima classe con Amazon. EventBridge

Il parametro Source viene mappato al parametro del percorso {source}, DetailType viene mappato al parametro del percorso {DetailType} e il parametro Detail viene mappato al corpo della richiesta.

Lo snippet non mostra il bus degli eventi o il IAM ruolo che concede a API Gateway le autorizzazioni per richiamare l'azione. 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"