本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 教學：建立具 Lambda 非代理整合的 REST API 在此演練中，我們使用 API Gateway 主控台建置一個 API，讓用戶端可以透過 Lambda 非代理整合 (也稱為自訂整合) 呼叫 Lambda 函數。如需有關 AWS Lambda 和 Lambda 函數的詳細資訊，請參閱 [AWS Lambda 開發人員指南](https://docs.aws.amazon.com/lambda/latest/dg/)。為方便學習，我們選擇了一個具有最少 API 設定的簡單 Lambda 函數，以逐步引導您建置具有 Lambda 自訂整合的 API Gateway API。必要時，我們會說明一些邏輯。如需 Lambda 自訂整合的更詳細範例，請參閱[教學課程：建立具有兩個 AWS 服務整合和一個 Lambda 非代理整合的計算器 REST API](integrating-api-with-aws-services-lambda.md)。建立 API 之前，請在 AWS Lambda中建立 Lambda 函數來設定 Lambda 後端，以下將進行說明。 **Topics** + [為 Lambda 非代理整合建立 Lambda 函數](#getting-started-new-lambda) + [建立具有 Lambda 非代理整合的 API](#getting-started-new-api) + [測試呼叫 API 方法](#getting-started-new-get) + [部署 API](#getting-started-deploy-api) + [在部署階段測試 API](#getting-started-test) + [清除](#getting-started-clean-up) ## 為 Lambda 非代理整合建立 Lambda 函數 **注意** 建立 Lambda 函數可能會導致 AWS 您的帳戶產生費用。在此步驟中，您會為 Lambda 自訂整合建立 "Hello, World\$1" 之類的 Lambda 函數。在此演練中，此函數稱為 `GetStartedLambdaIntegration`。以下是此 `GetStartedLambdaIntegration` Lambda 函數的實作： ------ #### [ Node.js ] ``` 'use strict'; var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']; var times = ['morning', 'afternoon', 'evening', 'night', 'day']; export const handler = async(event) => { console.log(event); // Parse the input for the name, city, time and day property values let name = event.name === null || event.name === undefined || event.name === "" ? 'you' : event.name; let city = event.city === undefined ? 'World' : event.city; let time = times.indexOf(event.time)<0 ? 'day' : event.time; let day = days.indexOf(event.day)<0 ? null : event.day; // Generate a greeting let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. '; if (day) greeting += 'Happy ' + day + '!'; // Log the greeting to CloudWatch console.log('Hello: ', greeting); // Return a greeting to the caller return {"greeting": greeting} }; ``` ------ #### [ Python ] ``` import json days = { 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'} times = {'morning', 'afternoon', 'evening', 'night', 'day'} def lambda_handler(event, context): print(event) # parse the input for the name, city, time, and day property values name = event.get("name") or 'you' city = event.get("city") or 'World' try: if event['time'] in times: time = event['time'] else: time = 'day' except KeyError: time = 'day' try: if event['day'] in days: day = event['day'] else: day = '' except KeyError: day = '' # Generate a greeting greeting = 'Good ' + time + ', ' + name + ' of ' + \ city + '.' + ['', ' Happy ' + day + '!'][day != ''] # Log the greeting to CloudWatch print(greeting) # Return a greeting to the caller return {"greeting": greeting} ``` ------ 對於 Lambda 自訂整合，API Gateway 會從用戶端傳遞 Lambda 函數的輸入作為整合請求內文。此輸入是 Lambda 函數處理常式的 `event` 物件。我們的 Lambda 函數很簡單。它會剖析 `event`、`name`、`city` 與 `time` 屬性的輸入 `day` 物件。然後，它會傳回問候語 (以 `{"message":greeting}` 的 JSON 物件形式) 給發起人。該訊息的模式為 `"Good [morning|afternoon|day], [name|you] in [city|World]. Happy day!"`。它假設 Lambda 函數的輸入屬於下列 JSON 物件： ``` { "city": "...", "time": "...", "day": "...", "name" : "..." } ``` 如需詳細資訊，請參閱 [AWS Lambda 開發人員指南](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)。此外，此函數會藉由呼叫 `console.log(...)` 將其執行記錄到 Amazon CloudWatch。這有助於在偵錯函數時追蹤呼叫。若要允許 `GetStartedLambdaIntegration` 函數記錄呼叫，請使用適當的政策來設定 IAM 角色，讓 Lambda 函數可以建立 CloudWatch 串流並將日誌項目新增至串流。Lambda 主控台會引導您建立必要的 IAM 角色與政策。如果您未使用 API Gateway 主控台設定 API (例如[從 OpenAPI 檔案匯入 API](https://github.com/aws-samples/api-gateway-secure-pet-store/blob/master/src/main/resources/swagger.yaml#L39) 時)，您必須明確建立 (如果需要) 並設定叫用角色與政策，API Gateway 才能叫用 Lambda 函數。如需如何為 API Gateway API 設定 Lambda 呼叫與執行角色的詳細資訊，請參閱[使用 IAM 許可權控制 REST API 的存取](permissions.md)。相較於 `GetStartedLambdaProxyIntegration` (Lambda 代理整合的 Lambda 函數)，`GetStartedLambdaIntegration` (Lambda 自訂整合的 Lambda 函數) 只會接受來自 API Gateway API 整合請求內文的輸入。該函數可以傳回任何 JSON 物件、字串、數值、布林值，或甚至是二進位 Blob 的輸出。相較之下，Lambda 代理整合的 Lambda 函數可以接受來自任何請求資料的輸入，但必須傳回特定 JSON 物件的輸出。Lambda 自訂整合的 `GetStartedLambdaIntegration` 函數可以接受 API 請求參數作為輸入，但前提是 API Gateway 在將用戶端請求轉送到後端之前，已將必要的 API 請求參數對應到整合請求內文。若要這樣做，API 開發人員必須建立對應範本，並在建立 API 時於 API 方法上設定此範本。現在，建立 `GetStartedLambdaIntegration` Lambda 函數。 **建立 Lambda 自訂整合的 `GetStartedLambdaIntegration` Lambda 函數** 1. 在 https：//[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/) 開啟 AWS Lambda 主控台。 1. 執行以下任意一項： + 出現歡迎頁面時，請選擇 **Get Started Now (立即開始使用)**，然後選擇 **Create function (建立函數)**。 + 出現 **Lambda > Functions (Lambda > 函數)** 清單頁面時，請選擇 **Create function (建立函數)**。 1. 選擇 **Author from scratch** (從頭開始撰寫)。 1. 在 **Author from scratch (從頭開始撰寫)** 窗格上，執行下列操作： 1. 在**名稱**，輸入 **GetStartedLambdaIntegration** 做為 Lambda 函數名稱。 1. 針對**執行期**，請選擇最新支援的 **Node.js** 或 **Python** 執行期。 1. 對於**架構**，請保留預設設定。 1. 在**許可**下，展開**變更預設執行角色**。從**執行角色**下拉式清單中，選擇**從 AWS 政策範本建立新角色**。 1. 在**角色名稱**中輸入角色名稱 (例如 **GetStartedLambdaIntegrationRole**)。 1. 對於 **Policy templates (政策範本)**，選擇 **Simple microservice permissions (簡易微服務許可)**。 1. 選擇 **Create function (建立函數)**。 1. 在 **Configure function (設定函數)** 窗格的 **Function code (函數程式碼)** 中，執行下列操作： 1. 將本節開頭列出的 Lambda 函數程式碼複製並貼到內嵌程式碼編輯器。 1. 對於此區段中的所有其他欄位，則保留預設選項。 1. 選擇 **Deploy (部署)**。 1. 若要測試新建立的函數，請選擇**測試**索引標籤。 1. **事件名稱**輸入 **HelloWorldTest**。 1. 對於**事件 JSON**，請使用下列命令取代預設程式碼。 ``` { "name": "Jonny", "city": "Seattle", "time": "morning", "day": "Wednesday" } ``` 1. 選擇**測試**以呼叫函數。**執行結果：成功**區段會隨即顯示。展開**詳細資訊**，您會看到下列輸出。 ``` { "greeting": "Good morning, Jonny of Seattle. Happy Wednesday!" } ``` 該輸出也會寫入 CloudWatch Logs。作為附帶練習，您可使用 IAM 主控台來檢視 Lambda 函數建立過程中所建立的 IAM 角色 (`GetStartedLambdaIntegrationRole`)。此 IAM 角色會附加兩個內嵌政策。其中一個規定 Lambda 執行的最基本許可。它允許在建立 Lambda 函數的區域中，對您帳戶的任何 CloudWatch 資源呼叫 CloudWatch `CreateLogGroup`。此政策也允許建立 `GetStartedLambdaIntegration` Lambda 函數的 CloudWatch 串流與記錄日誌事件。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "logs:CreateLogGroup", "Resource": "arn:aws:logs:us-east-1:111111111111:*" }, { "Effect": "Allow", "Action": [ "logs:CreateLogStream", "logs:PutLogEvents" ], "Resource": [ "arn:aws:logs:us-east-1:111111111111:log-group:/aws/lambda/GetStartedLambdaIntegration:*" ] } ] } ``` ------ 另一個政策文件適用於叫用此範例中 AWS 未使用的其他服務。您目前可以略過。 IAM 角色與信任實體相關聯，也就是 `lambda.amazonaws.com`。以下是信任關係： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ 此信任關係與內嵌政策的組合可讓 Lambda 函數叫用 `console.log()` 函數來將事件記錄到 CloudWatch Logs。 ## 建立具有 Lambda 非代理整合的 API 建立並測試 Lambda 函數 (`GetStartedLambdaIntegration`) 之後，您就可以透過 API Gateway API 公開函數。為了方便說明，我們會透過泛型 HTTP 方法公開 Lambda 函數。我們使用請求內文、URL 路徑變數、查詢字串與標頭，從用戶端接收必要的輸入資料。我們開啟 API 的 API Gateway 請求驗證程式，確保所有必要的資料都已正確定義與指定。我們設定對應範本，讓 API Gateway 可以將用戶端提供的請求資料轉換成後端 Lambda 函數所需的有效格式。 **建立具有 Lambda 非代理整合的 API** 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 如果這是您第一次使用 API Gateway，您會看到服務功能的介紹頁面。在 **REST API** 下方，選擇 **Build (組建)**。當 **Create Example API (建立範例 API)** 快顯出現時，選擇 **OK (確定)**。如果這不是第一次使用 API Gateway，請選擇 **Create API (建立 API)**。在 **REST API** 下方，選擇**組建**。 1. 對於**API 名稱**，輸入 **LambdaNonProxyAPI**。 1. 在**描述**，請輸入描述。 1. 將 **API 端點類型**保持設定為**區域**。 1. 針對 **IP 位址類型**，選擇 **IPv4**。 1. 選擇**建立 API**。建立 API 之後，請建立 **/\$1city\$1** 資源。這是具有路徑變數的資源範例，其會接受來自用戶端的輸入。稍後，您會使用對應範本將此路徑變數對應到 Lambda 函數輸入。 **建立資源** 1. 選擇**建立資源**。 1. 讓**代理資源**保持關閉。 1. 將**資源路徑**保持為 `/`。 1. 針對**資源名稱**，輸入 **\$1city\$1**。 1. 讓 **CORS (跨來源資源分享)** 保持關閉。 1. 選擇**建立資源**。在建立 **/\$1city\$1** 資源後，請建立 `ANY` 方法。`ANY` HTTP 動詞是用戶端在執行時間提交之有效 HTTP 方法的預留位置。此範例顯示 `ANY` 方法可用於 Lambda 自訂整合以及 Lambda 代理整合。 **建立 `ANY` 方法** 1. 選取 **/\$1city\$1** 資源，然後選擇**建立方法**。 1. 針對**方法類型**，選取 **ANY**。 1. 針對**整合類型**，選取 **Lambda 函數**。 1. 將 **Lambda 代理整合**保持關閉。 1. 針對 **Lambda 函數**，選取您建立 Lambda 函數 AWS 區域的，然後輸入函數名稱。 1. 選擇**方法請求設定**。此時，請開啟 URL 路徑變數、查詢字串參數與標頭的請求驗證程式，以確保所有必要的資料都已定義。在此範例中，您會建立 `time` 查詢字串參數和 `day` 標頭。 1. 對於**請求驗證程式**，選取**驗證查詢字串參數與標頭**。 1. 選擇 **URL 查詢字串參數**，然後執行下列動作： 1. 選擇**新增查詢字串**。 1. 對於**名稱**，輸入 **time**。 1. 開啟**必要**。 1. 讓**快取**保持關閉。 1. 選擇 **HTTP 請求標頭**，然後執行下列動作： 1. 選擇**新增標頭**。 1. 對於**名稱**，輸入 **day**。 1. 開啟**必要**。 1. 讓**快取**保持關閉。 1. 選擇**建立方法**。開啟請求驗證程式之後，請根據後端 Lambda 函數的要求，新增內文對應範本將傳入請求轉換為 JSON 承載，以設定 `ANY` 方法的整合請求。 **設定整合請求** 1. 在**整合請求**標籤上，於**整合請求設定**下，選擇**編輯**。 1. 針對**請求內文傳遞**，選取**未定義範本時 (建議)**。 1. 選擇**對應範本**。 1. 選擇**新增對應範本**。 1. 針對**內容類型**，輸入 **application/json**。 1. 針對**範本內文**，輸入下列程式碼： ``` #set($inputRoot = $input.path('$')) { "city": "$input.params('city')", "time": "$input.params('time')", "day": "$input.params('day')", "name": "$inputRoot.callerName" } ``` 1. 選擇**儲存**。 ## 測試呼叫 API 方法 API Gateway 主控台提供測試功能，可讓您測試呼叫 API，再進行部署。您可以使用主控台的 Test (測試) 功能，透過提交下列請求來測試 API： ``` POST /Seattle?time=morning day:Wednesday { "callerName": "John" } ``` 在此測試請求中，您會將 `ANY` 設定為 `POST`、將 `{city}` 設定為 `Seattle`、將 `Wednesday` 設定為 `day` 標頭值，並將 `"John"` 指派為 `callerName` 值。 **測試 `ANY` 方法** 1. 選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。 1. 針對**方法類型**，選取 `POST`。 1. 針對**路徑**，在**城市**下輸入 **Seattle**。 1. 針對**查詢字串**，輸入 **time=morning**。 1. 針對**標頭**，輸入 **day:Wednesday**。 1. 針對**請求內文**，輸入 **\$1 "callerName": "John" \$1**。 1. 選擇**測試**。遵循下列方式驗證所傳回的回應承載： ``` { "greeting": "Good morning, John of Seattle. Happy Wednesday!" } ``` 您也可以檢視日誌，查看 API Gateway 如何處理請求與回應。 ``` Execution log for request test-request Thu Aug 31 01:07:25 UTC 2017 : Starting execution for request: test-invoke-request Thu Aug 31 01:07:25 UTC 2017 : HTTP Method: POST, Resource Path: /Seattle Thu Aug 31 01:07:25 UTC 2017 : Method request path: {city=Seattle} Thu Aug 31 01:07:25 UTC 2017 : Method request query string: {time=morning} Thu Aug 31 01:07:25 UTC 2017 : Method request headers: {day=Wednesday} Thu Aug 31 01:07:25 UTC 2017 : Method request body before transformations: { "callerName": "John" } Thu Aug 31 01:07:25 UTC 2017 : Request validation succeeded for content type application/json Thu Aug 31 01:07:25 UTC 2017 : Endpoint request URI: https://lambda.us-west-2.amazonaws.com/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:GetStartedLambdaIntegration/invocations Thu Aug 31 01:07:25 UTC 2017 : Endpoint request headers: {x-amzn-lambda-integration-tag=test-request, Authorization=****************************************************************************************************************************************************************************************************************************************************************************************************************************************338c72, X-Amz-Date=20170831T010725Z, x-amzn-apigateway-api-id=beags1mnid, X-Amz-Source-Arn=arn:aws:execute-api:us-west-2:123456789012:beags1mnid/null/POST/{city}, Accept=application/json, User-Agent=AmazonAPIGateway_beags1mnid, X-Amz-Security-Token=FQoDYXdzELL//////////wEaDMHGzEdEOT/VvGhabiK3AzgKrJw+3zLqJZG4PhOq12K6W21+QotY2rrZyOzqhLoiuRg3CAYNQ2eqgL5D54+63ey9bIdtwHGoyBdq8ecWxJK/YUnT2Rau0L9HCG5p7FC05h3IvwlFfvcidQNXeYvsKJTLXI05/yEnY3ttIAnpNYLOezD9Es8rBfyruHfJfOqextKlsC8DymCcqlGkig8qLKcZ0hWJWVwiPJiFgL7laabXs++ZhCa4hdZo4iqlG729DE4gaV1mJVdoAagIUwLMo+y4NxFDu0r7I0/EO5nYcCrppGVVBYiGk7H4T6sXuhTkbNNqVmXtV3ch5bOlh7 [TRUNCATED] Thu Aug 31 01:07:25 UTC 2017 : Endpoint request body after transformations: { "city": "Seattle", "time": "morning", "day": "Wednesday", "name" : "John" } Thu Aug 31 01:07:25 UTC 2017 : Sending request to https://lambda.us-west-2.amazonaws.com/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:GetStartedLambdaIntegration/invocations Thu Aug 31 01:07:25 UTC 2017 : Received response. Integration latency: 328 ms Thu Aug 31 01:07:25 UTC 2017 : Endpoint response body before transformations: {"greeting":"Good morning, John of Seattle. Happy Wednesday!"} Thu Aug 31 01:07:25 UTC 2017 : Endpoint response headers: {x-amzn-Remapped-Content-Length=0, x-amzn-RequestId=c0475a28-8de8-11e7-8d3f-4183da788f0f, Connection=keep-alive, Content-Length=62, Date=Thu, 31 Aug 2017 01:07:25 GMT, X-Amzn-Trace-Id=root=1-59a7614d-373151b01b0713127e646635;sampled=0, Content-Type=application/json} Thu Aug 31 01:07:25 UTC 2017 : Method response body after transformations: {"greeting":"Good morning, John of Seattle. Happy Wednesday!"} Thu Aug 31 01:07:25 UTC 2017 : Method response headers: {X-Amzn-Trace-Id=sampled=0;root=1-59a7614d-373151b01b0713127e646635, Content-Type=application/json} Thu Aug 31 01:07:25 UTC 2017 : Successfully completed execution Thu Aug 31 01:07:25 UTC 2017 : Method completed with status: 200 ``` 日誌會顯示對應前的傳入請求，以及對應後的整合請求。測試失敗時，日誌可用於評估原始輸入是否正確或對應範本是否正常運作。 ## 部署 API 測試呼叫是一種模擬並有所限制。例如，它會略過 API 上所制定的任何授權機制。若要即時測試 API 執行，您必須先部署 API。若要部署 API，請建立一個階段來建立 API 在當時的快照。階段名稱也會定義 API 預設主機名稱後面的基底路徑。API 的根資源會附加在階段名稱後面。當您修改 API 時，您必須將它重新部署到新的或現有的階段，變更才會生效。 **將 API 部署到階段** 1. 選擇**部署 API**。 1. 針對**階段**，選取**新階段**。 1. 針對**階段名稱**，輸入 **test**。 **注意** 輸入必須為 UTF-8 編碼 (例如未本地化的) 文字。 1. 在**描述**，請輸入描述。 1. 選擇**部署**。在**階段詳細資訊**下，選擇複製圖示以複製 API 的調用 URL。API 基底 URL 的一般模式為 `https://api-id.region.amazonaws.com/stageName`。例如，在 `beags1mnid` 區域中建立並部署到 `us-west-2` 階段之 API (`test`) 的基底 URL 為 `https://beags1mnid.execute-api.us-west-2.amazonaws.com/test`。 ## 在部署階段測試 API 您有數種方式可以測試已部署的 API。針對僅使用 URL 路徑變數或查詢字串參數的 GET 請求，您可以在瀏覽器中輸入 API 資源 URL。針對其他方法，您必須使用更進階的 REST API 測試公用程式，例如 [POSTMAN](https://www.postman.com/) 或 [cURL](https://curl.se/)。 **使用 cURL 測試 API** 1. 在連線至網際網路的本機電腦上，開啟終端機視窗。 1. 若要測試 `POST /Seattle?time=evening`：複製下列 cURL 命令並將其貼入終端機視窗。 ``` curl -v -X POST \ 'https://beags1mnid.execute-api.us-west-2.amazonaws.com/test/Seattle?time=evening' \ -H 'content-type: application/json' \ -H 'day: Thursday' \ -H 'x-amz-docs-region: us-west-2' \ -d '{ "callerName": "John" }' ``` 您應該取得具有下列承載的成功回應： ``` {"greeting":"Good evening, John of Seattle. Happy Thursday!"} ``` 如果您在此方法請求中將 `POST` 變更為 `PUT`，您會取得相同的回應。 ## 清除若您不再需要因為此演練所建立的 Lambda 函數，可立即將其刪除。您也可以刪除隨附的 IAM 資源。 **警告** 如果您打算完成本系列中的其他演練，則不要刪除 Lambda 執行角色或 Lambda 呼叫角色。如果刪除您 API 相依的 Lambda 函數，這些 API 將無法再運作。而刪除 Lambda 函數無法復原。所以若要再次使用該 Lambda 函數，必須加以重新建立。如果刪除 Lambda 函數相依的 IAM 資源，Lambda 函數將無法再運作，而且所有相依於該函數的 API 將無法再運作。IAM 資源一經刪除，即無法復原。所以若要再次使用該 IAM 資源，必須加以重新建立。 **若要刪除 Lambda 函數** 1. 登入 AWS 管理主控台並在 https：//[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/) 開啟 AWS Lambda 主控台。 1. 從函數清單中選擇 **GetStartedLambdaIntegration**，然後依序選擇**動作**和**刪除函數**。出現提示時，再次選擇 **Delete (刪除)**。 **刪除相關聯的 IAM 資源** 1. 在以下網址開啟 IAM 主控台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。 1. 從 **Details (詳細資訊)** 中，選擇 **Roles (角色)**。 1. 從角色清單中選擇 **GetStartedLambdaIntegrationRole**，然後依序選擇**角色動作**和**刪除角色**。在主控台依照以下步驟刪除角色。