PAYLOAD1 | PAYLOAD2 | PAYLOAD3
```
在輸出中：
+ 如果沒有傳回額外的回應標頭`headers``multiValueHeaders`，則無法指定 、`cookies`、 和 `statusCode`金鑰。
+ `headers` 鍵只能包含單一值標頭。
+ 輸出預期標頭包含 `Transfer-Encoding: chunked`或 `Content-length: number`。如果您的函數未傳回其中一個標頭，API Gateway 會附加`Transfer-Encoding: chunked`到回應標頭。
+ `multiValueHeaders` 鍵可以包含多值標頭以及單一值標頭。您可以使用 `multiValueHeaders` 鍵來指定所有額外標頭，包括任何單一值標頭。
+ 如果您同時指定 `headers` 和 `multiValueHeaders` 的值，API Gateway 會將它們合併成一個清單。如果在兩者指定了相同的鍵值對，則只有 `multiValueHeaders` 中的值會出現在合併清單。
+ 中繼資料必須是有效的 JSON。僅支援 `headers`、 `multiValueHeaders``cookies`和 `statusCode`金鑰。
+ 您必須在中繼資料 JSON 之後提供分隔符號。分隔符號必須是 8 個 null 位元組，且必須出現在串流資料的前 16KB 內。
+ API Gateway 不需要方法回應承載的特定格式。
如果您使用函數 URL 串流 Lambda 函數，則必須修改 Lambda 函數的輸入和輸出，以滿足這些要求。
如果您的 Lambda 函數輸出不符合此格式的要求，API Gateway 可能仍會叫用您的 Lambda 函數。下表顯示 API Gateway 支援的 API 整合請求設定和 Lambda 函數程式碼的組合。這包括緩衝的回應傳輸模式支援的組合。
| 回應傳輸模式 | 函數程式碼遵循所需的格式 | Lambda 叫用 API | API Gateway 支援 |
| --- | --- | --- | --- |
| 串流 | 是 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 是。API Gateway 會串流您的回應。 |
| 串流 | 否 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 否。API Gateway 會叫用您的 Lambda 函數並傳回 500 錯誤回應。 |
| 串流 | 是 | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | 否。API Gateway 不支援此整合組態。 |
| 串流 | 否 | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | 否。API Gateway 不支援此整合組態。 |
| 緩衝 | 是 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 否。API Gateway 不支援此整合組態。 |
| 緩衝 | 否 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 否。API Gateway 不支援此整合組態。 |
| 緩衝 | 是 | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | API Gateway 會傳回 HTTP 標頭和狀態碼，但不會傳回回應內文。 |
| 緩衝 | 否 | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | 是。這是 Lambda 代理整合。如需詳細資訊，請參閱 [Lambda 代理整合](set-up-lambda-proxy-integrations.md)。 |
# 在 API Gateway 中設定 Lambda 代理整合與承載回應串流
當您設定回應承載串流時，您可以在資源的整合請求中指定傳輸模式。您可以在整合請求中設定這些設定，以控制 API Gateway 在整合回應之前和期間的行為。
## 回應串流的 Lambda 函數範例
您的 Lambda 函數必須遵循 [用於回應串流的 Lambda 代理整合格式](response-transfer-mode-lambda.md#response-transfer-mode-lambda-format)。我們建議您使用三個範例 Lambda 函數之一來測試回應串流。當您建立 Lambda 函數時，請務必執行下列動作：
+ 為您的函數提供足夠的逾時。我們建議您設定至少 1 分鐘的逾時，以了解回應串流。當您建立生產資源時，請確定 Lambda 函數逾時涵蓋完整的請求週期。如需詳細資訊，請參閱[設定 Lambda 函數逾時](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)。
+ 使用最新的 Node.js 執行時間。
+ 使用可使用 Lambda 回應串流的區域。
------
#### [ Using HttpResponseStream.from ]
下列程式碼範例使用 `awslambda.HttpResponseStream()`方法將 JSON 中繼資料物件和承載串流回用戶端，而不使用管道方法。您不需要建立分隔符號。如需詳細資訊，請參閱[撰寫啟用回應串流功能的 Lambda 函數](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html)。
```
export const handler = awslambda.streamifyResponse(
async (event, responseStream, context) => {
const httpResponseMetadata = {
"statusCode": 200,
"headers": {
"x-foo": "bar"
},
"multiValueHeaders": {
"x-mv1": ["hello", "world"],
"Set-Cookie": ["c1=blue", "c2=red"]
}
};
responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
await new Promise(r => setTimeout(r, 1000)); // synthetic delay
responseStream.write("First payload ");
await new Promise(r => setTimeout(r, 1000)); // synthetic delay
responseStream.write("Final payload");
responseStream.end();
});
```
------
#### [ Using the pipeline method ]
Lambda 建議您在撰寫啟用回應串流的函數時，使用原生 Node.js 執行時間提供的`awslambda.streamifyResponse()`裝飾項目，以及 `pipeline()`方法。當您使用管道方法時，您不需要建立分隔符號，Lambda 會為您執行此操作。如需詳細資訊，請參閱[撰寫啟用回應串流功能的 Lambda 函數](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html)。
下列程式碼範例會將 JSON 中繼資料物件和三個承載串流回用戶端。
```
import { pipeline } from 'node:stream/promises';
import { Readable } from 'node:stream';
export const handler = awslambda.streamifyResponse(
async (event, responseStream, context) => {
const httpResponseMetadata = {
statusCode: 200,
headers: {
"Content-Type": "text/plain",
"X-Custom-Header": "Example-Custom-Header"
}
};
responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
const dataStream = Readable.from(async function* () {
yield "FIRST payload\n";
await new Promise(r => setTimeout(r, 1000));
yield "SECOND payload\n";
await new Promise(r => setTimeout(r, 1000));
yield "THIRD payload\n";
await new Promise(r => setTimeout(r, 1000));
}());
await pipeline(dataStream, responseStream);
}
);
```
------
#### [ Without using the pipeline method ]
下列程式碼範例會將 JSON 中繼資料物件和三個承載串流回用戶端，而無需使用 `awslambda.HttpResponseStream()`方法。如果沒有 `awslambda.HttpResponseStream()`方法，您必須在中繼資料和承載之間包含 8 個 null 位元組的分隔符號。
```
export const handler = awslambda.streamifyResponse(async (event, response, ctx) => {
response.write('{"statusCode": 200, "headers": {"hdr-x": "val-x"}}');
response.write("\x00".repeat(8)); // DELIMITER
await new Promise(r => setTimeout(r, 1000));
response.write("FIRST payload");
await new Promise(r => setTimeout(r, 1000));
response.write("SECOND payload");
await new Promise(r => setTimeout(r, 1000));
response.write("FINAL payload");
response.end();
});
```
------
## 建立與承載回應串流的 Lambda 代理整合
下列程序說明如何建立與承載回應串流的 Lambda 代理整合。使用範例 Lambda 函數或建立您自己的函數。
------
#### [ AWS 管理主控台 ]
**建立與承載回應串流的 Lambda 代理整合**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 REST API。
1. 選擇**建立資源**。
1. 針對**資源名稱**，輸入 **streaming**。
1. 選擇**建立資源**。
1. 選取 **/streaming** 資源後，選擇**建立方法**。
1. 針對**方法類型**，選擇**任何**。
1. 對於 **整合類型**，選擇 **Lambda**。
1. 選擇 **Lambda 代理整合**。
1. 針對**回應傳輸模式**，選擇**串流**。
1. 針對 **Lambda 函數**，選擇 Lambda 函數的名稱。
API Gateway 主控台會自動使用 [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) API 來叫用 Lambda 函數。您負責撰寫啟用回應串流功能的 Lambda 函數。如需範例，請參閱 [回應串流的 Lambda 函數範例](#response-streaming-lambda-example)。
1. 選擇**建立方法**。
建立方法之後，請部署您的 API。
**部署 API**
1. 選擇**部署 API**。
1. 針對**階段**，選取**新階段**。
1. 針對**階段名稱**，輸入 **prod**。
1. 在**描述**，請輸入描述。
1. 選擇**部署**。
------
#### [ AWS CLI ]
下列程序說明如何匯入將 `responseTransferMode` 設為 的新 API`STREAM`。如果您有現有的整合 API 並想要修改 `responseTransferMode`，請參閱 [更新 Lambda 代理整合的回應傳輸模式](#response-streaming-lambda-update)。
**使用承載回應串流建立新的 API**
1. 複製下列 Open API 檔案，然後將其儲存為 `ResponseStreamDemoSwagger.yaml`。在此檔案中， `responseTransferMode` 設定為 `STREAM`，而整合 URI 設定為 `arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations`。
將 中的函數名稱取代`my-function`為啟用串流的函數，並將登入資料取代為具有允許`apigateway`服務呼叫 Lambda 函數之政策的 IAM 角色。
```
openapi: "3.0.1"
info:
title: "ResponseStreamingDemo"
version: "2025-04-28T17:28:25Z"
servers:
- url: "{basePath}"
variables:
basePath:
default: "prod"
paths:
/lambda:
get:
x-amazon-apigateway-integration:
httpMethod: "POST"
uri: "arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations"
type: "aws_proxy"
timeoutInMillis: 90000
responseTransferMode: "STREAM"
credentials: "arn:aws:iam::111122223333:role/apigateway-lambda-role"
```
您可以使用 Lambda 的 `add-permission`命令來新增以資源為基礎的許可，而不是為登入資料提供 IAM 角色。
1. 使用下列`import-rest-api`命令匯入您的 OpenAPI 定義：
```
aws apigateway import-rest-api \
--body 'fileb://~/ResponseStreamDemoSwagger.yaml' \
--parameters endpointConfigurationTypes=REGIONAL \
--region us-west-1
```
1. 使用下列`create-deployment`命令將您的新 API 部署到階段：
```
aws apigateway create-deployment \
--rest-api-id a1b2c2 \
--stage-name prod \
--region us-west-1
```
------
### 更新 Lambda 代理整合的回應傳輸模式
下列程序說明如何更新 Lambda 代理整合的回應傳輸模式。當您將回應傳輸模式變更為串流時，請更新您的 Lambda 函數，使其遵守回應串流的要求。使用範例 Lambda 函數或建立您自己的函數。
------
#### [ AWS 管理主控台 ]
**更新 Lambda 代理整合的回應傳輸模式**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 REST API。
1. 選擇一個方法。
1. 在**整合請求**索引標籤上，於**整合請求設定**下，選擇**編輯**。
1. 針對**回應傳輸模式**，選擇**串流**。
1. 針對 **Lambda 函數**，選擇 Lambda 函數的名稱。
1. 選擇**儲存**。
更新方法後，請部署您的 API。
**部署 API**
1. 選擇**部署 API**。
1. 針對**階段**，選取**新階段**。
1. 針對**階段名稱**，輸入 **prod**。
1. 在**描述**，請輸入描述。
1. 選擇**部署**。
------
#### [ AWS CLI ]
1. 更新您的 Lambda 函數以啟用串流。
1. 使用下列 AWS CLI 命令來更新整合的整合 URI 和回應傳輸模式：
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method ANY \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations\"}, {\"op\":\"replace\",\"path\":\"/responseTransferMode\",\"value\":\"STREAM\"}]" \
--region us-west-1
```
1. 重新部署 API 以使變更生效。
------
# 針對 API Gateway 中的回應串流問題進行故障診斷
下列疑難排解指引可能有助於解決使用回應串流APIs 的問題。
## 一般性問題的故障診斷
您可以使用 [TestInvokeMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_TestInvokeMethod.html) 或主控台的測試索引標籤來測試串流回應。下列考量事項可能會影響您使用測試叫用進行回應串流：
+ 當您測試方法時，API Gateway 會緩衝串流的回應承載。一旦符合下列任一條件，API Gateway 便會傳回包含緩衝承載的一次性回應：
+ 請求已完成
+ 已經過 35 秒
+ 已緩衝超過 1 MB 的回應承載
+ 如果超過 35 秒才傳回 HTTP 回應狀態和所有標頭，則 TestInvokeMethod 中傳回的回應狀態為 0。
+ API Gateway 不會產生任何執行日誌。
部署 API 之後，您可以使用 curl 命令來測試串流回應。建議您使用 `-i`選項，在輸出中包含通訊協定回應標頭。若要查看到達時的回應資料，請使用 curl 選項 `--no-buffer`
## 針對 cURL 錯誤進行故障診斷
如果您正在測試整合並收到錯誤 `curl: (18) transfer closed with outstanding read data remaining`，請確定整合的逾時時間夠長。如果您使用的是 Lambda 函數，則需要更新 Lambda 函數的回應逾時。如需詳細資訊，請參閱[設定 Lambda 函數逾時](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)。
## 使用存取記錄進行故障診斷
您可以使用 REST API 階段的存取日誌來記錄回應串流並進行疑難排解。除了現有的變數之外，您還可以使用下列存取日誌變數：
`$context.integration.responseTransferMode`
整合的回應傳輸模式。可以是 `BUFFERED` 或 `STREAMED`。
`$context.integration.timeToAllHeaders`
從用戶端接收所有整合回應標頭時，API Gateway 與 建立整合連線之間的時間。
`$context.integration.timeToFirstContent`
API Gateway 在收到第一個內容位元組時建立與 的整合連線之間的時間。
`$context.integration.latency` 或 `$context.integrationLatency`
當整合回應串流完成時，API Gateway 與 建立整合連線的時間。
下圖顯示這些存取日誌變數如何代表回應串流的不同元件。
![\[在 API Gateway 中存取回應串流的日誌變數\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/response-streaming-figure.png)
如需存取日誌的詳細資訊，請參閱[在 API Gateway 中設定 REST API 的 CloudWatch 記錄功能](set-up-logging.md)。您也可以使用 X-Ray 來監控回應串流。如需詳細資訊，請參閱[在 API Gateway 中使用 X-Ray 追蹤使用者對 REST API 的請求](apigateway-xray.md)。
# API Gateway 中 REST API 的私有整合
使用私有整合公開 Amazon VPC 內的 HTTP/HTTPS 資源，供 VPC 外部的用戶端存取。這會將對私有 VPC 資源的存取延伸到 VPC 邊界之外。您可以使用 API Gateway 支援的任何[授權方法](apigateway-control-access-to-api.md)來控制對您的 API 的存取。
若要建立私有整合，您必須先建立 VPC 連結。API Gateway 支援適用於 REST APIs VPC 連結 V2。VPC 連結 V2 可讓您建立私有整合，將 REST API 連線至 Application Load Balancer，而無需使用 Network Load Balancer。使用 Application Load Balancer 可讓您連線至 Amazon ECSs容器型應用程式和許多其他後端。VPC 連結 V1 被視為舊版整合類型。雖然 API Gateway 支援這些連結，但建議您不要建立新的 VPC 連結 V1。
## 考量事項
下列考量事項可能會影響您使用私有整合：
+ 所有資源都必須由相同的 擁有 AWS 帳戶。這包括負載平衡器、VPC 連結和 REST API。
+ 依預設，私有整合流量會使用 HTTP 通訊協定。若要使用 HTTPS，請指定包含安全伺服器名稱[https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)的 ，例如 `https://example.com:443/test`。
+ 在私有整合中，API Gateway 會在對後端資源的請求中包含 API 端點的[階段](set-up-stages.md)部分。例如，如果您請求 API 的`test`階段，API Gateway 會在私有整合的請求`test/path`中包含 。若要從對後端資源的請求移除階段名稱，請使用[參數映射](rest-api-parameter-mapping.md)來建立`$context.requestOverride.path`變數的覆寫。
+ AWS Cloud Map 不支援與 的私有整合。
**Topics**
+ [考量事項](#private-integrations-considerations)
+ [在 API Gateway 中設定 VPC 連結 V2](apigateway-vpc-links-v2.md)
+ [設定私有整合](set-up-private-integration.md)
+ [使用 VPC 連結 V1 的私有整合 （舊版）](vpc-links-v1.md)
# 在 API Gateway 中設定 VPC 連結 V2
VPC 連結可讓您建立私有整合，將 API 路由連線至 VPC 中的私有資源，例如 Application Load Balancer 或 Amazon ECS 容器型應用程式。私有整合使用 VPC 連結 V2 封裝 API Gateway 與目標 VPC 資源之間的連線。您可以重複使用不同資源和 APIs VPC 連結。
當您建立 VPC 連結時，API Gateway 會建立和管理您帳戶中 VPC 連結 V2 的[彈性網路介面](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)。此程序需要幾分鐘的時間。當 VPC 連結 V2 可供使用時，其狀態會從 轉換為 `PENDING` `AVAILABLE`。
**注意**
如果 60 天內沒有透過 VPC 連結傳送流量，則會變成 `INACTIVE`。當 VPC 連結處於 `INACTIVE` 狀態時，API Gateway 會刪除所有 VPC 連結的網路介面。這會導致依賴 VPC 連結的 API 請求失敗。如果 API 請求繼續，API Gateway 會重新佈建網路介面。建立網路介面並重新啟用 VPC 連結可能需要幾分鐘的時間。您可以使用 VPC 連結狀態來監控 VPC 連結的狀態。
## 使用 建立 VPC 連結 V2 AWS CLI
若要建立 VPC 連結 V2，所有涉及的資源都必須由相同的 AWS 帳戶擁有。以下 [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-vpc-link.html) 命令會建立 VPC 連結：
```
aws apigatewayv2 create-vpc-link --name MyVpcLink \
--subnet-ids subnet-aaaa subnet-bbbb \
--security-group-ids sg1234 sg5678
```
**注意**
VPC 連結 V2 是不可變的。建立 VPC 連結 V2 之後，您無法變更其子網路或安全群組。
## 使用 刪除 VPC 連結 V2 AWS CLI
以下 [delete-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-vpc-link.html) 命令會刪除 VPC 連結。
```
aws apigatewayv2 delete-vpc-link --vpc-link-id abcd123
```
## 各個區域的供應情形
下列區域和可用區域支援 VPC 連結 V2：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/apigateway-vpc-links-v2.html)
# 設定私有整合
若要建立與 Application Load Balancer 或 Network Load Balancer 的私有整合，您可以建立 HTTP 代理整合、指定要使用的 [VPC 連結 V2](apigateway-vpc-links-v2.md)，並提供 Network Load Balancer 或 Application Load Balancer 的 ARN。依預設，私有整合流量會使用 HTTP 通訊協定。若要使用 HTTPS，請指定包含安全伺服器名稱[https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)的 ，例如 `https://example.com:443/test`。如需如何使用私有整合建立 REST API 的完整教學課程，請參閱 [教學：建立具私有整合的 REST API](getting-started-with-private-integration.md)。
## 建立私有整合
下列程序說明如何使用 VPC 連結 V2 建立連線至負載平衡器的私有整合。
------
#### [ AWS 管理主控台 ]
如需如何建立私有整合的教學課程，請參閱 [教學：建立具私有整合的 REST API](getting-started-with-private-integration.md)。
------
#### [ AWS CLI ]
下列 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) 命令會使用 VPC 連結 V2 建立連線至負載平衡器的私有整合：
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id bbb111
```
您可以改用階段變數，而不是直接提供連線 ID。當您將 API 部署到階段時，您可以設定 VPC 連結 V2 ID。下列 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) 命令會使用 VPC 連結 V2 ID 的階段變數建立私有整合：
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkV2Id}"
```
請務必對階段變數表達式 (\$1\$1stageVariables.vpcLinkV2Id\$1) 進行雙引號，並逸出 \$1 字元。
------
#### [ OpenAPI ]
您可以匯入 API OpenAPI 檔案來設定具有私有整合的 API。這些設定類似具有 HTTP 整合之 API 的 OpenAPI 定義，但例外如下：
+ 您必須將 `connectionType` 明確地設定為 `VPC_LINK`。
+ 您必須將 `connectionId` 明確地設定為 `VpcLinkV2` 的 ID 或參考 `VpcLinkV2` ID 的階段變數。
+ 私有整合中的 `uri` 參數指向 VPC 中的 HTTP/HTTPS 端點，但改為用來設定整合請求的 `Host` 標頭。
+ 具有 VPC 中 HTTPS 端點之私有整合中的 `uri` 參數用來針對 VPC 端點上所安裝憑證中的網域名稱來驗證所指出的網域名稱。
您可以使用階段變數來參考 `VpcLinkV2` ID。或者，您可以將 ID 值直接指派給 `connectionId`。
下列 JSON 格式化 OpenAPI 檔案會顯示 API 的範例，具有階段變數 (`${stageVariables.vpcLinkIdV2}`) 所參考的 VPC 連結：
```
{
"swagger": "2.0",
"info": {
"version": "2017-11-17T04:40:23Z",
"title": "MyApiWithVpcLinkV2"
},
"host": "abcdef123.execute-api.us-west-2.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "https://example.com:443/path",
"passthroughBehavior": "when_no_match",
"connectionType": "VPC_LINK",
"connectionId": "${stageVariables.vpcLinkV2Id}",
"integration-target": "arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011",
"httpMethod": "GET",
"type": "http_proxy"
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## 更新私有整合
下列範例會更新私有整合的 VPC 連結 V2。
------
#### [ AWS 管理主控台 ]
**更新私有整合**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇具有私有整合的 REST API。
1. 選擇使用私有整合的資源和方法。
1. 在**整合請求**標籤上，於**整合請求設定**下，選擇**編輯**。
1. 您可以編輯私有整合的設定。如果您目前正在使用 VPC 連結 V1，您可以將 VPC 連結變更為 VPC 連結 V2。
1. 選擇**儲存**。
1. 重新部署 API 以使變更生效。
------
#### [ AWS CLI ]
下列 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) 命令會更新私有整合，以使用 VPC 連結 V2：
```
aws apigateway update-integration \
--rest-api-id a1b2c3d4e5 \
--resource-id a1b2c3 \
--http-method GET \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/connectionId\",\"value\":\"pk0000\"}, {\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"http://example.com\"}, {\"op\":\"replace\",\"path\":\"/integrationTarget\",\"value\":\"arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011\"}]"
```
------
# 使用 VPC 連結 V1 的私有整合 （舊版）
**注意**
下列私有整合實作會使用 VPC 連結 V1。VPC 連結 V1 是舊版資源。建議您將 [VPC 連結 V2 用於 REST APIs](apigateway-vpc-links-v2.md)。
若要建立私有整合，您必須先建立 Network Load Balancer。您的 Network Load Balancer 必須有一個[接聽程式](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html)，將請求路由至 VPC 中的資源。為了改善 API 可用性，請確定您的 Network Load Balancer 可將流量路由至 AWS 區域中一個以上可用區域內的資源。然後，您會建立用來連線 API 和 Network Load Balancer 的 VPC 連結。建立 VPC 連結後，您可以建立私有整合，以透過 VPC 連結和 Network Load Balancer 將流量從 API 路由到 VPC 中的資源。Network Load Balancer 和 API 必須擁有相同的 AWS 帳戶。
**Topics**
+ [設定 API Gateway 私有整合的 Network Load Balancer （舊版）](set-up-nlb-for-vpclink-using-console.md)
+ [授予 API Gateway 建立 VPC 連結的許可 （舊版）](grant-permissions-to-create-vpclink.md)
+ [使用 AWS CLI （舊版） 設定具有私有整合的 API Gateway API](set-up-api-with-vpclink-cli.md)
+ [用於私有整合的 API Gateway 帳戶 （舊版）](set-up-api-with-vpclink-accounts.md)
# 設定 API Gateway 私有整合的 Network Load Balancer （舊版）
**注意**
下列私有整合實作會使用 VPC 連結 V1。VPC 連結 V1 是舊版資源。建議您將 [VPC 連結 V2 用於 REST APIs](apigateway-vpc-links-v2.md)。
下列程序概述使用 Amazon EC2 主控台設定 API Gateway 私有整合之 Network Load Balancer (NLB) 的步驟，並提供每個步驟之詳細說明的參考。
對於每個 VPC 中的資源，您只需要設定一個 NLB 和一個 VPCLink。每個 NLB 皆支援多個[接聽程式](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html)和[目標群組](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html)。您可以設定每個服務為 NLB 上特定的接聽程式，使用單一 VPCLink 連接到 NLB。當您在 API Gateway 中建立私有整合時，將使用指定到每個服務的特定連接埠定義每個服務。如需詳細資訊，請參閱[教學：建立具私有整合的 REST API](getting-started-with-private-integration.md)。Network Load Balancer 和 API 必須擁有相同的 AWS 帳戶。
**使用 API Gateway 主控台建立私有整合的 Network Load Balancer**
1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)：// 開啟 Amazon EC2 主控台。
1. 在 Amazon EC2 執行個體上設定 Web 伺服器。如需範例設定，請參閱[在 Amazon Linux 2 上安裝 LAMP Web Server](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-lamp-amazon-linux-2.html)。
1. 建立 Network Load Balancer、註冊具有目標群組的 EC2 執行個體，並將目標群組新增至 Network Load Balancer 接聽程式。如需詳細資訊，請參閱 [Network Load Balancer 入門](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html)中的指示。
1. 建立 Network Load Balancer 之後，執行下列操作：
1. 記下 Network Load Balancer 的 ARN。您需要它才能在 API Gateway 中建立 VPC 連結，以整合 API 與受 Network Load Balancer 保護的 VPC 資源。
1. 針對 PrivateLink 關閉安全群組評估。
+ 若要使用主控台關閉 PrivateLink 流量的安全群組評估，您可以選擇**安全**標籤，然後選擇**編輯**。在**安全設定**中，清除**在 PrivateLink 流量強制執行輸入規則**。
+ 使用以下 [set-security-groups](https://docs.aws.amazon.com/cli/latest/reference/elbv2/set-security-groups.html) 命令關閉 PrivateLink 流量的安全群組評估：
```
aws elbv2 set-security-groups --load-balancer-arn arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/net/my-loadbalancer/abc12345 \
--security-groups sg-123345a --enforce-security-group-inbound-rules-on-private-link-traffic off
```
**注意**
請勿將任何相依性新增至 API Gateway CIDR，因為這些相依性必然會在未通知的情況下變更。
# 授予 API Gateway 建立 VPC 連結的許可 （舊版）
**注意**
下列私有整合實作會使用 VPC 連結 V1。VPC 連結 V1 是舊版資源。我們建議您將 [VPC 連結 V2 用於 REST APIs](apigateway-vpc-links-v2.md)。
若要讓您或您帳戶中的使用者建立和維護 VPC 連結，您或使用者必須有權建立、刪除和檢視 VPC 端點服務組態、變更 VPC 端點服務許可，以及檢查負載平衡器。若要授予這類許可，請使用下列步驟。
**授予建立、更新和刪除 VPC 連結的許可**
1. 建立與下列類似的 IAM 政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:POST",
"apigateway:GET",
"apigateway:PATCH",
"apigateway:DELETE"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/vpclinks",
"arn:aws:apigateway:us-east-1::/vpclinks/*"
]
},
{
"Effect": "Allow",
"Action": [
"elasticloadbalancing:DescribeLoadBalancers"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpointServiceConfiguration",
"ec2:DeleteVpcEndpointServiceConfigurations",
"ec2:DescribeVpcEndpointServiceConfigurations",
"ec2:ModifyVpcEndpointServicePermissions"
],
"Resource": "*"
}
]
}
```
------
如果您想要啟用 VPC 連結的標記，請務必允許標記操作。如需詳細資訊，請參閱[允許標記操作](apigateway-tagging-iam-policy.md#allow-tagging)。
1. 建立或選擇 IAM 角色，並將先前的政策連接至角色。
1. 將 IAM 角色指派給您或您帳戶中建立 VPC 連結的使用者。
# 使用 AWS CLI （舊版） 設定具有私有整合的 API Gateway API
**注意**
下列私有整合實作會使用 VPC 連結 V1。VPC 連結 V1 是舊版資源。建議您將 [VPC 連結 V2 用於 REST APIs](apigateway-vpc-links-v2.md)。
下列教學課程說明如何使用 AWS CLI 來建立 VPC 連結和私有整合。需要下列先決條件：
+ 您需要使用 VPC 來源來建立並設定 Network Load Balancer，並將其當成目標。如需詳細資訊，請參閱[設定 API Gateway 私有整合的 Network Load Balancer （舊版）](set-up-nlb-for-vpclink-using-console.md)。這必須與 API AWS 帳戶 位於相同的 中。您需要 Network Load Balancer ARN 才能建立 VPC 連結。
+ 若要建立和管理 `VpcLink`，您需要可在 API 中建立 `VpcLink` 的許可權。使用 `VpcLink` 不需要許可權。如需詳細資訊，請參閱[授予 API Gateway 建立 VPC 連結的許可 （舊版）](grant-permissions-to-create-vpclink.md)。
**使用 設定具有私有整合的 API AWS CLI**
1. 使用以下 [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-vpc-link.html) 命令會建立以指定的 Network Load Balancer 為目標的 `VpcLink`：
```
aws apigateway create-vpc-link \
--name my-test-vpc-link \
--target-arns arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef
```
此命令的輸出會確認收到請求，並顯示建立中 `VpcLink` 的 `PENDING` 狀態。
```
{
"status": "PENDING",
"targetArns": [
"arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef"
],
"id": "gim7c3",
"name": "my-test-vpc-link"
}
```
API Gateway 需要 2-4 分鐘才能完成建立 `VpcLink`。操作順利完成時，`status` 是 `AVAILABLE`。您可以使用下列 [get-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-vpc-link.html) 命令進行驗證：
```
aws apigateway get-vpc-link --vpc-link-id gim7c3
```
如果操作失敗，您會取得 `FAILED` 狀態，以及包含錯誤訊息的 `statusMessage`。例如，如果您嘗試建立具有已與 VPC 端點建立關聯之 Network Load Balancer 的 `VpcLink`，則會在 `statusMessage` 屬性上收到下列訊息：
```
"NLB is already associated with another VPC Endpoint Service"
```
順利建立 `VpcLink` 之後，您可以建立 API 並透過 `VpcLink` 將其與 VPC 資源整合。
記下新建立之 `VpcLink` 的 `id` 值。在此範例輸出中為 `gim7c3`。您需要它才能設定私有整合。
1. 使用以下 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 命令建立 API Gateway [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 資源：
```
aws apigateway create-rest-api --name 'My VPC Link Test'
```
請記下所傳回結果中 `RestApi` 的 `id` 值，和 `RestApi` 的 `rootResourceId` 值。您需要此值才能對 API 執行進一步操作。
接著在根資源 (`/`) 上建立只有 `GET` 方法的 API，並整合此方法與 `VpcLink`。
1. 使用以下 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 命令建立 `GET /` 方法：
```
aws apigateway put-method \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--authorization-type "NONE"
```
如果您未搭配 `VpcLink` 使用代理整合，至少也必須設定 `200` 狀態碼的方法回應。在這裡使用代理整合。
1. 建立 `GET /` 方法後，您可以設定整合。對於私有整合，您可以使用 `connection-id` 參數來提供 `VpcLink` ID。您可以使用階段變數或直接輸入 `VpcLink` ID。`uri` 參數不是用於將請求路由至端點，但用於設定 `Host` 標頭以及進行憑證驗證。
------
#### [ Use the VPC link ID ]
使用以下 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) 命令，以直接在整合中使用 `VpcLink` ID：
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id gim7c3
```
------
#### [ Use a stage variable ]
使用以下 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) 命令，以使用階段變數來參考 VPC 連結 ID。當您將 API 部署到階段時，可以設定 VPC 連結 ID。
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkId}"
```
請務必使用雙引號括住階段變數表達式 (`${stageVariables.vpcLinkId}`) 並逸出 `$` 字元。
------
您也可以隨時更新整合，以變更 `connection-id`。使用以下 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) 命令來更新整合：
```
aws apigateway update-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]'
```
請務必使用字串化 JSON 清單做為 `patch-operations` 參數值。
因為您使用了私有代理整合，所以 API 現在已準備好進行部署和執行測試。
1. 如果使用階段變數來定義 `connection-id`，您需要部署 API 來進行測試。使用以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令，以部署有階段變數的 API：
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name test \
--variables vpcLinkId=gim7c3
```
若要以不同的 `VpcLink` ID 更新階段變數 (例如 `asf9d7`)，請使用 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令：
```
aws apigateway update-stage \
--rest-api-id abcdef123 \
--stage-name test \
--patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7'
```
當使用 `VpcLink` ID 常值硬式編碼 `connection-id` 屬性時，您不需要部署 API 來進行測試。使用 [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html) 命令，在部署之前先測試您的 API。
1. 使用下列命令叫用 API：
```
curl -X GET https://abcdef123.execute-api.us-east-2.amazonaws.com/test
```
或者，您可以在 Web 瀏覽器中輸入 API 的調用 URL 來檢視結果。
# 用於私有整合的 API Gateway 帳戶 （舊版）
當您建立 `VpcLink` 時，下列特定區域 API Gateway 帳戶 ID 也會作為 `AllowedPrincipals` 自動新增至 VPC 端點服務。
| **區域** | **帳戶 ID** |
| --- | --- |
| us-east-1 | 392220576650 |
| us-east-2 | 718770453195 |
| us-west-1 | 968246515281 |
| us-west-2 | 109351309407 |
| ca-central-1 | 796887884028 |
| eu-west-1 | 631144002099 |
| eu-west-2 | 544388816663 |
| eu-west-3 | 061510835048 |
| eu-central-1 | 474240146802 |
| eu-central-2 | 166639821150 |
| eu-north-1 | 394634713161 |
| eu-south-1 | 753362059629 |
| eu-south-2 | 359345898052 |
| ap-northeast-1 | 969236854626 |
| ap-northeast-2 | 020402002396 |
| ap-northeast-3 | 360671645888 |
| ap-southeast-1 | 195145609632 |
| ap-southeast-2 | 798376113853 |
| ap-southeast-3 | 652364314486 |
| ap-southeast-4 | 849137399833 |
| ap-south-1 | 507069717855 |
| ap-south-2 | 644042651268 |
| ap-east-1 | 174803364771 |
| sa-east-1 | 287228555773 |
| me-south-1 | 855739686837 |
| me-central-1 | 614065512851 |
# API Gateway 中 REST API 的模擬整合
Amazon API Gateway 支援 API 方法的模擬整合。此功能可讓 API 開發人員直接從 API Gateway 產生 API 回應，而不需要整合後端。您是 API 開發人員，在專案開發完成之前，可以使用此功能來解鎖需要使用 API 的相依團隊。您也可以使用此功能來佈建您 API 的登錄頁面，以提供 API 的概觀，並導覽至 API。如需這類登錄頁面的範例，請參閱[教學課程：匯入範例來建立 REST API](api-gateway-create-api-from-example.md) 中所討論的範例 API 之根資源上的 GET 方法整合請求和回應。
作為 API 開發人員，您可決定 API Gateway 回應如何模擬整合請求。因此，您設定方法的整合請求和整合回應，以將回應與特定狀態碼建立關聯。若要讓具有模擬整合的方法傳回 `200` 回應，請設定整合請求內文映射範本來傳回下列內容。
```
{"statusCode": 200}
```
設定 `200` 整合回應，以具有下列內文映射範本，例如：
```
{
"statusCode": 200,
"message": "Go ahead without me."
}
```
例如，同樣地，若要讓方法傳回 `500` 錯誤回應，請設定整合請求內文映射範本來傳回下列內容。
```
{"statusCode": 500}
```
例如，設定具有下列映射範本的 `500` 整合回應：
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
或者，您可以讓模擬整合方法傳回預設整合回應，而不需要定義整合請求映射範本。預設整合回應具有未定義的 **HTTP status regex (HTTP 狀態 regex)**。請確定已設定適當的傳遞行為。
**注意**
模擬整合並不支援大型回應範本。如果您的使用案例需要這類範本，應考慮改用 Lambda 整合。
您可使用整合請求映射範本來插入應用程式邏輯，以根據特定條件決定要傳回的模擬整合回應。例如，您可以在傳入請求上使用 `scope` 查詢參數，決定是要傳回成功回應還是錯誤回應：
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
因此，模擬整合方法可讓內部呼叫通過，同時拒絕具有錯誤回應之其他類型的呼叫。
在本節中，我們將說明如何使用 API Gateway 主控台來啟用 API 方法的模擬整合。
**Topics**
+ [使用 API Gateway 主控台啟用模擬整合](how-to-mock-integration-console.md)
# 使用 API Gateway 主控台啟用模擬整合
您必須在 API Gateway 中有可用的方法。請遵循中的說明進行[教學：建立具有 HTTP 非代理整合的 REST API](api-gateway-create-api-step-by-step.md)
1. 選擇 API 資源，並選擇**建立方法**。
若要建立方法，請執行下列動作：
1. 針對**方法類型**，選取某個方法。
1. 針對**整合類型**，選取**模擬**。
1. 選擇**建立方法**。
1. 在**方法請求**索引標籤上，針對**方法請求設定**，選擇**編輯**。
1. 選擇 **URL 查詢字串參數**。選擇**新增查詢字串**，然後針對**名稱**輸入 **scope**。這個查詢參數會判斷發起人是否為內部。
1. 選擇**儲存**。
1. 在**方法回應**索引標籤上，選擇**建立回應**，然後執行下列動作：
1. 針對 **HTTP 狀態**，輸入 **500**。
1. 選擇**儲存**。
1. 在**整合請求**索引標籤上，針對**整合請求設定**，選擇**編輯**。
1. 選擇**對應範本**，然後執行下列動作：
1. 選擇**新增映射範本**。
1. 針對**內容類型**，輸入 **application/json**。
1. 針對**範本內文**，輸入下列內容：
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
1. 選擇**儲存**。
1. 在**整合回應**索引標籤上，針對**預設 - 回應**選擇**編輯**。
1. 選擇**對應範本**，然後執行下列動作：
1. 針對**內容類型**，輸入 **application/json**。
1. 針對**範本內文**，輸入下列內容：
```
{
"statusCode": 200,
"message": "Go ahead without me"
}
```
1. 選擇**儲存**。
1. 選擇**建立回應**。
若要建立 500 回應，請執行下列動作：
1. 對於 **HTTP 狀態 regex**，輸入 **5\$1d\$12\$1**。
1. 針對**方法回應狀態**，選取 **500**。
1. 選擇**儲存**。
1. 針對 **5\$1d\$12\$1 - 回應**，選擇**編輯**。
1. 選擇**對應範本**，然後選擇**新增對應範本**。
1. 針對**內容類型**，輸入 **application/json**。
1. 針對**範本內文**，輸入下列內容：
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
1. 選擇**儲存**。
1. 選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。若要測試模擬整合，請執行下列動作：
1. 在**查詢字串**下，輸入 `scope=internal`。選擇 **Test (測試)**。測試結果顯示：
```
Request: /?scope=internal
Status: 200
Latency: 26 ms
Response Body
{
"statusCode": 200,
"message": "Go ahead without me"
}
Response Headers
{"Content-Type":"application/json"}
```
1. 在 `Query strings` 下輸入 `scope=public`，或將其空白。選擇 **Test (測試)**。測試結果顯示：
```
Request: /
Status: 500
Latency: 16 ms
Response Body
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
Response Headers
{"Content-Type":"application/json"}
```
您也可以在模擬整合回應中傳回標頭，方法是先將標頭新增至方法回應，然後在整合回應中設定標頭映射。事實上，這就是 API Gateway 主控台透過傳回 CORS 必要標頭來啟用 CORS 支援的作法。
# API Gateway 中的 REST API 的請求驗證
您可以先設定 API Gateway 執行 API 請求的基本驗證，再繼續進行整合請求。驗證失敗時，API Gateway 會立即讓請求失敗、將 400 錯誤回應傳回給發起人，並在 CloudWatch Logs 中發布驗證結果。這樣可減少不必要的後端呼叫。更重要的是，它可讓您專注於應用程式特定的驗證努力。您可以驗證請求內文，方法為驗證必要的請求參數是否有效且為非 null 值，或指定模型結構描述進行更複雜的資料驗證。
**Topics**
+ [API Gateway 中的基本請求驗證概觀](#api-gateway-request-validation-basic-definitions)
+ [REST API 的資料模型](models-mappings-models.md)
+ [在 API Gateway 中設定基本請求驗證](api-gateway-request-validation-set-up.md)
+ [AWS CloudFormation 具有基本請求驗證的範例 API 範本](api-gateway-request-validation-sample-cloudformation.md)
## API Gateway 中的基本請求驗證概觀
API Gateway 可以執行基本請求驗證，以便您可以專注於後端的應用程式特定驗證。針對驗證，API Gateway 會驗證下列任一或兩個條件：
+ 是否包含 URI 中的必要請求參數、查詢字串以及傳入請求的標頭，而且不是空白。API Gateway 只會檢查參數是否存在，而不會檢查類型或格式。
+ 適用的請求承載會遵守方法中，針對所指內容類型設定的 [JSON 結構描述](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04)請求。如果找不到相符的內容類型，則不會執行請求驗證。若無論內容類型為何都要使用相同的模型，請將資料模型的內容類型設定為 `$default`。
若要開啟驗證，您必須在[請求驗證程式](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)中指定驗證規則、將驗證程式新增至 API 的[請求驗證程式對應](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)，並將驗證程式指派給個別 API 方法。
**注意**
請求內文驗證和 [API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為](integration-passthrough-behaviors.md) 是兩個獨立的主題。當請求承載沒有相符的模型結構描述時，您可以選擇傳遞或封鎖原始承載。如需詳細資訊，請參閱[API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為](integration-passthrough-behaviors.md)。
# REST API 的資料模型
在 API Gateway 中，模型會定義承載的資料結構。在 API Gateway 中，模型以 [JSON 結構描述草稿第 4 版](https://tools.ietf.org/html/draft-zyp-json-schema-04)定義。下列 JSON 物件是 Pet Store 範例中的範例資料。
```
{
"id": 1,
"type": "dog",
"price": 249.99
}
```
資料包含寵物的 `id`、`type` 和 `price`。此資料的模型可讓您：
+ 使用基本請求驗證。
+ 建立對應範本進行資料轉換。
+ 產生 SDK 時，建立使用者定義的資料類型 (UDT)。
![\[PetStore API 的範例 JSON 資料模型。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/how-to-validate-requests.png)
在這個模型中：
1. `$schema` 物件代表有效的 JSON 結構描述版本識別符。此結構描述為 JSON 結構描述草稿第 4 版。
1. `title` 物件是人類看得懂的模型識別符。這個標題是 `PetStoreModel`。
1. `required` 驗證關鍵字需要 `type` 和 `price`，才能進行基本請求驗證。
1. 模型的 `properties` 是 `id`、`type` 和 `price`。每個物件都有模型中描述的屬性。
1. 物件 `type` 只能具有值 `dog`、`cat` 或 `fish`。
1. 物件 `price` 是一個數字，且受到 `minimum` 為 25 且 `maximum` 為 500 的限制。
## PetStore 模型
```
1 {
2 "$schema": "http://json-schema.org/draft-04/schema#",
3 "title": "PetStoreModel",
4 "type" : "object",
5 "required" : [ "price", "type" ],
6 "properties" : {
7 "id" : {
8 "type" : "integer"
9 },
10 "type" : {
11 "type" : "string",
12 "enum" : [ "dog", "cat", "fish" ]
13 },
14 "price" : {
15 "type" : "number",
16 "minimum" : 25.0,
17 "maximum" : 500.0
18 }
19 }
20 }
```
在這個模型中：
1. 在第 2 行，`$schema` 物件代表有效的 JSON 結構描述版本識別符。此結構描述為 JSON 結構描述草稿第 4 版。
1. 在第 3 行，`title` 物件是人類看得懂的模型識別符。這個標題是 `PetStoreModel`。
1. 在第 5 行，`required` 驗證關鍵字需要 `type` 和 `price`，才能進行基本請求驗證。
1. 在第 6 至 17 行，模型的 `properties` 是 `id`、`type` 和 `price`。每個物件都有模型中描述的屬性。
1. 在第 12 行，物件 `type` 只能具有值 `dog`、`cat` 或 `fish`。
1. 在第 14 至 17 行，物件 `price` 是一個數字，且受到 `minimum` 為 25 且 `maximum` 為 500 的限制。
## 建立更複雜的模型
您可以使用 `$ref` 基本值，為較長的模型建立可重複使用的定義。例如，您可以在描述 `price` 物件的 `definitions` 區段中建立稱為 `Price` 的定義。`$ref` 的值是 `Price` 定義。
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReUsableRef",
"required" : ["price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "#/definitions/Price"
}
},
"definitions" : {
"Price": {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
您也可以參考外部模型檔案中定義的另一個模型結構描述。將 `$ref` 屬性的值設定為模型的位置。在下列範例中，`Price` 模型是在 API `a1234` 的 `PetStorePrice` 模型中定義的。
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStorePrice",
"type": "number",
"minimum": 25,
"maximum": 500
}
```
較長的模型可以參考 `PetStorePrice` 模型。
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReusableRefAPI",
"required" : [ "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice"
}
}
}
```
## 使用輸出資料模型
如果轉換您的資料，您可以在整合回應中定義承載模型。產生 SDK 時，可以使用承載模型。針對強型別語言 (例如 Java、Objective-C 或 Swift)，物件會對應到使用者定義的資料類型 (UDT)。如果您在產生 SDK 時透過資料模型提供 UDT，則 API Gateway 會建立該 UDT。如需資料轉型的詳細資訊，請參閱 [API Gateway 中 REST API 的映射範本轉換](models-mappings.md)。
下列範例是整合回應的輸出資料。
```
{
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
}
```
下列範例是描述輸出資料的承載模型。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PetStoreOutputModel",
"type" : "object",
"required" : [ "description", "askingPrice" ],
"properties" : {
"description" : {
"type" : "string"
},
"askingPrice" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
有了此模型，您可以呼叫 SDK，透過讀取 `PetStoreOutputModel[i].description` 和 `PetStoreOutputModel[i].askingPrice` 屬性，來擷取 `description` 和 `askingPrice` 屬性值。如果未提供模型，API Gateway 會使用空白模型來建立預設 UDT。
## 後續步驟
+ 本節提供的資源可讓您深入了解本主題中呈現的概念。
您可以遵循請求驗證教學課程：
+ [使用 API Gateway 主控台設定請求驗證](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-in-console)
+ [使用 設定基本請求驗證 AWS CLI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-cli)
+ [使用 OpenAPI 定義來設定基本請求驗證](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-importing-swagger)
+ 如需資料轉換和映射範本的詳細資訊，請參閱 [API Gateway 中 REST API 的映射範本轉換](models-mappings.md)。
# 在 API Gateway 中設定基本請求驗證
本節說明如何使用 主控台 AWS CLI和 OpenAPI 定義來設定 API Gateway 的請求驗證。
**Topics**
+ [使用 API Gateway 主控台設定請求驗證](#api-gateway-request-validation-setup-in-console)
+ [使用 設定基本請求驗證 AWS CLI](#api-gateway-request-validation-setup-cli)
+ [使用 OpenAPI 定義來設定基本請求驗證](#api-gateway-request-validation-setup-importing-swagger)
## 使用 API Gateway 主控台設定請求驗證
您可以使用 API Gateway 主控台來驗證請求，方法是為 API 請求選取三個驗證程式之一：
+ **驗證內文**。
+ **驗證查詢字串參數和標頭**。
+ **驗證內文、查詢字串參數和標頭**。
當您在 API 方法上套用其中一個驗證程式時，API Gateway 主控台會將驗證程式新增至 API 的 [RequestValidators](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) 對應。
若要遵循本教學課程，您將使用 CloudFormation 範本來建立不完整的 API Gateway API。此 API 具有 `/validator` 資源，其中含有 `GET` 和 `POST` 方法。這兩種方法會與 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 端點整合。您將設定兩種請求驗證：
+ 在 `GET` 方法中，您將設定 URL 查詢字串參數的請求驗證。
+ 在 `POST` 方法中，您將設定請求內文的請求驗證。
這將只允許某些 API 呼叫傳遞至 API。
下載並解壓縮 [的應用程式建立範本 CloudFormation](samples/request-validation-tutorial-console.zip)。您將使用此範本建立不完整的 API。您將完成 API Gateway 主控台中的其餘步驟。
**建立 CloudFormation 堆疊**
1. 在 https：//[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) 開啟 CloudFormation 主控台。
1. 選擇 **Create stack (建立堆疊)**，然後選擇 **With new resources (standard) (使用新資源 (標準))**。
1. 對於 **Specify template (指定範本)**，選擇 **Upload a template file (上傳範本檔案)**。
1. 選取您下載的範本。
1. 選擇 **Next** (下一步)。
1. 針對 **Stack name (堆疊名稱)**，輸入 **request-validation-tutorial-console**，然後選擇 **Next (下一步)**。
1. 針對 **Configure stack options (設定堆疊選項)**，選擇 **Next (下一步)**。
1. 針對 **功能**，確認 CloudFormation 可以在您的帳戶中建立 IAM 資源。
1. 選擇**下一步**，然後選擇**提交**。
CloudFormation 會佈建範本中指定的資源。完成資源佈建可能需要幾分鐘的時間。當您的 CloudFormation 堆疊狀態為 **CREATE\$1COMPLETE** 時，您就可以繼續進行下一個步驟。
**選取新建立的 API**
1. 選取新建立的 **request-validation-tutorial-console** 堆疊。
1. 選擇**資源**。
1. 在**實體 ID** 下，選擇您的 API。此連結會將您導向至 API Gateway 主控台。
在修改 `GET` 和 `POST` 方法之前，您必須建立模型。
**建立裝置**
1. 需有模型才能在傳入請求的內文上使用請求驗證。若要建立模型，請在主導覽窗格中選擇**模型**。
1. 選擇**建立模型**。
1. 對於**名稱**，輸入 **PetStoreModel**。
1. 針對**內容類型**，輸入 **application/json**。如果找不到相符的內容類型，則不會執行請求驗證。若要使用相同的模型，而不論內容類型為何，請輸入 **\$1default**。
1. 對於**描述**，輸入 **My PetStore Model** 作為模型描述。
1. 對於**模型結構描述**，將下列模型貼入程式碼編輯器中，然後選擇**建立**。
```
{
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
如需關於模型的詳細資訊，請參閱[REST API 的資料模型](models-mappings-models.md)。
**設定 `GET` 方法的請求驗證**
1. 在主導覽窗格中，選擇**資源**，然後選取 **GET** 方法。
1. 在**方法請求**索引標籤的**方法請求設定**下，選擇**編輯**。
1. 對於**請求驗證程式**，選取**驗證查詢字串參數與標頭**。
1. 在 **URL 查詢字串參數**下，執行下列動作：
1. 選擇**新增查詢字串**。
1. 對於**名稱**，輸入 **petType**。
1. 開啟**必要**。
1. 讓**快取**保持關閉。
1. 選擇**儲存**。
1. 在**整合請求**索引標籤上，於**整合請求設定**下，選擇**編輯**。
1. 在 **URL 查詢字串參數**下，執行下列動作：
1. 選擇**新增查詢字串**。
1. 對於**名稱**，輸入 **petType**。
1. 對於**映射自**，輸入 **method.request.querystring.petType**。這會將 **petType** 對應到寵物的類型。
如需資料對應的詳細資訊，請參閱[資料對應教學課程](set-up-data-transformations-in-api-gateway.md#mapping-example-console)。
1. 讓**快取**保持關閉。
1. 選擇**儲存**。
**測試 `GET` 方法的請求驗證**
1. 選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
1. 對於**查詢字串**，輸入 **petType=dog**，然後選擇**測試**。
1. 方法測試會傳回 `200 OK` 及狗的清單。
如需如何轉換此輸出資料的相關資訊，請參閱[資料對應教學課程](set-up-data-transformations-in-api-gateway.md#mapping-example-console)。
1. 移除 **petType=dog** 並選擇**測試**。
1. 方法測試會傳回 `400` 錯誤，並顯示下列錯誤訊息：
```
{
"message": "Missing required request parameters: [petType]"
}
```
**設定 `POST` 方法的請求驗證**
1. 在主導覽窗格中，選擇**資源**，然後選取 **POST** 方法。
1. 在**方法請求**索引標籤的**方法請求設定**下，選擇**編輯**。
1. 對於**請求驗證程式**，選取**驗證內文**。
1. 在**請求內文**下，選擇**新增模型**。
1. 針對**內容類型**，輸入 **application/json**。如果找不到相符的內容類型，則不會執行請求驗證。若要使用相同的模型，而不論內容類型為何，請輸入 `$default`。
對於**模型**，選取 **PetStoreModel**。
1. 選擇**儲存**。
**測試 `POST` 方法的請求驗證**
1. 選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
1. 對於**請求內文**，將下列內容貼入程式碼編輯器中：
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 400
}
```
選擇**測試**。
1. 方法測試會傳回 `200 OK` 和成功訊息。
1. 對於**請求內文**，將下列內容貼入程式碼編輯器中：
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 4000
}
```
選擇**測試**。
1. 方法測試會傳回 `400` 錯誤，並顯示下列錯誤訊息：
```
{
"message": "Invalid request body"
}
```
測試日誌底部會傳回請求內文無效的原因。在此案例中，寵物的價格超出了模型中指定的最高價格。
**刪除 CloudFormation 堆疊**
1. 在 https：//[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) 開啟 CloudFormation 主控台。
1. 選取您的 CloudFormation 堆疊。
1. 選擇**刪除**，然後確認您的選擇。
### 後續步驟
+ 如需如何轉換輸出資料並執行其他資料對應的相關資訊，請參閱[資料對應教學課程](set-up-data-transformations-in-api-gateway.md#mapping-example-console)。
+ 遵循[使用 AWS CLI設定基本請求驗證](#api-gateway-request-validation-setup-cli)教學課程，以使用 AWS CLI執行類似的步驟。
## 使用 設定基本請求驗證 AWS CLI
您可以使用 AWS CLI建立驗證程式來設定請求驗證。若要遵循本教學課程，您將使用 CloudFormation 範本來建立不完整的 API Gateway API。
**注意**
這與主控台教學課程的 CloudFormation 範本不同。
使用預先公開的 `/validator` 資源，您將建立 `GET` 和 `POST` 方法。這兩種方法會與 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 端點整合。您將設定下列兩個請求驗證：
+ 在 `GET` 方法上，您將建立 `params-only` 驗證程式來驗證 URL 查詢字串參數。
+ 在 `POST` 方法上，您將建立 `body-only` 驗證程式來驗證請求內文。
這將只允許某些 API 呼叫傳遞至 API。
**建立 CloudFormation 堆疊**
下載並解壓縮 [的應用程式建立範本 CloudFormation](samples/request-validation-tutorial-cli.zip)。
若要完成下列教學課程，您需要 [AWS Command Line Interface (AWS CLI) 第 2 版](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
對於長命令，逸出字元 (`\`) 用於將命令分割為多行。
**注意**
在 Windows 中，作業系統的內建終端機不支援您常用的某些 Bash CLI 命令 (例如 `zip`)。若要取得 Ubuntu 和 Bash 的 Windows 整合版本，請[安裝適用於 Linux 的 Windows 子系統](https://learn.microsoft.com/en-us/windows/wsl/install)。本指南中的 CLI 命令範例使用 Linux 格式。如果您使用的是 Windows CLI，必須重新格式化包含內嵌 JSON 文件的命令。
1. 使用下列命令來建立 CloudFormation 堆疊。
```
aws cloudformation create-stack --stack-name request-validation-tutorial-cli --template-body file://request-validation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation 會佈建範本中指定的資源。完成資源佈建可能需要幾分鐘的時間。使用下列命令來查看 CloudFormation 堆疊的狀態。
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli
```
1. 當您的 CloudFormation 堆疊狀態為 時`StackStatus: "CREATE_COMPLETE"`，請使用下列命令來擷取未來步驟的相關輸出值。
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
輸出值如下：
+ ApiId，這是 API 的 ID。對於本教學課程，API ID 為 `abc123`。
+ ResourceId，這是 `GET` 和 `POST` 方法公開所在驗證程式資源的 ID。對於本教學課程，資源 ID 為 `efg456`
**建立請求驗證程式並匯入模型**
1. 需有驗證程式才能搭配 AWS CLI使用請求驗證。使用下列命令建立僅驗證請求參數的驗證程式。
```
aws apigateway create-request-validator --rest-api-id abc123 \
--no-validate-request-body \
--validate-request-parameters \
--name params-only
```
請記下 `params-only` 驗證程式的 ID。
1. 使用下列命令建立僅驗證請求內文的驗證程式。
```
aws apigateway create-request-validator --rest-api-id abc123 \
--validate-request-body \
--no-validate-request-parameters \
--name body-only
```
請記下 `body-only` 驗證程式的 ID。
1. 需有模型才能在傳入請求的內文上使用請求驗證。使用下列命令匯入模型。
```
aws apigateway create-model --rest-api-id abc123 --name PetStoreModel --description 'My PetStore Model' --content-type 'application/json' --schema '{"type": "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : {"type" : "integer"},"type" : {"type" : "string", "enum" : [ "dog", "cat", "fish" ]},"name" : { "type" : "string"},"price" : {"type" : "number","minimum" : 25.0, "maximum" : 500.0}}}}'
```
如果找不到相符的內容類型，則不會執行請求驗證。若要使用相同的模型，而不論內容類型為何，請指定 `$default` 為索引鍵。
**建立 `GET` 和 `POST` 方法**
1. 使用下列命令，在 `/validate` 資源上新增 `GET` HTTP 方法。此命令會建立 `GET` 方法、新增 `params-only` 驗證程式，並視需要設定查詢字串 `petType`。
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--authorization-type "NONE" \
--request-validator-id aaa111 \
--request-parameters "method.request.querystring.petType=true"
```
使用下列命令，在 `/validate` 資源上新增 `POST` HTTP 方法。此命令會建立 `POST` 方法、新增 `body-only` 驗證程式，並將模型附加至僅內文驗證程式。
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
--request-validator-id bbb222 \
--request-models 'application/json'=PetStoreModel
```
1. 使用下列命令設定 `GET /validate` 方法的 `200 OK` 回應。
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200
```
使用下列命令設定 `POST /validate` 方法的 `200 OK` 回應。
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. 使用下列命令，為 `GET /validation` 方法設定具有所指定 HTTP 端點的 `Integration`。
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--type HTTP \
--integration-http-method GET \
--request-parameters '{"integration.request.querystring.type" : "method.request.querystring.petType"}' \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
使用下列命令，為 `POST /validation` 方法設定具有所指定 HTTP 端點的 `Integration`。
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type HTTP \
--integration-http-method GET \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
1. 使用下列命令設定 `GET /validation` 方法的整合回應。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456\
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
使用下列命令設定 `POST /validation` 方法的整合回應。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern ""
```
**若要測試 API**
1. 若要測試將為查詢字串執行請求驗證的 `GET` 方法，請使用下列命令：
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--path-with-query-string '/validate?petType=dog'
```
結果將傳回 `200 OK` 和狗清單。
1. 在不包括查詢字串 `petType` 的情況下，使用下列命令進行測試，
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
結果將傳回 `400` 錯誤。
1. 若要測試將為請求內文執行請求驗證的 `POST` 方法，請使用下列命令：
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }'
```
結果將傳回 `200 OK` 和成功訊息。
1. 使用下列命令，以利用無效內文進行測試。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 1000 }'
```
結果將傳回 `400` 錯誤，因為狗的價格超過了模型定義的最高價格。
**刪除 CloudFormation 堆疊**
+ 使用下列命令來刪除您的 CloudFormation 資源。
```
aws cloudformation delete-stack --stack-name request-validation-tutorial-cli
```
## 使用 OpenAPI 定義來設定基本請求驗證
您可以在 API 層級宣告請求驗證程式，方法是在 [x-amazon-apigateway-request-validators 物件](api-gateway-swagger-extensions-request-validators.md) 對應中指定一組 [x-amazon-apigateway-request-validators.requestValidator 物件](api-gateway-swagger-extensions-request-validators.requestValidator.md) 物件，以選取要驗證請求的哪一部分。在範例 OpenAPI 定義中，有兩個驗證程式：
+ `all` 驗證程式，其會同時驗證內文 (使用 `RequestBodyModel` 資料模型) 和參數。
此 `RequestBodyModel` 資料模型要求輸入 JSON 物件包含 `name`、`type` 和 `price` 屬性。`name` 屬性可以是任意字串、`type` 必須是其中一個指定的列舉欄位 (`["dog", "cat", "fish"]`)，而 `price` 的範圍必須是 25 到 500。`id` 不是必要參數。
+ `param-only`，其僅會驗證參數。
若要在 API 的所有方法上開啟請求驗證程式，請在 OpenAPI 定義的 API 層級指定 [x-amazon-apigateway-request-validator 屬性](api-gateway-swagger-extensions-request-validator.md) 屬性。在範例 OpenAPI 定義中，除非特別覆寫，否則會在所有 API 方法上使用 `all` 驗證程式。使用模型驗證主體時，如果找不到相符的內容類型，則不會執行請求驗證。若要使用相同的模型，而不論內容類型為何，請指定 `$default` 為索引鍵。
若要在個別方法上開啟請求驗證程式，請在方法層級指定 `x-amazon-apigateway-request-validator` 屬性。在範例 (OpenAPI 定義) 中，`param-only` 驗證程式會覆寫 `GET` 方法上的 `all` 驗證程式。
若要將 OpenAPI 範例匯入至 API Gateway，請參閱下列指示，[將區域 API 匯入至 API Gateway](import-export-api-endpoints.md) 或 [將邊緣最佳化 API 匯入至 API Gateway](import-edge-optimized-api.md)。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ReqValidators Sample",
"version" : "1.0.0"
},
"servers" : [ {
"url" : "/{basePath}",
"variables" : {
"basePath" : {
"default" : "/v1"
}
}
} ],
"paths" : {
"/validation" : {
"get" : {
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RequestBodyModel"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"RequestBodyModel" : {
"required" : [ "name", "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"maximum" : 500.0,
"minimum" : 25.0,
"type" : "number"
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Error"
}
},
"Error" : {
"type" : "object"
}
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"version" : "1.0.0",
"title" : "ReqValidators Sample"
},
"basePath" : "/v1",
"schemes" : [ "https" ],
"paths" : {
"/validation" : {
"get" : {
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"consumes" : [ "application/json" ],
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"type" : "string"
}, {
"in" : "body",
"name" : "RequestBodyModel",
"required" : true,
"schema" : {
"$ref" : "#/definitions/RequestBodyModel"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"definitions" : {
"RequestBodyModel" : {
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Error"
}
},
"Error" : {
"type" : "object"
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
# AWS CloudFormation 具有基本請求驗證的範例 API 範本
下列 CloudFormation 範例範本定義會定義已啟用請求驗證的範例 API。API 是 [PetStore API](http://petstore-demo-endpoint.execute-api.com/petstore/pets) 的子集。它會公開 `POST` 方法以將寵物新增至 `pets` 集合，並公開 `GET` 方法以依指定的類型來查詢寵物。
這裡會宣告兩種請求驗證程式：
**`GETValidator`**
此驗證程式會在 `GET` 方法上啟用。它可讓 API Gateway 驗證傳入請求中已包含不是空白的必要查詢參數 (`q1`)。
**`POSTValidator`**
此驗證程式會在 `POST` 方法上啟用。它可讓 API Gateway 驗證，當內容類型為 `application/json` 時，承載請求格式是否遵循指定的 `RequestBodyModel`，如果找不到相符的內容類型，則不會執行請求驗證。若無論內容類型為何都要使用相同的模型，可指定 `$default`。`RequestBodyModel` 包含一個額外的模型 `RequestBodyModelId`，用於定義寵物 ID。
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: ReqValidatorsSample
RequestBodyModelId:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModelId
properties:
id:
type: integer
RequestBodyModel:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet type, name, price, and ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModel
required:
- price
- name
- type
type: object
properties:
id:
"$ref": !Sub
- 'https://apigateway.amazonaws.com/restapis/${Api}/models/${RequestBodyModelId}'
- Api: !Ref Api
RequestBodyModelId: !Ref RequestBodyModelId
price:
type: number
minimum: 25
maximum: 500
name:
type: string
type:
type: string
enum:
- "dog"
- "cat"
- "fish"
GETValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: params-only
RestApiId: !Ref Api
ValidateRequestBody: False
ValidateRequestParameters: True
POSTValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: body-only
RestApiId: !Ref Api
ValidateRequestBody: True
ValidateRequestParameters: False
ValidationResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'validation'
ValidationMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: GET
AuthorizationType: NONE
RequestValidatorId: !Ref GETValidator
RequestParameters:
method.request.querystring.q1: true
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ValidationMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: POST
AuthorizationType: NONE
RequestValidatorId: !Ref POSTValidator
RequestModels:
application/json : !Ref RequestBodyModel
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: POST
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- ValidationMethodGet
- RequestBodyModel
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}'
```
# API Gateway 中用於 REST API 的資料轉換
**注意**
本節說明可搭配非代理整合使用的功能。不過，我們建議您盡可能針對 REST API 使用代理整合。代理整合採用簡化的整合設定，並且可隨著後端演進，而不必縮減現有的設定。如需詳細資訊，請參閱[選擇 API Gateway API 整合類型](api-gateway-api-integration-types.md)。
如果您使用非代理整合，您可以使用 API Gateway 的兩項功能來轉換方法請求和整合回應。如果方法請求採用與整合請求承載不同的承載格式，則您可以轉換方法請求。如果整合回應傳回的承載格式與方法回應中需要傳回的格式不同，則您可以轉換整合回應。如需有關請求生命週期的詳細資訊，請參閱 [REST API 的範例資源](rest-api-develop.md#rest-api-develop-example)。
下列範例說明資料轉換，其中標頭 `"x-version:beta"` 的 `x-version` 標頭參數會轉換成 `app-version` 標頭參數。整合請求中會進行 `x-version` 到 `app-version` 的資料轉換。如此一來，整合端點就會收到轉換後的標頭參數值。當整合端點傳回狀態碼時，狀態碼會在方法回應之前，從 `200` 轉換為 `204`。
![\[API Gateway 資料轉換圖\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/develop-non-proxy.png)
若要建立資料轉換，您可以使用下列功能：
**參數映射**
在參數映射中，您可以修改整合請求 URL 路徑參數、URL 查詢字串參數或 HTTP 標頭值，但無法修改整合請求承載。您也可以修改 HTTP 回應標頭值。使用參數映射建立跨來源資源分享 (CORS) 的靜態標頭值。
您可以在代理和非代理整合的整合請求中使用參數映射，但若要將參數映射用於整合回應，則需要非代理整合。參數映射不需要使用 [ Velocity 範本語言 (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 編寫任何指令碼。如需詳細資訊，請參閱[API Gateway 中 REST API 的參數映射](rest-api-parameter-mapping.md)。
**映射範本轉換**
在映射範本轉換中，您可以使用映射範本來對應 URL 路徑參數、URL 查詢字串參數、HTTP 標頭，以及整合請求或整合回應內文。*映射範本*是以 [Velocity 範本語言 (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 表達的指令碼，會使用 [JSONPath 表達式](https://goessner.net/articles/JsonPath/)並根據 `Content-type` 標頭套用至承載。
您可以使用映射範本執行下列操作：
+ 選取要使用整合傳送的資料 AWS 服務，例如 Amazon DynamoDB 或 Lambda 函數或 HTTP 端點。如需詳細資訊，請參閱[教學課程：修改 AWS 服務整合的整合請求和回應](set-up-data-transformations-in-api-gateway.md)。
+ 有條件地覆寫 API 的整合請求和整合回應參數、建立新的標頭值，以及覆寫狀態碼。如需詳細資訊，請參閱[覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。
若整合請求內文的 `Content-type` 標頭沒有相符的映射範本，您也可以指定 API 的行為。這稱為整合傳遞行為。如需詳細資訊，請參閱[API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為](integration-passthrough-behaviors.md)。
## 選擇參數映射或映射範本轉換
我們建議您盡可能使用參數映射來轉換資料。如果您的 API 要求您變更內文，或要求您根據傳入的整合請求或整合回應執行條件式覆寫和修改，而且您無法使用代理整合，則使用映射範本轉換。
# API Gateway 中 REST API 的參數映射
**注意**
如果您使用的是 HTTP API，請參閱 [在 API Gateway 中轉換 HTTP API 的 API 請求和回應](http-api-parameter-mapping.md)。
在參數映射中，您可以對應請求或回應參數。您可以使用參數映射表達式或靜態值來對應參數。如需映射表達式的清單，請參閱 [API Gateway 中 REST API 的參數映射來源參考](rest-api-parameter-mapping-sources.md)。您可以在代理和非代理整合的整合請求中使用參數映射，但若要將參數映射用於整合回應，則需要非代理整合。
例如，您可以將方法請求標頭參數 `puppies` 對應到整合請求標頭參數 `DogsAge0`。之後如果用戶端將標頭 `puppies:true` 傳送至您的 API，則整合請求會將請求標頭 `DogsAge0:true` 傳送至整合端點。下圖顯示此範例的請求生命週期。
![\[請求的 API Gateway 參數映射範例圖\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
若要使用 API Gateway 建立此範例，請參閱 [範例 1：將方法請求參數對應至整合請求參數](request-response-data-mappings.md#request-response-data-mappings-example-1)。
另一個範例是，您也可以將整合回應標頭參數 `kittens` 對應至方法回應標頭參數 `CatsAge0`。之後如果整合端點傳回 `kittens:false`，則用戶端會收到標頭 `CatsAge0:false`。下圖顯示此範例的請求生命週期。
![\[回應的 API Gateway 參數映射範例圖\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [API Gateway 中 REST API 的參數映射範例](request-response-data-mappings.md)
+ [API Gateway 中 REST API 的參數映射來源參考](rest-api-parameter-mapping-sources.md)
# API Gateway 中 REST API 的參數映射範例
下列範例示範如何使用 API Gateway 主控台、OpenAPI 和 CloudFormation 範本建立參數映射表達式。如需如何使用參數映射來建立所需 CORS 標頭的範例，請參閱 [API Gateway 中 REST API 的 CORS](how-to-cors.md)。
## 範例 1：將方法請求參數對應至整合請求參數
下列範例會將方法請求標頭參數 `puppies` 對應至整合請求標頭參數 `DogsAge0`。
------
#### [ AWS 管理主控台 ]
**對應方法請求參數**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 REST API。
1. 選擇一個方法。
您的方法必須有非代理整合。
1. 針對**方法請求設定**，選擇**編輯**。
1. 選擇 **HTTP 請求標頭**。
1. 選擇**新增標頭**。
1. 對於**名稱**，輸入 **puppies**。
1. 選擇**儲存**。
1. 選擇**整合請求**索引標籤，然後針對**整合請求設定**，選擇**編輯**。
AWS 管理主控台 會自動`puppies`為您從 新增參數映射`method.request.header.puppies `至 ，但您需要變更**名稱**以符合整合端點預期的請求標頭參數。
1. 對於**名稱**，輸入 **DogsAge0**。
1. 選擇**儲存**。
1. 重新部署 API 以使變更生效。
下列步驟說明如何驗證參數映射是否成功。
**(選用) 測試參數映射**
1. 選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
1. 針對標頭，輸入 **puppies:true**。
1. 選擇**測試**。
1. 在**日誌**中，結果應如下所示：
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
請求標頭參數已從 `puppies` 變更為 `DogsAge0`。
------
#### [ CloudFormation ]
在此範例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 屬性將 OpenAPI 定義檔案匯入 API Gateway 中。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## 範例 2：將多個方法請求參數對應至不同的整合請求參數
下列範例會將多值方法請求查詢字串參數 `methodRequestQueryParam` 對應至整合請求查詢字串參數 `integrationQueryParam`，並將方法請求標頭參數 `methodRequestHeaderParam` 對應至整合請求路徑參數 `integrationPathParam`。
------
#### [ AWS 管理主控台 ]
**對應方法請求參數**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 REST API。
1. 選擇一個方法。
您的方法必須有非代理整合。
1. 針對**方法請求設定**，選擇**編輯**。
1. 選擇 **URL 查詢字串參數**。
1. 選擇**新增查詢字串**。
1. 對於**名稱**，輸入 **methodRequestQueryParam**。
1. 選擇 **HTTP 請求標頭**。
1. 選擇**新增標頭**。
1. 對於**名稱**，輸入 **methodRequestHeaderParam**。
1. 選擇**儲存**。
1. 選擇**整合請求**索引標籤，然後針對**整合請求設定**，選擇**編輯**。
1. 選擇 **URL 路徑參數**。
1. 選擇**新增路徑參數**。
1. 對於**名稱**，輸入 **integrationPathParam**。
1. 對於**映射自**，輸入 **method.request.header.methodRequestHeaderParam**。
這樣做會將您在方法請求中指定的方法請求標頭，對應至新的整合請求路徑參數。
1. 選擇 **URL 查詢字串參數**。
1. 選擇**新增查詢字串**。
1. 對於**名稱**，輸入 **integrationQueryParam**。
1. 對於**映射自**，輸入 **method.request.multivaluequerystring.methodRequestQueryParam**。
這樣做會將多值查詢字串參數對應至新的單一值整合請求查詢字串參數。
1. 選擇**儲存**。
1. 重新部署 API 以使變更生效。
------
#### [ CloudFormation ]
在此範例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 屬性將 OpenAPI 定義檔案匯入 API Gateway 中。
以下 OpenAPI 定義會針對 HTTP 整合建立下列參數映射：
+ 將名為 `methodRequestHeaderParam` 的方法請求標頭對應到名為 `integrationPathParam` 的整合請求路徑參數
+ 將名為 `methodRequestQueryParam` 的多值方法請求查詢字串對應到名為 `integrationQueryParam` 的整合請求查詢字串
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定義會針對 HTTP 整合建立下列參數映射：
+ 將名為 `methodRequestHeaderParam` 的方法請求標頭對應到名為 `integrationPathParam` 的整合請求路徑參數
+ 將名為 `methodRequestQueryParam` 的多值方法請求查詢字串對應到名為 `integrationQueryParam` 的整合請求查詢字串
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 範例 3：將欄位從 JSON 請求內文對應至整合請求參數
您也可以使用 [JSONPath 表達式](http://goessner.net/articles/JsonPath/index.html#e2)，從 JSON 請求內文中的欄位對應整合請求參數。下列範例會將方法請求內文對應至名為 `body-header` 的整合請求標頭，並將部分請求內文 (如 JSON 表達式所示) 對應至名為 `pet-price` 的整合請求標頭。
若要測試此範例，請提供包含價格類別的輸入，如下所示：
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ AWS 管理主控台 ]
**對應方法請求參數**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 REST API。
1. 選擇 `POST`、`PUT`、`PATCH` 或 `ANY` 方法。
您的方法必須有非代理整合。
1. 針對**整合請求設定**，選擇**編輯**。
1. 選擇 **URL 請求標頭參數**。
1. 選擇**新增請求標頭參數**。
1. 對於**名稱**，輸入 **body-header**。
1. 對於**映射自**，輸入 **method.request.body**。
這樣做會將方法請求內文對應至新的整合請求標頭參數。
1. 選擇**新增請求標頭參數**。
1. 對於**名稱**，輸入 **pet-price**。
1. 對於**映射自**，輸入 ** method.request.body[0].price**。
這樣做會將部分方法請求內文對應至新的整合請求標頭參數。
1. 選擇**儲存**。
1. 重新部署 API 以使變更生效。
------
#### [ CloudFormation ]
在此範例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 屬性將 OpenAPI 定義檔案匯入 API Gateway 中。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定義會從 JSON 請求內文中的欄位對應整合請求參數。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 範例 4：將整合回應對應至方法回應
您也可以將整合回應對應至方法回應。下列範例會將整合回應內文對應至名為 `location` 的方法回應標頭、將整合回應標頭 `x-app-id` 對應至方法回應標頭 `id`，並將多值整合回應標頭 `item` 對應至方法回應標頭 `items`。
------
#### [ AWS 管理主控台 ]
**對應整合回應**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 REST API。
1. 選擇一個方法。
您的方法必須有非代理整合。
1. 選擇**方法回應**索引標籤，然後針對**回應 200** 選擇**編輯**。
1. 針對**標頭名稱**，選擇**新增標頭**。
1. 建立三個分別名為 **id**、**item** 和 **location** 的標頭。
1. 選擇**儲存**。
1. 選擇**整合回應**索引標籤，然後針對**預設 - 回應**選擇**編輯**。
1. 在**標頭映射**下，輸入以下內容。
1. 針對 **id**，輸入 **integration.response.header.x-app-id**
1. 針對 **item**，輸入 **integration.response.multivalueheader.item**
1. 針對 **location**，輸入 **integration.response.body.redirect.url**
1. 選擇**儲存**。
1. 重新部署 API 以使變更生效。
------
#### [ CloudFormation ]
在此範例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 屬性將 OpenAPI 定義檔案匯入 API Gateway 中。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定義會將整合回應對應至方法回應。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# API Gateway 中 REST API 的參數映射來源參考
當您建立參數映射時，請指定要修改的方法請求或整合回應參數，並指定如何修改這些參數。
下表顯示您可以對應的方法請求參數，以及建立映射的表達式。在這些表達式中，*name* 是方法請求參數的名稱。例如，若要對應請求標頭參數 `puppies`，則使用表達式 `method.request.header.puppies`。您的表達式必須符合規則表達式 `'^[a-zA-Z0-9._$-]+$]'`。您可以在代理和非代理整合的整合請求中使用參數映射。
| **映射的資料來源** | **映射表達式** |
| --- | --- |
| 方法請求路徑 | method.request.path.name |
| 方法請求查詢字串 | method.request.querystring.name |
| 多值方法請求查詢字串 | method.request.multivaluequerystring.name |
| 方法請求標頭 | method.request.header.name |
| 多值方法請求標頭 | method.request.multivalueheader.name |
| 方法請求內文 | method.request.body |
| 方法請求內文 (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION* 是請求的內文中，JSON 欄位的 JSONPath 表達式。如需詳細資訊，請參閱 [JSONPath 表達式](http://goessner.net/articles/JsonPath/index.html#e2)。 |
| 階段變數 | stageVariables.name |
| 環境變數 | `context.name` name 必須是[支援的環境變數](api-gateway-mapping-template-reference.md#context-variable-reference)之一。 |
| 靜態值 | `'static_value'`. *static\$1value* 是字串常值，而且前後必須加上單引號。例如 `'https://www.example.com'`。 |
下表顯示您可以對應的整合回應參數，以及建立映射的表達式。在這些表達式中，*name* 是整合回應參數的名稱。您可以從任何整合回應標頭或整合回應內文、\$1context 變數或靜態值，對應方法回應標頭。若要針對整合回應使用參數映射，則您需要非代理整合。
| 映射的資料來源 | 對應表達式 |
| --- | --- |
| 整合回應標頭 | integration.response.header.name |
| 整合回應標頭 | integration.response.multivalueheader.name |
| 整合回應內文 | integration.response.body |
| 整合回應內文 (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION* 是回應的內文中，JSON 欄位的 JSONPath 表達式。如需詳細資訊，請參閱 [JSONPath 表達式](http://goessner.net/articles/JsonPath/index.html#e2)。 |
| 階段變數 | stageVariables.name |
| 環境變數 | `context.name` name 必須是[支援的環境變數](api-gateway-mapping-template-reference.md#context-variable-reference)之一。 |
| 靜態值 | ` 'static_value'` *static\$1value* 是字串常值，而且前後必須加上單引號。例如 `'https://www.example.com'`。 |
# API Gateway 中 REST API 的映射範本轉換
映射範本轉換會使用映射範本來修改您的整合請求或整合回應。*映射範本*是以 [Velocity 範本語言 (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 表達的指令碼，會使用 [JSONPath](https://goessner.net/articles/JsonPath/) 並根據 `Content-type` 標頭套用至承載。您會使用映射範本來進行映射範本轉換。本節說明與映射範本相關的概念性資訊。
下圖顯示與 PetStore 整合端點整合之 `POST /pets` 資源的請求生命週期。在此 API 中，使用者會傳送有關寵物的資料，而整合端點會傳回與寵物相關聯的認養費。在此請求生命週期中，映射範本轉換會篩選傳送至整合端點的請求內文，以及篩選來自整合端點的回應內文。
![\[請求生命週期範例\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/mapping-template-transforms.png)
以下各節說明請求和回應生命週期。
## 方法請求和整合請求
在上述範例中，如果這是傳送至方法請求的請求內文：
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
此請求內文的格式不正確，無法供整合端點使用，因此 API Gateway 會執行映射範本轉換。API Gateway 只會執行映射範本轉換，因為有針對 Content-Type `application/json` 定義的映射範本。如果您未針對 Content-Type 定義映射範本，則根據預設，API Gateway 會透過整合請求將內文傳遞至整合端點。若要修改此行為，請參閱 [API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為](integration-passthrough-behaviors.md)。
下列映射範本會先轉換整合請求中的方法請求資料，再將其傳送至整合端點：
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. `$inputRoot` 變數代表上一節中原始 JSON 資料的根物件。指令以 `#` 符號開始。
1. `dog` 是使用者的 `id` 和字串值的串連。
1. `Age` 來自方法請求內文。
然後，下列輸出會轉送至整合端點：
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## 整合回應和方法回應
成功對整合端點發出請求後，端點會將回應傳送至 API Gateway 的整合回應。以下是來自整合端點的輸出資料範例：
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
方法回應預期的承載與整合回應傳回的承載不同。API Gateway 會執行映射範本轉換。API Gateway 只會執行映射範本轉換，因為有針對 Content-Type `application/json` 定義的映射範本。如果您未針對 Content-Type 定義映射範本，則根據預設，API Gateway 會透過整合回應將內文傳遞至方法回應。若要修改此行為，請參閱 [API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為](integration-passthrough-behaviors.md)。
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
下列輸出會傳送至方法回應：
```
{"adoptionFee": 19.95}
```
映射範本轉換範例至此完成。我們建議您盡可能使用代理整合來轉換資料，而不要使用映射範本轉換。如需詳細資訊，請參閱[選擇 API Gateway API 整合類型](api-gateway-api-integration-types.md)。
# API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為
如果您的方法請求具有承載，而您未針對 `Content-Type` 標頭定義映射範本，則您可以選擇透過整合請求將用戶端提供的請求承載傳遞至後端，而不進行轉換。這個過程稱為整合傳遞。
傳入請求的實際傳遞行為是由此設定決定。共有三個選項：
**當沒有範本符合請求 Content-Type 標頭時**
當方法請求內容類型不符合與對應範本相關聯的任何內容類型時，如果您想要讓方法請求內文透過整合請求傳遞到後端而不進行轉換，請選擇此選項。
呼叫 API Gateway API 時，您可以透過在[整合](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)上將 `WHEN_NO_MATCH` 設定為 `passthroughBehavior` 屬性值來選擇此選項。
**未定義範本時 (建議)**
當整合請求中未定義任何對應範本時，如果您想要讓方法請求內文透過整合請求傳遞到後端而不進行轉換，請選擇此選項。如果選取此選項時已定義範本，則具有承載但內容類型不符合任何已定義映射範本的方法請求將會遭拒，並顯示 HTTP 415 Unsupported Media Type (不支援的媒體類型) 回應。
呼叫 API Gateway API 時，您可以透過在[整合](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)上將 `WHEN_NO_TEMPLATES` 設定為 `passthroughBehavior` 屬性值來選擇此選項。
**從不**
當整合請求中未定義任何對應範本時，如果您不想要讓方法請求內文透過整合請求傳遞到後端而不進行轉換，請選擇此選項。如果選取此選項時已定義範本，未映射內容類型的方法請求會遭到拒絕，並顯示 HTTP 415 Unsupported Media Type (不支援的媒體類型) 回應。
呼叫 API Gateway API 時，您可以透過在[整合](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)上將 `NEVER` 設定為 `passthroughBehavior` 屬性值來選擇此選項。
下列範例說明可能的傳遞行為。
範例 1：針對 `application/json` 內容類型在整合請求中定義的一個對應範本。
| Content-type | 傳遞選項 | Behavior (行為) |
| --- | --- | --- |
| 無 API Gateway 預設為 `application/json` | WHEN\$1NO\$1MATCH | 使用此範本轉換請求承載。 |
| 無 API Gateway 預設為 `application/json` | WHEN\$1NO\$1TEMPLATES | 使用此範本轉換請求承載。 |
| 無 API Gateway 預設為 `application/json` | NEVER | 使用此範本轉換請求承載。 |
| application/json | WHEN\$1NO\$1MATCH | 使用此範本轉換請求承載。 |
| application/json | WHEN\$1NO\$1TEMPLATES | 使用此範本轉換請求承載。 |
| application/json | NEVER | 使用此範本轉換請求承載。 |
| application/xml | WHEN\$1NO\$1MATCH | 請求承載未轉換，而且會依現狀傳送到後端。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | 請求遭到拒絕，回應為 HTTP 415 Unsupported Media Type。 |
| application/xml | NEVER | 請求遭到拒絕，回應為 HTTP 415 Unsupported Media Type。 |
範例 2：針對 `application/xml` 內容類型在整合請求中定義的一個對應範本。
| Content-type | 傳遞選項 | Behavior (行為) |
| --- | --- | --- |
| 無 API Gateway 預設為 `application/json` | WHEN\$1NO\$1MATCH | 請求承載未轉換，而且會依現狀傳送到後端。 |
| 無 API Gateway 預設為 `application/json` | WHEN\$1NO\$1TEMPLATES | 請求遭到拒絕，回應為 HTTP 415 Unsupported Media Type。 |
| 無 API Gateway 預設為 `application/json` | NEVER | 請求遭到拒絕，回應為 HTTP 415 Unsupported Media Type。 |
| application/json | WHEN\$1NO\$1MATCH | 請求承載未轉換，而且會依現狀傳送到後端。 |
| application/json | WHEN\$1NO\$1TEMPLATES | 請求遭到拒絕，回應為 HTTP 415 Unsupported Media Type。 |
| application/json | NEVER | 請求遭到拒絕，回應為 HTTP 415 Unsupported Media Type。 |
| application/xml | WHEN\$1NO\$1MATCH | 使用此範本轉換請求承載。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | 使用此範本轉換請求承載。 |
| application/xml | NEVER | 使用此範本轉換請求承載。 |
範例 3：整合請求中未定義任何映射範本。
| Content-type | 傳遞選項 | Behavior (行為) |
| --- | --- | --- |
| 無 API Gateway 預設為 `application/json` | WHEN\$1NO\$1MATCH | 請求承載未轉換，而且會依現狀傳送到後端。 |
| 無 API Gateway 預設為 `application/json` | WHEN\$1NO\$1TEMPLATES | 請求承載未轉換，而且會依現狀傳送到後端。 |
| 無 API Gateway 預設為 `application/json` | NEVER | 請求遭到拒絕，回應為 HTTP 415 Unsupported Media Type。 |
| application/json | WHEN\$1NO\$1MATCH | 請求承載未轉換，而且會依現狀傳送到後端。 |
| application/json | WHEN\$1NO\$1TEMPLATES | 請求承載未轉換，而且會依現狀傳送到後端。 |
| application/json | NEVER | 請求遭到拒絕，回應為 HTTP 415 Unsupported Media Type。 |
| application/xml | WHEN\$1NO\$1MATCH | 請求承載未轉換，而且會依現狀傳送到後端。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | 請求承載未轉換，而且會依現狀傳送到後端。 |
| application/xml | NEVER | 請求遭到拒絕，回應為 HTTP 415 Unsupported Media Type。 |
# API Gateway 中 REST API 的其他映射範本範例
下列範例顯示 API Gateway 中的相簿 API，其使用映射範本來轉換整合請求和整合回應資料。此 API 也會使用資料模型來定義方法請求和整合回應承載。如需更多有關資料模型的詳細資訊，請參閱 [REST API 的資料模型](models-mappings-models.md)。
## 方法請求和整合請求
以下是定義方法請求內文的模型。此輸入模型會要求發起人上傳一張相片，並要求每頁至少 10 張相片。您可以使用此輸入模型來產生 SDK，或針對您的 API 使用請求驗證。使用請求驗證時，如果方法請求內文未遵循模型的資料結構，則 API Gateway 會讓請求失敗。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
以下是遵循上述資料模型之資料結構的方法請求內文範例。
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
在此範例中，如果用戶端提交了上述方法請求內文，則此映射範本會轉換承載，使其符合整合端點要求的格式。
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
下列範例是轉換的輸出資料：
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
此資料會傳送到整合請求，然後再傳送到整合端點。
## 整合回應和方法回應
以下是整合端點中相片資料的範例輸出模型。您可以使用此模型作為方法回應模型，當您為 API 產生強型別 SDK 時，需要這樣做。這會導致輸出在 Java 或 Objective-C 中轉換成適當的類別。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
整合端點的回應可能無法使用遵循此模型的資料結構。例如，整合回應可能如下所示：
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
下列範例映射範本會將整合回應資料轉換為方法回應預期的格式：
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
下列範例是轉換的輸出資料：
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
此資料會傳送到方法回應，然後再傳回用戶端。
# 覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼
您可以使用映射範本轉換來覆寫任何類型的請求參數、回應標頭或回應狀態碼。使用映射範本執行下列操作：
+ 執行多對一參數映射
+ 在套用標準 API Gateway 映射之後覆寫參數
+ 根據內文內容或其他參數值，有條件地映射參數
+ 以程式設計方式建立新參數
+ 覆寫由您的整合端點所傳回的狀態碼
覆寫是最終。覆寫只能套用到每個參數一次。如果您嘗試覆寫相同的參數多次，API Gateway 會傳回 `5XX` 回應。如果您必須多次在整個範本中覆寫相同的參數，我們建議您建立變數與在範本結尾套用覆寫。只會在整個範本剖析後才套用範本。
## 範例 1：根據整合內文覆寫狀態碼
下列範例使用[範例 API](api-gateway-create-api-from-example.md)，根據整合回應內文覆寫狀態碼。
------
#### [ AWS 管理主控台 ]
**根據整合回應內文覆寫狀態碼**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 **Create API (建立 API)**。
1. 針對 **REST API**，選擇**組建**。
1. 針對 **API 詳細資訊**，選擇**範例 API**。
1. 選擇**建立 API**。
API Gateway 會建立範例寵物商店 API。若要擷取有關寵物的資訊，您可以使用 API 方法請求 `GET /pets/{petId}`，其中 `{petId}` 是對應寵物 ID 號碼的路徑參數。
在此範例中，您會在偵測到錯誤條件時，將 `GET` 方法的回應程式碼覆寫為 `400`。
1. 在**資源**樹狀結構中的 `/{petId}` 下，選擇 `GET` 方法。
1. 首先，測試目前的 API 實作。
選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
1. 針對 **petId**，輸入 **-1**，然後選擇**測試**。
**回應內文**指出超出範圍錯誤：
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
此外，**日誌**下的最後一行結尾為：`Method completed with status: 200`。
整合已成功完成，但發生錯誤。現在您將根據整合回應覆寫狀態碼。
1. 在**整合回應**索引標籤上，針對**預設 - 回應**，選擇**編輯**。
1. 選擇**對應範本**。
1. 選擇**新增對應範本**。
1. 針對**內容類型**，輸入 **application/json**。
1. 針對**範本內文**，輸入下列內容：
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
如果整合回應包含字串 `error`，則此映射範本會使用 `$context.responseOverride.status` 變數將狀態碼覆寫為 `400`。
1. 選擇**儲存**。
1. 選擇**測試**標籤。
1. 針對 **petId**，輸入 **-1**。
1. 在結果中，**Response Body (回應內文)** 表示超出範圍錯誤：
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
然而，**日誌**下的最後一列結尾現在會是：`Method completed with status: 400`。
------
#### [ CloudFormation ]
在此範例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 屬性將 OpenAPI 定義檔案匯入 API Gateway 中。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定義會建立 `GET pets/{petId}` 資源，並根據整合內文覆寫狀態碼。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## 範例 2：覆寫請求標頭並建立新標頭
下列範例使用[範例 API](api-gateway-create-api-from-example.md) 覆寫請求標頭並建立新標頭。
------
#### [ AWS 管理主控台 ]
**透過建立新標頭來覆寫方法的請求標頭**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇您在上述教學課程中建立的範例 API。API 的名稱應為 **PetStore**。
1. 在**資源**樹狀結構中的 `/pet` 下，選擇 `GET` 方法。
1. 在**方法請求**索引標籤上，針對**方法請求設定**，選擇**編輯**。
1. 選擇 **HTTP 請求標頭**，然後選擇**新增標頭**。
1. 對於**名稱**，輸入 **header1**。
1. 選擇**新增標頭**，然後建立名為 **header2** 的第二個標頭。
1. 選擇**儲存**。
現在，請使用映射範本將這些標頭合併成一個標頭值。
1. 在**整合請求**索引標籤上，針對**整合請求設定**，選擇**編輯**。
1. 針對**請求內文傳遞**，選取**未定義範本時 (建議)**。
1. 選擇**對應範本**，然後執行下列動作：
1. 選擇**新增映射範本**。
1. 針對**內容類型**，輸入 **application/json**。
1. 針對**範本內文**，輸入下列內容：
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
此映射範本會將 `header1` 覆寫為字串 `pets`，並建立結合 `header1` 和 `header2` 且名為 `$header3Value` 的多值標頭。
1. 選擇**儲存**。
1. 選擇**測試**標籤。
1. 在**標頭**下，複製下列程式碼：
```
header1:header1Val
header2:header2Val
```
1. 選擇 **Test (測試)**。
在**日誌**中，您應該會看到包括此文字的項目：
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
在此範例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 屬性將 OpenAPI 定義檔案匯入 API Gateway 中。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定義會建立 `GET pets` 資源，以及覆寫請求標頭並建立新標頭。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
若要使用映射範本覆寫，請新增一或多個下列 `$context` 變數。如需 `$context` 變數清單，請參閱 [資料轉換的內容變數](api-gateway-mapping-template-reference.md#context-variable-reference)。
# 教學課程：修改 AWS 服務整合的整合請求和回應
下列教學課程說明如何使用映射範本轉換來設定映射範本，以使用主控台和 CLI AWS 轉換整合請求和回應。
**Topics**
+ [使用 API Gateway 主控台設定資料轉換](#mapping-example-console)
+ [使用 CLI AWS 設定資料轉換](#mapping-example-cli)
+ [已完成的資料轉換 CloudFormation 範本](#api-gateway-data-transformations-full-cfn-stack)
## 使用 API Gateway 主控台設定資料轉換
在本教學課程中，您將使用下列 .zip 檔案 [data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-console.zip)，建立不完整的 API 和 DynamoDB 資料表。此不完整的 API 具有 `/pets` 資源，其中含有 `GET` 和 `POST` 方法。
+ `GET` 方法將從 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 端點取得資料。輸出資料將根據 [API Gateway 中 REST API 的映射範本轉換](models-mappings.md) 中的對應範本進行轉換。
+ `POST` 方法可讓使用者使用對應範本，將寵物資訊 `POST` 至 Amazon DynamoDB 資料表。
下載並解壓縮 [的應用程式建立範本 CloudFormation](samples/data-transformation-tutorial-console.zip)。您將使用此範本建立 DynamoDB 資料表，以發布寵物資訊和不完整的 API。您將完成 API Gateway 主控台中的其餘步驟。
**建立 CloudFormation 堆疊**
1. 在 https：//[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) 開啟 CloudFormation 主控台。
1. 選擇 **Create stack (建立堆疊)**，然後選擇 **With new resources (standard) (使用新資源 (標準))**。
1. 對於 **Specify template (指定範本)**，選擇 **Upload a template file (上傳範本檔案)**。
1. 選取您下載的範本。
1. 選擇 **Next** (下一步)。
1. 針對 **Stack name (堆疊名稱)**，輸入 **data-transformation-tutorial-console**，然後選擇 **Next (下一步)**。
1. 針對 **Configure stack options (設定堆疊選項)**，選擇 **Next (下一步)**。
1. 針對 **功能**，確認 CloudFormation 可以在您的帳戶中建立 IAM 資源。
1. 選擇**下一步**，然後選擇**提交**。
CloudFormation 會佈建範本中指定的資源。完成資源佈建可能需要幾分鐘的時間。當您的 CloudFormation 堆疊狀態為 **CREATE\$1COMPLETE** 時，您就可以繼續進行下一個步驟。
**測試 `GET` 整合回應**
1. 在 CloudFormation 堆疊**的資源**索引標籤上**data-transformation-tutorial-console**，選取 API 的實體 ID。
1. 在主導覽窗格中，選擇**資源**，然後選取 **GET** 方法。
1. 選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
測試的輸出將顯示下列內容：
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
您將根據 [API Gateway 中 REST API 的映射範本轉換](models-mappings.md)中的對應範本轉換此輸出。
**轉換 `GET` 整合回應**
1. 選擇**整合回應**索引標籤。
目前，沒有已定義的對應範本，因此不會轉換整合回應。
1. 針對**預設 - 回應**，選擇**編輯**。
1. 選擇**對應範本**，然後執行下列動作：
1. 選擇**新增映射範本**。
1. 針對**內容類型**，輸入 **application/json**。
1. 針對**範本內文**，輸入下列內容：
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
選擇**儲存**。
**測試 `GET` 整合回應**
+ 選擇**測試**索引標籤，然後選擇**測試**。
測試的輸出將顯示轉換後的回應。
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**從 `POST` 方法轉換輸入資料**
1. 選擇 **POST** 方法。
1. 選擇**整合請求**索引標籤，然後針對**整合請求設定**，選擇**編輯**。
CloudFormation 範本已填入一些整合請求欄位。
+ 整合類型為 AWS 服務。
+ AWS 服務 是 DynamoDB。
+ HTTP 方法為 `POST`。
+ 動作為 `PutItem`。
+ 允許 API Gateway 將項目放入 DynamoDB 資料表的執行角色是 `data-transformation-tutorial-console-APIGatewayRole`. CloudFormation created this role，以允許 API Gateway 具有與 DynamoDB 互動的最低許可。
尚未指定 DynamoDB 資料表的名稱。您將在下列步驟中指定此名稱。
1. 針對**請求內文傳遞**，選取**永不**。
這意味著 API 將拒絕 Content-Type 沒有對應範本的資料。
1. 選擇**對應範本**。
1. **內容類型**會設定為 `application/json`。這表示不是 application/json 的內容類型將遭 API 拒絕。如需整合傳遞行為的詳細資訊，請參閱 [API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為](integration-passthrough-behaviors.md)。
1. 將下列程式碼輸入至文字編輯器。
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
此範本會將資料表指定為 `data-transformation-tutorial-console-ddb`，並將項目設為 `id`、`type` 和 `price`。這些項目將來自 `POST` 方法的內文。您也可以使用資料模型來協助建立對應範本。如需詳細資訊，請參閱[API Gateway 中的 REST API 的請求驗證](api-gateway-method-request-validation.md)。
1. 選擇**儲存**以儲存您的映射範本。
**從 `POST` 方法新增方法和整合回應**
CloudFormation 已建立空白方法和整合回應。您將編輯此回應，以提供詳細資訊。如需如何編輯回應的詳細資訊，請參閱 [API Gateway 中 REST API 的參數映射範例](request-response-data-mappings.md)。
1. 在**整合回應**索引標籤上，針對**預設 - 回應**選擇**編輯**。
1. 選擇**對應範本**，然後選擇**新增對應範本**。
1. 針對 **Content-Type**，輸入 **application/json**。
1. 在程式碼編輯器中，輸入下列輸出對應範本以傳送輸出訊息：
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
如需內容變數的詳細資訊，請參閱 [資料轉換的內容變數](api-gateway-mapping-template-reference.md#context-variable-reference)。
1. 選擇**儲存**以儲存您的對應範本。
**測試 `POST` 方法**
選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
1. 在請求內文中，輸入下列範例。
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. 選擇**測試**。
輸出應該會顯示您的成功訊息。
您可以在 [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) 開啟 DynamoDB 主控台，以驗證範例項目是否位於您的資料表中。
**刪除 CloudFormation 堆疊**
1. 在 https：//[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) 開啟 CloudFormation 主控台。
1. 選取您的 CloudFormation 堆疊。
1. 選擇**刪除**，然後確認您的選擇。
## 使用 CLI AWS 設定資料轉換
在本教學課程中，您將使用下列 .zip 檔案 [data-transformation-tutorial-cli.zip](samples/data-transformation-tutorial-cli.zip)，建立不完整的 API 和 DynamoDB 資料表。這個不完整的 API 具有 `/pets` 資源，其中含有與 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 端點整合的 `GET` 方法。您將建立 `POST` 方法，以連線至 DynamoDB 資料表，並使用對應範本將資料輸入至 DynamoDB 資料表。
+ 您將根據 [API Gateway 中 REST API 的映射範本轉換](models-mappings.md)中的對應範本轉換輸出資料。
+ 您將建立 `POST` 方法，允許使用者使用對應範本，將寵物資訊 `POST` 至 Amazon DynamoDB 資料表。
**建立 CloudFormation 堆疊**
下載並解壓縮 [的應用程式建立範本 CloudFormation](samples/data-transformation-tutorial-cli.zip)。
若要完成下列教學課程，您需要 [AWS Command Line Interface (AWS CLI) 第 2 版](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
對於長命令，逸出字元 (`\`) 用於將命令分割為多行。
**注意**
在 Windows 中，作業系統的內建終端機不支援您常用的某些 Bash CLI 命令 (例如 `zip`)。若要取得 Ubuntu 和 Bash 的 Windows 整合版本，請[安裝適用於 Linux 的 Windows 子系統](https://learn.microsoft.com/en-us/windows/wsl/install)。本指南中的 CLI 命令範例使用 Linux 格式。如果您使用的是 Windows CLI，必須重新格式化包含內嵌 JSON 文件的命令。
1. 使用下列命令來建立 CloudFormation 堆疊。
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation 會佈建範本中指定的資源。完成資源佈建可能需要幾分鐘的時間。使用下列命令來查看 CloudFormation 堆疊的狀態。
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. 當您的 CloudFormation 堆疊狀態為 時`StackStatus: "CREATE_COMPLETE"`，請使用下列命令來擷取未來步驟的相關輸出值。
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
輸出值如下：
+ ApiRole，這是允許 API Gateway 將項目放入 DynamoDB 資料表的角色名稱。對於本教學課程，角色名稱為 `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`。
+ DDBTableName，這是 DynamoDB 資料表的名稱。對於本教學課程，資料表名稱為 `data-transformation-tutorial-cli-ddb`。
+ ResourceId，這是 `GET` 和 `POST` 方法公開所在寵物資源的 ID。對於本教學課程，資源 ID 為 `efg456`
+ ApiId，這是 API 的 ID。對於本教學課程，API ID 為 `abc123`。
**在資料轉換之前測試 `GET` 方法**
+ 使用下列命令測試 `GET` 方法。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
測試的輸出將顯示下列內容。
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
您將根據 [API Gateway 中 REST API 的映射範本轉換](models-mappings.md)中的對應範本轉換此輸出。
**轉換 `GET` 整合回應**
+ 使用下列命令更新 `GET` 方法的整合回應。將 *rest-api-id* 和 *resource-id* 取代為您的值。
使用下列命令建立整合回應。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**測試 `GET` 方法**
+ 使用下列命令測試 `GET` 方法。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
測試的輸出將顯示轉換後的回應。
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**建立 `POST` 方法**
1. 使用下列命令，在 `/pets` 資源上建立新方法。
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
此方法可讓您將寵物資訊傳送至您在 CloudFormation 堆疊中建立的 DynamoDB 資料表。
1. 使用下列命令在 `POST`方法上建立 AWS 服務 整合。
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. 使用下列命令，為 `POST` 方法的成功呼叫建立方法回應。
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. 使用下列命令，為 `POST` 方法的成功呼叫建立整合回應。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**測試 `POST` 方法**
+ 使用下列命令測試 `POST` 方法。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
輸出將顯示成功訊息。
**刪除 CloudFormation 堆疊**
+ 使用下列命令來刪除您的 CloudFormation 資源。
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## 已完成的資料轉換 CloudFormation 範本
下列範例是已完成的 CloudFormation 範本，其會使用 和 `POST`方法建立具有 `/pets` 資源的 API `GET`和 DynamoDB 資料表。
+ `GET` 方法將從 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 端點取得資料。輸出資料將根據 [API Gateway 中 REST API 的映射範本轉換](models-mappings.md)中的對應範本進行轉換。
+ `POST` 方法可讓使用者使用對應範本，將寵物資訊 `POST` 至 DynamoDB 資料表。
### 範本範例 CloudFormation
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# 使用變數進行 API Gateway 映射範本轉換的範例
以下範例說明如何在映射範本中使用 `$context`、`input` 和 `util` 變數。您可以使用模擬整合或 Lambda 非代理整合，將輸入事件傳回至 API Gateway。如需資料轉換支援的所有變數的清單，請參閱 [用於 API Gateway 資料轉換的變數](api-gateway-mapping-template-reference.md)。
## 範例 1：將多個 `$context` 變數傳遞至整合端點
以下範例顯示一個映射範本，其會將傳入的 `$context` 變數映射至整合請求承載中名稱稍有不同的後端變數：
```
{
"stage" : "$context.stage",
"request_id" : "$context.requestId",
"api_id" : "$context.apiId",
"resource_path" : "$context.resourcePath",
"resource_id" : "$context.resourceId",
"http_method" : "$context.httpMethod",
"source_ip" : "$context.identity.sourceIp",
"user-agent" : "$context.identity.userAgent",
"account_id" : "$context.identity.accountId",
"api_key" : "$context.identity.apiKey",
"caller" : "$context.identity.caller",
"user" : "$context.identity.user",
"user_arn" : "$context.identity.userArn"
}
```
此映射範本的輸出應如下所示：
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
其中一個變數是 API 金鑰。此範例假設該方法需要 API 金鑰。
## 範例 2：透過 JSON 承載將所有請求參數傳遞至整合端點
下列範例會透過 JSON 承載將所有請求參數 (包含 `path`、`querystring` 和 `header`) 傳遞至整合端點：
```
#set($allParams = $input.params())
{
"params" : {
#foreach($type in $allParams.keySet())
#set($params = $allParams.get($type))
"$type" : {
#foreach($paramName in $params.keySet())
"$paramName" : "$util.escapeJavaScript($params.get($paramName))"
#if($foreach.hasNext),#end
#end
}
#if($foreach.hasNext),#end
#end
}
}
```
如果請求具有下列輸入參數：
+ 名為 `myparam` 的路徑參數
+ 查詢字串參數 `querystring1=value1,value2`
+ 標頭 `"header1" : "value1"`。
此映射範本的輸出應如下所示：
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## 範例 3：將方法請求的子區段傳遞至整合端點
下列範例使用輸入參數 `name` 僅擷取 `name` 參數，並使用輸入參數 `input.json('$')` 擷取方法請求的整個內文：
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
對於包含查詢字串參數 `name=Bella&type=dog` 和下列內文的請求：
```
{
"Price" : "249.99",
"Age": "6"
}
```
此映射範本的輸出應如下所示：
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
此映射範本會移除查詢字串參數 `type=dog`。
如果 JSON 輸入包含 JavaScript 無法剖析的非逸出字元，則 API Gateway 可能會傳回 400 回應。套用 `$util.escapeJavaScript($input.json('$'))` 以確保 JSON 輸入可正確剖析。
套用 `$util.escapeJavaScript($input.json('$'))` 的前一個範例如下所示：
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
在這種情況下，此映射範本的輸出應如下所示：
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## 範例 4：使用 JSONPath 表達式將方法請求的子區段傳遞至整合端點
下列範例使用 JSONPath 表達式，僅從請求內文擷取輸入參數 `name` 和 `Age`：
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
對於包含查詢字串參數 `name=Bella&type=dog` 和下列內文的請求：
```
{
"Price" : "249.99",
"Age": "6"
}
```
此映射範本的輸出應如下所示：
```
{
"name" : "Bella",
"body" : "6"
}
```
此映射範本會從內文中移除查詢字串參數 `type=dog` 和 `Price` 欄位。
如果方法請求承載包含 JavaScript 無法剖析的非逸出字元，API Gateway 可能會傳回 `400` 回應。套用 `$util.escapeJavaScript()` 以確保 JSON 輸入可正確剖析。
套用 `$util.escapeJavaScript($input.json('$.Age'))` 的前一個範例如下所示：
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
在這種情況下，此映射範本的輸出應如下所示：
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## 範例 5：使用 JSONPath 表達式將有關方法請求的資訊傳遞至整合端點
下列範例使用 `$input.params()`、`$input.path()` 和 `$input.json()` 將有關方法請求的資訊傳送至整合端點。此映射範本使用 `size()` 方法來提供清單中的元素數量。
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
對於包含路徑參數 `123` 和下列內文的請求：
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
此映射範本的輸出應如下所示：
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
如果方法請求承載包含 JavaScript 無法剖析的非逸出字元，API Gateway 可能會傳回 `400` 回應。套用 `$util.escapeJavaScript()` 以確保 JSON 輸入可正確剖析。
套用 `$util.escapeJavaScript($input.json('$.things'))` 的前一個範例如下所示：
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
此映射範本的輸出應如下所示：
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```
# 用於 API Gateway 資料轉換的變數
建立參數映射時，您可以使用內容變數作為資料來源。建立映射範本轉換時，您可以在您使用 [Velocity 範本語言 (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 編寫的指令碼中使用內容變數、輸入和 util 變數。如需使用這些參考變數的映射範本範例，請參閱 [使用變數進行 API Gateway 映射範本轉換的範例](api-gateway-mapping-variable-examples.md)。
如需存取記錄的參考變數清單，請參閱 [API Gateway 存取記錄的變數](api-gateway-variables-for-access-logging.md)。
## 資料轉換的內容變數
您可以使用下列區分大小寫的 `$context` 變數進行資料轉換。
| 參數 | Description |
| --- | --- |
| \$1context.accountId | API 擁有者 AWS 的帳戶 ID。 |
| \$1context.apiId | API Gateway 指派給您 API 的識別碼。 |
| \$1context.authorizer.claims.property | 成功驗證方法發起人之後，從 Amazon Cognito 使用者集區傳回之宣告的屬性。如需詳細資訊，請參閱 [使用 Amazon Cognito 使用者集區做為授權方，藉以控制對 REST API 的存取](apigateway-integrate-with-cognito.md)。 呼叫 `$context.authorizer.claims` 會傳回 null。 |
| \$1context.authorizer.principalId | 與用戶端所傳送並從 API Gateway Lambda 授權方 (先前稱作自訂授權方) 所傳回之字符相關聯的主要使用者身分。如需詳細資訊，請參閱 [使用 API Gateway Lambda 授權方](apigateway-use-lambda-authorizer.md)。 |
| \$1context.authorizer.property | API Gateway Lambda 授權方函數所傳回 `context` 映射之指定索引鍵/值組的字串化值。例如，如果授權方傳回下列 `context` 映射： "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} 呼叫 `$context.authorizer.key` 會傳回 `"value"` 字串，呼叫 `$context.authorizer.numKey` 會傳回 `"1"` 字串，而呼叫 `$context.authorizer.boolKey` 會傳回 `"true"` 字串。 對於*屬性*，唯一支援的特殊字元是底線 `(_)` 字元。 如需詳細資訊，請參閱[使用 API Gateway Lambda 授權方](apigateway-use-lambda-authorizer.md)。 |
| \$1context.awsEndpointRequestId | AWS 端點的請求 ID。 |
| \$1context.deploymentId | API 部署的 ID。 |
| \$1context.domainName | 用來調用 API 的完整網域名稱。這應該與傳入的 `Host` 標頭相同。 |
| \$1context.domainPrefix | `$context.domainName` 的第一個標籤。 |
| \$1context.error.message | 包含 API Gateway 錯誤訊息的字串。此變數只能用於 Velocity 範本語言引擎無法處理的 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 本文映射範本及存取記錄中的簡單變數替換。如需詳細資訊，請參閱[使用 CloudWatch 指標監控 WebSocket API 執行](apigateway-websocket-api-logging.md)及[設定閘道回應以自訂錯誤回應](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)。 |
| \$1context.error.messageString | \$1context.error.message 的引用值，即 "\$1context.error.message"。 |
| \$1context.error.responseType | [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 的[類型](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType)。此變數只能用於 Velocity 範本語言引擎無法處理的 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 本文映射範本及存取記錄中的簡單變數替換。如需詳細資訊，請參閱[使用 CloudWatch 指標監控 WebSocket API 執行](apigateway-websocket-api-logging.md)及[設定閘道回應以自訂錯誤回應](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)。 |
| \$1context.error.validationErrorString | 字串，其中包含詳細的驗證錯誤訊息。 |
| \$1context.extendedRequestId | API Gateway 產生和指派給 API 請求的延伸 ID。延伸請求 ID 包含有助於偵錯和疑難排解的資訊。 |
| \$1context.httpMethod | 使用的 HTTP 方法。有效值包含：`DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST` 和 `PUT`。 |
| \$1context.identity.accountId | 與請求相關聯的 AWS 帳戶 ID。 |
| \$1context.identity.apiKey | 對於需要 API 金鑰的 API 方法，此變數是與方法請求相關聯的 API 金鑰。對於不需要 API 金鑰的方法，此變數為 null。如需詳細資訊，請參閱 [API Gateway 中 REST API 的用量計畫和 API 金鑰](api-gateway-api-usage-plans.md)。 |
| \$1context.identity.apiKeyId | 與需要 API 金鑰之 API 請求相關聯的 API 金鑰 ID。 |
| \$1context.identity.caller | 已簽署請求之發起人的主體識別符。支援使用 IAM 授權的資源。 |
| \$1context.identity.cognitoAuthenticationProvider | 提出請求的發起人所使用的所有 Amazon Cognito 驗證提供者清單 (以逗號分隔)。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。 例如，適用於 Amazon Cognito 使用者集區的身分，`cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` 如需有關 Amazon Cognito 驗證提供者的詳細資訊，請參閱《[Amazon Cognito 開發人員指南](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)》中的*使用聯合身分*。 |
| \$1context.identity.cognitoAuthenticationType | 提出請求的發起人的 Amazon Cognito 驗證類型。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。可能的值包括用於已驗證身分的 `authenticated` 和未經驗證身分的 `unauthenticated`。 |
| \$1context.identity.cognitoIdentityId | 提出請求的發起人的 Amazon Cognito 身分 ID。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。 |
| \$1context.identity.cognitoIdentityPoolId | 提出請求的發起人的 Amazon Cognito 身分集區 ID。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。 |
| \$1context.identity.principalOrgId | [AWS 組織 ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html)。 |
| \$1context.identity.sourceIp | 對 API Gateway 端點提出請求之即時 TCP 連線的來源 IP 位址。 |
| \$1context.identity.clientCert.clientCertPem | 用戶端在交互 TLS 驗證期間所呈現的 PEM 編碼用戶端憑證。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。 |
| \$1context.identity.clientCert.subjectDN | 用戶端提供之憑證主體的辨別名稱。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。 |
| \$1context.identity.clientCert.issuerDN | 用戶端提供之憑證發行者的辨別名稱。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。 |
| \$1context.identity.clientCert.serialNumber | 憑證的序號。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。 |
| \$1context.identity.clientCert.validity.notBefore | 憑證無效之前的日期。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。 |
| \$1context.identity.clientCert.validity.notAfter | 憑證無效之後的日期。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。 |
| \$1context.identity.vpcId | 對 API Gateway 端點提出請求之 VPC 的 VPC ID。 |
| \$1context.identity.vpceId | 對 API Gateway 端點提出請求之 VPC 端點的 VPC 端點 ID。只會在您擁有私有 API 時顯示。 |
| \$1context.identity.user | 將針對資源存取授權之使用者的主體識別符。支援使用 IAM 授權的資源。 |
| \$1context.identity.userAgent | API 發起人的 [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 標頭。 |
| \$1context.identity.userArn | 身分驗證之後識別之有效使用者的 Amazon Resource Name (ARN)。如需詳細資訊，請參閱[https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)。 |
| \$1context.isCanaryRequest | 如果請求導向 Canary，則傳回 `true`；如果請求未導向 Canary，則傳回 `false`。只會在啟用 Canary 時顯示。 |
| \$1context.path | 請求路徑。例如，對於 https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child 的非代理請求 URL，\$1context.path 值是 /\$1stage\$1/root/child。 |
| \$1context.protocol | 請求通訊協定，例如 HTTP/1.1。 API Gateway API 可以接受 HTTP/2 請求，但 API Gateway 會使用 HTTP/1.1 將請求傳送至後端整合。因此，即使用戶端傳送使用 HTTP/2 的請求，請求通訊協定也會記錄為 HTTP/1.1。 |
| \$1context.requestId | 請求的 ID。用戶端可以覆寫此請求 ID。使用 `$context.extendedRequestId` 即可取得 API Gateway 產生的唯一請求 ID。 |
| \$1context.requestOverride.header.header\$1name | 請求標題會覆寫。如果此參數已經定義，它包含要使用的標頭 (而不是在 **Integration Request (整合請求)** 窗格中定義的 **HTTP Headers (HTTP 標頭)**)。如需詳細資訊，請參閱 [覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。 |
| \$1context.requestOverride.path.path\$1name | 請求路徑會覆寫。如果此參數已經定義，它包含要使用的請求路徑 (而不是在 **Integration Request (整合請求)** 窗格中定義的 **URL Path Parameters (URL 路徑參數)**)。如需詳細資訊，請參閱 [覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。 |
| \$1context.requestOverride.querystring.querystring\$1name | 請求查詢字串會覆寫。如果此參數已經定義，它包含要使用的請求查詢字串 (而不是在 **Integration Request (整合請求) ** 窗格中定義的 **URL Query String (URL 查詢字串)**)。如需詳細資訊，請參閱 [覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。 |
| \$1context.responseOverride.header.header\$1name | 回應標題會覆寫。如果此參數已經定義，它包含要傳回的標頭 (而不是在 Integration Response (整合回應) 窗格中定義為 Default mapping (預設映射) 的 Response header (回應標頭))。如需詳細資訊，請參閱 [覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。 |
| \$1context.responseOverride.status | 回應狀態碼會覆寫。如果此參數已經定義，它包含要傳回的狀態碼 (而不是在 Integration Response (整合回應) 窗格中定義為 Default mapping (預設映射) 的 Method response status (方法回應狀態))。如需詳細資訊，請參閱 [覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。 |
| \$1context.requestTime | [CLF](https://httpd.apache.org/docs/current/logs.html#common) 格式化請求時間 (dd/MMM/yyyy:HH:mm:ss \$1-hhmm)。 |
| \$1context.requestTimeEpoch | [Epoch](https://en.wikipedia.org/wiki/Unix_time) 格式化的要求時間，以毫秒為單位。 |
| \$1context.resourceId | API Gateway 指派給您的資源的識別碼。 |
| \$1context.resourcePath | 您資源的路徑。例如，對於非代理請求 URI `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`，`$context.resourcePath` 值是 `/root/child`。如需詳細資訊，請參閱 [教學：建立具有 HTTP 非代理整合的 REST API](api-gateway-create-api-step-by-step.md)。 |
| \$1context.stage | API 請求的部署階段 (例如，`Beta` 或 `Prod`)。 |
| \$1context.wafResponseCode | 從 [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) 收到的回應：`WAF_ALLOW` 或 `WAF_BLOCK`。若該階段與 web ACL 不相關聯，將不會設定此值。如需詳細資訊，請參閱 [使用 AWS WAF 來保護 API Gateway APIs 中的 REST API](apigateway-control-access-aws-waf.md)。 |
| \$1context.webaclArn | Web ACL 的完整 ARN，用來決定是否允許或封鎖請求。若該階段與 web ACL 不相關聯，將不會設定此值。如需詳細資訊，請參閱[使用 AWS WAF 來保護 API Gateway APIs 中的 REST API](apigateway-control-access-aws-waf.md)。 |
## 輸入變數
您可以使用下列區分大小寫的 `$input` 變數來參考方法請求承載和方法請求參數。可使用以下函數：
| 變數和函數 | 描述 |
| --- | --- |
| \$1input.body | 傳回原始請求承載做為字串。您可以使用 `$input.body` 保留整個浮點數，例如 `10.00`。 |
| \$1input.json(x) | 此函數會評估 JSONPath 表達式，並傳回結果作為 JSON 字串。 例如，`$input.json('$.pets')` 會傳回代表 `pets` 結構的 JSON 字串。 如需 JSONPath 的詳細資訊，請參閱 [JSONPath](https://goessner.net/articles/JsonPath/) 或[適用於 Java 的 JSONPath](https://github.com/json-path/JsonPath)。 |
| \$1input.params() | 傳回所有請求參數的映射。我們建議您使用 `$util.escapeJavaScript` 清理結果，以避免潛在的注入攻擊。為了完全控制請求清理，請使用沒有模板的代理整合，並處理整合中的請求清理。 |
| \$1input.params(x) | 從路徑、查詢字串或標頭值 (以此順序搜尋) 傳回方法請求參數值，而參數名稱字串為 `x`。我們建議您使 `$util.escapeJavaScript` 用清理參數，以避免潛在的注入攻擊。為了完全控制參數清理，請使用沒有模板的代理整合，並處理整合中的請求清理。 |
| \$1input.path(x) | 採用 JSONPath 表達式字串 (`x`)，並傳回結果的 JSON 物件呈現。這可讓您存取和運用 [Apache Velocity 範本語言 (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 中原生承載的元素。 例如，如果表達式 `$input.path('$.pets')` 傳回如下物件： [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').size()` 會傳回 `"3"`。 如需 JSONPath 的詳細資訊，請參閱 [JSONPath](https://goessner.net/articles/JsonPath/) 或[適用於 Java 的 JSONPath](https://github.com/json-path/JsonPath)。 |
## 階段變數
您可以使用下列階段變數作為方法整合中 ARN 和 URL 的預留位置。如需詳細資訊，請參閱[在 API Gateway 中使用 REST API 的階段變數](stage-variables.md)。
| 語法 | Description |
| --- | --- |
| \$1stageVariables.variable\$1name、\$1stageVariables['variable\$1name'] 或 \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name* 代表階段變數名稱。 |
## Util 變數
您可以使用下列區分大小寫的 `$util` 變數，針對映射範本使用公用程式函數。除非特別指定，否則預設字元集為 UTF-8。
| 函數 | 描述 |
| --- | --- |
| \$1util.escapeJavaScript() | 使用 JavaScript 字串規則來逸出字串中的字元。 此函數會將任何一般單引號 (`'`) 轉換為逸出單引號 (`\'`)。不過，逸出單引號不適用於 JSON。因此，將此函數的輸出用於 JSON 屬性時，您必須將任何逸出單引號 (`\'`) 轉換為一般單引號 (`'`)。下列範例顯示這種情況： "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")" |
| \$1util.parseJson() | 採用「字串化」JSON，並傳回結果的物件呈現。您可以使用此函數的結果，來存取和運用 Apache Velocity 範本語言 (VTL) 中原生承載的元素。例如，如果您有下列承載： {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} 並使用下列映射範本 #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
您將會收到下列輸出： {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | 將字串轉換為 "application/x-www-form-urlencoded" 格式。 |
| \$1util.urlDecode() | 解碼 "application/x-www-form-urlencoded" 字串。 |
| \$1util.base64Encode() | 將資料編碼為 base64 編碼字串。 |
| \$1util.base64Decode() | 解碼 base64 編碼字串中的資料。 |
# API Gateway 中 REST API 的閘道回應
閘道回應以 API Gateway 定義的回應類型識別。回應包含 HTTP 狀態碼、一組由參數對應指定的額外標頭，以及非 [VTL](https://velocity.apache.org/engine/devel/vtl-reference.html) 對應範本所產生的承載。
在 API Gateway REST API 中，閘道回應以 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 表示。在 OpenAPI 中，`GatewayResponse` 執行個體是以 [x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md) 延伸來加以說明。
若要啟用閘道回應，您可以在 API 層級設定[支援回應類型](supported-gateway-response-types.md)的閘道回應。每當 API Gateway 傳回該類型的回應時，就會套用閘道回應中定義的標頭映射與承載映射範本，將映射的結果傳回給 API 發起人。
在下一節中，我們將示範如何使用 API Gateway 主控台與 API Gateway REST API 來設定閘道回應。
## 設定閘道回應以自訂錯誤回應
如果 API Gateway 無法處理傳入請求，則它會傳送錯誤回應給用戶端，但不會將請求轉送到整合後端。錯誤回應預設包含一則簡短的描述性錯誤訊息。例如，如果您嘗試在未定義的 API 資源上呼叫操作，您會收到 `{ "message": "Missing Authentication Token" }` 訊息的錯誤回應。如果您是初次使用 API Gateway，您可能會發現很難了解實際發生錯誤的原因。
針對一些錯誤回應，API Gateway 允許 API 開發人員進行自訂以傳回不同格式的回應。在 `Missing Authentication Token` 範例中，您可以將含有可能原因的提示新增至原始回應承載，如下列範例所示：`{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}`。
當您的 API 在外部交換和 AWS 雲端之間協調時，您可以使用 VTL 映射範本進行整合請求或整合回應，將承載從一個格式映射到另一個格式。不過，VTL 對應範本僅適用於具有成功回應的有效請求。
針對無效的請求，API Gateway 會完全略過整合並傳回錯誤回應。您必須使用自訂，將錯誤回應轉譯成 Exchange 相容的格式。在本例中，會在只支援簡單變數替換的非 VTL 對應範本中轉譯自訂。
將 API Gateway 所產生的錯誤回應一般化為 API Gateway 所產生的任何回應，此操作稱為*閘道回應*。這可區分 API Gateway 所產生的回應與整合回應。閘道回應對應範本可存取 `$context` 變數值與 `$stageVariables` 屬性值，以及 `method.request.param-position.param-name` 格式的方法請求參數。
如需 `$context` 變數的詳細資訊，請參閱「[資料轉換的內容變數](api-gateway-mapping-template-reference.md#context-variable-reference)」。如需有關 `$stageVariables` 的詳細資訊，請參閱 [階段變數](api-gateway-mapping-template-reference.md#stagevariables-template-reference)。如需有關方法請求參數的詳細資訊，請參閱 [輸入變數](api-gateway-mapping-template-reference.md#input-variable-reference)。
**Topics**
+ [設定閘道回應以自訂錯誤回應](#customize-gateway-responses)
+ [使用 API Gateway 主控台設定 REST API 的閘道回應](set-up-gateway-response-using-the-console.md)
+ [使用 API Gateway REST API 設定閘道回應](set-up-gateway-response-using-the-api.md)
+ [設定 OpenAPI 中的閘道回應自訂](set-up-gateway-responses-in-swagger.md)
+ [API Gateway 的閘道回應類型](supported-gateway-response-types.md)
# 使用 API Gateway 主控台設定 REST API 的閘道回應
下列範例顯示如何使用 API Gateway 主控台設定 REST API 的閘道回應
**使用 API Gateway 主控台自訂閘道回應**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 REST API。
1. 在主導覽窗格中，選擇**閘道資源**。
1. 選擇回應類型，然後選擇**編輯**。在此逐步說明中，我們使用**遺漏身分驗證權杖**作為範例。
1. 您可以變更 API Gateway 所產生的**狀態碼**，以傳回符合您的 API 需求的不同狀態碼。在此範例中，自訂會將狀態碼從預設值 (`403`) 變更為 `404`，因為當用戶端呼叫可視為找不到的不支援或無效資源時會出現此錯誤訊息。
1. 若要傳回自訂標頭，請在**回應標頭**下，選擇**新增標頭**。為了方便說明，我們新增下列自訂標頭：
```
Access-Control-Allow-Origin:'a.b.c'
x-request-id:method.request.header.x-amzn-RequestId
x-request-path:method.request.path.petId
x-request-query:method.request.querystring.q
```
在上述標頭對應中，靜態網域名稱 (`'a.b.c'`) 會對應到 `Allow-Control-Allow-Origin` 標頭以允許 API 的 CORS 存取；`x-amzn-RequestId` 的輸入請求標頭會對應到回應中的 `request-id`；傳入請求的 `petId` 路徑變數會對應到回應中的 `request-path` 標頭；而原始請求的 `q` 查詢參數會對應到回應的 `request-query` 標頭。
1. 在**回應範本**下，將**內容類型**保持為 `application/json`，然後在**範本內文**編輯器中輸入下列內文對應範本：
```
{
"message":"$context.error.messageString",
"type": "$context.error.responseType",
"statusCode": "'404'",
"stage": "$context.stage",
"resourcePath": "$context.resourcePath",
"stageVariables.a": "$stageVariables.a"
}
```
此範例示範如何將 `$context` 與 `$stageVariables` 屬性對應到閘道回應內文的屬性。
1. 選擇**儲存變更**。
1. 將 API 部署到新的或現有的階段。
透過呼叫下列 CURL 命令進行閘道回應測試，並假設映射 API 方法的調用 URL 為 `https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/{petId}`：
```
curl -v -H 'x-amzn-RequestId:123344566' https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/5/type?q=1
```
由於額外查詢字串參數 `q=1` 與 API 不相容，因此會從指定的閘道回應傳回錯誤。您應該取得類似如下的閘道回應：
```
> GET /custErr/pets/5?q=1 HTTP/1.1
Host: o81lxisefl.execute-api.us-east-1.amazonaws.com
User-Agent: curl/7.51.0
Accept: */*
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 334
Connection: keep-alive
Date: Tue, 02 May 2017 03:15:47 GMT
x-amzn-RequestId: 123344566
Access-Control-Allow-Origin: a.b.c
x-amzn-ErrorType: MissingAuthenticationTokenException
header-1: static
x-request-query: 1
x-request-path: 5
X-Cache: Error from cloudfront
Via: 1.1 441811a054e8d055b893175754efd0c3.cloudfront.net (CloudFront)
X-Amz-Cf-Id: nNDR-fX4csbRoAgtQJ16u0rTDz9FZWT-Mk93KgoxnfzDlTUh3flmzA==
{
"message":"Missing Authentication Token",
"type": MISSING_AUTHENTICATION_TOKEN,
"statusCode": '404',
"stage": custErr,
"resourcePath": /pets/{petId},
"stageVariables.a": a
}
```
上述範例假設 API 後端是[寵物店](http://petstore-demo-endpoint.execute-api.com/petstore/pets)，而且 API 已定義階段變數 `a`。
# 使用 API Gateway REST API 設定閘道回應
使用 API Gateway REST API 自訂閘道回應之前，您必須已建立 API 並已取得其識別符。若要擷取 API 識別符，您可以遵循 [restapi:gateway-responses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) 連結關係並查看結果。
**使用 API Gateway REST API 自訂閘道回應**
1. 若要覆寫整個 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 執行個體，請呼叫 [gatewayresponse:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutGatewayResponse.html) 動作。在 URL 路徑參數中指定所需的 [responseType](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType)，並在請求酬載中提供 [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#statusCode)、[responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseParameters) 及 [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseTemplates) 映射。
1. 若要更新 `GatewayResponse` 執行個體的一部分，請呼叫 [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html) 動作。在 URL 路徑參數中指定所需的 `responseType`，並在請求承載中提供您需要的個別 `GatewayResponse` 屬性，例如 `responseParameters` 或 `responseTemplates` 映射。
# 設定 OpenAPI 中的閘道回應自訂
您可以在 API 根層級使用 `x-amazon-apigateway-gateway-responses` 延伸，來自訂 OpenAPI 中的閘道回應。下列 OpenAPI 定義示範如何自訂 `MISSING_AUTHENTICATION_TOKEN` 類型的 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)。
```
"x-amazon-apigateway-gateway-responses": {
"MISSING_AUTHENTICATION_TOKEN": {
"statusCode": 404,
"responseParameters": {
"gatewayresponse.header.x-request-path": "method.input.params.petId",
"gatewayresponse.header.x-request-query": "method.input.params.q",
"gatewayresponse.header.Access-Control-Allow-Origin": "'a.b.c'",
"gatewayresponse.header.x-request-header": "method.input.params.Accept"
},
"responseTemplates": {
"application/json": "{\n \"message\": $context.error.messageString,\n \"type\": \"$context.error.responseType\",\n \"stage\": \"$context.stage\",\n \"resourcePath\": \"$context.resourcePath\",\n \"stageVariables.a\": \"$stageVariables.a\",\n \"statusCode\": \"'404'\"\n}"
}
}
```
在此範例中，自訂會將狀態碼從預設值 (`403`) 變更為 `404`。它也會將 `application/json` 媒體類型的四個標頭參數與一個內文對應範本新增至閘道回應。
# API Gateway 的閘道回應類型
API Gateway 公開下列 API 開發人員可自訂的閘道回應。
| 閘道回應類型 | 預設狀態碼 | 描述 |
| --- | --- | --- |
| ACCESS\$1DENIED | 403 | 授權失敗的閘道回應；例如，自訂或 Amazon Cognito 授權方拒絕存取時。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| API\$1CONFIGURATION\$1ERROR | 500 | 無效 API 組態的閘道回應，包括提交的端點地址無效、制定二進位支援時二進位資料的 Base64 編碼失敗，或整合回應映射不符合任何範本且未設定預設範本。如果未指定回應類型，此回應預設為 `DEFAULT_5XX` 類型。 |
| AUTHORIZER\$1CONFIGURATION\$1ERROR | 500 | 無法連線到自訂或 Amazon Cognito 授權方時的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_5XX` 類型。 |
| AUTHORIZER\$1FAILURE | 500 | 自訂或 Amazon Cognito 授權方無法驗證發起人時的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_5XX` 類型。 |
| BAD\$1REQUEST\$1PARAMETERS | 400 | 根據啟用的請求驗證程式無法驗證請求參數時的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| BAD\$1REQUEST\$1BODY | 400 | 根據啟用的請求驗證程式無法驗證請求內文時的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| DEFAULT\$14XX | Null | 狀態碼為 `4XX` 之未指定回應類型的預設閘道回應。變更此後援閘道回應的狀態碼會將所有其他 `4XX` 回應的狀態碼變更為新的值。將此狀態碼重設為 Null 會將所有其他 `4XX` 回應的狀態碼還原成其原始值。 [AWS WAF 自訂回應](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html)優先於自訂閘道回應。 |
| DEFAULT\$15XX | Null | 狀態碼為 `5XX` 之未指定回應類型的預設閘道回應。變更此後援閘道回應的狀態碼會將所有其他 `5XX` 回應的狀態碼變更為新的值。將此狀態碼重設為 Null 會將所有其他 `5XX` 回應的狀態碼還原成其原始值。 |
| EXPIRED\$1TOKEN | 403 | AWS 身分驗證字符過期錯誤的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| INTEGRATION\$1FAILURE | 504 | 整合失敗錯誤的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_5XX` 類型。 |
| INTEGRATION\$1TIMEOUT | 504 | 整合逾時錯誤的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_5XX` 類型。 |
| INVALID\$1API\$1KEY | 403 | 針對需要 API 金鑰之方法提交的 API 金鑰無效的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| INVALID\$1SIGNATURE | 403 | 無效 AWS 簽章錯誤的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| MISSING\$1AUTHENTICATION\$1TOKEN | 403 | 遺漏身分驗證字符錯誤的閘道回應，例如用戶端嘗試呼叫不支援的 API 方法或資源時。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| QUOTA\$1EXCEEDED | 429 | 用量計劃超額錯誤的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| REQUEST\$1TOO\$1LARGE | 413 | 請求太大錯誤的閘道回應。如果未指定回應類型，此回應預設為：`HTTP content length exceeded 10485760 bytes`。 |
| RESOURCE\$1NOT\$1FOUND | 404 | API 請求通過身分驗證與授權之後 (API 金鑰身分驗證與授權除外)，API Gateway 找不到指定資源時的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| THROTTLED | 429 | 超過用量計劃、方法、階段或帳戶層級調節限制時的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| UNAUTHORIZED | 401 | 自訂或 Amazon Cognito 授權方無法驗證發起人時的閘道回應。 |
| UNSUPPORTED\$1MEDIA\$1TYPE | 415 | 承載屬於不支援的媒體類型時的閘道回應 (如果啟用嚴格的傳遞行為)。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 |
| WAF\$1FILTERED | 403 | 請求遭 AWS WAF封鎖時所出現的閘道回應。如果未指定回應類型，此回應預設為 `DEFAULT_4XX` 類型。 [AWS WAF 自訂回應](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html)優先於自訂閘道回應。 |
# API Gateway 中 REST API 的 CORS
[跨來源資源共享 (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 是一種瀏覽器安全功能，限制從瀏覽器中執行之指令碼啟動的跨來源 HTTP 請求。如需詳細資訊，請參閱[什麼是 CORS？](https://aws.amazon.com/what-is/cross-origin-resource-sharing/)。
## 決定是否啟用 CORS 支援
*跨來源* HTTP 請求是針對下列項目所提出的請求：
+ 不同的*網域* (例如，從 `example.com` 到 `amazondomains.com`)
+ 不同的*子網域* (例如，從 `example.com` 到 `petstore.example.com`)
+ 不同的*連接埠* (例如，從 `example.com` 到 `example.com:10777`)
+ 不同的*通訊協定* (例如，從 `https://example.com` 到 `http://example.com`)
如果您無法存取 API 並收到包含 `Cross-Origin Request Blocked` 的錯誤訊息，您可能需要啟用 CORS。
跨來源 HTTP 請求可分為兩種類型：*簡單*請求和*非簡單*請求。
## 針對簡單請求啟用 CORS
如果下列所有條件皆為真，則 HTTP 請求為*簡單*請求：
+ 它是針對只允許 `GET`、`HEAD` 和 `POST` 請求的 API 資源所發出的。
+ 如果它是 `POST` 方法請求，則必須包含 `Origin` 標頭。
+ 請求承載內容類型為 `text/plain`、`multipart/form-data` 或 `application/x-www-form-urlencoded`。
+ 請求不包含自訂標頭。
+ [Mozilla CORS 文件中針對簡單請求](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests)列出的任何其他需求。
對於簡單的跨來源 `POST` 方法請求，來自您資源的回應需要包含標頭 `Access-Control-Allow-Origin: '*'` 或 `Access-Control-Allow-Origin:'origin'`。
所有其他跨來源 HTTP 請求都是*非簡單*請求。
## 針對非簡單請求啟用 CORS
如果您的 API 資源收到非簡單請求，則您必須啟用其他 CORS 支援，取決於您的整合類型。
### 針對非代理整合啟用 CORS
對於這些整合，[CORS 通訊協定](https://fetch.spec.whatwg.org/#http-cors-protocol)需要瀏覽器將預檢請求傳送到伺服器，並等待伺服器的核准 (或請求憑證)，然後再傳送實際請求。您必須設定 API，才能將適當的回應傳送至預檢請求。
若要建立預檢回應：
1. 建立具有模擬整合的 `OPTIONS` 方法。
1. 將下列回應標頭新增至 200 方法回應：
+ `Access-Control-Allow-Headers`
+ `Access-Control-Allow-Methods`
+ `Access-Control-Allow-Origin`
1. 將整合傳遞行為設定為 `NEVER`。在此案例中，未映射內容類型的方法請求會遭到拒絕，並顯示 HTTP 415 Unsupported Media Type (不支援的媒體類型) 回應。如需詳細資訊，請參閱[API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為](integration-passthrough-behaviors.md)。
1. 輸入回應標頭的值。若要允許所有來源、所有方法和常見的標頭，請使用下列標頭值：
+ `Access-Control-Allow-Headers: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'`
+ `Access-Control-Allow-Methods: 'DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH'`
+ `Access-Control-Allow-Origin: '*'`
在建立預檢請求之後，至少針對所有 200 回應，您必須為所有已啟用 CORS 的方法傳回 `Access-Control-Allow-Origin: '*'` 或 `Access-Control-Allow-Origin:'origin'` 標頭。
### 使用 為非代理整合啟用 CORS AWS 管理主控台
您可以使用 AWS 管理主控台 來啟用 CORS。API Gateway 會建立 `OPTIONS` 方法，並將 `Access-Control-Allow-Origin` 標頭新增至現有方法的整合回應。這並不一定可行，有時您需要手動修改整合回應，至少針對所有 200 回應，為所有已啟用 CORS 的方法傳回 `Access-Control-Allow-Origin` 標題。
如果您將 API 的二進位媒體類型設定為 `*/*`，當 API Gateway 建立 `OPTIONS` 方法時，請將 `contentHandling` 變更為 `CONVERT_TO_TEXT`。
以下 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) 命令會將整合請求的 `contentHandling` 變更為 `CONVERT_TO_TEXT`：
```
aws apigateway update-integration \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
以下 [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html) 命令會將整合回應的 `contentHandling` 變更為 `CONVERT_TO_TEXT`：
```
aws apigateway update-integration-response \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--status-code 200 \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
## 針對代理整合啟用 CORS 支援
對於 Lambda 代理整合或 HTTP 代理整合，您的後端負責傳回 `Access-Control-Allow-Origin`、`Access-Control-Allow-Methods` 和 `Access-Control-Allow-Headers` 標頭，因為代理整合不會傳回整合回應。
下列範例 Lambda 函數會傳回必要的 CORS 標頭：
------
#### [ Node.js ]
```
export const handler = async (event) => {
const response = {
statusCode: 200,
headers: {
"Access-Control-Allow-Headers" : "Content-Type",
"Access-Control-Allow-Origin": "https://www.example.com",
"Access-Control-Allow-Methods": "OPTIONS,POST,GET"
},
body: JSON.stringify('Hello from Lambda!'),
};
return response;
};
```
------
#### [ Python 3 ]
```
import json
def lambda_handler(event, context):
return {
'statusCode': 200,
'headers': {
'Access-Control-Allow-Headers': 'Content-Type',
'Access-Control-Allow-Origin': 'https://www.example.com',
'Access-Control-Allow-Methods': 'OPTIONS,POST,GET'
},
'body': json.dumps('Hello from Lambda!')
}
```
------
**Topics**
+ [決定是否啟用 CORS 支援](#apigateway-cors-request-types)
+ [針對簡單請求啟用 CORS](#apigateway-cors-simple-request)
+ [針對非簡單請求啟用 CORS](#apigateway-enable-cors-non-simple)
+ [針對代理整合啟用 CORS 支援](#apigateway-enable-cors-proxy)
+ [使用 API Gateway 主控台在資源上啟用 CORS](how-to-cors-console.md)
+ [使用 API Gateway 匯入 API 在資源上啟用 CORS](enable-cors-for-resource-using-swagger-importer-tool.md)
+ [測試 API Gateway API 的 CORS](apigateway-test-cors.md)
# 使用 API Gateway 主控台在資源上啟用 CORS
您可以使用 API Gateway 主控台，為您已建立的 REST API 資源上的一個或所有方法啟用 CORS 支援。啟用 COR 支援後，將整合傳遞行為設定為 `NEVER`。在此案例中，未映射內容類型的方法請求會遭到拒絕，並顯示 HTTP 415 Unsupported Media Type (不支援的媒體類型) 回應。如需詳細資訊，請參閱[API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為](integration-passthrough-behaviors.md)
**重要**
資源可以包含子資源。對資源及其方法啟用 CORS 支援並不會對子資源及其方法遞迴啟用此支援。
**若要在 REST API 資源上啟用 CORS 支援**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇一個 API。
1. 在**資源**下，選擇一個資源。
1. 在**資源詳細資訊**區段中，選擇**啟用 CORS**。
![\[在資源窗格中，選擇啟用 CORS。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors.png)
1. 在**啟用 CORS** 方塊中，執行下列操作：
1. (選用) 如果您已建立自訂閘道回應，並且想要針對回應啟用 CORS 支援，請選取閘道回應。
1. 選取每一種方法以啟用 CORS 支援。`OPTION` 方法必須啟用 CORS。
如果您為 `ANY` 方法啟用 CORS 支援，則所有方法的 CORS 都會啟用。
1. 在 **Access-Control-Allow-Headers** 輸入欄位中，輸入逗號分隔標頭清單的靜態字串，用戶端必須在資源的實際請求中提交這些標頭。使用主控台提供的 `'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` 標頭清單，或指定您自己的標頭。
1. 使用主控台提供的 `'*'` 值以做為 **Access-Control-Allow-Origin** 標頭值，以允許所有來源中的存取請求，或指定允許其存取資源的起源。
1. 選擇**儲存**。
![\[選擇允許哪些標頭\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors-resources.png)
**重要**
將上述說明應用在代理整合中的 `ANY` 方法時，不會設定任何適用的 CORS 標頭。反之，您的後端必須傳回適當的 CORS 標頭，例如 `Access-Control-Allow-Origin`。
在 `GET` 方法上啟用 CORS 之後，如果資源中尚未有 `OPTIONS` 方法，則系統會將此方法新增至資源。`OPTIONS` 方法的 `200` 回應會自動設定為傳回三個 `Access-Control-Allow-*` 標頭，來完成預檢交握。此外，根據預設也會設定實際 (`GET`) 方法，以在其 200 回應中傳回 `Access-Control-Allow-Origin` 標頭。對於其他類型的回應，如果您不想要傳回 `Cross-origin access` 錯誤，則需要使用 '\$1' 或特定來源手動進行設定，以傳回 `Access-Control-Allow-Origin'` 標頭。
在您的資源上啟用 CORS 支援之後，您必須部署或重新部署 API，新的設定才能生效。如需詳細資訊，請參閱[建立部署](set-up-deployments.md#create-deployment)。
**注意**
如果您在遵循程序後無法在資源上啟用 CORS 支援，建議您比較 CORS 組態與範例 API `/pets` 資源。若要了解如何建立範例 API，請參閱 [教學課程：匯入範例來建立 REST API](api-gateway-create-api-from-example.md)。
# 使用 API Gateway 匯入 API 在資源上啟用 CORS
如果您使用 [API Gateway 匯入 API](api-gateway-import-api.md)，即可透過 OpenAPI 檔案來設定 CORS 支援。您必須先在傳回必要標頭的資源中定義 `OPTIONS` 方法。
**注意**
Web 瀏覽器必須在每個接受 CORS 請求的 API 方法中設定 Access-Control-Allow-Headers 與 Access-Control-Allow-Origin 標頭。此外，某些瀏覽器會先向相同資源中的 `OPTIONS` 方法提出 HTTP 請求，然後預期收到相同的標頭。
## 示例 `Options` 方法
下列範例為模擬整合建立 `OPTIONS` 方法。
------
#### [ OpenAPI 3.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
tags:
- CORS
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
type: mock
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
```
------
#### [ OpenAPI 2.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
consumes:
- "application/json"
produces:
- "application/json"
tags:
- CORS
x-amazon-apigateway-integration:
type: mock
requestTemplates: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
一旦您為資源設定 `OPTIONS` 方法，您就可以將必要的標頭新增至相同資源中需要接受 CORS 請求的其他方法。
1. 對回應類型宣告 **Access-Control-Allow-Origin** 與 **Headers**。
------
#### [ OpenAPI 3.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
1. 在 `x-amazon-apigateway-integration` 標籤中，將這些標頭的對應設定為您的靜態值：
------
#### [ OpenAPI 3.0 ]
```
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
responseTemplates:
application/json: |
{}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
```
------
## API 範例
下列範例會建立具有 `HTTP` 整合 `OPTIONS` 方法和 `GET` 方法的完整 API。
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "cors-api"
description: "cors-api"
version: "2024-01-16T18:36:01Z"
servers:
- url: "/{basePath}"
variables:
basePath:
default: "/test"
paths:
/:
get:
operationId: "GetPet"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
components:
schemas:
Empty:
type: "object"
```
------
#### [ OpenAPI 2.0 ]
```
swagger: "2.0"
info:
description: "cors-api"
version: "2024-01-16T18:36:01Z"
title: "cors-api"
basePath: "/test"
schemes:
- "https"
paths:
/:
get:
operationId: "GetPet"
produces:
- "application/json"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
type: "string"
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
"200":
description: "200 response"
schema:
$ref: "#/definitions/Empty"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Headers:
type: "string"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
definitions:
Empty:
type: "object"
```
------
# 測試 API Gateway API 的 CORS
您可以透過叫用 API 來測試 API 的 CORS 組態，並在回應中檢查 CORS 標頭。下面的 `curl` 命令會傳送 OPTIONS 請求至已部署的 API。
```
curl -v -X OPTIONS https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}
```
```
< HTTP/1.1 200 OK
< Date: Tue, 19 May 2020 00:55:22 GMT
< Content-Type: application/json
< Content-Length: 0
< Connection: keep-alive
< x-amzn-RequestId: a1b2c3d4-5678-90ab-cdef-abc123
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token
< x-amz-apigw-id: Abcd=
< Access-Control-Allow-Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT
```
回應中的 `Access-Control-Allow-Origin`、`Access-Control-Allow-Headers` 和 `Access-Control-Allow-Methods` 標頭會顯示 API 支援 CORS。如需詳細資訊，請參閱[API Gateway 中 REST API 的 CORS](how-to-cors.md)。
# API Gateway 中 REST API 的二進位媒體類型
在 API Gateway 中，API 請求與回應可以有文字或二進位承載。文字承載是 `UTF-8` 編碼的 JSON 字串。二進位承載是文字承載以外的任何項目。例如，二進位承載可以是 JPEG 檔案、GZip 檔案或 XML 檔案。支援二進位媒體所需的 API 組態取決於您的 API 是否使用代理或非代理整合。
如果您使用代理整合與承載回應串流，則不需要設定二進位媒體類型。如需詳細資訊，請參閱[在 API Gateway 中串流代理整合的整合回應](response-transfer-mode.md)。
## AWS Lambda 代理整合
若要處理 AWS Lambda 代理整合的二進位承載，您必須對函數的回應進行 base64 編碼。您也必須為 API 配置 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)。您的 API `binaryMediaTypes` 組態是 API 視為二進位資料的內容類型列表。範例二進位媒體類型包括 `image/png` 或 `application/octet-stream`。您可以使用萬用字元 (`*`) 來涵蓋多種媒體類型。
API Gateway 會使用來自用戶端的第一個 `Accept` 標頭來判斷回應是否應該傳回二進位媒體。若要在無法控制 `Accept` 標頭值的順序 (例如來自瀏覽器的請求) 時傳回二進位媒體，請將 API 的二進位媒體類型設定為 `*/*`。
如需範例程式碼，請參閱 [在 API Gateway 中從 Lambda 代理整合傳回二進位媒體](lambda-proxy-binary-media.md)。
如果您使用 Lambda 代理整合與承載回應串流，則不需要設定二進位媒體類型。如需詳細資訊，請參閱[在 API Gateway 中設定 Lambda 代理整合與承載回應串流](response-transfer-mode-lambda.md)。
## 非代理伺服器整合
若要處理非代理整合的二進位承載，您可以將媒體類型新增至 `RestApi` 資源的 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) 清單。您的 API `binaryMediaTypes` 組態是 API 視為二進位資料的內容類型列表。或者，您可以在 [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 與 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 資源上設定 [contentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) 屬性。`contentHandling` 值可以是 `CONVERT_TO_BINARY`、`CONVERT_TO_TEXT` 或未定義。
**注意**
若是 `MOCK` 或私有整合，不支援在 AWS 管理主控台中設定 `contentHandling` 屬性。您必須使用 AWS CLI CloudFormation、 或 SDK 來設定`contentHandling`屬性。
根據 `contentHandling` 值，以及回應的 `Content-Type` 標頭或傳入請求的 `Accept` 標頭是否符合 `binaryMediaTypes` 清單中的項目，API Gateway 可以將原始二進位位元組編碼為 Base64 編碼字串、將 Base64 編碼字串解碼回其原始位元組，或傳遞本文而不進行任何修改。
您必須遵循下列方式設定 API，以在 API Gateway 中支援 API 的二進位承載：
+ 將所需的二進位媒體類型新增至 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 資源上的 `binaryMediaTypes` 清單。如果未定義此屬性與 `contentHandling` 屬性，則會將承載當作 UTF-8 編碼的 JSON 字串來處理。
+ 將 [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 資源的 `contentHandling` 屬性定址。
+ 若要讓請求承載從 base64 編碼的字串轉換為其二進位 Blob，請將屬性設定為 `CONVERT_TO_BINARY`。
+ 若要將請求承載從二進位 Blob 轉換為 base64 編碼的字串，請將屬性設定為 `CONVERT_TO_TEXT`。
+ 若要在不修改的情況下傳遞承載，請將屬性保留為未定義。若要在未經修改的情況下傳遞二進位承載，您也必須確定 `Content-Type` 符合其中一個 `binaryMediaTypes` 項目，並且已針對 API 啟用[傳遞行為](integration-passthrough-behaviors.md)。
+ 設定 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 資源的 `contentHandling` 屬性。`contentHandling` 屬性、用戶端請求中的 `Accept` 標頭，以及 API 的 `binaryMediaTypes` 組合會決定 API Gateway 處理內容類型轉換的方式。如需詳細資訊，請參閱[API Gateway 中的內容類型轉換](api-gateway-payload-encodings-workflow.md)。
**重要**
當請求的 `Accept` 標頭中包含多個媒體類型時，API Gateway 只會採用第一個 `Accept` 媒體類型。如果您無法控制 `Accept` 媒體類型的順序，而且二進位內容的媒體類型不是清單中的第一個類型，您可以在 API 的 `binaryMediaTypes` 清單中新增第一個 `Accept` 媒體類型。API Gateway 將以二進位處理此清單中的所有內容類型。
例如，若要在瀏覽器中使用 `![]()
` 元素來傳送 JPEG 檔案，瀏覽器可能會在請求中傳送 `Accept:image/webp,image/*,*/*;q=0.8`。透過將 `image/webp` 新增至 `binaryMediaTypes` 清單，端點就能收到二進位格式的 JPEG 檔案。
如需 API Gateway 如何處理文字和二進位承載的詳細資訊，請參閱[API Gateway 中的內容類型轉換](api-gateway-payload-encodings-workflow.md)。
# API Gateway 中的內容類型轉換
您的 API 的 `binaryMediaTypes`、用戶端請求中的標頭，以及整合 `contentHandling` 屬性的組合將決定 API Gateway 編碼有效承載的方式。
下表顯示 API Gateway 如何轉換請求的 `Content-Type` 標頭、[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 資源的 `binaryMediaTypes` 清單與 [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 資源的 `contentHandling` 屬性值之特定組態的請求酬載。
| 方法請求承載 | 請求 `Content-Type` 標頭 | `binaryMediaTypes` | `contentHandling` | 整合請求承載 |
| --- | --- | --- | --- | --- |
| 文字資料 | 任何資料類型 | 未定義 | 未定義 | UTF8 編碼字串 |
| 文字資料 | 任何資料類型 | 未定義 | CONVERT\$1TO\$1BINARY | Base64 解碼的二進位 Blob |
| 文字資料 | 任何資料類型 | 未定義 | CONVERT\$1TO\$1TEXT | UTF8 編碼字串 |
| 文字資料 | 文字資料類型 | 設定相符媒體類型 | 未定義 | 文字資料 |
| 文字資料 | 文字資料類型 | 設定相符媒體類型 | CONVERT\$1TO\$1BINARY | Base64 解碼的二進位 Blob |
| 文字資料 | 文字資料類型 | 設定相符媒體類型 | CONVERT\$1TO\$1TEXT | 文字資料 |
| 二進位資料 | 二進位資料類型 | 設定相符媒體類型 | 未定義 | 二進位資料 |
| 二進位資料 | 二進位資料類型 | 設定相符媒體類型 | CONVERT\$1TO\$1BINARY | 二進位資料 |
| 二進位資料 | 二進位資料類型 | 設定相符媒體類型 | CONVERT\$1TO\$1TEXT | Base64 編碼字串 |
下表顯示 API Gateway 如何轉換請求的 `Accept` 標頭、[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 資源的 `binaryMediaTypes` 清單與 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 資源的 `contentHandling` 屬性值之特定組態的回應酬載。
**重要**
當請求的 `Accept` 標頭中包含多個媒體類型時，API Gateway 只會採用第一個 `Accept` 媒體類型。如果您無法控制 `Accept` 媒體類型的順序，而且二進位內容的媒體類型不是清單中的第一個類型，您可以在 API 的 `binaryMediaTypes` 清單中新增第一個 `Accept` 媒體類型。API Gateway 將以二進位處理此清單中的所有內容類型。
例如，若要在瀏覽器中使用 `![]()
` 元素來傳送 JPEG 檔案，瀏覽器可能會在請求中傳送 `Accept:image/webp,image/*,*/*;q=0.8`。透過將 `image/webp` 新增至 `binaryMediaTypes` 清單，端點就能收到二進位格式的 JPEG 檔案。
| 整合回應承載 | 請求 `Accept` 標頭 | `binaryMediaTypes` | `contentHandling` | 方法回應承載 |
| --- | --- | --- | --- | --- |
| 文字或二進位資料 | 文字類型 | 未定義 | 未定義 | UTF8 編碼字串 |
| 文字或二進位資料 | 文字類型 | 未定義 | CONVERT\$1TO\$1BINARY | Base64 解碼的 Blob |
| 文字或二進位資料 | 文字類型 | 未定義 | CONVERT\$1TO\$1TEXT | UTF8 編碼字串 |
| 文字資料 | 文字類型 | 設定相符媒體類型 | 未定義 | 文字資料 |
| 文字資料 | 文字類型 | 設定相符媒體類型 | CONVERT\$1TO\$1BINARY | Base64 解碼的 Blob |
| 文字資料 | 文字類型 | 設定相符媒體類型 | CONVERT\$1TO\$1TEXT | UTF8 編碼字串 |
| 文字資料 | 二進位類型 | 設定相符媒體類型 | 未定義 | Base64 解碼的 Blob |
| 文字資料 | 二進位類型 | 設定相符媒體類型 | CONVERT\$1TO\$1BINARY | Base64 解碼的 Blob |
| 文字資料 | 二進位類型 | 設定相符媒體類型 | CONVERT\$1TO\$1TEXT | UTF8 編碼字串 |
| 二進位資料 | 文字類型 | 設定相符媒體類型 | 未定義 | Base64 編碼字串 |
| 二進位資料 | 文字類型 | 設定相符媒體類型 | CONVERT\$1TO\$1BINARY | 二進位資料 |
| 二進位資料 | 文字類型 | 設定相符媒體類型 | CONVERT\$1TO\$1TEXT | Base64 編碼字串 |
| 二進位資料 | 二進位類型 | 設定相符媒體類型 | 未定義 | 二進位資料 |
| 二進位資料 | 二進位類型 | 設定相符媒體類型 | CONVERT\$1TO\$1BINARY | 二進位資料 |
| 二進位資料 | 二進位類型 | 設定相符媒體類型 | CONVERT\$1TO\$1TEXT | Base64 編碼字串 |
將文字承載轉換成二進位 Blob 時，API Gateway 會假設文字資料是 Base64 編碼字串，並將二進位資料輸出為 Base64 解碼的 Blob。如果轉換失敗，它會傳回 `500` 回應，表示 API 組態錯誤。您不會為這類轉換提供對應範本，但您必須在 API 上啟用[傳遞行為](integration-passthrough-behaviors.md)。
將二進位承載轉換成文字字串時，API Gateway 一律會在二進位資料上套用 Base64 編碼。您可以為這類承載定義對應範本，但只能透過 `$input.body` 存取對應範本中的 Base64 編碼字串，如下列範例對應範本摘要所示。
```
{
"data": "$input.body"
}
```
若要傳遞二進位承載而不進行任何修改，您必須在 API 上啟用[傳遞行為](integration-passthrough-behaviors.md)。
# 使用 API Gateway 主控台啟用二進位支援
本節說明如何使用 API Gateway 主控台來啟用二進位支援。舉例來說，我們使用與 Amazon S3 整合的 API。我們將重點放在設定支援的媒體類型，以及指定應該如何處理承載的作業上。如需如何建立與 Amazon S3 整合之 API 的詳細資訊，請參閱[教學：建立 REST API 做為 Amazon S3 代理](integrating-api-with-aws-services-s3.md)。
**使用 API Gateway 主控台啟用二進位支援**
1. 設定 API 的二進位媒體類型：
1. 建立新的 API 或選擇現有的 API。在此範例中，我們將 API 命名為 `FileMan`。
1. 在主導覽面板中所選取的 API 下，選擇 **API 設定**。
1. 在 **API 設定**窗格的**二進位媒體類型**區段中，選擇**管理媒體類型**。
1. 選擇**新增二進位媒體類型**。
1. 在輸入文字欄位中，輸入必要的媒體類型，例如 **image/png**。如果需要，請重複此步驟來新增更多媒體類型。若要支援所有二進位媒體類型，請指定 `*/*`。
1. 選擇**儲存變更**。
1. 設定如何處理 API 方法的訊息承載：
1. 在 API 中建立新的資源或選擇現有的資源。在此範例中，我們使用 `/{folder}/{item}` 資源。
1. 在資源上建立新的方法或選擇現有的方法。舉例來說，我們使用與 Amazon S3 中 `GET /{folder}/{item}` 動作整合的 `Object GET` 方法。
1. 針對**內容處理**，選擇一個選項。
![\[在 API Gateway 主控台中設定 GET 方法。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png)
如果您不想要在用戶端與後端接受相同的二進位格式時轉換本文，請選擇**傳遞**。例如，當後端需要二進位請求承載以 JSON 屬性傳入時，選擇**轉換為文字**，以將二進位本文轉換成 Base64 編碼字串。此外，當用戶端提交 Base64 編碼字串且後端需要原始二進位格式時，或是當端點傳回 Base64 編碼字串且用戶端只接受二進位輸出時，選擇**轉換為二進位**。
1. 針對**請求內文傳遞**，選擇**未定義範本時 (建議)**以在請求內文上啟用傳遞行為。
您也可以選擇**永不**。這意味著 API 將拒絕 content-types 沒有對應範本的資料。
1. 在整合請求中保留傳入請求的 `Accept` 標頭。如果您將 `contentHandling` 設定為 `passthrough` 並想要在執行階段覆寫該設定，則應該這麼做。
![\[在整合請求中保留 Accept 標頭。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png)
1. 若要轉換成文字，請定義對應範本，將 Base64 編碼的二進位資料設為必要的格式。
以下是要轉換為文字的對應範本範例：
```
{
"operation": "thumbnail",
"base64Image": "$input.body"
}
```
此對應範本的格式取決於輸入的端點需求。
1. 選擇**儲存**。
# 使用 API Gateway REST API 啟用二進位支援
下列作業示範如何使用 API Gateway REST API 呼叫來啟用二進位支援。
**Topics**
+ [將支援的二進位媒體類型新增與更新至 API](#api-gateway-payload-encodings-setup-with-api-set-encodings-map)
+ [設定請求承載轉換](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding)
+ [設定回應承載轉換](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding)
+ [將二進位資料轉換成文字資料](#api-gateway-payload-encodings-convert-binary-to-string)
+ [將文字資料轉換成二進位承載](#api-gateway-payload-encodings-convert-string-to-binary)
+ [傳遞二進位承載](#api-gateway-payload-encodings-pass-binary-as-is)
## 將支援的二進位媒體類型新增與更新至 API
若要讓 API Gateway 支援新的二進位媒體類型，您必須將二進位媒體類型新增至 `RestApi` 資源的 `binaryMediaTypes` 清單。例如，若要讓 API Gateway 處理 JPEG 影像，請將 `RestApi` 請求提交至 `PATCH` 資源：
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/image~1jpeg"
}
]
}
```
`image/jpeg` 的 MIME 類型規格是 `path` 屬性值的一部分，因此會逸出為 `image~1jpeg`。
若要更新支援的二進位媒體類型，請從 `binaryMediaTypes` 資源的 `RestApi` 清單中取代或移除媒體類型。例如，若要將二進位支援從 JPEG 檔案變更為原始位元組，請對 `PATCH` 資源提交 `RestApi` 請求，如下所示。
```
PATCH /restapis/
{
"patchOperations" : [{
"op" : "replace",
"path" : "/binaryMediaTypes/image~1jpeg",
"value" : "application/octet-stream"
},
{
"op" : "remove",
"path" : "/binaryMediaTypes/image~1jpeg"
}]
}
```
## 設定請求承載轉換
如果端點需要二進位輸入，請將 `contentHandling` 資源的 `Integration` 屬性設定為 `CONVERT_TO_BINARY`。若要執行這項操作，請提交 `PATCH` 請求，如下所示：
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## 設定回應承載轉換
如果用戶端接受二進位 Blob 格式的結果，而不是從端點傳回的 Base64 編碼承載，將 `IntegrationResponse` 資源的 `contentHandling` 屬性設定為 `CONVERT_TO_BINARY`。若要這樣做，請提交 `PATCH` 請求，如下所示：
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## 將二進位資料轉換成文字資料
若要透過 API Gateway 將二進位資料做為輸入 AWS Lambda 或 Kinesis 的 JSON 屬性傳送，請執行下列動作：
1. 將 `application/octet-stream` 的新二進位媒體類型新增至 API 的 `binaryMediaTypes` 清單，以啟用 API 的二進位承載支援。
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. 在 `CONVERT_TO_TEXT` 資源的 `contentHandling` 屬性上設定 `Integration`，並提供對應範本，以將二進位資料的 Base64 編碼字串指派給 JSON 屬性。在下列範例中，JSON 屬性是持有 Base64 編碼字串的 `body` 與 `$input.body`。
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_TEXT"
},
{
"op" : "add",
"path" : "/requestTemplates/application~1octet-stream",
"value" : "{\"body\": \"$input.body\"}"
}
]
}
```
## 將文字資料轉換成二進位承載
假設 Lambda 函數會傳回 Base64 編碼字串格式的影像檔。若要透過 API Gateway 將此二進位輸出傳遞給用戶端，請執行下列操作：
1. 新增 `binaryMediaTypes` 的二進位媒體類型 (如果尚未在清單中)，以更新 API 的 `application/octet-stream` 清單。
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream",
}]
}
```
1. 將 `contentHandling` 資源上的 `Integration` 屬性設定為 `CONVERT_TO_BINARY`。請勿定義對應範本。如果您未定義映射範本，API Gateway 可呼叫傳遞範本，將 Base64 解碼的二進位 Blob 做為影像檔傳回至用戶端。
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}
]
}
```
## 傳遞二進位承載
若要使用 API Gateway 將映像儲存在 Amazon S3 儲存貯體中，請執行下列動作：
1. 新增 `binaryMediaTypes` 的二進位媒體類型 (如果尚未在清單中)，以更新 API 的 `application/octet-stream` 清單。
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. 在 `contentHandling` 資源的 `Integration` 屬性上設定 `CONVERT_TO_BINARY`。將 `WHEN_NO_MATCH` 設定為 `passthroughBehavior` 屬性值，而不需要定義對應範本。這可讓 API Gateway 叫用傳遞範本。
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
},
{
"op" : "replace",
"path" : "/passthroughBehaviors",
"value" : "WHEN_NO_MATCH"
}
]
}
```
# API Gateway 的匯入與匯出內容編碼
若要匯入 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 上的 `binaryMediaTypes` 清單，請使用 API OpenAPI 定義檔的下列 API Gateway 延伸。此延伸也可用來匯出 API 設定。
+ [x-amazon-apigateway-binary-media-types 屬性](api-gateway-swagger-extensions-binary-media-types.md)
若要匯入與匯出 `Integration` 或 `IntegrationResponse` 資源上的 `contentHandling` 屬性值，請使用 OpenAPI 定義的下列 API Gateway 延伸：
+ [x-amazon-apigateway-integration 物件](api-gateway-swagger-extensions-integration.md)
+ [x-amazon-apigateway-integration.response 物件](api-gateway-swagger-extensions-integration-response.md)
# 在 API Gateway 中從 Lambda 代理整合傳回二進位媒體
要從 [AWS Lambda 代理整合](set-up-lambda-proxy-integrations.md)傳回二進位媒體，您需要對 Lambda 函數的回應進行 base64 編碼。您還必須[配置 API 的二進位媒體類型](api-gateway-payload-encodings-configure-with-console.md)。當您設定 API 的二進位媒體類型時，API 會將該內容類型視為二進位資料。承載大小上限為 10 MB。
**注意**
若要使用網頁瀏覽器來叫用具有此範例整合的 API，請將 API 的二進位媒體類型設定為 `*/*`。API Gateway 會使用來自用戶端的第一個 `Accept` 標頭來判斷回應是否應該傳回二進位媒體。若要在無法控制 `Accept` 標頭值的順序 (例如來自瀏覽器的請求) 時傳回二進位媒體，請將 API 的二進位媒體類型設定為 `*/*` (適用於所有內容類型)。
下列範例 Lambda 函數可將二進位映像從 Amazon S3 或文字傳回給用戶端。該函數的回應會包括一個 `Content-Type` 標頭，以指示給用戶端它傳回的資料類型。該函數會有條件地在其回應中設定 `isBase64Encoded` 屬性，具體取決於它傳回的資料類型。
------
#### [ Node.js ]
```
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"
const client = new S3Client({region: 'us-east-2'});
export const handler = async (event) => {
var randomint = function(max) {
return Math.floor(Math.random() * max);
}
var number = randomint(2);
if (number == 1){
const input = {
"Bucket" : "bucket-name",
"Key" : "image.png"
}
try {
const command = new GetObjectCommand(input)
const response = await client.send(command);
var str = await response.Body.transformToByteArray();
} catch (err) {
console.error(err);
}
const base64body = Buffer.from(str).toString('base64');
return {
'headers': { "Content-Type": "image/png" },
'statusCode': 200,
'body': base64body,
'isBase64Encoded': true
}
} else {
return {
'headers': { "Content-Type": "text/html" },
'statusCode': 200,
'body': "This is text
",
}
}
}
```
------
#### [ Python ]
```
import base64
import boto3
import json
import random
s3 = boto3.client('s3')
def lambda_handler(event, context):
number = random.randint(0,1)
if number == 1:
response = s3.get_object(
Bucket='bucket-name',
Key='image.png',
)
image = response['Body'].read()
return {
'headers': { "Content-Type": "image/png" },
'statusCode': 200,
'body': base64.b64encode(image).decode('utf-8'),
'isBase64Encoded': True
}
else:
return {
'headers': { "Content-type": "text/html" },
'statusCode': 200,
'body': "This is text
",
}
```
------
若要進一步了解二進位媒體類型，請參閱[API Gateway 中 REST API 的二進位媒體類型](api-gateway-payload-encodings.md)。
# 透過 API Gateway API 存取 Amazon S3 中的二進位檔案
下列範例示範如何使用 OpenAPI 檔案來存取 Amazon S3 中的影像、如何從 Amazon S3 下載影像，以及如何將影像上傳至 Amazon S3。
**Topics**
+ [存取 Amazon S3 中影像之範例 API 的 OpenAPI 檔案](#api-gateway-content-encodings-example-image-s3-swagger-file)
+ [從 Amazon S3 下載影像](#api-gateway-content-encodings-example-download-image-from-s3)
+ [將影像上傳至 Amazon S3](#api-gateway-content-encodings-example-upload-image-to-s3)
## 存取 Amazon S3 中影像之範例 API 的 OpenAPI 檔案
下列 OpenAPI 檔案顯示一個範例 API，說明如何從 Amazon S3 下載影像檔，以及如何將影像檔上傳至 Amazon S3。此 API 會公開用於下載及上傳指定影像檔的 `GET /s3?key={file-name}` 與 `PUT /s3?key={file-name}` 方法。`GET` 方法會在「200 OK」回應中，將 Base64 編碼字串格式的影像檔當作 JSON 輸出的一部分傳回，後面接著所提供的映射範本。`PUT` 方法接受原始二進位 Blob 作為輸入，並傳回「200 OK」回應與空的承載。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/s3": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling": "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/s3": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200" }
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling" : "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## 從 Amazon S3 下載影像
從 Amazon S3 下載二進位 Blob 格式的影像檔 (`image.jpg`)：
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
成功回應如下所示：
```
200 OK HTTP/1.1
[raw bytes]
```
由於 `Accept` 標頭已設定為 `application/octet-stream` 的二進位媒體類型，而且啟用 API 的二進位支援，因此會傳回原始位元組。
或者，若要從 Amazon S3 下載 Base64 編碼字串 (格式化為 JSON 屬性) 格式的影像檔 (`image.jpg`)，請將回應範本新增至 200 整合回應，如下列粗體 OpenAPI 定義區塊所示：
```
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
},
```
要下載影像檔的請求如下所示：
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
成功回應如下所示：
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## 將影像上傳至 Amazon S3
將二進位 Blob 格式的影像檔 (`image.jpg`) 上傳至 Amazon S3：
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
成功回應如下所示：
```
200 OK HTTP/1.1
```
將 Base64 編碼字串格式的影像檔 (`image.jpg`) 上傳至 Amazon S3：
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
輸入承載必須是 Base64 編碼字串，因為 `Content-Type` 標頭值已設定為 `application/json`。成功回應如下所示：
```
200 OK HTTP/1.1
```
# 使用 API Gateway API 存取 Lambda 中的二進位檔案
下列 OpenAPI 範例示範如何 AWS Lambda 透過 API Gateway API 存取 中的二進位檔案。此 API 會公開用於下載及上傳指定影像檔的 `GET /lambda?key={file-name}` 與 `PUT /lambda?key={file-name}` 方法。`GET` 方法會在「200 OK」回應中，將 Base64 編碼字串格式的影像檔當作 JSON 輸出的一部分傳回，後面接著所提供的映射範本。`PUT` 方法接受原始二進位 Blob 作為輸入，並傳回「200 OK」回應與空的承載。
您建立 API 呼叫的 Lambda 函數，而該函數必須傳回具有 `application/json` 的 `Content-Type` 標頭的 base64 編碼字串。
**Topics**
+ [存取 Lambda 中影像之範例 API 的 OpenAPI 檔案](#api-gateway-content-encodings-example-image-lambda-swagger-file)
+ [從 Lambda 下載影像](#api-gateway-content-encodings-example-download-image-from-lambda)
+ [將影像上傳至 Lambda](#api-gateway-content-encodings-example-upload-image-to-lambda)
## 存取 Lambda 中影像之範例 API 的 OpenAPI 檔案
下列 OpenAPI 檔案顯示一個範例 API，說明如何從 Lambda 下載影像檔，以及如何將影像檔上傳至 Lambda。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/lambda": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling": "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/lambda": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling" : "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## 從 Lambda 下載影像
從 Lambda 下載二進位 Blob 格式的影像檔 (`image.jpg`)：
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
成功回應如下所示：
```
200 OK HTTP/1.1
[raw bytes]
```
從 Lambda 下載 Base64 編碼字串格式的影像檔 (`image.jpg`) 並格式化為 JSON 屬性：
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
成功回應如下所示：
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## 將影像上傳至 Lambda
將二進位 Blob 格式的影像檔 (`image.jpg`) 上傳至 Lambda：
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
成功回應如下所示：
```
200 OK
```
將 Base64 編碼字串格式的影像檔 (`image.jpg`) 上傳至 Lambda：
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
成功回應如下所示：
```
200 OK
```
# 在 API Gateway 中調用 REST API
若要呼叫已部署的 API，用戶端會將請求提交至 API Gateway 元件服務的 URL 以執行 API (也稱為 `execute-api`)。
REST API 的基本 URL 格式如下所示：
```
https://api-id.execute-api.region.amazonaws.com/stage/
```
其中 *api-id* 是 API 識別碼，*region* 是 AWS 區域，而 *stage* 是 API 部署的階段名稱。
**重要**
在您可以叫用 API 之前，您必須先在 API Gateway 中部署 API。如需有關部署 API 的指示，請參閱[在 API Gateway 中部署 REST API](how-to-deploy-api.md)。
**Topics**
+ [取得 API 的調用 URL](#apigateway-how-to-call-rest-api)
+ [呼叫 API](#apigateway-call-api)
+ [使用 API Gateway 主控台來測試 REST API 方法](how-to-test-method.md)
+ [使用由 API Gateway 產生的 Java 軟體開發套件來執行 REST API](how-to-call-apigateway-generated-java-sdk.md)
+ [使用由 API Gateway 為 REST API 產生的 Android 軟體開發套件](how-to-generate-sdk-android.md)
+ [使用 API Gateway 為 REST API 所產生的 JavaScript 軟體開發套件](how-to-generate-sdk-javascript.md)
+ [使用由 API Gateway 為 REST API 產生的 Ruby 軟體開發套件](how-to-call-sdk-ruby.md)
+ [在 Objective-C 或 Swift 中使用 API Gateway 為 REST API 產生的 iOS 軟體開發套件](how-to-generate-sdk-ios.md)
## 取得 API 的調用 URL
您可以使用主控台 AWS CLI，或匯出的 OpenAPI 定義來取得 API 的調用 URL。
### 使用主控台取得 API 的調用 URL
下列程序顯示如何在 REST API 主控台取得 API 的調用 URL。
**使用 REST API 主控台取得 API 的調用 URL**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇部署的 API。
1. 從主導覽窗格選擇**階段**。
1. 在**階段詳細資訊**下，選擇複製圖示以複製 API 的調用 URL。
此 URL 適用於 API 的根資源。
![\[在建立 REST API 之後，主控台會顯示 API 的調用 URL。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png)
1. 若要取得 API 中另一個資源的 API 調用 URL，請展開次要導覽窗格下的階段，然後選擇某個方法。
1. 選擇複製圖示以複製 API 的資源層級調用 URL。
![\[REST API 的資源層級 URL 位於階段的次要導覽窗格下。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/resource-level-invoke-url.png)
#### 使用 AWS CLI 取得 API 的調用 URL
下列程序顯示如何使用 AWS CLI 取得 API 的調用 URL。
**使用 AWS CLI 取得 API 的調用 URL**
1. 使用下列命令以取得 `rest-api-id`。此命令會傳回您區域中的所有 `rest-api-id` 值。如需詳細資訊，請參閱 [get-rest-apis](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-rest-apis.html)。
```
aws apigateway get-rest-apis
```
1. 將範例 `rest-api-id` 取代為您的 `rest-api-id`，將範例 *\$1stage-name\$1* 取代為您的 *\$1stage-name\$1*，並將 *\$1region\$1* 取代為您的區域。
```
https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/
```
##### 使用 API 的匯出 OpenAPI 定義檔以取得 API 的調用 URL
您也可以合併 API 之已匯出 OpenAPI 定義檔的 `host` 與 `basePath` 欄位，藉以建構根 URL。如需有關如何匯出 API 的指示，請參閱 [從 API Gateway 匯出 REST API](api-gateway-export-api.md)。
## 呼叫 API
您可以使用瀏覽器、curl 或其他應用程式 (例如 [Postman](https://www.postman.com/)) 呼叫已部署的 API。
此外，您可以使用 API Gateway 主控台來測試 API 呼叫。測試時會使用 API Gateway 的 `TestInvoke` 功能，其允許在部署 API 之前進行 API 測試。如需更多詳細資訊，請參閱 [使用 API Gateway 主控台來測試 REST API 方法](how-to-test-method.md)。
**注意**
引動過程 URL 中的查詢字串參數值不能包含 `%%`。
### 使用 Web 瀏覽器調用 API
如果您的 API 允許匿名存取，您可以使用任何 Web 瀏覽器來調用任何 `GET` 方法。在瀏覽器的位址列中輸入完整的調用 URL。
對於其他方法或任何需要驗證的呼叫，您必須指定承載或簽署請求。您可以使用其中一個 AWS 軟體開發套件，在 HTML 頁面或用戶端應用程式後方的指令碼中處理這些作業。
#### 使用 curl 調用 API
您可以使用終端機中的 [curl](https://curl.se/) 等工具來呼叫 API。下列範例 curl 命令會在 API `prod` 階段的 `getUsers` 資源上調用 GET 方法。
------
#### [ Linux or Macintosh ]
```
curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
```
------
#### [ Windows ]
```
curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers"
```
------
# 使用 API Gateway 主控台來測試 REST API 方法
使用 API Gateway 主控台來測試 REST API 方法。
**Topics**
+ [先決條件](#how-to-test-method-prerequisites)
+ [使用 API Gateway 主控台測試方法](#how-to-test-method-console)
## 先決條件
+ 您必須指定所要測試之方法的設定。請遵循中的說明進行[API Gateway 中 REST API 的方法](how-to-method-settings.md)
## 使用 API Gateway 主控台測試方法
**重要**
使用 API Gateway 主控台測試方法可能會對資源產生無法復原的變更。使用 API Gateway 主控台測試方法與在 API Gateway 主控台之外呼叫方法是相同的。例如，如果您使用 API Gateway 主控台呼叫刪除 API 資源的方法，當方法呼叫成功時，將會刪除 API 的資源。
**若要測試方法**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 REST API。
1. 在 **Resources (資源)** 窗格中，選擇您要測試的方法。
1. 選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
![\[使用測試標籤來測試您的 API。其位於方法回應標籤旁。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-test-new-console.png)
在顯示的任何方塊 (例如**查詢字串**、**標頭**和**請求內文**) 中輸入值。主控台預設應用程式/json 表單中的方法要求包含這些值。
如要了解可能需要指定的其他選項，請聯絡 API 擁有者。
1. 選擇 **Test (測試)**。下列資訊會隨即顯示：
+ **Request (請求)** 是針對方法所呼叫的資源路徑。
+ **Status (狀態)** 是回應的 HTTP 狀態碼。
+ **延遲 (ms)** 是從呼叫者收到請求，到傳回回應之間的時間。
+ **回應內文**是 HTTP 回應內文。
+ **回應標頭**是 HTTP 回應標頭。
**提示**
根據映射，HTTP 狀態碼、回應內文與回應標頭可能會與 Lambda 函數、HTTP 代理或 AWS 服務代理所傳送的內容不同。
+ **Logs (日誌)** 是模擬的 Amazon CloudWatch Logs 項目，如果在 API Gateway 主控台之外呼叫此方法，將會寫入該項目。
**注意**
雖然 CloudWatch Logs 項目是模擬的，但方法呼叫的結果是真實的。
除了使用 API Gateway 主控台之外，您還可以使用適用於 API Gateway 的 AWS CLI 或 AWS 軟體開發套件來測試方法的叫用。若要使用 AWS CLI 來執行這項操作，請參閱 [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html)。
# 使用由 API Gateway 產生的 Java 軟體開發套件來執行 REST API
在本節中，我們以[簡易計算機](simple-calc-lambda-api-swagger-definition.md) API 為例，概述使用 API Gateway 為 REST API 所產生之 Java 軟體開發套件的步驟。繼續之前，您必須完成[在 API Gateway 中為 REST API 產生 SDK](how-to-generate-sdk.md)中的步驟。
**安裝及使用 API Gateway 所產生的 Java 軟體開發套件**
1. 將您稍早下載之 API Gateway 所產生的 .zip 檔案內容解壓縮。
1. 下載並安裝 [Apache Maven](https://maven.apache.org/) (必須是 3.5 版或更新版本)。
1. 下載並安裝 [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)。
1. 設定 `JAVA_HOME` 環境變數。
1. 前往存放 pom.xml 檔案的解壓縮開發套件資料夾。此資料夾預設為 `generated-code`。執行 **mvn install** 命令，將已編譯的成品檔案安裝到您的本機 Maven 儲存庫。這會建立 `target` 資料夾，其中包含已編譯的開發套件程式庫。
1. 在空目錄中輸入下列命令建立用戶端專案 Stub，以使用安裝的開發套件程式庫呼叫 API。
```
mvn -B archetype:generate \
-DarchetypeGroupdId=org.apache.maven.archetypes \
-DgroupId=examples.aws.apig.simpleCalc.sdk.app \
-DartifactId=SimpleCalc-sdkClient
```
**注意**
上述命令中加入了分隔符號 `\` 以利閱讀。整個命令應該放在一行且不使用分隔符號。
此命令會建立應用程式 Stub。應用程式 Stub 在專案根目錄 (上述命令中的 *SimpleCalc-sdkClient*) 下包含 `pom.xml` 檔案與 `src` 資料夾。一開始有兩個來源檔案：`src/main/java/{package-path}/App.java` 與 `src/test/java/{package-path}/AppTest.java`。在此範例中，*\$1package-path\$1* 是 `examples/aws/apig/simpleCalc/sdk/app`。此套件路徑衍生自 `DarchetypeGroupdId` 值。您可以使用 `App.java` 檔案作為用戶端應用程式的範本，而且您可以視需要在相同的資料夾中新增其他檔案。您可以使用 `AppTest.java` 檔案作為應用程式的單元測試範本，而且您可以視需要將其他測試程式碼檔案新增至相同的測試資料夾。
1. 將所產生 `pom.xml` 檔案中的套件相依性更新為以下內容，並視需要替代成您專案的 `groupId`、`artifactId`、`version` 與 `name` 屬性：
```
4.0.0
examples.aws.apig.simpleCalc.sdk.app
SimpleCalc-sdkClient
jar
1.0-SNAPSHOT
SimpleCalc-sdkClient
http://maven.apache.org
com.amazonaws
aws-java-sdk-core
1.11.94
my-apig-api-examples
simple-calc-sdk
1.0.0
junit
junit
4.12
test
commons-io
commons-io
2.5
org.apache.maven.plugins
maven-compiler-plugin
3.5.1
1.8
1.8
```
**注意**
如果 `aws-java-sdk-core` 的相依成品有較新版本與以上指定的版本 (`1.11.94`) 不相容，則必須將 `` 標籤更新為較新版本。
1. 接下來，我們將示範如何透過呼叫開發套件的 `getABOp(GetABOpRequest req)`、`getApiRoot(GetApiRootRequest req)` 與 `postApiRoot(PostApiRootRequest req)` 方法，使用開發套件來呼叫 API。這些方法分別對應到具有 `GET /{a}/{b}/{op}` API 請求承載的 `GET /?a={x}&b={y}&op={operator}`、`POST /` 與 `{"a": x, "b": y, "op": "operator"}` 方法。
請更新 `App.java` 檔案如下：
```
package examples.aws.apig.simpleCalc.sdk.app;
import java.io.IOException;
import com.amazonaws.opensdk.config.ConnectionConfiguration;
import com.amazonaws.opensdk.config.TimeoutConfiguration;
import examples.aws.apig.simpleCalc.sdk.*;
import examples.aws.apig.simpleCalc.sdk.model.*;
import examples.aws.apig.simpleCalc.sdk.SimpleCalcSdk.*;
public class App
{
SimpleCalcSdk sdkClient;
public App() {
initSdk();
}
// The configuration settings are for illustration purposes and may not be a recommended best practice.
private void initSdk() {
sdkClient = SimpleCalcSdk.builder()
.connectionConfiguration(
new ConnectionConfiguration()
.maxConnections(100)
.connectionMaxIdleMillis(1000))
.timeoutConfiguration(
new TimeoutConfiguration()
.httpRequestTimeout(3000)
.totalExecutionTimeout(10000)
.socketTimeout(2000))
.build();
}
// Calling shutdown is not necessary unless you want to exert explicit control of this resource.
public void shutdown() {
sdkClient.shutdown();
}
// GetABOpResult getABOp(GetABOpRequest getABOpRequest)
public Output getResultWithPathParameters(String x, String y, String operator) {
operator = operator.equals("+") ? "add" : operator;
operator = operator.equals("/") ? "div" : operator;
GetABOpResult abopResult = sdkClient.getABOp(new GetABOpRequest().a(x).b(y).op(operator));
return abopResult.getResult().getOutput();
}
public Output getResultWithQueryParameters(String a, String b, String op) {
GetApiRootResult rootResult = sdkClient.getApiRoot(new GetApiRootRequest().a(a).b(b).op(op));
return rootResult.getResult().getOutput();
}
public Output getResultByPostInputBody(Double x, Double y, String o) {
PostApiRootResult postResult = sdkClient.postApiRoot(
new PostApiRootRequest().input(new Input().a(x).b(y).op(o)));
return postResult.getResult().getOutput();
}
public static void main( String[] args )
{
System.out.println( "Simple calc" );
// to begin
App calc = new App();
// call the SimpleCalc API
Output res = calc.getResultWithPathParameters("1", "2", "-");
System.out.printf("GET /1/2/-: %s\n", res.getC());
// Use the type query parameter
res = calc.getResultWithQueryParameters("1", "2", "+");
System.out.printf("GET /?a=1&b=2&op=+: %s\n", res.getC());
// Call POST with an Input body.
res = calc.getResultByPostInputBody(1.0, 2.0, "*");
System.out.printf("PUT /\n\n{\"a\":1, \"b\":2,\"op\":\"*\"}\n %s\n", res.getC());
}
}
```
在上述範例中，用來執行個體化開發套件用戶端的組態設定僅供說明，不一定是建議的最佳實務。此外，呼叫 `sdkClient.shutdown()` 是選擇性的，特別是如果您需要精確控制何時釋放資源。
我們已示範使用 Java 開發套件呼叫 API 的基本模式。您可以延伸說明來呼叫其他 API 方法。
# 使用由 API Gateway 為 REST API 產生的 Android 軟體開發套件
在本節中，我們將概述使用 API Gateway 為 REST API 所產生之 Android 軟體開發套件的步驟。您必須已完成[在 API Gateway 中為 REST API 產生 SDK](how-to-generate-sdk.md)中的步驟，才能繼續往下進行。
**注意**
所產生的開發套件與 Android 4.4 (含) 以前的版本不相容。如需詳細資訊，請參閱 [Amazon API Gateway 重要說明](api-gateway-known-issues.md)。
**安裝及使用 API Gateway 所產生的 Android 軟體開發套件**
1. 將您稍早下載之 API Gateway 所產生的 .zip 檔案內容解壓縮。
1. 下載並安裝 [Apache Maven](https://maven.apache.org/) (最好是 3.x 版)。
1. 下載並安裝 [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)。
1. 設定 `JAVA_HOME` 環境變數。
1. 執行 **mvn install** 命令，將已編譯的成品檔案安裝到您的本機 Maven 儲存庫。這會建立 `target` 資料夾，其中包含已編譯的開發套件程式庫。
1. 將 `target` 資料夾中的開發套件檔案 (其名稱衍生自您在產生開發套件時所指定的 **Artifact Id** (成品 ID) 與 **Artifact Version** (成品版本)，例如 `simple-calcsdk-1.0.0.jar`)，連同 `target/lib` 資料夾中的所有其他程式庫，一起複製到您專案的 `lib` 資料夾中。
如果您使用 Android Studio，請在您的用戶端應用程式模組下建立一個 `libs` 資料夾，然後將必要的 .jar 檔案複製到此資料夾中。確認模組之 Gradle 檔案中的相依性區段包含以下內容。
```
compile fileTree(include: ['*.jar'], dir: 'libs')
compile fileTree(include: ['*.jar'], dir: 'app/libs')
```
確定未宣告重複的 .jar 檔案。
1. 使用 `ApiClientFactory` 類別來初始化 API Gateway 產生的軟體開發套件。例如：
```
ApiClientFactory factory = new ApiClientFactory();
// Create an instance of your SDK. Here, 'SimpleCalcClient.java' is the compiled java class for the SDK generated by API Gateway.
final SimpleCalcClient client = factory.build(SimpleCalcClient.class);
// Invoke a method:
// For the 'GET /?a=1&b=2&op=+' method exposed by the API, you can invoke it by calling the following SDK method:
Result output = client.rootGet("1", "2", "+");
// where the Result class of the SDK corresponds to the Result model of the API.
//
// For the 'GET /{a}/{b}/{op}' method exposed by the API, you can call the following SDK method to invoke the request,
Result output = client.aBOpGet(a, b, c);
// where a, b, c can be "1", "2", "add", respectively.
// For the following API method:
// POST /
// host: ...
// Content-Type: application/json
//
// { "a": 1, "b": 2, "op": "+" }
// you can call invoke it by calling the rootPost method of the SDK as follows:
Input body = new Input();
input.a=1;
input.b=2;
input.op="+";
Result output = client.rootPost(body);
// where the Input class of the SDK corresponds to the Input model of the API.
// Parse the result:
// If the 'Result' object is { "a": 1, "b": 2, "op": "add", "c":3"}, you retrieve the result 'c') as
String result=output.c;
```
1. 若要使用 Amazon Cognito 憑證提供者授權呼叫您的 API，請使用 `ApiClientFactory` 類別透過 API Gateway 所產生的軟體開發套件來傳遞一組 AWS 憑證，如下列範例所示。
```
// Use CognitoCachingCredentialsProvider to provide AWS credentials
// for the ApiClientFactory
AWSCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider(
context, // activity context
"identityPoolId", // Cognito identity pool id
Regions.US_EAST_1 // region of Cognito identity pool
);
ApiClientFactory factory = new ApiClientFactory()
.credentialsProvider(credentialsProvider);
```
1. 若要使用 API Gateway 所產生的軟體開發套件來設定 API 金鑰，請使用類似如下的程式碼。
```
ApiClientFactory factory = new ApiClientFactory()
.apiKey("YOUR_API_KEY");
```
# 使用 API Gateway 為 REST API 所產生的 JavaScript 軟體開發套件
下列程序顯示如何使用 API Gateway 產生的 JavaScript SDK。
**注意**
這些說明假設您已完成[在 API Gateway 中為 REST API 產生 SDK](how-to-generate-sdk.md)中的指示。
**重要**
如果您的 API 只定義了 ANY 方法，則產生的軟體開發套件將不會包含 `apigClient.js` 檔案，而且您將需要自行定義 ANY 方法。
**安裝、啟動及呼叫 API Gateway 為 REST API 所產生的 JavaScript 軟體開發套件**
1. 將您稍早下載之 API Gateway 所產生的 .zip 檔案內容解壓縮。
1. 針對 API Gateway 所產生之軟體開發套件將會呼叫的所有方法，啟用跨來源資源分享 (CORS)。如需說明，請參閱[API Gateway 中 REST API 的 CORS](how-to-cors.md)。
1. 在您的網頁中，包含下列指令碼的參考。
```
```
1. 在您的程式碼中，使用類似如下的程式碼來初始化 API Gateway 所產生的軟體開發套件。
```
var apigClient = apigClientFactory.newClient();
```
若要使用 AWS 登入資料初始化 API Gateway 產生的 SDK，請使用類似以下的程式碼。如果您使用 AWS 登入資料，對 API 的所有請求都會簽署。
```
var apigClient = apigClientFactory.newClient({
accessKey: 'ACCESS_KEY',
secretKey: 'SECRET_KEY',
});
```
若要搭配 API Gateway 所產生的軟體開發套件使用 API 金鑰，請使用類似如下的程式碼，將 API 金鑰當做參數傳遞給 `Factory` 物件。如果您使用 API 金鑰，則會將它指定為 `x-api-key` 標頭的一部分，而且 API 的所有請求都會經過簽署。這表示您必須為每個請求設定適當的 CORS Accept 標頭。
```
var apigClient = apigClientFactory.newClient({
apiKey: 'API_KEY'
});
```
1. 使用類似如下的程式碼，在 API Gateway 中呼叫 API 方法。每個呼叫會傳回成功與失敗回呼的結果。
```
var params = {
// This is where any modeled request parameters should be added.
// The key is the parameter name, as it is defined in the API in API Gateway.
param0: '',
param1: ''
};
var body = {
// This is where you define the body of the request,
};
var additionalParams = {
// If there are any unmodeled query parameters or headers that must be
// sent with the request, add them here.
headers: {
param0: '',
param1: ''
},
queryParams: {
param0: '',
param1: ''
}
};
apigClient.methodName(params, body, additionalParams)
.then(function(result){
// Add success callback code here.
}).catch( function(result){
// Add error callback code here.
});
```
此處，*methodName* 是從方法請求的資源路徑與 HTTP 動詞建構而來。對於 SimpleCalc API，開發套件方法用於 API 方法
```
1. GET /?a=...&b=...&op=...
2. POST /
{ "a": ..., "b": ..., "op": ...}
3. GET /{a}/{b}/{op}
```
對應的開發套件方法如下所示：
```
1. rootGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the query parameters
2. rootPost(null, body); // where body={"a": ..., "b": ..., "op": ...}
3. aBOpGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the path parameters
```
# 使用由 API Gateway 為 REST API 產生的 Ruby 軟體開發套件
下列程序顯示如何使用 API Gateway 產生的 Ruby SDK。
**注意**
這些說明假設您已完成「[在 API Gateway 中為 REST API 產生 SDK](how-to-generate-sdk.md)」中的說明。
**安裝、執行個體化和呼叫 API Gateway 為 REST API 產生的 Ruby 軟體開發套件**
1. 解壓縮下載的 Ruby 開發套件檔案。產生的開發套件來源如下所示。
![\[將下載的 Ruby 開發套件檔案解壓縮到 Ruby 模組\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/ruby-gem-of-generated-sdk-for-simplecalc.png)
1. 在終端機視窗中使用以下 shell 命令，從產生的開發套件來源建立 Ruby Gem：
```
# change to /simplecalc-sdk directory
cd simplecalc-sdk
# build the generated gem
gem build simplecalc-sdk.gemspec
```
在此之後，**simplecalc-sdk-1.0.0.gem** 即可使用。
1. 安裝 gem：
```
gem install simplecalc-sdk-1.0.0.gem
```
1. 建立用戶端應用程式。在應用程式中執行個體化和初始化 Ruby 開發套件用戶端：
```
require 'simplecalc-sdk'
client = SimpleCalc::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50
)
```
如果 API 已設定 `AWS_IAM`類型的授權，您可以在初始化`secretKey`期間提供 `accessKey`和 來包含發起人的 AWS 登入資料：
```
require 'pet-sdk'
client = Pet::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50,
access_key_id: 'ACCESS_KEY',
secret_access_key: 'SECRET_KEY'
)
```
1. 在應用程式中透過開發套件呼叫 API。
**提示**
如果您不熟悉開發套件方法呼叫慣例，您可以參閱產生的開發套件 `client.rb` 資料夾中的 `lib` 檔案。此資料夾包含每個受支援 API 方法呼叫的文件。
探索受支援的操作：
```
# to show supported operations:
puts client.operation_names
```
這會產生以下顯示畫面，分別對應到 `GET /?a={.}&b={.}&op={.}`、`GET /{a}/{b}/{op}` 和 `POST /` 的 API 方法，加上 `{a:"…", b:"…", op:"…"}` 格式的承載：
```
[:get_api_root, :get_ab_op, :post_api_root]
```
若要呼叫 `GET /?a=1&b=2&op=+` API 方法，請呼叫以下 Ruby 開發套件方法：
```
resp = client.get_api_root({a:"1", b:"2", op:"+"})
```
若要呼叫 `POST /` API 方法加上 `{a: "1", b: "2", "op": "+"}` 承載，請呼叫以下 Ruby 開發套件方法：
```
resp = client.post_api_root(input: {a:"1", b:"2", op:"+"})
```
若要呼叫 `GET /1/2/+` API 方法，請呼叫以下 Ruby 開發套件方法：
```
resp = client.get_ab_op({a:"1", b:"2", op:"+"})
```
成功的開發套件方法呼叫傳回以下回應：
```
resp : {
result: {
input: {
a: 1,
b: 2,
op: "+"
},
output: {
c: 3
}
}
}
```
# 在 Objective-C 或 Swift 中使用 API Gateway 為 REST API 產生的 iOS 軟體開發套件
在本教學中，我們會示範如何在 Objective-C 或 Swift 應用程式中，使用 API Gateway 為 REST API 產生的 iOS 軟體開發套件，以呼叫基礎 API。我們會以 [SimpleCalc API](simple-calc-lambda-api.md) 為例，說明下列主題：
+ 如何在 Xcode 專案中安裝所需的 AWS Mobile SDK 元件
+ 如何在呼叫 API 的方法前，先建立 API 用戶端物件
+ 如何透過 API 用戶端物件上對應的開發套件方法呼叫 API 方法
+ 如何使用開發套件的對應模型類別準備方法輸入和剖析其結果
**Topics**
+ [使用產生的 iOS 開發套件 (Objective-C) 呼叫 API](#how-to-use-sdk-ios-objc)
+ [使用產生的 iOS 開發套件 (Swift) 呼叫 API](#how-to-generate-sdk-ios-swift)
## 使用產生的 iOS 開發套件 (Objective-C) 呼叫 API
開始下列程序之前，您必須先在 Objective-C 中完成[在 API Gateway 中為 REST API 產生 SDK](how-to-generate-sdk.md)中的 iOS 步驟，並下載已產生之軟體開發套件的 .zip 檔案。
### 在 Objective-C 專案中安裝由 API Gateway 產生的 AWS 行動 SDK 和 iOS SDK
下列程序說明如何安裝開發套件。
**安裝和使用 API Gateway 在 Objective-C 中產生的 iOS 軟體開發套件**
1. 將您稍早下載之 API Gateway 所產生的 .zip 檔案內容解壓縮。使用 [SimpleCalc API](simple-calc-lambda-api.md)，您可能希望將解壓縮的開發套件資料夾重新命名成類似 **sdk\$1objc\$1simple\$1calc**。在這個開發套件資料夾中，有 `README.md` 檔案和 `Podfile` 檔案。`README.md` 檔案包含開發套件的安裝和使用說明。本教學提供這些說明的詳細資訊。安裝利用 [CocoaPods](https://cocoapods.org) 匯入所需的 API Gateway 程式庫和其他相依 AWS 的 Mobile SDK 元件。您必須更新 `Podfile`，將開發套件匯入至您應用程式的 Xcode 專案。未封存的開發套件資料夾也包含 `generated-src` 資料夾，其中包含 API 之已產生開發套件的原始程式碼。
1. 啟動 Xcode 並建立新的 iOS Objective-C 專案。請記下專案的目標。您需要在 `Podfile` 中設定它。
![\[在 Xcode 中尋找目標。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-find-target.png)
1. 若要使用 CocoaPods AWS Mobile SDK for iOS 將 匯入 Xcode 專案，請執行下列動作：
1. 在終端機視窗中執行下列命令來安裝 CocoaPods：
```
sudo gem install cocoapods
pod setup
```
1. 將 `Podfile` 檔案從解壓縮開發套件資料夾複製至包含 Xcode 專案檔的相同目錄。將下列區塊：
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
使用您專案的目標名稱：
```
target 'app_objc_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
如果您的 Xcode 專案已包含一個名為 `Podfile` 的檔案，請將下行程式碼新增到此檔案：
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. 開啟終端機視窗並執行下列命令：
```
pod install
```
這會安裝 API Gateway 元件和其他相依的 AWS Mobile SDK 元件。
1. 關閉 Xcode 專案，然後開啟 `.xcworkspace` 檔案重新啟動 Xcode。
1. 從解壓縮的開發套件 `.h` 目錄將所有的 `.m` 和 `generated-src` 檔案新增到您的 Xcode 專案。
![\[.h 和 .m 檔案位於產生的來源中\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-add-sdk-src.png)
若要透過明確下載 AWS Mobile SDK 或使用 [Carthage](https://github.com/Carthage/Carthage#installing-carthage) 將 AWS Mobile SDK for iOS Objective-C 匯入您的專案，請遵循 *README.md* 檔案中的指示。請務必僅使用其中一個選項來匯入 AWS Mobile SDK。
### 使用 Objective-C 專案中 API Gateway 產生的 iOS 軟體開發套件呼叫 API 方法
當您使用兩個模型來處理這些方法的輸入 (`SIMPLE_CALC`) 和輸出 (`Input`)，為這個 [SimpleCalc API](simple-calc-lambda-api.md) 產生字首為 `Result` 的開發套件後，在開發套件中，產生的 API 用戶端類別會變為 `SIMPLE_CALCSimpleCalcClient`，而對應的資料類別則會分別成為 `SIMPLE_CALCInput` 和 `SIMPLE_CALCResult`。API 請求和回應會對應至開發套件方法，如下所示：
+ 下列的 API 請求：
```
GET /?a=...&b=...&op=...
```
會成為下列的開發套件方法：
```
(AWSTask *)rootGet:(NSString *)op a:(NSString *)a b:(NSString *)b
```
如果 `AWSTask.result` 模型已新增至方法回應，則 `SIMPLE_CALCResult` 屬性為 `Result` 類型。否則，屬性為 `NSDictionary` 類型。
+ 下列的此 API 請求：
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
會成為下列的開發套件方法：
```
(AWSTask *)rootPost:(SIMPLE_CALCInput *)body
```
+ 下列的 API 請求：
```
GET /{a}/{b}/{op}
```
會成為下列的開發套件方法：
```
(AWSTask *)aBOpGet:(NSString *)a b:(NSString *)b op:(NSString *)op
```
下列程序說明如何在 Objective-C 應用程式原始碼中呼叫 API 方法；例如，在 `viewDidLoad` 檔案中作為 `ViewController.m` 委派的一部分。
**透過 API Gateway 所產生的 iOS 軟體開發套件來呼叫 API**
1. 匯入 API 用戶端類別標頭檔案，以能在應用程式中呼叫 API 用戶端類別：
```
#import "SIMPLE_CALCSimpleCalc.h"
```
`#import` 陳述式也針對兩個模型類別匯入 `SIMPLE_CALCInput.h` 和 `SIMPLE_CALCResult.h`。
1. 將 API 用戶端類別執行個體化：
```
SIMPLE_CALCSimpleCalcClient *apiInstance = [SIMPLE_CALCSimpleCalcClient defaultClient];
```
若要使用 Amazon Cognito 與 API，請先在預設的 `AWSServiceManager` 物件上設定 `defaultServiceConfiguration` 屬性，如下所示，然後呼叫 `defaultClient` 方法以建立 API 用戶端物件 (如前例所示)：
```
AWSCognitoCredentialsProvider *creds = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:your_cognito_pool_id];
AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:creds];
AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration;
```
1. 呼叫 `GET /?a=1&b=2&op=+` 方法來執行 `1+2`：
```
[[apiInstance rootGet: @"+" a:@"1" b:@"2"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField1.text = [self handleApiResponse:task];
return nil;
}];
```
協助程式函數 `handleApiResponse:task` 會在此將結果格式化為字串並顯示在文字欄位中 (`_textField1`)。
```
- (NSString *)handleApiResponse:(AWSTask *)task {
if (task.error != nil) {
return [NSString stringWithFormat: @"Error: %@", task.error.description];
} else if (task.result != nil && [task.result isKindOfClass:[SIMPLE_CALCResult class]]) {
return [NSString stringWithFormat:@"%@ %@ %@ = %@\n",task.result.input.a, task.result.input.op, task.result.input.b, task.result.output.c];
}
return nil;
}
```
產生的顯示畫面為 `1 + 2 = 3`。
1. 呼叫具有承載的 `POST /` 來執行 `1-2`：
```
SIMPLE_CALCInput *input = [[SIMPLE_CALCInput alloc] init];
input.a = [NSNumber numberWithInt:1];
input.b = [NSNumber numberWithInt:2];
input.op = @"-";
[[apiInstance rootPost:input] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField2.text = [self handleApiResponse:task];
return nil;
}];
```
產生的顯示畫面為 `1 - 2 = -1`。
1. 呼叫 `GET /{a}/{b}/{op}` 來執行 `1/2`：
```
[[apiInstance aBOpGet:@"1" b:@"2" op:@"div"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField3.text = [self handleApiResponse:task];
return nil;
}];
```
產生的顯示畫面為 `1 div 2 = 0.5`。在此，`div` 用來代替 `/`，因為後端的[簡單 Lambda 函數](simple-calc-nodejs-lambda-function.md)不處理 URL 編碼的路徑變數。
## 使用產生的 iOS 開發套件 (Swift) 呼叫 API
開始下列程序之前，您必須先在 Swift 中完成[在 API Gateway 中為 REST API 產生 SDK](how-to-generate-sdk.md)中的 iOS 步驟，並下載已產生之軟體開發套件的 .zip 檔案。
**Topics**
+ [在 Swift 專案中安裝 AWS 行動 SDK 和 API Gateway 產生的 SDK](#use-sdk-ios-swift-install-sdk)
+ [在 Swift 專案中透過 API Gateway 所產生的 iOS 軟體開發套件來呼叫 API 方法](#use-sdk-ios-swift-call-api)
### 在 Swift 專案中安裝 AWS 行動 SDK 和 API Gateway 產生的 SDK
下列程序說明如何安裝開發套件。
**安裝和使用 API Gateway 在 Swift 中產生的 iOS 軟體開發套件**
1. 將您稍早下載之 API Gateway 所產生的 .zip 檔案內容解壓縮。使用 [SimpleCalc API](simple-calc-lambda-api.md)，您可能希望將解壓縮的開發套件資料夾重新命名成類似 **sdk\$1swift\$1simple\$1calc**。在這個開發套件資料夾中，有 `README.md` 檔案和 `Podfile` 檔案。`README.md` 檔案包含開發套件的安裝和使用說明。本教學提供這些說明的詳細資訊。安裝會利用 [CocoaPods](https://cocoapods.org) 來匯入所需的 AWS Mobile 開發套件元件。您必須更新 `Podfile`，以將開發套件匯入至您 Swift 應用程式的 Xcode 專案。未封存的開發套件資料夾也包含 `generated-src` 資料夾，其中包含 API 之已產生開發套件的原始程式碼。
1. 啟動 Xcode 並建立新的 iOS Swift 專案。請記下專案的目標。您需要在 `Podfile` 中設定它。
![\[在 Xcode 中尋找目標。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-find-target.png)
1. 若要使用 CocoaPods 將所需的 AWS Mobile SDK 元件匯入 Xcode 專案，請執行下列動作：
1. 如果未安裝，請在終端機視窗中執行下列命令來安裝 CocoaPods：
```
sudo gem install cocoapods
pod setup
```
1. 將 `Podfile` 檔案從解壓縮開發套件資料夾複製至包含 Xcode 專案檔的相同目錄。將下列區塊：
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
取代為您專案的目標名稱，如下所示：
```
target 'app_swift_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
如果您的 Xcode 專案已包含具有正確目標的 `Podfile`，您可以只將下列程式碼行新增至 `do ... end` 迴圈：
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. 開啟終端機視窗，並在應用程式目錄中執行下列命令：
```
pod install
```
這會將 API Gateway 元件和任何相依的 AWS Mobile SDK 元件安裝到應用程式的專案中。
1. 關閉 Xcode 專案，然後開啟 `*.xcworkspace` 檔案重新啟動 Xcode。
1. 將所有開發套件的標頭檔案 (`.h`) 和 Swift 原始程式碼檔案 (`.swift`) 從擷取的 `generated-src` 目錄新增至 Xcode 專案。
![\[.h 和 .swift 檔案位於產生的來源中\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-add-sdk-src.png)
1. 若要啟用從 Swift 程式碼專案呼叫 AWS Mobile SDK 的 Objective-C 程式庫，請在您 Xcode 專案組態的 **Swift 編譯器 - 一般**設定下，在 **Objective-C 橋接標頭**屬性上設定`Bridging_Header.h`檔案路徑：
![\[在「Swift 編譯器 - 一般」下，設定 Bridging_Header.h 檔案路徑。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-bridging-header.png)
**提示**
您可以在 Xcode 的搜尋方塊中輸入 **bridging**，以尋找 **Objective-C Bridging Header (Objective-C 橋接標頭)** 屬性。
1. 建置 Xcode 專案，驗證已正確地設定它，再繼續進行。如果您的 Xcode 使用的 Swift 版本比 AWS Mobile SDK 支援的版本更新，您會收到 Swift 編譯器錯誤。在這種情況下，於 **Swift Compiler - Version (Swift 編譯器 - 版本)** 設定下方，將 **Use Legacy Swift Language Version (使用傳統 Swift 語言版本)** 屬性設定為 **Yes (是)**：
![\[將 Legacy Swift 語言版本屬性設定為「是」。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-legacy-swift-version.png)
若要透過明確下載 AWS Mobile SDK 或使用 [Carthage](https://github.com/Carthage/Carthage#installing-carthage) 將適用於 iOS 的 AWS Mobile SDK 匯入您的專案，請遵循 SDK 套件隨附的 `README.md` 檔案中的指示。請務必僅使用其中一個選項來匯入 AWS Mobile SDK。
### 在 Swift 專案中透過 API Gateway 所產生的 iOS 軟體開發套件來呼叫 API 方法
當您使用兩個模型說明 API 請求和回應的輸入 (`Input`) 和輸出 (`Result`)，為這個 [SimpleCalc API](simple-calc-lambda-api.md) 產生字首為 `SIMPLE_CALC` 的開發套件後，在開發套件中，產生的 API 用戶端類別會變為 `SIMPLE_CALCSimpleCalcClient`，而對應的資料類別則會分別成為 `SIMPLE_CALCInput` 和 `SIMPLE_CALCResult`。API 請求和回應會對應至開發套件方法，如下所示：
+ 下列的 API 請求：
```
GET /?a=...&b=...&op=...
```
會成為下列的開發套件方法：
```
public func rootGet(op: String?, a: String?, b: String?) -> AWSTask
```
如果 `AWSTask.result` 模型已新增至方法回應，則 `SIMPLE_CALCResult` 屬性為 `Result` 類型。否則，它為 `NSDictionary` 類型。
+ 下列的此 API 請求：
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
會成為下列的開發套件方法：
```
public func rootPost(body: SIMPLE_CALCInput) -> AWSTask
```
+ 下列的 API 請求：
```
GET /{a}/{b}/{op}
```
會成為下列的開發套件方法：
```
public func aBOpGet(a: String, b: String, op: String) -> AWSTask
```
下列程序說明如何在 Swift 應用程式原始碼中呼叫 API 方法；例如，在 `viewDidLoad()` 檔案中做為 `ViewController.m` 委派的一部分。
**透過 API Gateway 所產生的 iOS 軟體開發套件來呼叫 API**
1. 將 API 用戶端類別執行個體化：
```
let client = SIMPLE_CALCSimpleCalcClient.default()
```
若要搭配 API 使用 Amazon Cognito，請先設定預設 AWS 服務組態 （如下所示），再取得`default`方法 （如先前所示）：
```
let credentialsProvider = AWSCognitoCredentialsProvider(regionType: AWSRegionType.USEast1, identityPoolId: "my_pool_id")
let configuration = AWSServiceConfiguration(region: AWSRegionType.USEast1, credentialsProvider: credentialsProvider)
AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration
```
1. 呼叫 `GET /?a=1&b=2&op=+` 方法來執行 `1+2`：
```
client.rootGet("+", a: "1", b:"2").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
其中，helper 函數 `self.showResult(task)` 會將結果或錯誤列印至主控台，例如：
```
func showResult(task: AWSTask) {
if let error = task.error {
print("Error: \(error)")
} else if let result = task.result {
if result is SIMPLE_CALCResult {
let res = result as! SIMPLE_CALCResult
print(String(format:"%@ %@ %@ = %@", res.input!.a!, res.input!.op!, res.input!.b!, res.output!.c!))
} else if result is NSDictionary {
let res = result as! NSDictionary
print("NSDictionary: \(res)")
}
}
}
```
在生產應用程式中，您可以在文字欄位中顯示結果或錯誤。產生的顯示畫面為 `1 + 2 = 3`。
1. 呼叫具有承載的 `POST /` 來執行 `1-2`：
```
let body = SIMPLE_CALCInput()
body.a=1
body.b=2
body.op="-"
client.rootPost(body).continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
產生的顯示畫面為 `1 - 2 = -1`。
1. 呼叫 `GET /{a}/{b}/{op}` 來執行 `1/2`：
```
client.aBOpGet("1", b:"2", op:"div").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
產生的顯示畫面為 `1 div 2 = 0.5`。在此，`div` 用來代替 `/`，因為後端的[簡單 Lambda 函數](simple-calc-nodejs-lambda-function.md)不處理 URL 編碼的路徑變數。
# 在 API Gateway 中使用 OpenAPI 開發 REST API
您可以使用 API Gateway 將 REST API 從外部定義檔案匯入至 API Gateway。目前，API Gateway 支援 [OpenAPI v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) 和 [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) 定義檔案，例外狀況列於 [適用於 REST API 的 Amazon API Gateway 重要說明](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis) 中。您可以用新的定義覆寫 API 來更新 API，或與現有的 API 合併定義。您可以在請求 URL 中使用 `mode` 查詢參數來指定選項。
如需從 API Gateway 主控台使用「匯入 API」功能的教學課程，請參閱[教學課程：匯入範例來建立 REST API](api-gateway-create-api-from-example.md)。
**Topics**
+ [將邊緣最佳化 API 匯入至 API Gateway](import-edge-optimized-api.md)
+ [將區域 API 匯入至 API Gateway](import-export-api-endpoints.md)
+ [匯入 OpenAPI 檔案以更新現有的 API 定義](api-gateway-import-api-update.md)
+ [設定 OpenAPI `basePath` 屬性](api-gateway-import-api-basePath.md)
+ [AWS OpenAPI 匯入的 變數](import-api-aws-variables.md)
+ [將 API 匯入 API Gateway 的錯誤和警告](api-gateway-import-api-errors-warnings.md)
+ [從 API Gateway 匯出 REST API](api-gateway-export-api.md)
# 將邊緣最佳化 API 匯入至 API Gateway
您可以匯入 API OpenAPI 定義檔來建立新的邊緣最佳化 API，方法是指定 `EDGE` 端點類型做為匯入操作的額外輸入 (除了 OpenAPI 檔案之外)。您可以使用 API Gateway 主控台 AWS CLI或 AWS SDK 來執行此操作。
如需從 API Gateway 主控台使用「匯入 API」功能的教學課程，請參閱[教學課程：匯入範例來建立 REST API](api-gateway-create-api-from-example.md)。
**Topics**
+ [使用 API Gateway 主控台匯入邊緣最佳化 API](#import-edge-optimized-api-with-console)
+ [使用 匯入邊緣最佳化 API AWS CLI](#import-edge-optimized-api-with-awscli)
## 使用 API Gateway 主控台匯入邊緣最佳化 API
若要使用 API Gateway 主控台匯入邊緣最佳化 API，請執行以下操作：
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 **Create API (建立 API)**。
1. 在 **REST API** 下，選擇 **Import** (匯入)。
1. 複製 API 的 OpenAPI 定義並將它貼入程式碼編輯器，或選擇**選擇檔案**，從本機磁碟機載入 OpenAPI 檔案。
1. 對於 **API 端點類型**，選取**邊緣最佳化**。
1. 選擇**建立 API** 以開始匯入 OpenAPI 定義。
## 使用 匯入邊緣最佳化 API AWS CLI
以下 [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) 命令會從 OpenAPI 定義檔案匯入 API，以建立新的邊緣最佳化 API：
```
aws apigateway import-rest-api \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
或將 `endpointConfigurationTypes` 查詢字串參數明確指定為 `EDGE`：
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=EDGE \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# 將區域 API 匯入至 API Gateway
當您匯入 API 時，可以選擇 API 的區域端點組態。您可以使用 API Gateway 主控台 AWS CLI、 或 AWS SDK。
當您匯出 API 時，API 端點組態不會包含在匯出的 API 定義中。
如需從 API Gateway 主控台使用「匯入 API」功能的教學課程，請參閱[教學課程：匯入範例來建立 REST API](api-gateway-create-api-from-example.md)。
**Topics**
+ [使用 API Gateway 主控台匯入區域性 API](#import-regional-api-with-console)
+ [使用 匯入區域 API AWS CLI](#import-regional-api-with-awscli)
## 使用 API Gateway 主控台匯入區域性 API
若要使用 API Gateway 主控台匯入區域端點的 API，請執行下列動作：
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 **Create API (建立 API)**。
1. 在 **REST API** 下，選擇 **Import** (匯入)。
1. 複製 API 的 OpenAPI 定義並將它貼入程式碼編輯器，或選擇**選擇檔案**，從本機磁碟機載入 OpenAPI 檔案。
1. 對於 **API 端點類型**，選取**區域**。
1. 選擇**建立 API** 以開始匯入 OpenAPI 定義。
## 使用 匯入區域 API AWS CLI
以下 [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) 命令會匯入 OpenAPI 定義檔案，並將端點類型設為區域：
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=REGIONAL \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# 匯入 OpenAPI 檔案以更新現有的 API 定義
您可以匯入 API 定義只更新現有的 API，無需變更其端點組態，以及階段與階段變數，或參考 API 金鑰。
匯入到更新操作可在兩種模式下進行：合併或覆寫。
當 API (`A`) 合併到另一個 (`B`)，如果兩個 API 不共用任何衝突的定義，則產生的 API 會保留 `A` 和 `B` 兩者的定義。發生衝突時，合併 API (`A`) 之方法定義會覆寫被合併 API (`B`) 的對應方法定義。例如，假設 `B` 已宣告以下列方法傳回 `200` 和 `206` 回應：
```
GET /a
POST /a
```
而 `A` 宣告以下列方法傳回 `200` 和 `400` 回應：
```
GET /a
```
當 `A` 合併到 `B`，產生的 API 會產出以下方法：
```
GET /a
```
傳回 `200` 和 `400` 回應，且
```
POST /a
```
傳回 `200` 和 `206` 回應。
合併 API 適用於您已將外部 API 定義分解成多個更小的組件，而且一次只想要套用其中一個組件的變更時。例如，如果多個小組負責 API 的不同組件並有不同速率的變更時，則可能會出現此情況。在此模式下，現有 API 中的項目若在已匯入的定義中沒有特別定義，則會保持不變。
當 API (`A`) 覆寫另一個 API (`B`)，產生的 API 會採用覆寫的 API (`A`) 之定義。覆寫 API 適用於外部 API 定義包含完整的 API 定義時。在此模式下，現有 API 中的項目若在已匯入的定義中沒有特別定義，則會遭到刪除。
若要合併 API，請將 `PUT` 請求提交給 `https://apigateway..amazonaws.com/restapis/?mode=merge`。`restapi_id` 路徑參數值指定要與所提供的 API 定義合併的 API。
下列程式碼片段顯示 `PUT` 請求範例，其中會將 JSON 中的 OpenAPI API 定義做為承載與 API Gateway 中已指定的 API 合併。
```
PUT /restapis/?mode=merge
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
合併更新操作可將兩個完整的 API 定義合併在一起。對於小型累加變更，您可以使用[資源更新](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html)操作。
若要覆寫 API，請將 `PUT` 請求提交給 `https://apigateway..amazonaws.com/restapis/?mode=overwrite`。`restapi_id` 路徑參數指定要使用所提供 API 定義覆寫的 API。
下列程式碼片段顯示使用 JSON 格式 OpenAPI 定義的承載覆寫請求的範例：
```
PUT /restapis/?mode=overwrite
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
未指定 `mode` 查詢參數時，會假設使用合併。
**注意**
`PUT` 操作為等冪，但不可部分完成。這表示如果在處理到一半時發生系統錯誤，API 最後可能會是錯誤狀態。不過，重複此操作會成功將 API 放到相同的最終狀態，就像是成功進行的第一個操作。
# 設定 OpenAPI `basePath` 屬性
在 [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) 中，您可以使用 `basePath` 屬性來提供 `paths` 屬性中所定義之每個路徑之前的一或多個路徑部分。由於 API Gateway 表達資源路徑的方式有幾種，因此匯入 API 功能會在匯入期間提供下列選項來解譯 `basePath` 屬性：ignore、prepend 和 split。
在 [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/) 中，`basePath` 不再是頂層屬性。相反地，API Gateway 會使用[伺服器變數](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject)做為慣例。匯入 API 功能會提供相同選項，以在匯入期間解譯基本路徑。基本路徑會依下列所述進行識別：
+ 如果 API 未包含任何 `basePath` 變數，則匯入 API 功能會檢查 `server.url` 字串，以查看其是否包含超過 `"/"` 的路徑。若是，該路徑會用作基本路徑。
+ 如果 API 只包含一個 `basePath` 變數，則匯入 API 功能會使用它，做為基本路徑，即使未在 `server.url` 中參考它也一樣。
+ 如果 API 包含多個 `basePath` 變數，則匯入 API 功能只會使用第一個變數，做為基本路徑。
## Ignore
如果 OpenAPI 檔案具有 `basePath` 的 `/a/b/c` 值，而且 `paths` 屬性包含 `/e` 與 `/f`，則下列 `POST` 或 `PUT` 請求：
```
POST /restapis?mode=import&basepath=ignore
```
```
PUT /restapis/api_id?basepath=ignore
```
會導致 API 中的下列資源：
+ `/`
+ `/e`
+ `/f`
結果是將 `basePath` 視為不存在，並提供與主機相關之所有已宣告的 API 資源。例如，當您有自訂網域名稱，其 API 映射未包含 *Base Path (基底路徑)* 以及參考您生產階段的 *Stage (階段)* 值，就可以使用此選項。
**注意**
API Gateway 會自動為您建立根資源，即使您的定義檔中沒有明確宣告也一樣。
未指定時，`basePath` 預設會採用 `ignore`。
## 前綴
如果 OpenAPI 檔案具有 `basePath` 的 `/a/b/c` 值，而且 `paths` 屬性包含 `/e` 與 `/f`，則下列 `POST` 或 `PUT` 請求：
```
POST /restapis?mode=import&basepath=prepend
```
```
PUT /restapis/api_id?basepath=prepend
```
會導致 API 中的下列資源：
+ `/`
+ `/a`
+ `/a/b`
+ `/a/b/c`
+ `/a/b/c/e`
+ `/a/b/c/f`
結果是將 `basePath` 視為指定其他資源 (不含方法)，並將其新增至已宣告的資源集。例如，當不同小組負責 API 的不同組件，而且 `basePath` 可能參考每個小組之 API 組件的路徑位置時，就可以使用此選項。
**注意**
API Gateway 會自動為您建立中繼資源，即使您的定義中沒有明確宣告也一樣。
## Split
如果 OpenAPI 檔案具有 `basePath` 的 `/a/b/c` 值，而且 `paths` 屬性包含 `/e` 與 `/f`，則下列 `POST` 或 `PUT` 請求：
```
POST /restapis?mode=import&basepath=split
```
```
PUT /restapis/api_id?basepath=split
```
會導致 API 中的下列資源：
+ `/`
+ `/b`
+ `/b/c`
+ `/b/c/e`
+ `/b/c/f`
結果是將最上層的路徑部分 `/a` 視為每個資源路徑的開頭，並在 API 本身內建立其他資源 (不含方法)。例如，當 `a` 是您要公開為 API 一部分的階段名稱時，就可以使用此選項。
# AWS OpenAPI 匯入的 變數
您可以在 OpenAPI 定義中使用下列 AWS 變數。API Gateway 會在匯入 API 時解析變數。若要指定變數，請使用 `${variable-name}`。下表說明可用的 AWS 變數。
| 變數名稱 | Description |
| --- | --- |
| AWS::AccountId | 匯入 API AWS 的帳戶 ID。例如：123456789012。 |
| AWS::Partition | 匯入 API 的 AWS 分割區。對於標準 AWS 區域，分割區為 aws。 |
| AWS::Region | 匯入 API AWS 的區域。例如 us-east-2。 |
## AWS 變數範例
下列範例使用 AWS 變數來指定 整合的 AWS Lambda 函數。
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "tasks-api"
version: "v1.0"
paths:
/:
get:
summary: List tasks
description: Returns a list of tasks
responses:
200:
description: "OK"
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Task"
500:
description: "Internal Server Error"
content: {}
x-amazon-apigateway-integration:
uri:
arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations
responses:
default:
statusCode: "200"
passthroughBehavior: "when_no_match"
httpMethod: "POST"
contentHandling: "CONVERT_TO_TEXT"
type: "aws_proxy"
components:
schemas:
Task:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
```
------
# 將 API 匯入 API Gateway 的錯誤和警告
當您將外部定義檔案匯入 API Gateway 時，API Gateway 可能會產生警告和錯誤。下列各節討論匯入期間可能發生的錯誤和警告。
## 匯入期間的錯誤
匯入期間，OpenAPI 文件無效等重大問題可能會產生錯誤。這些錯誤會在失敗回應中以例外狀況 (例如 `BadRequestException`) 傳回。發生錯誤時，會捨棄新的 API 定義，而且不會對現有的 API 進行變更。
## 匯入期間的警告
匯入期間，遺失模型參考等次要問題可能會產生警告。如果發生警告，並將 `failonwarnings=false` 查詢表達式附加至請求 URL，操作將會繼續。否則會復原更新。根據預設，`failonwarnings` 會設定為 `false`。在此類情況下，警告會在所產生的 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 資源中的欄位回傳。否則，警告會以例外狀況中的訊息傳回。
# 從 API Gateway 匯出 REST API
一旦您使用 API Gateway 主控台或其他方式，在 API Gateway 中建立並配置 REST API，就可以使用 API Gateway Export API (屬於 Amazon API Gateway 控制服務的一部分) 將其匯出至 OpenAPI 檔案。若要使用 API Gateway Export API，您必須簽署 API 請求。如需簽署請求的詳細資訊，請參閱《*IAM 使用者指南*》中的[簽署 AWS API 請求](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)。您可以選擇在匯出的 OpenAPI 定義檔中包含 API Gateway 整合延伸項目和 [Postman](https://www.postman.com) 延伸項目。
**注意**
使用 匯出 API 時 AWS CLI，請務必包含延伸項目參數，如下列範例所示，以確保包含`x-amazon-apigateway-request-validator`延伸項目：
```
aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json
```
如果 API 的承載類型不是 `application/json`，則無法匯出 API。如果您嘗試，則會收到錯誤回應，指出找不到 JSON 內文模型。
## 匯出 REST API 的請求
使用匯出 API 時，您可以提交 GET 請求並將欲匯出的 API 指定為 URL 路徑的一部分，藉此匯出現有 REST API。請求 URL 的格式如下：
------
#### [ OpenAPI 3.0 ]
```
https:///restapis//stages//exports/oas30
```
------
#### [ OpenAPI 2.0 ]
```
https:///restapis//stages//exports/swagger
```
------
您可以附加 `extensions` 查詢字串，以指定要包含 API Gateway 延伸 (具有 `integration` 值) 或是 Postman 延伸 (具有 `postman` 值)。
此外，您也可以將 `Accept` 標頭設定為 `application/json` 或 `application/yaml`，分別接收 JSON 或 YAML 格式的 API 定義輸出。
如需使用 API Gateway Export API 提交 GET 請求的詳細資訊，請參閱 [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html)。
**注意**
如果您在 API 中定義模型，則模型必須適用於內容類型「application/json」，API Gateway 才會匯出模型。否則，API Gateway 會擲回例外狀況，其錯誤訊息為「只發現 ... 的非 JSON 內文模型」。
模型必須包含屬性，或是定義為特定 JSONSchema 類型。
## 下載 JSON 格式的 REST API OpenAPI 定義
以 JSON 格式的 OpenAPI 定義匯出並下載 REST API：
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/json
```
------
例如，在這裡，`` 可以是 `us-east-1`。如需可使用 API Gateway 的所有區域，請參閱[區域和端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region)。
## 下載 YAML 格式的 REST API OpenAPI 定義
以 YAML 格式的 OpenAPI 定義匯出並下載 REST API：
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## 下載 JSON 格式且具有 Postman 延伸的 REST API OpenAPI 定義
以 JSON 格式的 OpenAPI 定義搭配 Postman 匯出並下載 REST API：
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
## 下載 YAML 格式且具有 API Gateway 整合的 REST API OpenAPI 定義
以 YAML 格式的 OpenAPI 定義搭配 API Gateway 整合匯出並下載 REST API：
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## 使用 API Gateway 主控台匯出 REST API
[將 REST API 部署至階段](set-up-deployments.md#create-deployment)之後，即可繼續使用 API Gateway 主控台，將階段中的 API 匯出至 OpenAPI 檔案。
在 API Gateway 主控台的**階段**窗格中，選擇**階段動作**、**匯出**。
![\[使用 API Gateway 主控台匯出 REST API\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/export-new-console.png)
指定 **API 規格類型**、**格式**和**延伸模組**，以下載 API 的 OpenAPI 定義。