È possibile integrare le API HTTP con i servizi AWS utilizzando integrazioni di prima classe. Un'integrazione di prima classe collega una route di un'API HTTP a un'API di un servizio AWS. Quando un client richiama una route supportata da un'integrazione di prima classe, API Gateway richiama un'API del servizio AWS per conto dell'utente. Ad esempio, è possibile utilizzare integrazioni di prima classe per inviare un messaggio a una coda di Amazon Simple Queue Service o per avviare una macchina a stati con 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.
Nella tabella seguente vengono descritti i parametri supportati della richiesta di mappatura.
Tipo | Esempio | Note |
---|---|---|
Valore intestazione | $request.header.name |
I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. API Gateway combina più valori di intestazione con virgole, ad esempio "header1":
"value1,value2" . |
Valore della stringa di query | $request.querystring.name |
I nomi delle stringhe di query fanno distinzione tra maiuscole e minuscole. API Gateway combina più valori con virgole, ad esempio "querystring1":
"Value1,Value2" . |
Parametro del percorso | $request.path.name |
Il valore di un parametro del percorso nella richiesta. Ad esempio, se l'instradamento è /pets/{petId} , è possibile mappare il parametro petId della richiesta con $request.path.petId . |
Passthrough corpo richiesta | $request.body | API Gateway passa l'intero corpo della richiesta. |
Corpo di richiesta | $request.body.name |
Un'espressione di percorso JSON$request.body.. ) e di filtro (?( ) non sono supportate. NotaQuando si specifica un percorso JSON, 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 |
Variabile di contesto | $context.variableName |
Valore di una variabile di contesto supportata. |
Variabile di fase | $stageVariables.variableName |
Il valore di una variabile di fase. |
Valore statico | stringa |
Un valore costante. |
Creazione di un'integrazione di prima classe
Prima di creare un'integrazione di prima classe, è necessario creare un ruolo IAM che conceda ad API Gateway le autorizzazioni per richiamare l'operazione del servizio AWS 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, scegliere un'operazione di un servizio AWS supportato, ad esempio SQS-SendMessage
, configurare i parametri della richiesta e fornire un ruolo che conceda ad API Gateway le autorizzazioni per richiamare l'API del servizio AWS integrato. A seconda del sottotipo di integrazione, sono necessari diversi parametri di richiesta. Per ulteriori informazioni, consulta Riferimento al sottotipo di integrazione.
Il seguente comando della AWS CLI crea un'integrazione che invia un messaggio Amazon SQS.
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"}'
Creazione di un'integrazione di prima classe mediante AWS CloudFormation
L'esempio seguente mostra uno snippet AWS CloudFormation che crea un instradamento /{source}/{detailType}
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 router di eventi o il ruolo IAM che concede le autorizzazioni Gateway API per richiamare l'operazione 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"