本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 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\$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) CONVERT\$1TO\$1TEXT，將二進位承載轉換為 base64 編碼的字串或將文字承載轉換為 utf-8 編碼的字串，或以原生方式傳遞文字承載，不予修改；和 2) CONVERT\$1TO\$1BINARY，將文字承載轉換為 Base64 編碼的 blob，或以原生方式傳遞二進位承載，不予修改。 |
| 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 是唯一支援的值。如需進一步了解，請參閱[在 APIs 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，請求參數是一個金鑰值映射，指定傳遞給帶有特定 `integrationSubtype` 的 `AWS_PROXY` 整合。您可以提供靜態值，或映射請求資料、階段變數或在執行階段評估的內容變數。如需進一步了解，請參閱[在 APIs 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/zh_tw/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 字串的雙引號 (") 必須是逸出字串 (\$1")。