# API Gateway で HTTP API の AWS のサービス統合を作成する
<a name="http-api-develop-integrations-aws-services"></a>

HTTP API と AWS のサービスは、*ファーストクラス統合*を使用して統合できます。ファーストクラス統合は、HTTP API ルートを AWS のサービス API に接続します。クライアントがファーストクラス統合でサポートされるルートを呼び出すと、API Gateway は AWS のサービス API を呼び出します。例えば、ファーストクラス統合を使用して、Amazon Simple Queue Service キューにメッセージを送信したり、AWS Step Functions ステートマシンを起動したりすることができます。サポートされているサービスアクションについては、「[統合サブタイプのリファレンス](http-api-develop-integrations-aws-services-reference.md)」を参照してください。

## リクエストパラメータのマッピング
<a name="http-api-develop-integrations-aws-services-parameter-mapping"></a>

ファーストクラス統合には、必須およびオプションのパラメータがあります。統合を作成するには、すべての必須のパラメータを設定する必要があります。静的な値を使用するか、実行時に動的に評価されるパラメータをマッピングできます。サポートされている統合とパラメータの完全なリストについては、「[統合サブタイプのリファレンス](http-api-develop-integrations-aws-services-reference.md)」を参照してください。

次の表は、サポートされているマッピング要求パラメータを示しています。


| タイプ | 例 | コメント | 
| --- | --- | --- | 
| ヘッダー値 | \$1request.header.name | ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。 | 
| クエリ文字列値 | \$1request.querystring.name | クエリ文字列名では大文字と小文字が区別されます。API Gateway は複数の値をコンマで結合します (例: "querystring1": "Value1,Value2")。 | 
| パスパラメータ | \$1request.path.name | リクエストのパスパラメータの値。例えば、ルートが /pets/\$1petId\$1 の場合は、\$1request.path.petId を使用してリクエストの petId パラメータをマッピングできます。 | 
| リクエストボディのパススルー | \$1request.body | API Gateway はリクエストボディ全体をパススルーします。 | 
| リクエストボディ | \$1request.body.name | [JSON パス式](https://goessner.net/articles/JsonPath/index.html#e2)。再帰下降 (\$1request.body..name) およびフィルター式 (?(expression)) はサポートされていません。 JSON パスを指定すると、API Gateway はリクエスト本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、`$request.body` を指定します。  | 
| コンテキスト変数 | \$1context.variableName | サポートされている[コンテキスト変数](http-api-logging-variables.md)の値。 | 
| ステージ変数 | \$1stageVariables.variableName | [ステージ変数](http-api-stages.stage-variables.md)の値。 | 
| 静的な値 | string | 定数値。 | 

## ファーストクラス統合を作成する
<a name="http-api-develop-integrations-aws-services-example"></a>

ファーストクラス統合を作成する前に、統合する AWS のサービスアクションを呼び出す API Gateway アクセス許可を付与する IAM ロールを作成する必要があります。詳細については、「[AWS のサービスのロールの作成](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)」を参照してください。

ファーストクラス統合を作成するには、`SQS-SendMessage` などのサポートされている AWS のサービスアクションを選択し、リクエストパラメータを設定して、統合された AWS のサービス API を呼び出すアクセス許可を API Gateway に付与するロールを提供します。統合サブタイプに応じて、異なるリクエストパラメータが必要です。詳細については、「[統合サブタイプのリファレンス](http-api-develop-integrations-aws-services-reference.md)」を参照してください。

次の [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、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"}'
```

## CloudFormation を使用してファーストクラス統合を作成する
<a name="http-api-develop-integrations-aws-services-example-cfn"></a>

次の例は、Amazon EventBridge とのファーストクラス統合を使用して `/{source}/{detailType}` ルートを作成する CloudFormation スニペットを示しています。

`Source` パラメータは `{source}` パスパラメータ、`DetailType` は `{DetailType}` パスパラメータ、`Detail` パラメータはリクエスト本文にマップされます。

このスニペットは、`PutEvents` アクションを呼び出すための API Gateway アクセス許可を付与するイベントバスや IAM ロールを表示しません。

```
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"
```

# 統合サブタイプのリファレンス
<a name="http-api-develop-integrations-aws-services-reference"></a>

以下の[統合サブタイプ](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype)は HTTP API でサポートされています。

**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>

カスタムイベントを、ルールとマッチングできるように Amazon EventBridge に送信します。


| [Parameter] (パラメータ) | 必須 | 
| --- | --- | 
| 詳細 | True | 
| DetailType | True | 
| 送信元 | True | 
| 時間 | False | 
| EventBusName | False | 
| リソース | False | 
| リージョン | False | 
| TraceHeader | False | 

詳細については、* Amazon EventBridge API リファレンス*の「[PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html)」を参照してください。

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

指定されたキューにメッセージを配信します。


| [Parameter] (パラメータ) | 必須 | 
| --- | --- | 
| QueueUrl | True | 
| MessageBody | True | 
| DelaySeconds | False | 
| MessageAttributes | False | 
| MessageDeduplicationId | False | 
| MessageGroupId | False | 
| MessageSystemAttributes | False | 
| リージョン | False | 

詳細については、*Amazon Simple Queue Service API リファレンス*の「[SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)」を参照してください。

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

指定されたキューから 1 個以上 (最大 10 個) のメッセージを取得します。


| [Parameter] (パラメータ) | 必須 | 
| --- | --- | 
| QueueUrl | True | 
| AttributeNames | False | 
| MaxNumberOfMessages | False | 
| MessageAttributeNames | False | 
| ReceiveRequestAttemptId | False | 
| VisibilityTimeout | False | 
| WaitTimeSeconds | False | 
| リージョン | False | 

詳細については、*Amazon Simple Queue Service API リファレンス*の「[ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)」を参照してください。

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

指定されたキュー内の指定されたメッセージを削除します。


| [Parameter] (パラメータ) | 必須 | 
| --- | --- | 
| ReceiptHandle | True | 
| QueueUrl | True | 
| リージョン | False | 

詳細については、*Amazon Simple Queue Service API リファレンス*の「[DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html)」を参照してください。

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

指定されたキュー内のすべてのメッセージを削除します。


| [Parameter] (パラメータ) | 必須 | 
| --- | --- | 
| QueueUrl | True | 
| リージョン | False | 

詳細については、*Amazon Simple Queue Service API リファレンス*の 「[PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html)」を参照してください。

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

設定に関する情報を受け取ります。


| [Parameter] (パラメータ) | 必須 | 
| --- | --- | 
| アプリケーション | True | 
| 環境 | True | 
| 設定 | True | 
| ClientId | True | 
| ClientConfigurationVersion | False | 
| リージョン | False | 

詳細については、*AWS AppConfig API リファレンス*の「[GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html)」を参照してください。

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

1 つのデータレコードを Amazon Kinesis Data Streams に書き込みます。


| [Parameter] (パラメータ) | 必須 | 
| --- | --- | 
| StreamName | True | 
| データ | True | 
| PartitionKey | True | 
| SequenceNumberForOrdering | False | 
| ExplicitHashKey | False | 
| リージョン | False | 

詳細については、*Amazon Kinesis Data Streams API リファレンス*の「[PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html)」を参照してください。

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

ステートマシンの実行を開始します。


| [Parameter] (パラメータ) | 必須 | 
| --- | --- | 
| StateMachineArn | True | 
| 名前 | False | 
| Input | False | 
| リージョン | False | 

詳細については、*AWS Step Functions API リファレンス*の「[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)」を参照してください。

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

同期状態マシンの実行を開始します。


| [Parameter] (パラメータ) | 必須 | 
| --- | --- | 
| StateMachineArn | True | 
| 名前 | False | 
| Input | False | 
| リージョン | False | 
| TraceHeader | False | 

詳細については、*AWS Step Functions API リファレンス*の「[StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html)」を参照してください。

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

実行を停止します。


| [Parameter] (パラメータ) | 必須 | 
| --- | --- | 
| ExecutionArn | True | 
| 原因 | False | 
| エラー | False | 
| リージョン | False | 

詳細については、*AWS Step Functions API リファレンス*の「[StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html)」を参照してください。