# x-amazon-apigateway-integration オブジェクト
<a name="api-gateway-swagger-extensions-integration"></a>

 このメソッドのために使用するバックエンド統合の詳細を指定します。この拡張は、[OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) オブジェクトの拡張プロパティです。その結果、 [API Gateway 統合](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)オブジェクトが作成されます。


| プロパティ名 | タイプ | 説明 | 
| --- | --- | --- | 
| cacheKeyParameters | string の配列 | 値がキャッシュされるリクエストパラメーターのリスト。 | 
| cacheNamespace | string | キャッシュされた関連パラメーターの API 固有のタググループ。 | 
| connectionId | string | プライベート統合の [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) の ID。 | 
| connectionType | string | 統合の接続タイプ。有効な値は、プライベート統合の場合は "VPC\$1LINK"、それ以外の場合は "INTERNET" です。 | 
| credentials | string |   AWS IAM ロールベースの認証情報については、該当する IAM ロールの ARN を指定します。指定しない場合、認証情報はデフォルトでリソースベースのアクセス許可に設定されます。API がリソースにアクセスできるようにするためには、リソースベースのアクセス許可を手動で追加する必要があります。詳細については、「[リソースポリシーを使用してアクセス許可を付与する](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html#intro-permission-model-access-policy)」を参照してください。 注意: IAM 認証情報を使用するときは、この API が最適なパフォーマンスのためにデプロイされているリージョンで [AWS STS リージョンのエンドポイント](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html)が有効化されていることを確認してください。  | 
| contentHandling | string | リクエストのペイロードエンコード変換タイプ。有効な値は、1) バイナリペイロードを Base64 でエンコードされた文字列に変換する場合、テキストペイロードを CONVERT\$1TO\$1TEXT でエンコードされた文字列に変換する場合、変更なしでテキストペイロードをネイティブに渡す場合の utf-8 と、2) テキストペイロードを Base64 でデコードされた BLOB に変換する場合、または変更なしでバイナリペイロードをネイティブに渡す場合の CONVERT\$1TO\$1BINARY です。 | 
| httpMethod | string |  統合リクエストで使用される HTTP メソッドです。Lambda 関数の呼び出しでは、値は POST である必要があります。 | 
| integrationSubtype | string | AWS のサービス統合の統合サブタイプを指定します。HTTP API に対してのみサポートされます。サポートされている統合サブタイプについては、「[統合サブタイプのリファレンス](http-api-develop-integrations-aws-services-reference.md)」を参照してください。 | 
| integrationTarget | string | リクエストを送信する ALB または NLB リスナー。VPC リンク V2 を使用するプライベート統合でのみサポートされます。詳細については、「[API Gateway で VPC リンク V2 を設定する](apigateway-vpc-links-v2.md)」を参照してください。 | 
| passthroughBehavior | string |  マッピングされていないコンテンツタイプのリクエストペイロードを、変更なしで統合リクエストに渡す方法を指定します。サポートされる値は when\$1no\$1templates、when\$1no\$1match、never です。詳細については、「[Integration.passthroughBehavior](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#passthroughBehavior)」を参照してください。 | 
| payloadFormatVersion | string | 統合に送信されるペイロードの形式を指定します。HTTP API に必須です。HTTP API の場合、Lambda プロキシ統合でサポートされている値は 1.0 および 2.0 です。他のすべての統合では、1.0 が唯一サポートされている値です。詳細については、「[API Gateway で HTTP API の AWS Lambda プロキシ統合を作成する](http-api-develop-integrations-lambda.md)」と「[統合サブタイプのリファレンス](http-api-develop-integrations-aws-services-reference.md)」を参照してください。 | 
| requestParameters | [x-amazon-apigateway-integration.requestParameters オブジェクト](api-gateway-swagger-extensions-integration-requestParameters.md) | REST API では、メソッドリクエストパラメータから統合リクエストパラメータへのマッピングを指定します。サポートされているリクエストパラメーターは、`querystring`、`path`、`header`、および `body` です。 HTTP API の場合、リクエストパラメータは、指定した `AWS_PROXY` と `integrationSubtype` の統合に渡すパラメータを指定するキーと値のマップです。静的値、マップリクエストデータ、ランタイムに評価されるステージ変数やコンテキスト変数のいずれかを指定できます。詳細については、「[API Gateway で HTTP API の AWS のサービス統合を作成する](http-api-develop-integrations-aws-services.md)」を参照してください。  | 
| requestTemplates | [x-amazon-apigateway-integration.requestTemplates オブジェクト](api-gateway-swagger-extensions-integration-requestTemplates.md) | 指定された MIME タイプのリクエストペイロード用のマッピングテンプレートです。 | 
| responses | [x-amazon-apigateway-integration.responses オブジェクト](api-gateway-swagger-extensions-integration-responses.md) | メソッドのレスポンスを定義し、統合レスポンスからメソッドレスポンスまで必要なパラメーターマッピングまたはペイロードマッピングを指定します。 | 
| responseTransferMode | string | 統合のレスポンス転送モード。BUFFERED を使用すると、API Gateway は送信を開始する前に完全なレスポンスを受信するまで待機します。STREAM を使用すると、API Gateway は部分的なレスポンスが利用可能になったときに、クライアントに送信します。詳細については[API Gateway でプロキシ統合の統合レスポンスをストリーミングする](response-transfer-mode.md)を参照してください。 | 
| timeoutInMillis | integer | 統合タイムアウトは 50 ミリ秒～29,000 ミリ秒です。 | 
| type | string |  特定のバックエンドを持つ統合のタイプ。有効な値は次のとおりです。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html) 統合タイプの詳細については、「[integration:type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type)」を参照してください。  | 
| tlsConfig | [x-amazon-apigateway-integration.tlsConfig オブジェクト](api-gateway-extensions-integration-tls-config.md) | 統合の TLS 設定を指定します。 | 
| uri | string | バックエンドのエンドポイント URI。aws タイプの統合の場合、この URI は ARN 値です。HTTP 統合の場合、この URI は、https または http スキームを含む HTTP エンドポイントの URL です。 | 

## x-amazon-apigateway-integration の例
<a name="api-gateway-swagger-extensions-integration-example"></a>

HTTP API の場合、OpenAPI 定義のコンポーネントセクションで統合を定義できます。詳細については、「[x-amazon-apigateway-integrations オブジェクト](api-gateway-extensions-integrations.md)」を参照してください。

```
"x-amazon-apigateway-integration": {
    "$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
```

 次の例では、Lambda 関数との統合を作成します。デモンストレーションの目的で、以下の例の `requestTemplates` および `responseTemplates` のサンプルマッピングテンプレートは、`{ "name":"value_1", "key":"value_2", "redirect": {"url" :"..."} }` の JSON 出力または `{ "stage":"value_1", "user-id":"value_2" }` の XML 出力を生成するために、`<stage>value_1</stage>` という JSON 形式のペイロードに適用されるものとします。

```
"x-amazon-apigateway-integration" : {
    "type" : "aws",
    "uri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:012345678901:function:HelloWorld/invocations",
    "httpMethod" : "POST",
    "credentials" : "arn:aws:iam::012345678901:role/apigateway-invoke-lambda-exec-role",
    "requestTemplates" : {
                "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
                "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> "
    },
    "requestParameters" : {
        "integration.request.path.stage" : "method.request.querystring.version",
        "integration.request.querystring.provider" : "method.request.querystring.vendor"
    },
    "cacheNamespace" : "cache namespace",
    "cacheKeyParameters" : [],
    "responses" : {
        "2\\d{2}" : {
            "statusCode" : "200",
            "responseParameters" : {
                "method.response.header.requestId" : "integration.response.header.cid"
            },
            "responseTemplates" : {
                "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
                "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> "
            }
        },
        "302" : {
            "statusCode" : "302",
            "responseParameters" : {
                "method.response.header.Location" : "integration.response.body.redirect.url"
            }
        },
        "default" : {
            "statusCode" : "400",
            "responseParameters" : {
                "method.response.header.test-method-response-header" : "'static value'"
            }
        }
    }
}
```

マッピングテンプレートの JSON 文字列の二重引用符「"」は、エスケープ文字を付けて「\$1"」とする必要があります。