本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# API Gateway 中 REST API 的 HTTP 整合
您可以使用 HTTP 代理整合或 HTTP 自訂整合，將 API 方法與 HTTP 端點進行整合。
API Gateway 支援以下端點連接埠：80、443 及 1024-65535。
使用代理整合時，設定非常簡單。如果您不在乎內容編碼或快取，您只需要根據後端需求來設定 HTTP 方法與 HTTP 端點 URI。
使用自訂整合時，需要進行更多的設定。除了代理整合設定步驟，您還需要指定傳入請求資料如何對應到整合請求，以及產生的整合回應資料如何對應到方法回應。
**Topics**
+ [在 API Gateway 中設定 HTTP 代理整合](#api-gateway-set-up-http-proxy-integration-on-proxy-resource)
+ [在 API Gateway 中設定 HTTP 自訂整合](#set-up-http-custom-integrations)
## 在 API Gateway 中設定 HTTP 代理整合
若要設定代理資源與 HTTP 代理整合類型搭配，請建立 API 資源與 Greedy 路徑參數 (例如 `/parent/{proxy+}`) 搭配，並將此資源與 `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}` 方法上的 HTTP 後端端點 (例如 `ANY`) 整合。Greedy 路徑參數必須位於資源路徑結尾。
如同非代理資源，您可以使用 API Gateway 主控台、匯入 OpenAPI 定義檔，或直接呼叫 API Gateway REST API，來設定具有 HTTP 代理整合的代理資源。如需使用 API Gateway 主控台來設定代理資源與 HTTP 整合搭配的詳細說明，請參閱[教學：建立具有 HTTP 代理整合的 REST API](api-gateway-create-api-as-simple-proxy-for-http.md)。
下列 OpenAPI 定義檔顯示一個其代理資源與 [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) 網站整合的 API 範例。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-09-12T23:19:28Z",
"title": "PetStoreWithProxyResource"
},
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.proxy": "method.request.path.proxy"
},
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"cacheNamespace": "rbftud",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "http_proxy"
}
}
}
},
"servers": [
{
"url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
]
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-09-12T23:19:28Z",
"title": "PetStoreWithProxyResource"
},
"host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.proxy": "method.request.path.proxy"
},
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"cacheNamespace": "rbftud",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "http_proxy"
}
}
}
}
}
```
------
在此範例中，快取金鑰是在代理資源的 `method.request.path.proxy` 路徑參數上宣告。當您使用 API Gateway 主控台建立 API 時，這是預設設定。API 的基底路徑 (對應到階段的 `/test`) 會對應到網站的 PetStore 頁面 (`/petstore`)。單一整合請求使用 API 的 Greedy 路徑變數與 catch-all `ANY` 方法來鏡射整個 PetStore 網站。下列範例說明此鏡射。
+ **將 `ANY` 設定為 `GET`，將 `{proxy+}` 設定為 `pets`**
從前端啟動的方法請求：
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
```
傳送到後端的整合請求：
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
```
`ANY` 方法與代理資源的執行時間執行個體皆有效。呼叫會傳回 `200 OK` 回應與含有從後端傳回之第一批寵物的承載。
+ **將 `ANY` 設定為 `GET`，將 `{proxy+}` 設定為 `pets?type=dog`**
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1
```
傳送到後端的整合請求：
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1
```
`ANY` 方法與代理資源的執行時間執行個體皆有效。呼叫會傳回 `200 OK` 回應與含有從後端傳回之第一批指定狗類的承載。
+ **將 `ANY` 設定為 `GET`，將 `{proxy+}` 設定為 `pets/{petId}`**
從前端啟動的方法請求：
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1
```
傳送到後端的整合請求：
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1
```
`ANY` 方法與代理資源的執行時間執行個體皆有效。呼叫會傳回 `200 OK` 回應與含有從後端傳回之指定寵物的承載。
+ **將 `ANY` 設定為 `POST`，將 `{proxy+}` 設定為 `pets`**
從前端啟動的方法請求：
```
POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
Content-Type: application/json
Content-Length: ...
{
"type" : "dog",
"price" : 1001.00
}
```
傳送到後端的整合請求：
```
POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
Content-Type: application/json
Content-Length: ...
{
"type" : "dog",
"price" : 1001.00
}
```
`ANY` 方法與代理資源的執行時間執行個體皆有效。呼叫會傳回 `200 OK` 回應與含有從後端傳回之新建立寵物的承載。
+ **將 `ANY` 設定為 `GET`，將 `{proxy+}` 設定為 `pets/cat`**
從前端啟動的方法請求：
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat
```
傳送到後端的整合請求：
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat
```
代理資源路徑的執行時間執行個體未對應到後端端點，且產生的請求無效。因此會傳回 `400 Bad Request` 回應與下列錯誤訊息。
```
{
"errors": [
{
"key": "Pet2.type",
"message": "Missing required field"
},
{
"key": "Pet2.price",
"message": "Missing required field"
}
]
}
```
+ **將 `ANY` 設定為 `GET`，將 `{proxy+}` 設定為 `null`**
從前端啟動的方法請求：
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test
```
傳送到後端的整合請求：
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
目標資源是代理資源的父系，但未在該資源的 API 中定義 `ANY` 方法的執行時間執行個體。因此，這個 `GET` 請求會傳回 `403 Forbidden` 回應與 API Gateway 所傳回的 `Missing Authentication Token` 錯誤訊息。如果 API 在父資源 (`ANY`) 上公開 `GET` 或 `/` 方法，呼叫會傳回 `404 Not Found` 回應與後端所傳回的 `Cannot GET /petstore` 訊息。
針對任何用戶端請求，如果目標端點 URL 無效，或 HTTP 動詞有效但不受支援，則後端會傳回 `404 Not Found` 回應。針對不支援的 HTTP 方法，則會傳回 `403 Forbidden` 回應。
## 在 API Gateway 中設定 HTTP 自訂整合
若使用 HTTP 自訂整合 (也稱為非代理整合)，您就能更精細地控制要在 API 方法與 API 整合之間傳遞哪些資料，以及如何傳遞這些資料。您會透過資料對應來執行此作業。
在方法請求設定過程中，您可以在 [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 資源上設定 [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#requestParameters) 屬性。這會宣告哪些從用戶端佈建的方法請求參數，是要對應到整合請求參數或適用的內文屬性，再發送到後端。然後，在整合請求設定過程中，您可以在映射的 [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 資源上設定 [requestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestParameters) 屬性，來指定參數對參數的映射。您也可以設定 [requestTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestTemplates) 屬性，針對每個支援的內容類型各指定一個映射範本。對應範本會將方法請求參數或內文對應到整合請求內文。
同樣地，在方法回應設定過程中，您可以在 [Method Response](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) 資源上設定 [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) 屬性。這會宣告哪些要發送到用戶端的方法回應參數，是要從後端傳回之整合回應參數或特定適用的內文屬性對應而來。接著您可以設定 [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)，以根據後端的回應選擇整合回應。對於非代理 HTTP 整合，這是規則表達式。例如，若要將所有 2xx HTTP 回應狀態碼從 HTTP 端點對應至此輸出對應，請使用 `2\d{2}`。
**注意**
API Gateway 使用 Java 模式 regex 進行回應映射。如需詳細資訊，請參閱 Oracle 文件中的[模式](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html)一節。
然後，在整合回應設定過程中，您可以在映射的 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 資源上設定 [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseParameters) 屬性，來指定參數對參數的映射。您也可以設定 [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseTemplates) 映射，針對每個支援的內容類型各指定一個映射範本。對應範本會將整合回應參數或整合回應內文屬性對應到方法回應內文。
如需設定映射範本的詳細資訊，請參閱[API Gateway 中用於 REST API 的資料轉換](rest-api-data-transformations.md)。