# 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 | \$1request.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 | \$1request.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 | \$1request.path.name | O valor de um parâmetro de caminho na solicitação. Por exemplo, se a rota for /pets/\$1petId\$1, você poderá mapear o parâmetro petId da solicitação com \$1request.path.petId. | 
| Solicitar passagem do corpo | \$1request.body | O API Gateway transmite todo o corpo da solicitação. | 
| Corpo da solicitação | \$1request.body.name | Uma [expressão de caminho JSON](https://goessner.net/articles/JsonPath/index.html#e2). Descidas recursivas (\$1request.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 | \$1context.variableName | O valor de uma [variável de contexto](http-api-logging-variables.md) compatível. | 
| Variável de estágio | \$1stageVariables.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"
```

# Referência do subtipo de integração
<a name="http-api-develop-integrations-aws-services-reference"></a>

Os [subtipos de integração](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype) a seguir são compatíveis com APIs HTTP.

**Topics**
+ [EventBridge-PutEvents 1.0](#EventBridge-PutEvents)
+ [SQS-SendMessage 1.0](#SQS-SendMessage)
+ [SQS-ReceiveMessage 1.0](#SQS-ReceiveMessage)
+ [SQS-DeleteMessage 1.0](#SQS-DeleteMessage)
+ [SQS-PurgeQueue 1.0](#SQS-PurgeQueue)
+ [AppConfig-GetConfiguration 1.0](#AppConfig-GetConfiguration)
+ [Kinesis-PutRecord 1.0](#Kinesis-PutRecord)
+ [StepFunctions-StartExecution 1.0](#StepFunctions-StartExecution)
+ [StepFunctions-StartSyncExecution 1.0](#StepFunctions-StartSyncExecution)
+ [StepFunctions-StopExecution 1.0](#StepFunctions-StopExecution)

## EventBridge-PutEvents 1.0
<a name="EventBridge-PutEvents"></a>

Envia eventos personalizados para o Amazon EventBridge para que eles possam ser correspondidos a regras.


| Parâmetro | Obrigatório | 
| --- | --- | 
| Detalhes | Verdadeiro | 
| DetailType | Verdadeiro | 
| Origem | Verdadeiro | 
| Tempo | Falso | 
| EventBusName | Falso | 
| Recursos | Falso | 
| Região | Falso | 
| TraceHeader | Falso | 

Para saber mais, consulte [PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html) na *Referência de API do Amazon EventBridge*.

## SQS-SendMessage 1.0
<a name="SQS-SendMessage"></a>

Entrega uma mensagem para a fila especificada.


| Parâmetro | Obrigatório | 
| --- | --- | 
| QueueUrl | Verdadeiro | 
| MessageBody | Verdadeiro | 
| DelaySeconds | Falso | 
| MessageAttributes | Falso | 
| MessageDeduplicationId | Falso | 
| MessageGroupId | Falso | 
| MessageSystemAttributes | Falso | 
| Região | Falso | 

Para saber mais, consulte [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) na *Referência de API do Amazon Simple Queue Service*.

## SQS-ReceiveMessage 1.0
<a name="SQS-ReceiveMessage"></a>

Recupera uma ou mais mensagens (até 10) de uma fila especificada.


| Parâmetro | Obrigatório | 
| --- | --- | 
| QueueUrl | Verdadeiro | 
| AttributeNames | Falso | 
| MaxNumberOfMessages | Falso | 
| MessageAttributeNames | Falso | 
| ReceiveRequestAttemptId | Falso | 
| VisibilityTimeout | Falso | 
| WaitTimeSeconds | Falso | 
| Região | Falso | 

Para saber mais, consulte [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) na *Referência de API do Amazon Simple Queue Service*.

## SQS-DeleteMessage 1.0
<a name="SQS-DeleteMessage"></a>

Exclui a mensagem especificada da fila especificada.


| Parâmetro | Obrigatório | 
| --- | --- | 
| ReceiptHandle | Verdadeiro | 
| QueueUrl | Verdadeiro | 
| Região | Falso | 

Para saber mais, consulte [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html) na *Referência de API do Amazon Simple Queue Service*.

## SQS-PurgeQueue 1.0
<a name="SQS-PurgeQueue"></a>

Exclui todas as mensagens da fila especificada.


| Parâmetro | Obrigatório | 
| --- | --- | 
| QueueUrl | Verdadeiro | 
| Região | Falso | 

Para saber mais, consulte [PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html) na *Referência de API do Amazon Simple Queue Service*.

## AppConfig-GetConfiguration 1.0
<a name="AppConfig-GetConfiguration"></a>

Receba informações sobre uma configuração.


| Parâmetro | Obrigatório | 
| --- | --- | 
| Aplicativo | Verdadeiro | 
| Ambiente | Verdadeiro | 
| Configuração | Verdadeiro | 
| ClientId | Verdadeiro | 
| ClientConfigurationVersion | Falso | 
| Região | Falso | 

Para saber mais, consulte [GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html) na *Referência da API AppConfig da AWS*.

## Kinesis-PutRecord 1.0
<a name="Kinesis-PutRecord"></a>

Grava um único registro de dados em um stream de dados do Amazon Kinesis.


| Parâmetro | Obrigatório | 
| --- | --- | 
| StreamName | Verdadeiro | 
| Dados | Verdadeiro | 
| PartitionKey | Verdadeiro | 
| SequenceNumberForOrdering | Falso | 
| ExplicitHashKey | Falso | 
| Região | Falso | 

Para saber mais, consulte [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html) na *Referência de API do Amazon Kinesis Data Streams*.

## StepFunctions-StartExecution 1.0
<a name="StepFunctions-StartExecution"></a>

Inicia uma execução de máquina de estado.


| Parâmetro | Obrigatório | 
| --- | --- | 
| StateMachineArn | Verdadeiro | 
| Nome | Falso | 
| Entrada | Falso | 
| Região | Falso | 

Para saber mais, consulte [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) na *Referência da API do AWS Step Functions*.

## StepFunctions-StartSyncExecution 1.0
<a name="StepFunctions-StartSyncExecution"></a>

Inicia uma execução de máquina de estado síncrono.


| Parâmetro | Obrigatório | 
| --- | --- | 
| StateMachineArn | Verdadeiro | 
| Nome | Falso | 
| Entrada | Falso | 
| Região | Falso | 
| TraceHeader | Falso | 

Para saber mais, consulte [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) na *Referência da API do AWS Step Functions*.

## StepFunctions-StopExecution 1.0
<a name="StepFunctions-StopExecution"></a>

Interrompe uma execução.


| Parâmetro | Obrigatório | 
| --- | --- | 
| ExecutionArn | Verdadeiro | 
| Causa | Falso | 
| Erro | Falso | 
| Região | Falso | 

Para saber mais, consulte [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html) na *Referência da API do AWS Step Functions*.