教學課程：搭配使用 Lambda 與 API Gateway

在此教學課程中，您將建立 REST API，並透過此 API 調用 Lambda 函數。Lambda 函數會對 DynamoDB 資料表執行建立、讀取、更新及刪除 (CRUD) 操作。這裡提供的函數僅供示範，您將學習如何設定可調用任何 Lambda 函數的 API Gateway REST API。

使用 API Gateway 為使用者提供安全的 HTTP 端點以調用 Lambda 函數，並透過流量限流以及自動驗證和授權 API 呼叫，協助管理函數的大量呼叫。API Gateway 也提供使用 AWS Identity and Access Management (IAM) 和 Amazon Cognito 的彈性安全控制。對於需要預先授權才能呼叫應用程式的使用案例，這非常有用。

提示

Lambda 提供兩種透過 HTTP 端點叫用函數的方式：API Gateway 和 Lambda URLs。如果您不確定哪種是最適合使用案例的方法，請參閱 選取一種使用 HTTP 請求調用 Lambda 函數的方法。

完成本教學課程需逐一進行以下階段：

1. 以 Python 或 Node.js 建立並設定 Lambda 函數，用於對 DynamoDB 資料表執行操作。

2. 在 API Gateway 中建立 REST API 以連接 Lambda 函數。

3. 建立 DynamoDB 資料表，然後在主控台中使用您的 Lambda 函數進行測試。

4. 在終端內使用 curl 部署 API 並測試完整設定。

完成這些階段後，您將了解如何使用 API Gateway 建立 HTTP 端點，以安全地調用任何規模的 Lambda 函數。您也會學習如何部署 API，以及如何在控制台中以及使用終端傳送 HTTP 請求來進行測試。

先決條件

安裝 AWS Command Line Interface

如果您尚未安裝 AWS Command Line Interface，請依照安裝或更新最新版本 AWS CLI中的步驟進行安裝。

本教學課程需使用命令列終端機或 Shell 來執行命令。在 Linux 和 macOS 中，使用您偏好的 Shell 和套件管理工具。

注意

在 Windows 中，作業系統的內建終端不支援您常與 Lambda 搭配使用的某些 Bash CLI 命令 (例如 zip)。若要取得 Ubuntu 和 Bash 的 Windows 整合版本，請安裝適用於 Linux 的 Windows 子系統。

建立許可政策

在您可以為 Lambda 函數建立執行角色之前，您必須先建立許可政策，以授予函數存取所需 AWS 資源的許可。在本教學課程中，政策允許 Lambda 對 DynamoDB 資料表執行 CRUD 操作，以及寫入 Amazon CloudWatch Logs。

建立政策

1. 開啟 IAM 主控台中的政策頁面。

2. 選擇建立政策。

3. 選擇 JSON 索引標籤，然後將下列政策貼到 JSON 編輯器。

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "Stmt1428341300017",
         "Action": [
           "dynamodb:DeleteItem",
           "dynamodb:GetItem",
           "dynamodb:PutItem",
           "dynamodb:Query",
           "dynamodb:Scan",
           "dynamodb:UpdateItem"
         ],
         "Effect": "Allow",
         "Resource": "*"
       },
       {
         "Sid": "",
         "Resource": "*",
         "Action": [
           "logs:CreateLogGroup",
           "logs:CreateLogStream",
           "logs:PutLogEvents"
         ],
         "Effect": "Allow"
       }
     ]
   }

4. 選擇下一步：標籤。

5. 選擇下一步：檢閱。

6. 在檢閱政策下，針對政策名稱，輸入 lambda-apigateway-policy。

7. 選擇建立政策。

建立執行角色

執行角色是 AWS Identity and Access Management (IAM) 角色，授予 Lambda 函數存取 AWS 服務 和資源的許可。若要讓函數對 DynamoDB 資料表執行操作，您需附加在上個步驟中建立的許可政策。

建立執行角色並附加自訂許可政策

1. 開啟 IAM 主控台中的角色頁面。

2. 選擇 建立角色。

3. 信任的實體類型請選擇 AWS 服務，使用案例則選擇 Lambda。

4. 選擇下一步。

5. 在政策搜尋方塊中，輸入 lambda-apigateway-policy。

6. 在搜尋結果中，選取您建立的政策 (lambda-apigateway-policy)，然後選擇下一步。

7. 在 角色詳細資料 底下，角色名稱 請輸入 lambda-apigateway-role，然後選擇 建立角色 。

在教學課程的後續階段中，需用到您剛才建立的角色之 Amazon Resource Name (ARN)。在 IAM 主控台的 角色 頁面上，選擇角色的名稱 (lambda-apigateway-role)，然後複製 摘要 頁面上顯示的 角色 ARN 。

建立函數

下列程式碼範例會從 API Gateway 接收事件輸入，指定要對您建立的 DynamoDB 資料表執行的操作及一些承載資料。如果函數收到的參數有效，就會對資料表執行請求的操作。

Node.js

範例 index.mjs

請注意 region 設定。這必須符合您部署函數和建立 DynamoDB 資料表 AWS 區域 的 。

import { DynamoDBDocumentClient, PutCommand, GetCommand, 
         UpdateCommand, DeleteCommand} from "@aws-sdk/lib-dynamodb";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

const ddbClient = new DynamoDBClient({ region: "us-east-2" });
const ddbDocClient = DynamoDBDocumentClient.from(ddbClient);

// Define the name of the DDB table to perform the CRUD operations on
const tablename = "lambda-apigateway";

/**
 * Provide an event that contains the following keys:
 *
 *   - operation: one of 'create,' 'read,' 'update,' 'delete,' or 'echo'
 *   - payload: a JSON object containing the parameters for the table item
 *     to perform the operation on
 */
export const handler = async (event, context) => {
   
     const operation = event.operation;
   
     if (operation == 'echo'){
          return(event.payload);
     }
     
    else { 
        event.payload.TableName = tablename;
        let response;
        
        switch (operation) {
          case 'create':
               response = await ddbDocClient.send(new PutCommand(event.payload));
               break;
          case 'read':
               response = await ddbDocClient.send(new GetCommand(event.payload));
               break;
          case 'update':
               response = ddbDocClient.send(new UpdateCommand(event.payload));
               break;
          case 'delete':
               response = ddbDocClient.send(new DeleteCommand(event.payload));
               break;
          default:
            response = 'Unknown operation: ${operation}';
          }
        console.log(response);
        return response;
    }
};

注意

在此範例中，DynamoDB 資料表的名稱定義為函數程式碼中的變數。在實際的應用程式中，最佳實務是將此參數做為環境變數來傳遞，並避免對資料表名稱進行硬式編碼。如需詳細資訊，請參閱使用 AWS Lambda 環境變數。

建立函數

1. 將程式碼範例儲存為名為 的檔案index.mjs，並視需要編輯程式碼中指定的 AWS 區域。程式碼中指定的區域，必須與您稍後在教學課程中建立的 DynamoDB 資料表區域相同。

2. 使用以下 zip 命令建立部署套件。

   zip function.zip index.mjs

3. 使用 create-function AWS CLI 命令建立 Lambda 函數。對於 role 參數，輸入您先前複製的執行角色 Amazon Resource Name (ARN)。

   aws lambda create-function \
   --function-name LambdaFunctionOverHttps \
   --zip-file fileb://function.zip \
   --handler index.handler \
   --runtime nodejs22.x \
   --role arn:aws:iam::123456789012:role/service-role/lambda-apigateway-role

Python 3

範例 LambdaFunctionOverHttps.py

import boto3

# Define the DynamoDB table that Lambda will connect to
table_name = "lambda-apigateway"

# Create the DynamoDB resource
dynamo = boto3.resource('dynamodb').Table(table_name)

# Define some functions to perform the CRUD operations
def create(payload):
    return dynamo.put_item(Item=payload['Item'])

def read(payload):
    return dynamo.get_item(Key=payload['Key'])

def update(payload):
    return dynamo.update_item(**{k: payload[k] for k in ['Key', 'UpdateExpression', 
    'ExpressionAttributeNames', 'ExpressionAttributeValues'] if k in payload})

def delete(payload):
    return dynamo.delete_item(Key=payload['Key'])

def echo(payload):
    return payload

operations = {
    'create': create,
    'read': read,
    'update': update,
    'delete': delete,
    'echo': echo,
}

def lambda_handler(event, context):
    '''Provide an event that contains the following keys:
      - operation: one of the operations in the operations dict below
      - payload: a JSON object containing parameters to pass to the 
        operation being performed
    '''
    
    operation = event['operation']
    payload = event['payload']
    
    if operation in operations:
        return operations[operation](payload)
        
    else:
        raise ValueError(f'Unrecognized operation "{operation}"')

注意

在此範例中，DynamoDB 資料表的名稱定義為函數程式碼中的變數。在實際的應用程式中，最佳實務是將此參數做為環境變數來傳遞，並避免對資料表名稱進行硬式編碼。如需詳細資訊，請參閱使用 AWS Lambda 環境變數。

若要建立函數

1. 將程式碼範例儲存為名為 LambdaFunctionOverHttps.py 的檔案。

2. 使用以下 zip 命令建立部署套件。

   zip function.zip LambdaFunctionOverHttps.py

3. 使用 create-function AWS CLI 命令建立 Lambda 函數。對於 role 參數，輸入您先前複製的執行角色 Amazon Resource Name (ARN)。

   aws lambda create-function \
   --function-name LambdaFunctionOverHttps \
   --zip-file fileb://function.zip \
   --handler LambdaFunctionOverHttps.lambda_handler \
   --runtime python3.12 \
   --role arn:aws:iam::123456789012:role/service-role/lambda-apigateway-role

使用 叫用 函數 AWS CLI

在將函數與 API Gateway 整合之前，請確認已成功部署該函數。建立測試事件，其中包含 API Gateway API 將傳送至 Lambda 的參數， AWS CLI invoke並使用 命令來執行函數。

使用 叫用 Lambda 函數 AWS CLI

1. 將下面的 JSON 儲存為名為 input.txt 的檔案。

   {
       "operation": "echo",
       "payload": {
           "somekey1": "somevalue1",
           "somekey2": "somevalue2"
       }
   }

2. 執行下列 invoke AWS CLI 命令。

   aws lambda invoke \
   --function-name LambdaFunctionOverHttps \
   --payload file://input.txt outputfile.txt \
   --cli-binary-format raw-in-base64-out

   如果您使用的是第 2 AWS CLI 版，則需要 cli-binary-format選項。若要讓此成為預設的設定，請執行 aws configure set cli-binary-format raw-in-base64-out。若要取得更多資訊，請參閱《AWS Command Line Interface 使用者指南第 2 版》中 AWS CLI 支援的全域命令列選項。

   您應該會看到下列回應：

   {
       "StatusCode": 200,
       "ExecutedVersion": "LATEST"
   }

3. 確認函數已執行您在 JSON 測試事件中指定的 echo 操作。檢查 outputfile.txt 檔案，並確認包含下列內容：

   {"somekey1": "somevalue1", "somekey2": "somevalue2"}

使用 API Gateway 建立 REST API

在此步驟中，您將建立用來調用 Lambda 函數的 API Gateway REST API。

若要建立 API

1. 開啟 API Gateway 主控台。

2. 選擇 建立 API 。

3. 在 REST API 方塊中，選擇 建置 。

4. 在 API 詳細資訊下，讓新增 API維持在已選取的狀態，然後對於 API 名稱，輸入 DynamoDBOperations。

5. 選擇 建立 API 。

在 REST API 上建立資源

若要將 HTTP 方法新增到 API 中，首先需為該方法建立用來操作的資源。您可以在此建立資源來管理 DynamoDB 資料表。

若要建立資源

1. 在 API Gateway 主控台中，在 API 的資源頁面上，選擇建立資源。

2. 在資源詳細資訊中，針對資源名稱輸入 DynamoDBManager。

3. 選擇 建立資源 。

建立 HTTP POST 方法

在此步驟中，您將為 DynamoDBManager 資源建立方法 (POST)。您需將此 POST 方法連結到 Lambda 函數，如此一來當方法收到 HTTP 請求，API Gateway 就會調用 Lambda 函數。

注意

基於本教學課程的目的，會使用一個 HTTP 方法 (POST) 來調用單一 Lambda 函數，該函數會對 DynamoDB 資料表執行所有操作。在實際的應用程式中，最佳實務是針對每項操作使用不同的 Lambda 函數和 HTTP 方法。如需詳細資訊，請參閱無伺服器園地中的 The Lambda Monolith。

建立 POST 方法

1. 在 API 的資源頁面上，確定已反白選取 /DynamoDBManager 資源。然後，在方法窗格中，選擇建立方法。

2. 針對方法類型，選擇 POST。

3. 對於整合類型，讓 Lambda 函數維持在已選取的狀態。

4. 對於 Lambda 函數，請為函數 (LambdaFunctionOverHttps) 選擇 Amazon Resource Name (ARN)。

5. 選擇建立方法。

建立 DynamoDB 資料表

建立空白的 DynamoDB 資料表，Lambda 函數會對該資料表執行 CRUD 操作。

若要建立 DynamoDB 資料表

1. 開啟 DynamoDB 主控台的資料表頁面。

2. 選擇 建立資料表 。

3. 在 Table details (資料表詳細資訊) 下，執行下列動作：

   1. 對於 Table name (資料表名稱)，請輸入 lambda-apigateway。

   2. 對於 Partition key (分割區索引鍵)，輸入id，並保持資料類型設定為 String (字串)。

4. 在 Table settings (資料表設定) 下，保留 Default settings (預設設定)。

5. 選擇 建立資料表 。

測試 API Gateway、Lambda 和 DynamoDB 的整合

您現在已準備好測試 API Gateway API 方法與 Lambda 函數和 DynamoDB 資料表的整合。使用 API Gateway 主控台，您可以利用主控台的測試功能，將請求直接傳送至您的 POST 方法。在此步驟中，首先需使用 create 操作將新項目新增至 DynamoDB 資料表，然後使用 update 操作來修改項目。

測試 1：在 DynamoDB 資料表中建立新項目

1. 在 API Gateway 主控台中，選擇您的 API (DynamoDBOperations)。

2. 在 DynamoDBManager 資源下方，選擇 POST 方法。

   

3. 選擇測試標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。

4. 在測試方法下，讓查詢字串和標頭留空。對於請求主體，貼上下列 JSON：

   {
     "operation": "create",
     "payload": {
       "Item": {
         "id": "1234ABCD",
         "number": 5
       }
     }
   }

5. 選擇 測試 。

   測試完成時顯示的結果應該會顯示 200 狀態。此狀態碼表示 create 操作成功。

   若要確認，您可以檢查 DynamoDB 資料表現在是否包含新項目。

6. 開啟 DynamoDB 主控台的 資料表頁面 ，然後選擇 lambda-apigateway 資料表。

7. 選擇 探索資料表項目 。在 Items returned (傳回的項目) 窗格中，應該會看到一個包含 id 1234ABCD 和 number 5 的項目。範例：

   

測試 2 ：更新 DynamoDB 資料表中的項目

1. 在 API Gateway 主控台中，返回到 POST 方法的測試分頁。

2. 在測試方法下，讓查詢字串和標頭留空。對於請求主體，貼上下列 JSON：

   {
       "operation": "update",
       "payload": {
           "Key": {
               "id": "1234ABCD"
           },
           "UpdateExpression": "SET #num = :newNum",
           "ExpressionAttributeNames": {
               "#num": "number"
           },
           "ExpressionAttributeValues": {
               ":newNum": 10
           }
       }
   }

3. 選擇 測試 。

   測試完成時顯示的結果應該會顯示 200 狀態。此狀態碼表示 update 操作成功。

   若要確認，請檢查 DynamoDB 資料表中的項目是否已修改。

4. 開啟 DynamoDB 主控台的 資料表頁面 ，然後選擇 lambda-apigateway 資料表。

5. 選擇 探索資料表項目 。在 Items returned (傳回的項目) 窗格中，應該會看到一個包含 id 1234ABCD 和 number 10 的項目。

   

部署 API

為了讓用戶端能呼叫您的 API，您必須建立部署並建立相關聯的階段。階段代表 API 的快照，包括其方法和整合項目。

部署 API

1. 開啟 API Gateway 主控台中的 API 頁面，然後選擇 DynamoDBOperations API。

2. 在 API 的資源頁面上，選擇部署 API。

3. 對於階段，請選擇*新增階段*，然後在階段名稱輸入 test。

4. 選擇部署。

5. 在階段詳細資訊窗格中，複製調用 URL。您將在下一個步驟中使用此資料來透過 HTTP 請求調用函數。

使用 curl 來透過 HTTP 請求調用函數

您現在可以透過向 API 發出 HTTP 請求來調用 Lambda 函數。在此步驟中，您將在 DynamoDB 資料表中建立新項目，然後對該項目執行讀取、更新和刪除操作。

若要使用 curl 在 DynamoDB 資料表中建立項目

1. 使用您在上個步驟中複製的調用 URL 執行下列 curl 命令。將 curl 與 -d (資料) 選項搭配使用時，系統會自動使用 HTTP POST 方法。

   curl https://l8togsqxd8.execute-api.us-east-2.amazonaws.com/test/DynamoDBManager \
   -d '{"operation": "create", "payload": {"Item": {"id": "5678EFGH", "number": 15}}}'

   如果操作成功，您應該會看到傳回的回應及 HTTP 狀態碼 200。

2. 您也可以使用 DynamoDB 主控台執行下列步驟，驗證新項目是否在您的資料表中：

   1. 開啟 DynamoDB 主控台的 資料表頁面 ，然後選擇 lambda-apigateway 資料表。

   2. 選擇 探索資料表項目 。在 Items returned (傳回的項目) 窗格中，應該會看到一個包含 id 5678EFGH 和 number 15 的項目。

若要使用 curl 讀取 DynamoDB 資料表中的項目

• 執行以下 curl 命令來讀取您剛建立之項目的值。使用您自己的調用 URL。

  curl https://avos4dr2rk.execute-api.us-east-2.amazonaws.com/test/DynamoDBManager -d \
  '{"operation": "read", "payload": {"Key": {"id": "5678EFGH"}}}'

  視您選擇 Node.js 或 Python 函數程式碼而定，您應該會看到類似下列其中一項的輸出：

  Node.js

  {"$metadata":{"httpStatusCode":200,"requestId":"7BP3G5Q0C0O1E50FBQI9NS099JVV4KQNSO5AEMVJF66Q9ASUAAJG",
  "attempts":1,"totalRetryDelay":0},"Item":{"id":"5678EFGH","number":15}}

  Python

  {"Item":{"id":"5678EFGH","number":15},"ResponseMetadata":{"RequestId":"QNDJICE52E86B82VETR6RKBE5BVV4KQNSO5AEMVJF66Q9ASUAAJG",
  "HTTPStatusCode":200,"HTTPHeaders":{"server":"Server","date":"Wed, 31 Jul 2024 00:37:01 GMT","content-type":"application/x-amz-json-1.0",
  "content-length":"52","connection":"keep-alive","x-amzn-requestid":"QNDJICE52E86B82VETR6RKBE5BVV4KQNSO5AEMVJF66Q9ASUAAJG","x-amz-crc32":"2589610852"},
  "RetryAttempts":0}}

若要使用 curl 更新 DynamoDB 資料表中的項目

1. 執行下列 curl 命令，透過變更 number 值來更新您剛建立的項目。使用您自己的調用 URL。

   curl https://avos4dr2rk.execute-api.us-east-2.amazonaws.com/test/DynamoDBManager \
   -d '{"operation": "update", "payload": {"Key": {"id": "5678EFGH"}, "UpdateExpression": "SET #num = :new_value", "ExpressionAttributeNames": {"#num": "number"}, "ExpressionAttributeValues": {":new_value": 42}}}'

2. 若要確認項目的 number 值已更新，請執行另一個讀取命令：

   curl https://avos4dr2rk.execute-api.us-east-2.amazonaws.com/test/DynamoDBManager \
   -d '{"operation": "read", "payload": {"Key": {"id": "5678EFGH"}}}'

若要使用 curl 刪除 DynamoDB 資料表中的項目

1. 執行以下 curl 命令來刪除您剛剛建立的項目。使用您自己的調用 URL。

   curl https://l8togsqxd8.execute-api.us-east-2.amazonaws.com/test/DynamoDBManager \
   -d '{"operation": "delete", "payload": {"Key": {"id": "5678EFGH"}}}'

2. 確認刪除操作成功。在 DynamoDB 主控台 探索項目 頁面的 傳回的項目 窗格中，確認具有 id 5678EFGH 的項目已不存在於資料表中。

清除資源 (選用)

除非您想要保留為此教學課程建立的資源，否則您現在便可刪除。透過刪除不再使用 AWS 的資源，您可以避免不必要的費用 AWS 帳戶。

若要刪除 Lambda 函數

1. 開啟 Lambda 主控台中的 函數頁面。

2. 選擇您建立的函數。

3. 選擇 Actions (動作)、Delete (刪除)。

4. 在文字輸入欄位中輸入 confirm，然後選擇刪除。

刪除執行角色

1. 開啟 IAM 主控台中的 角色頁面 。

2. 選取您建立的執行角色。

3. 選擇刪除。

4. 在文字輸入欄位中輸入角色的名稱，然後選擇 刪除 。

若要刪除 API

1. 開啟 API Gateway 主控台中的 API 頁面 。

2. 選取您建立的 API。

3. 選擇 動作 、刪除 。

4. 選擇 刪除 。

若要刪除 DynamoDB 資料表

1. 開啟 DynamoDB 主控台的 資料表頁面 。

2. 選取您建立的資料表。

3. 選擇 刪除 。

4. 在文字方塊中輸入 delete。

5. 選擇 刪除資料表 。