Criar integrações de serviços da AWS para APIs HTTP

Você pode integrar sua API HTTP com serviços da AWS usando integrações de primeira classe. Uma integração de primeira classe conecta uma rota de API HTTP a uma API de serviço da AWS. Quando um cliente invoca uma rota apoiada por uma integração de primeira classe, o API Gateway invoca uma API de serviço da AWS para você. Por exemplo, é possível usar integrações de primeira classe para enviar uma mensagem para uma fila do Amazon Simple Queue Service ou iniciar uma máquina de estado do AWS Step Functions. Para obter ações de serviço compatíveis, consulte Referência do subtipo de integração.

Mapear parâmetros de solicitação

Integrações de primeira classe têm parâmetros obrigatórios e opcionais. É necessário configurar todos os parâmetros necessários para criar uma integração. Você pode usar valores estáticos ou mapear parâmetros que são avaliados dinamicamente no tempo de execução. Para obter uma lista completa de integrações e parâmetros compatíveis, consulte Referência do subtipo de integração.

Mapeamento de parâmetros
Tipo	Exemplo	Observações
Valor de cabeçalho	$request.header.nome	Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. O API Gateway combina vários valores de cabeçalho com vírgulas, por exemplo, "header1": "value1,value2".
Valor da string de consulta	$request.querystring.nome	Os nomes de strings de consulta diferenciam maiúsculas e minúsculas O API Gateway combina vários valores com vírgulas, por exemplo, "querystring1": "Value1,Value2".
Parâmetro de caminho	$request.path.name	O valor de um parâmetro de caminho na solicitação. Por exemplo, se a rota for /pets/{petId}, você poderá mapear o parâmetro petId da solicitação com $request.path.petId.
Solicitar passagem do corpo	$request.body	O API Gateway transmite todo o corpo da solicitação.
Corpo da solicitação	$request.body.name	Uma expressão de caminho JSON. Descidas recursivas ($request.body..name) e expressões de filtro (?(expression)) não são compatíveis. nota Quando você especifica um caminho JSON, o API Gateway trunca o corpo da solicitação em 100 KB e, em seguida, aplica a expressão de seleção. Para enviar cargas maiores que 100 KB, especifique $request.body.
Variável de contexto	$context.variableName	O valor de uma variável de contexto compatível.
Variável de estágio	$stageVariables.variableName	O valor de uma variável de estágio.
Valor estático	string	Um valor constante.

Criar uma integração de primeira classe

Antes de criar uma integração de primeira classe, é necessário criar uma função do IAM que conceda ao API Gateway permissões para invocar a ação de serviço da AWS à qual você está se integrando. Para saber mais, consulte Criação de uma função para um serviço da AWS.

Para criar uma integração de primeira classe, escolha uma ação de serviço da AWS compatível, como SQS-SendMessage, configure os parâmetros de solicitação e forneça uma função que conceda ao API Gateway permissões para invocar a API de serviço integrado da AWS. Dependendo do subtipo de integração, diferentes parâmetros de solicitação são necessários. Para saber mais, consulte Referência do subtipo de integração.

O comando da AWS CLI a seguir cria uma integração que envia uma mensagem do 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"}'

Criar uma integração de primeira classe usando o AWS CloudFormation

O exemplo a seguir mostra um trecho do AWS CloudFormation que cria uma rota /{source}/{detailType} com uma integração de primeira classe com o Amazon EventBridge.

O parâmetro Source é mapeado para o parâmetro de caminho {source}, o DetailType é mapeado para o parâmetro de caminho {DetailType} e o parâmetro Detail é mapeado para o corpo da solicitação.

O trecho não mostra o barramento de eventos ou o perfil do IAM que concede permissões ao API Gateway para invocar a ação 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"