# Criar integrações de serviços da AWS para APIs HTTP no API Gateway
<a name="http-api-develop-integrations-aws-services"></a>

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](http-api-develop-integrations-aws-services-reference.md).

## Mapear parâmetros de solicitação
<a name="http-api-develop-integrations-aws-services-parameter-mapping"></a>

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](http-api-develop-integrations-aws-services-reference.md).

A tabela a seguir descreve os parâmetros de solicitação de mapeamento compatíveis.


| 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](https://goessner.net/articles/JsonPath/index.html#e2). Descidas recursivas ($request.body..{{name}}) e expressões de filtro (?({{expression}})) não são compatíveis.  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](http-api-logging-variables.md) compatível. | 
| Variável de estágio | $stageVariables.{{variableName}} | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). | 
| Valor estático | {{string}} | Um valor constante. | 

## Criar uma integração de primeira classe
<a name="http-api-develop-integrations-aws-services-example"></a>

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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html).

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](http-api-develop-integrations-aws-services-reference.md).

O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo 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 CloudFormation
<a name="http-api-develop-integrations-aws-services-example-cfn"></a>

O exemplo a seguir mostra um trecho do 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"
```