# x-amazon-apigateway-integration 对象
指定用于该方法的后端集成的详细信息。此扩展是 [OpenAPI 操作](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\_LINK"，否则为 "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) CONVERT\_TO\_TEXT，用于将二进制负载转换为 Base64 编码字符串，或者将文本负载转换为 utf-8 编码字符串，或者在无任何修改的情况下直接传递文本负载，以及 2) CONVERT\_TO\_BINARY，用于将文本负载转换为 Base64 解码的二进制大型对象，或者在无任何修改的情况下直接传递二进制负载。 |
| 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\_no\_templates、when\_no\_match 和 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 毫秒到 29000 毫秒之间。 |
| type | string | 与指定后端的集成的类型。有效值为：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/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 object](api-gateway-extensions-integration-tls-config.md) | 指定集成的 TLS 配置。 |
| uri | string | 后端的端点 URI。对于 aws 类型的集成，此为一个 ARN 值。对于 HTTP 集成，此为 HTTP 端点的 URL，包括 https 或 http 方案。 |
## x-amazon-apigateway-integration 示例
对于 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` 适用于以下 JSON 格式的负载：`{ "name":"value_1", "key":"value_2", "redirect": {"url" :"..."} }`，以生成 `{ "stage":"value_1", "user-id":"value_2" }` 的 JSON 输出或 `value_1` 的 XML 输出。
```
"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('$')) $root.name "
},
"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('$')) $root.name "
}
},
"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 字符串的双引号 (") 必须是转义字符串 (\\")。