# 使用 Amazon API Gateway 端点调用 Lambda 函数 您可以使用 Amazon API Gateway 为 Lambda 函数创建带有 HTTP 端点的 Web API。API Gateway 提供工具，用于创建和记录向 Lambda 函数路由 HTTP 请求的 Web API。您可以使用身份验证和授权控制来保护对 API 的访问。您的 API 可以通过互联网传输流量，也可以仅允许在您的 VPC 内访问。 **提示** Lambda 提供了两种方法来通过 HTTP 端点调用函数：API Gateway 和 Lambda 函数 URL。如果您不确定哪种方法最适合您的应用场景，请参阅[选择使用 HTTP 请求调用 Lambda 函数的方法](apig-http-invoke-decision.md)。 API 中的资源会定义一个或多个方法，如 GET 或 POST。方法具有将请求传送给 Lambda 函数或其他集成类型的集成。您可以单独定义每个资源和方法，也可以使用特定的资源和方法类型来匹配属于特定模式的所有请求。[代理资源](https://docs.amazonaws.cn/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html)会捕获某个资源下的所有路径。`ANY` 方法会捕获所有 HTTP 方法。 **Topics** + [ ## 选择 API 类型 ](#services-apigateway-apitypes) + [ ## 向 Lambda 函数添加终端节点 ](#apigateway-add) + [ ## 代理集成 ](#apigateway-proxy) + [ ## 事件格式 ](#apigateway-example-event) + [ ## 响应格式 ](#apigateway-types-transforms) + [ ## 权限 ](#apigateway-permissions) + [ ## 示例应用程序 ](#services-apigateway-samples) + [ ## Powertools for Amazon Lambda 中的事件处理程序 ](#services-apigateway-powertools) + [ # 教程：利用 API Gateway 使用 Lambda ](services-apigateway-tutorial.md) + [ # 利用 API Gateway API 处理 Lambda 错误 ](services-apigateway-errors.md) + [ # 选择使用 HTTP 请求调用 Lambda 函数的方法 ](apig-http-invoke-decision.md) ## 选择 API 类型 API Gateway 支持三种可调用 Lambda 函数的 API 类型： + [HTTP API](https://docs.amazonaws.cn/apigateway/latest/developerguide/http-api.html)：一种轻型的低延迟 RESTful API。 + [REST API](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-rest-api.html)：一种功能丰富的可定制 RESTful API。 + [WebSocket API](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-websocket-api.html)：一种 Web API，可与客户端保持持久连接并进行全双工通信。 HTTP API 和 REST API 都是用于处理 HTTP 请求并返回响应的 RESTful API。HTTP API 后推出，是使用 API Gateway 版本 2 API 构建的。以下是 HTTP API 的新功能： **HTTP API 功能** + **自动部署** – 当您修改路线或集成时，更改会自动部署到启用了自动部署的阶段。 + **默认阶段** – 您可以创建默认阶段 (`$default`)，以便在 API URL 的根路径处提供请求。对于具名阶段，必须在路径的开头包含阶段名称。 + **CORS 配置** – 您可以配置 API，使其将 CORS 标头添加到传出响应中，而不是在函数代码中手动添加。 REST API 是 API Gateway 自发布起就支持的典型 RESTful API。REST API 现在具有更多的自定义、集成和管理功能。 **REST API 功能** + **集成类型** – REST API 支持自定义 Lambda 集成。使用自定义集成，您可以直接将请求正文发送到函数，也可以对其应用转换模板，然后再发送到函数。 + **访问控制** – REST API 支持更多身份验证和授权选项。 + **监控和跟踪** – REST API 支持 Amazon X-Ray 跟踪和其他日志记录选项。 有关详细比较，请参阅《API Gateway 开发人员指南》**中的[在 HTTP API 和 REST API 之间选择](https://docs.amazonaws.cn/apigateway/latest/developerguide/http-api-vs-rest.html)。 WebSocket API 也使用 API Gateway 版本 2 API 并支持类似的功能集。对于受益于客户端和 API 之间的持久连接的应用程序，请使用 WebSocket API。WebSocket API 提供全双工通信，这意味着客户端和 API 都可以持续发送消息，而无需等待响应。 HTTP API 支持简化的事件格式（2.0 版）。有关来自 HTTP API 的事件的示例，请参阅[针对 API Gateway 中的 HTTP API 创建 Amazon Lambda 代理集成](https://docs.amazonaws.cn//apigateway/latest/developerguide/http-api-develop-integrations-lambda.html)。 有关更多信息，请参阅[针对 API Gateway 中的 HTTP API 创建 Amazon Lambda 代理集成](https://docs.amazonaws.cn/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html)。 ## 向 Lambda 函数添加终端节点 **向 Lambda 函数添加公有端点** 1. 打开 Lamba 控制台的[函数](https://console.amazonaws.cn/lambda/home#/functions)页面。 1. 选择函数。 1. 在 **Function overview**（函数概览）下，选择 **Add trigger**（添加触发器）。 1. 选择 **API Gateway (API 网关)**。 1. 选择 **Create an API**（创建 API）或 **Use an existing API**（使用现有 API）。 1. **New API（新 API）：**对于 **API type**（API 类型），请选择 **HTTP API**。有关更多信息，请参阅 [选择 API 类型](#services-apigateway-apitypes)。 1. **现有 API：**从下拉列表中选择 API 或输入 API ID（例如，r3pmxmplak）。 1. 对于 **Security (安全性)**，请选择 **Open (打开)**。 1. 选择**添加**。 ## 代理集成 API Gateway API 由阶段、资源、方法和集成组成。阶段和资源决定终端节点的路径： **API 路径格式** + `/prod/` – `prod` 阶段和根资源。 + `/prod/user` – `prod` 阶段和 `user` 资源。 + `/dev/{proxy+}` – `dev` 阶段中的路线。 + `/` – (HTTP API) 默认阶段和根资源。 Lambda 集成将路径和 HTTP 方法的组合映射到 Lambda 函数。您可以将 API Gateway 配置为按原样（自定义集成）传递 HTTP 请求体，或者将请求正文封装在包含所有请求信息（包括标头、资源、路径和方法）的文档中。 有关更多信息，请参阅 [API Gateway 中的 Lambda 代理集成](https://docs.amazonaws.cn/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html)。 ## 事件格式 Amazon API Gateway 会使用包含 HTTP 请求的 JSON 表示形式的事件[同步](invocation-sync.md)调用函数。对于自定义集成，该事件为请求的正文。对于代理集成，该事件具有已确定的结构。有关来自 API Gateway REST API 的代理事件的示例，请参阅《API Gateway 开发人员指南》**中的[用于代理集成的 Lambda 函数的输入格式](https://docs.amazonaws.cn/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format)。 ## 响应格式 API Gateway 会等待函数响应并将结果转发给调用方。对于自定义集成，您可以定义集成响应和方法响应，以将函数的输出转换为 HTTP 响应。对于代理集成，函数必须以特定格式的响应形式来做出响应。 以下示例显示了来自 Node.js 函数的响应对象。该响应对象表示包含 JSON 文档的成功 HTTP 响应。 **Example index.mjs：代理集成响应对象（Node.js）** ``` var response = { "statusCode": 200, "headers": { "Content-Type": "application/json" }, "isBase64Encoded": false, "multiValueHeaders": { "X-Custom-Header": ["My value", "My other value"], }, "body": "{\n \"TotalCodeSize\": 104330022,\n \"FunctionCount\": 26\n}" } ``` Lambda 运行时会将响应对象序列化为 JSON 并将其发送给 API。此 API 会解析该响应并用它来创建 HTTP 响应，然后再将其发送到发出原始请求的客户端。 **Example HTTP 响应** ``` < HTTP/1.1 200 OK < Content-Type: application/json < Content-Length: 55 < Connection: keep-alive < x-amzn-RequestId: 32998fea-xmpl-4268-8c72-16138d629356 < X-Custom-Header: My value < X-Custom-Header: My other value < X-Amzn-Trace-Id: Root=1-5e6aa925-ccecxmplbae116148e52f036 < { "TotalCodeSize": 104330022, "FunctionCount": 26 } ``` ## 权限 Amazon API Gateway 将从函数的[基于资源的策略](access-control-resource-based.md)获取调用函数的权限。您可以授予对整个 API 的调用权限，也可以仅授予对某个阶段、资源或方法的有限访问权限。 当您使用 Lambda 控制台、API Gateway 控制台或 Amazon SAM 模板向函数添加 API 时，会自动更新函数的基于资源的策略。以下是一个示例函数策略。 **Example 函数策略** **** ``` { "Version":"2012-10-17", "Id": "default", "Statement": [ { "Sid": "nodejs-apig-functiongetEndpointPermissionProd-BWDBXMPLXE2F", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "lambda:InvokeFunction", "Resource": "arn:aws-cn:lambda:cn-north-1:111122223333:function:nodejs-apig-function-1G3MXMPLXVXYI", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" }, "ArnLike": { "aws:SourceArn": "arn:aws-cn:execute-api:cn-north-1:111122223333:ktyvxmpls1/*/GET/" } } } ] } ``` 您可以通过以下 API 操作手动管理函数策略权限： + [AddPermission](https://docs.amazonaws.cn/lambda/latest/api/API_AddPermission.html) + [RemovePermission](https://docs.amazonaws.cn/lambda/latest/api/API_RemovePermission.html) + [GetPolicy](https://docs.amazonaws.cn/lambda/latest/api/API_GetPolicy.html) 使用 `add-permission` 命令，可授予对现有 API 的调用权限。示例： ``` aws lambda add-permission \ --function-name my-function \ --statement-id apigateway-get --action lambda:InvokeFunction \ --principal apigateway.amazonaws.com.cn \ --source-arn "arn:aws:execute-api:cn-north-1:123456789012:mnh1xmpli7/default/GET/" ``` 您应看到以下输出： ``` { "Statement": "{\"Sid\":\"apigateway-test-2\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"apigateway.amazonaws.com.cn\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:cn-north-1:123456789012:function:my-function\",\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:execute-api:cn-north-1:123456789012:mnh1xmpli7/default/GET\"}}}" } ``` **注意** 如果您的函数和 API 位于不同的 Amazon Web Services 区域，则源 ARN 中的区域标识符必须与函数的区域（而不是 API 的区域）匹配。当 API Gateway 调用函数时，它会使用基于 API ARN 的资源 ARN，但该资源 ARN 已被修改为与函数的区域相匹配。 此示例中的源 ARN 授予对 API 默认阶段根资源 GET 方法的集成的权限，其 ID为 `mnh1xmpli7`。您可以在源 ARN 中使用星号授予对多个阶段、方法或资源的权限。 **资源模式** + `mnh1xmpli7/*/GET/*` – 对所有阶段中的所有资源调用 GET 方法。 + `mnh1xmpli7/prod/ANY/user` – 对 `prod` 阶段中的 `user` 资源调用 ANY 方法。 + `mnh1xmpli7/*/*/*` – 对所有阶段中的所有资源调用 ANY 方法。 有关查看策略和删除语句的详细信息，请参阅[在 Lambda 中查看基于资源的 IAM 策略](access-control-resource-based.md)。 ## 示例应用程序 [带有 Node.js 的 API Gateway](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/nodejs-apig) 示例应用程序包含具有 Amazon SAM 模板的函数，该模板可用于创建启用了 Amazon X-Ray 跟踪的 REST API。它还包含用于部署和调用函数、测试 API 以及执行清理的脚本。 ## Powertools for Amazon Lambda 中的事件处理程序 在编写由 API Gateway 端点（HTTP 或 REST）调用的 Lambda 函数时，Powertools for Amazon Lambda 工具包中的事件处理程序提供路由、中间件、CORS 配置、OpenAPI 规范生成、请求验证、错误处理和其他有用的功能。事件处理程序实用程序适用于 Python 和 TypeScript/JavaScript。有关更多信息，请参阅 *Powertools for Amazon Lambda (Python) 文档*中的[事件处理程序 REST API](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/) 和 *Powertools for Amazon Lambda (TypeScript) 文档*中的[事件处理程序 HTTP API](https://docs.amazonaws.cn/powertools/typescript/latest/features/event-handler/http/)。 ### Python ``` from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import APIGatewayRestResolver from aws_lambda_powertools.logging import correlation_paths from aws_lambda_powertools.utilities.typing.lambda_context import LambdaContext app = APIGatewayRestResolver() logger = Logger() @app.get("/healthz") def ping(): return {"message": "health status ok"} @logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST) def lambda_handler(event: dict, context: LambdaContext) -> dict: return app.resolve(event, context) ``` ### Typescript ``` import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest'; import { Logger } from '@aws-lambda-powertools/logger'; import { correlationPaths, search, } from '@aws-lambda-powertools/logger/correlationId'; import type { Context } from 'aws-lambda/handler'; const logger = new Logger({ correlationIdSearchFn: search, }); const app = new Router({ logger }); app.get("/healthz", async () => { return { message: "health status ok" }; }); export const handler = async (event: unknown, context: Context) => { // You can continue using other utilities just as before logger.addContext(context); logger.setCorrelationId(event, correlationPaths.API_GATEWAY_REST); return app.resolve(event, context); }; ``` # 教程：利用 API Gateway 使用 Lambda 在本教程中，您将创建 REST API，您可以借助它使用 HTTP 请求调用 Lambda 函数。Lambda 函数将对 DynamoDB 表执行创建、读取、更新和删除（CRUD）操作。此处提供此函数用于演示，但您将学习配置可以调用任何 Lambda 函数的 API Gateway REST API。 ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/APIG_tut_resources.png) 使用 API Gateway 可为用户提供安全的 HTTP 端点来调用 Lambda 函数，并可以通过节流流量以及自动验证和授权 API 调用来帮助管理大量函数调用。API Gateway 还使用 Amazon Identity and Access Management（IAM）和 Amazon Cognito 提供灵活的安全控制。对于需要预先授权才能调用应用程序的使用案例而言，这非常有用。 **提示** Lambda 提供了两种方法来通过 HTTP 端点调用函数：API Gateway 和 Lambda 函数 URL。如果您不确定哪种方法最适合您的应用场景，请参阅[选择使用 HTTP 请求调用 Lambda 函数的方法](apig-http-invoke-decision.md)。 要完成本教程，您需要经历以下阶段： 1. 在 Python 或 Node.js 中创建和配置 Lambda 函数以对 DynamoDB 表执行操作。 1. 在 API Gateway 中创建 REST API 以连接 Lambda 函数。 1. 创建 DynamoDB 表，并在控制台中使用 Lambda 函数对其进行测试。 1. 部署 API 并在终端中使用 curl 测试完整设置。 完成这些阶段后，您将了解如何使用 API Gateway 创建 HTTP 端点，该端点可以安全地调用任何规模的 Lambda 函数。此外，您将了解如何部署 API、如何在控制台中对其进行测试以及如何使用终端发送 HTTP 请求。 ## 创建权限策略 为 Lambda 函数创建[执行角色](lambda-intro-execution-role.md)之前，首先需要创建权限策略以授予函数访问所需 Amazon 资源的权限。在本教程中，该策略允许 Lambda 对 DynamoDB 表执行 CRUD 操作并写入 Amazon CloudWatch Logs。 **创建策略** 1. 打开 IAM 控制台的 [Policies（策略）页面](https://console.amazonaws.cn/iam/home#/policies)。 1. 选择**创建策略**。 1. 选择 **JSON** 选项卡，然后将以下自定义策略粘贴到 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" } ] } ``` ------ 1. 选择**下一步：标签**。 1. 选择**下一步：审核**。 1. 在 **Review policy (查看策略)** 下，为策略 **Name (名称)** 输入 **lambda-apigateway-policy**。 1. 选择**创建策略**。 ## 创建执行角色 [执行角色](lambda-intro-execution-role.md)是一个 Amazon Identity and Access Management（IAM）角色，用于向 Lambda 函数授予访问 Amazon Web Services 服务 和资源的权限。要使函数对 DynamoDB 表执行操作，您需要附加上一步中创建的权限策略。 **创建执行角色并附加自定义权限策略** 1. 打开 IAM 控制台的[角色页面](https://console.amazonaws.cn/iam/home#/roles)。 1. 选择**创建角色**。 1. 对于可信实体，选择 **Amazon 服务**，对于使用案例，选择 **Lambda**。 1. 选择**下一步**。 1. 在策略搜索框中，输入 **lambda-apigateway-policy**。 1. 在搜索结果中，选择您创建的策略（`lambda-apigateway-policy`），然后选择 **Next**（下一步）。 1. 在 **Role details**（角色详细信息）下，为 **Role name**（角色名称）输入 **lambda-apigateway-role**，然后选择 **Create role**（创建角色）。 ## 创建 Lambda 函数 1. 打开 Lambda 控制台的[“函数”页面](https://console.amazonaws.cn/lambda/home#/functions)，然后选择**创建函数**。 1. 选择**从头开始创作**。 1. 对于**函数名称**，请输入 `LambdaFunctionOverHttps`。 1. 对于**运行时**，选择最新的 Node.js 或 Python 运行时。 1. 在**权限**下，展开**更改默认执行角色**。 1. 选择**使用现有角色**，然后选择您之前创建的 **lambda-apigateway-role** 角色。 1. 选择**创建函数**。 1. 在**代码源**窗格中，将默认代码替换为下面的 Node.js 或 Python 代码。 ------ #### [ Node.js ] `region` 设置必须与您部署函数和[创建 DynamoDB 表](#services-apigateway-tutorial-table)的 Amazon Web Services 区域相匹配。 **Example index.mjs** ``` import { DynamoDBDocumentClient, PutCommand, GetCommand, UpdateCommand, DeleteCommand} from "@aws-sdk/lib-dynamodb"; import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; const ddbClient = new DynamoDBClient({ region: "cn-north-1" }); 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; } }; ``` ------ #### [ Python ] **Example lambda\$1function.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 表的名称定义为函数代码中的变量。在实际应用程序中，最佳做法是将此参数作为环境变量传递，并避免对表名称进行硬编码。有关更多信息，请参阅[使用 Amazon Lambda 环境变量](https://docs.amazonaws.cn/lambda/latest/dg/configuration-envvars.html)。 1. 在**部署**部分，选择**部署**以更新函数的代码： ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/getting-started-tutorial/deploy-console.png) ## 测试此函数 将函数与 API Gateway 集成之前，请确认您已成功部署该函数。使用 Lambda 控制台向您的函数发送测试事件。 1. 在函数的 Lambda 控制台页面上，选择**测试**选项卡。 ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/test-tab.png) 1. 向下滚动到**事件 JSON** 部分，并将默认事件替换为以下内容。此事件与 Lambda 函数预期的结构相匹配。 ``` { "operation": "echo", "payload": { "somekey1": "somevalue1", "somekey2": "somevalue2" } } ``` 1. 选择**测试**。 1. 在**执行函数：成功**下，展开**详细信息**。您应看到以下响应： ``` { "somekey1": "somevalue1", "somekey2": "somevalue2" } ``` ## 使用 API Gateway 创建 REST API 在此步骤中，您将创建用于调用 Lambda 函数的 API Gateway REST API。 **创建 API** 1. 打开 [API Gateway 控制台](https://console.amazonaws.cn/apigateway)。 1. 选择 **Create API (创建 API)**。 1. 在 **REST API** 框中，选择 **Build (构建)**。 1. 在 **API 详细信息**下，将**新建 API** 保留为选中状态，然后在 **API 名称**中输入 **DynamoDBOperations**。 1. 选择**创建 API**。 ## 在 REST API 上创建资源 要将 HTTP 方法添加到 API，您首先需要创建资源供该方法运行。您可以在此处创建资源来管理 DynamoDB 表。 **创建资源** 1. 在 [API Gateway 控制台](https://console.amazonaws.cn/apigateway)中，在您的 API 的**资源**页面上，选择**创建资源**。 1. 在**资源详细信息**中，在**资源名称**中输入 **DynamoDBManager**。 1. 选择**创建资源**。 ## 创建 HTTP POST 方法 在此步骤中，您将为 `DynamoDBManager` 资源创建方法（`POST`）。您可以将此 `POST` 方法链接到 Lambda 函数，以便当该方法接收 HTTP 请求时，API Gateway 可以调用 Lambda 函数。 **注意** 就本教程而言，一个 HTTP 方法（`POST`）可用于调用一个 Lambda 函数，该函数将对 DynamoDB 表执行全部操作。在实际应用程序中，最佳做法是针对每个操作使用不同的 Lambda 函数和 HTTP 方法。有关更多信息，请参阅 Serverless Land 中的 [The Lambda monolith](https://serverlessland.com/content/service/lambda/guides/aws-lambda-operator-guide/monolith)。 **创建 POST 方法** 1. 在您的 API 的**资源**页面上，确保突出显示 `/DynamoDBManager` 资源。然后，在**方法**窗格中，选择**创建方法**。 1. 对于**方法类型**，选择 **POST**。 1. 对于**集成类型**，将 **Lambda 函数**保留为选中状态。 1. 对于 **Lambda 函数**，选择函数（`LambdaFunctionOverHttps`）的 Amazon 资源名称（ARN）。 1. 选择**创建方法**。 ## 创建 DynamoDB 表 创建一个空的 DynamoDB 表，Lambda 函数将对其执行 CRUD 操作。 **创建 DynamoDB 表** 1. 打开 DynamoDB 控制台中 [Tables page](https://console.amazonaws.cn/dynamodbv2#tables)（表页面）。 1. 选择**创建表**。 1. 在 **Table details (表详细信息)** 下，执行以下操作： 1. 对于**表名称**，输入 **lambda-apigateway**。 1. 对于 **Partition key (分区键)**，输入 **id**，并将数据类型设置为 **String (字符串)**。 1. 在 **Table settings**（表设置）下，使用 **Default settings**（默认设置）。 1. 选择**创建表**。 ## 测试 API Gateway、Lambda 和 DynamoDB 的集成 现在，您已准备好测试 API Gateway API 方法与 Lambda 函数和 DynamoDB 表的集成。借助 API Gateway 控制台，您可以使用控制台的测试功能将请求直接发送到 `POST` 方法。在此步骤中，您首先使用 `create` 操作将新项目添加到 DynamoDB 表，然后使用 `update` 操作修改该项目。 **测试 1：在 DynamoDB 表中创建新项目** 1. 在 [API Gateway console](https://console.amazonaws.cn/apigateway)（API Gateway 控制台）中，选择 API（`DynamoDBOperations`）。 1. 在 `DynamoDBManager` 资源下，选择 **POST** 方法。 1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。 1. 在**测试方法**下，将**查询字符串**和**标头**留空。对于**请求正文**，粘贴以下 JSON： ``` { "operation": "create", "payload": { "Item": { "id": "1234ABCD", "number": 5 } } } ``` 1. 选择**测试**。 测试完成后，所显示的结果应显示状态 `200`。此状态代码表示 `create` 操作成功。 要进行确认，请检查 DynamoDB 表现在是否包含新项目。 1. 打开 DynamoDB 控制台中的 [Tables page](https://console.amazonaws.cn/dynamodbv2#tables)（表页面），然后选择 `lambda-apigateway` 表。 1. 选择 **Explore table items**（浏览表项目）。在 **Items returned**（返回的项目）窗格中，您会看到一个带 **id** `1234ABCD` 和 **number**（编号）`5` 的项目。示例： ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/items-returned.png) **测试 2：更新 DynamoDB 表中的项目** 1. 在 [API Gateway 控制台](https://console.amazonaws.cn/apigateway)中，返回到 POST 方法的**测试**选项卡。 1. 在**测试方法**下，将**查询字符串**和**标头**留空。对于**请求正文**，粘贴以下 JSON： ``` { "operation": "update", "payload": { "Key": { "id": "1234ABCD" }, "UpdateExpression": "SET #num = :newNum", "ExpressionAttributeNames": { "#num": "number" }, "ExpressionAttributeValues": { ":newNum": 10 } } } ``` 1. 选择**测试**。 测试完成后，所显示的结果应显示状态 `200`。此状态代码表示 `update` 操作成功。 要进行确认，请检查 DynamoDB 表中的项目是否已修改。 1. 打开 DynamoDB 控制台中的 [Tables page](https://console.amazonaws.cn/dynamodbv2#tables)（表页面），然后选择 `lambda-apigateway` 表。 1. 选择 **Explore table items**（浏览表项目）。在 **Items returned**（返回的项目）窗格中，您会看到一个带 **id** `1234ABCD` 和 **number**（编号）`10` 的项目。 ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/items-returned-2.png) ## 部署 API 要让客户端调用 API，您必须创建部署和关联的阶段。阶段表示 API 的快照，包括其方法和集成。 **部署 API** 1. 打开 [API Gateway console](https://console.amazonaws.cn/apigateway)（API Gateway 控制台）的 **API** 页面，然后选择 `DynamoDBOperations` API。 1. 在您的 API 的**资源**页面上，选择**部署 API**。 1. 对于**阶段**，请选择**\$1新建阶段\$1**，然后在**阶段名称**中输入 **test**。 1. 选择**部署**。 1. 在**阶段详细信息**窗格中，复制**调用 URL**。您将在下一步中使用它，通过 HTTP 请求调用函数。 ## 使用 curl 通过 HTTP 请求调用函数 现在，您可以通过向 API 发出 HTTP 请求来调用 Lambda 函数。在此步骤中，您将在 DynamoDB 表中创建一个新项目，然后对该项目执行读取、更新和删除操作。 **使用 curl 在 DynamoDB 表中创建项目** 1. 在本地计算机上打开终端或命令提示符，使用您在上一步中复制的调用 URL 运行以下 `curl` 命令。此命令使用以下选项： + `-H`：向请求添加自定义标头。这里，它将内容类型指定为 JSON。 + `-d`：在请求正文中发送数据。此选项默认使用 HTTP POST 方法。 ------ #### [ Linux/macOS ] ``` curl https://l8togsqxd8.execute-api.cn-north-1.amazonaws.com.cn/test/DynamoDBManager \ -H "Content-Type: application/json" \ -d '{"operation": "create", "payload": {"Item": {"id": "5678EFGH", "number": 15}}}' ``` ------ #### [ PowerShell ] ``` curl.exe 'https://l8togsqxd8.execute-api.cn-north-1.amazonaws.com.cn/test/DynamoDBManager' -H 'Content-Type: application/json' -d '{\"operation\": \"create\", \"payload\": {\"Item\": {\"id\": \"5678EFGH\", \"number\": 15}}}' ``` ------ 如果操作成功，您应该会看到返回的响应，其中包含 HTTP 状态代码 200。 1. 您还可以使用 DynamoDB 控制台，通过执行以下操作来验证新项目是否在表中： 1. 打开 DynamoDB 控制台中的 [Tables page](https://console.amazonaws.cn/dynamodbv2#tables)（表页面），然后选择 `lambda-apigateway` 表。 1. 选择 **Explore table items**（浏览表项目）。在 **Items returned**（返回的项目）窗格中，您会看到一个带 **id** `5678EFGH` 和 **number**（编号）`15` 的项目。 **使用 curl 读取 DynamoDB 表中的项目** + 在终端或命令提示符中，运行以下 `curl` 命令读取您刚创建的项目的值。使用您自己的调用 URL。 ------ #### [ Linux/macOS ] ``` curl https://l8togsqxd8.execute-api.cn-north-1.amazonaws.com.cn/test/DynamoDBManager \ -H "Content-Type: application/json" \ -d '{"operation": "read", "payload": {"Key": {"id": "5678EFGH"}}}' ``` ------ #### [ PowerShell ] ``` curl.exe 'https://l8togsqxd8.execute-api.cn-north-1.amazonaws.com.cn/test/DynamoDBManager' -H 'Content-Type: application/json' -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。 ------ #### [ Linux/macOS ] ``` curl https://l8togsqxd8.execute-api.cn-north-1.amazonaws.com.cn/test/DynamoDBManager \ -H "Content-Type: application/json" \ -d '{"operation": "update", "payload": {"Key": {"id": "5678EFGH"}, "UpdateExpression": "SET #num = :new_value", "ExpressionAttributeNames": {"#num": "number"}, "ExpressionAttributeValues": {":new_value": 42}}}' ``` ------ #### [ PowerShell ] ``` curl.exe 'https://l8togsqxd8.execute-api.cn-north-1.amazonaws.com.cn/test/DynamoDBManager' -H 'Content-Type: application/json' -d '{\"operation\": \"update\", \"payload\": {\"Key\": {\"id\": \"5678EFGH\"}, \"UpdateExpression\": \"SET #num = :new_value\", \"ExpressionAttributeNames\": {\"#num\": \"number\"}, \"ExpressionAttributeValues\": {\":new_value\": 42}}}' ``` ------ 1. 要确认项目的 `number` 值已更新，再运行一条 read 命令： ------ #### [ Linux/macOS ] ``` curl https://l8togsqxd8.execute-api.cn-north-1.amazonaws.com.cn/test/DynamoDBManager \ -H "Content-Type: application/json" \ -d '{"operation": "read", "payload": {"Key": {"id": "5678EFGH"}}}' ``` ------ #### [ PowerShell ] ``` curl.exe 'https://l8togsqxd8.execute-api.cn-north-1.amazonaws.com.cn/test/DynamoDBManager' -H 'Content-Type: application/json' -d '{\"operation\": \"read\", \"payload\": {\"Key\": {\"id\": \"5678EFGH\"}}}' ``` ------ **使用 curl 删除 DynamoDB 表中的项目** 1. 在终端或命令提示符中，运行以下 `curl` 命令以删除您刚创建的项目。使用您自己的调用 URL。 ------ #### [ Linux/macOS ] ``` curl https://l8togsqxd8.execute-api.cn-north-1.amazonaws.com.cn/test/DynamoDBManager \ -H "Content-Type: application/json" \ -d '{"operation": "delete", "payload": {"Key": {"id": "5678EFGH"}}}' ``` ------ #### [ PowerShell ] ``` curl.exe 'https://l8togsqxd8.execute-api.cn-north-1.amazonaws.com.cn/test/DynamoDBManager' -H 'Content-Type: application/json' -d '{\"operation\": \"delete\", \"payload\": {\"Key\": {\"id\": \"5678EFGH\"}}}' ``` ------ 1. 确认删除操作是否成功。在 DynamoDB 控制台**浏览项目**页面的**返回的项目**窗格中，验证表中是否不再包含带 **id** `5678EFGH` 的项目。 ## 清除资源（可选） 除非您想要保留为本教程创建的资源，否则可立即将其删除。通过删除您不再使用的 Amazon 资源，可防止您的 Amazon Web Services 账户 产生不必要的费用。 **删除 Lambda 函数** 1. 打开 Lamba 控制台的 [Functions（函数）页面](https://console.amazonaws.cn/lambda/home#/functions)。 1. 选择您创建的函数。 1. 依次选择**操作**和**删除**。 1. 在文本输入字段中键入 **confirm**，然后选择**删除**。 **删除执行角色** 1. 打开 IAM 控制台的[角色页面](https://console.amazonaws.cn/iam/home#/roles)。 1. 选择您创建的执行角色。 1. 选择**删除**。 1. 在文本输入字段中输入角色名称，然后选择**删除**。 **删除 API** 1. 打开 API Gateway 控制台的 [API 页面](https://console.amazonaws.cn/apigateway/main/apis)。 1. 选择您创建的 API。 1. 依次选择**操作**和**删除**。 1. 选择**删除**。 **删除 DynamoDB 表** 1. 打开 DynamoDB 控制台中 [Tables page](https://console.amazonaws.cn//dynamodb/home#tables:)（表页面）。 1. 选择您创建的表。 1. 选择**删除**。 1. 在文本框中输入 **delete**。 1. 选择 **删除表**。 # 利用 API Gateway API 处理 Lambda 错误 API Gateway 将所有调用和函数错误视为内部错误。如果 Lambda API 拒绝调用请求，API Gateway 会返回 500 错误代码。如果函数运行但返回错误，或返回格式错误的响应，API Gateway 会返回 502。在这两种情况下，来自 API Gateway 的响应的正文都是 `{"message": "Internal server error"}`。 **注意** API Gateway 不会重试 Lambda 调用。如果 Lambda 返回错误，API Gateway 会向客户端返回错误响应。 以下示例显示导致 API Gateway 中出现函数错误和 502 的请求的 X-Ray 跟踪映射。客户端收到通用错误消息。 ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/tracemap-apig-502.png) 要自定义错误响应，您必须捕获代码中的错误并以所需格式设置响应的格式。 **Example [index.mjs](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/nodejs-apig/function/index.mjs)：格式设置错误** ``` var formatError = function(error){ var response = { "statusCode": error.statusCode, "headers": { "Content-Type": "text/plain", "x-amzn-ErrorType": error.code }, "isBase64Encoded": false, "body": error.code + ": " + error.message } return response } ``` API Gateway 将此响应转换为带有自定义状态代码和正文的 HTTP 错误。在跟踪映射中，函数节点为绿色，因为它处理了错误。 ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/tracemap-apig-404.png) # 选择使用 HTTP 请求调用 Lambda 函数的方法 Lambda 的许多常见使用案例都涉及使用 HTTP 请求调用函数。例如，您可能希望 Web 应用程序通过浏览器请求调用函数。Lambda 函数还可用于创建完整的 REST API、处理来自移动应用程序的用户交互、通过 HTTP 调用处理来自外部服务的数据，或者创建自定义 Webhook。 以下几节介绍了通过 HTTP 调用 Lambda 的选择，并提供了有助于您针对特定使用案例做出正确决策的信息。 ## 在选择 HTTP 调用方法时，您有什么选择？ Lambda 提供了两种使用 HTTP 请求调用函数的主要方法：[函数 URL](urls-configuration.md) 和 [API Gateway](services-apigateway.md)。这两个选项之间的主要差异如下所示： + **Lambda 函数 URL** 为 Lambda 函数提供了简单、直接的 HTTP 端点。它们针对简单性和成本效益进行了优化，且提供了通过 HTTP 公开 Lambda 函数的最快路径。 + **API Gateway** 是用于构建功能齐全的 API 的更高级服务。API Gateway 针对大规模构建和管理生产 API 进行了优化，并提供了用于安全、监控和流量管理的全面工具。 ## 在已经知道自己要求的情况下的建议 如果您已经明确自己的要求，则以下是我们的基本建议： 建议在简单的应用程序或原型设计中使用**[函数 URL](urls-configuration.md)**，其中您只需要基本身份验证方法和请求/响应处理，并且希望将成本和复杂性降至最低。 **[API Gateway](services-apigateway.md)** 是大规模生产应用程序或需要更高级功能的情况下的更好选择，例如 [OpenAPI 描述](https://www.openapis.org/)支持、身份验证选项选择、自定义域名或丰富的请求/响应处理（包括节流、缓存和请求/响应转换）。 ## 选择用于调用 Lambda 函数的方法时要考虑的事项 在函数 URL 与 API Gateway 之间进行选择时，您需要考虑以下因素： + 您的身份验证需求，例如您需要 OAuth 还是 Amazon Cognito 来对用户进行身份验证 + 您的扩展要求和要实施的 API 的复杂性 + 您是否需要请求验证和请求/响应格式等高级功能 + 您的监控要求 + 您的成本目标 通过了解这些因素，您可以选择能平衡安全性、复杂性和成本要求的最佳选项。 以下信息汇总了两个选项之间的主要差异。 ### 身份验证 + **函数 URL** 通过 Amazon Identity and Access Management（IAM）提供基本身份验证选项。您可以将端点配置为公有（无身份验证）或要求 IAM 身份验证。通过 IAM 身份验证，您可以使用标准 Amazon 凭证或 IAM 角色来控制访问权限。虽然设置起来很简单，但与其他身份验证方法相比，此方法提供的选项有限。 + **API Gateway** 提供对更全面的身份验证选项的访问权限。除了 IAM 身份验证外，您还可以使用 [Lambda 授权方](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)（自定义身份验证逻辑）、[Amazon Cognito](https://docs.amazonaws.cn/cognito/latest/developerguide/what-is-amazon-cognito.html) 用户池和 OAuth 2.0 流。这种灵活性使您能够实施复杂的身份验证方案，包括第三方身份验证提供商、基于令牌的身份验证和多重身份验证。 ### 请求/响应处理 + **函数 URL** 提供了基本的 HTTP 请求和响应处理。它们支持标准 HTTP 方法，并包括内置的跨源资源共享（CORS）支持。虽然它们可以自然地处理 JSON 有效载荷和查询参数，但不提供请求转换或验证功能。响应处理同样简单 – 客户端从您的 Lambda 函数接收的响应与 Lambda 返回的响应完全相同。 + **API Gateway** 提供了高级的请求和响应处理功能。您可以定义请求验证器、使用映射模板转换请求和响应、设置请求/响应标头，以及实施响应缓存。API Gateway 还支持二进制有效载荷和自定义域名，并且可以在响应到达客户端之前对其修改。您可以通过使用 JSON 架构来为请求/响应验证和转换设置模型。 ### 扩展 + **函数 URL** 可直接根据您的 Lambda 函数的并发限制进行扩展，并通过将函数扩展到其配置的最大并发限制来处理流量激增。达到该限制后，Lambda 将使用 HTTP 429 响应来响应其他请求。由于没有内置的队列机制，因此处理扩展完全取决于您的 Lambda 函数的配置。默认情况下，Lambda 函数每个 Amazon Web Services 区域的并发执行限制为 1000 次。 + **API Gateway** 在 Lambda 自己的扩展基础上提供了额外的扩展功能。其中包括内置的请求队列和节流控制，使您可以更妥善地管理流量激增。默认情况下，API Gateway 每个区域每秒最多可以处理 1 万个请求，容量爆增为每秒 5000 个请求。还提供了在不同级别（API、阶段或方法）限制请求的工具，以保护您的后端。 ### 监控 + **函数 URL** 通过 Amazon CloudWatch 指标来提供基本监控，包括请求计数、延迟和错误率。您可以访问标准 Lambda 指标和日志，它们显示了进入函数的原始请求。虽然这提供了基本的运营可见性，但这些指标主要侧重于函数执行。 + **API Gateway** 提供全面的监控功能，其中包括详细的指标、日志记录和跟踪选项。您可以通过 CloudWatch 监控 API 调用、延迟、错误率和缓存命中/未命中率。API Gateway 还与 Amazon X-Ray 集成，用于分布式跟踪，并提供可自定义的日志记录格式。 ### 成本 + **函数 URL** 遵循标准 Lambda 定价模型 – 您只需按函数调用和计算时间付费。URL 端点本身不收取额外费用。如果您不需要 API Gateway 的其他功能，则会使其成为简单 API 或低流量应用程序的经济实惠之选。 + **API Gateway** 提供[免费套餐](https://www.amazonaws.cn/api-gateway/pricing/#Free_Tier)，其中包括为 REST API 接收的一百万次 API 调用和为 HTTP API 接收的一百万次 API 调用。此后，API Gateway 将对 API 调用、数据传输和缓存（如果已启用）收费。请参阅 API Gateway [定价页面](https://www.amazonaws.cn/api-gateway/pricing/)，了解您自己的使用案例的成本。 ### 其他功能 + **函数 URL** 旨在实现简单性以及 Lambda 直接集成。它们同时支持 HTTP 和 HTTPS 端点，提供内置的 CORS 支持，并提供双堆栈（IPv4 和 IPv6）端点。虽然它们缺乏高级功能，但在需要以快速、直接的方式通过 HTTP 公开 Lambda 函数的场景中，它们表现出色。 + **API Gateway** 包括许多其他功能，例如 API 版本控制、阶段管理、使用计划的 API 密钥、通过 Swagger/OpenAPI 提供的 API 文档、WebSocket API、VPC 内的私有 API，以及用于提高安全性的 WAF 集成。它还支持金丝雀部署、用于测试的模拟集成以及与 Lambda 之外的其他 Amazon Web Services 服务的集成。 ## 选择调用 Lambda 函数的方法 现在，您已经了解了在 Lambda 函数 URL 与 API Gateway 之间进行选择的标准以及它们之间的主要区别，您可以选择最符合您需求的选项，并使用以下资源来帮助您开始使用它。 ------ #### [ Function URLs ] **通过以下资源开始使用函数 URL** + 按照[使用函数 URL 创建 Lambda 函数](urls-webhook-tutorial.md)教程进行操作 + 在本指南的[创建和管理 Lambda 函数 URL](urls-configuration.md) 章节中了解有关函数 URL 的更多信息 + 通过执行以下操作，尝试控制台内指导教程**创建简单的 Web 应用程序**： 1. 打开 Lamba 控制台的[函数页面](https://console.amazonaws.cn/lambda/home#/functions)。 1. 选择屏幕右上角的图标打开帮助面板。 ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/console_help_screenshot.png) 1. 选择**教程**。 1. 在**创建简单的 Web 应用程序**中，选择**开始教程**。 ------ #### [ API Gateway ] **通过以下资源开始使用 Lambda 和 API Gateway** + 按照[利用 API Gateway 使用 Lambda](services-apigateway-tutorial.md) 教程，创建与后端 Lambda 函数集成的 REST API。 + 要详细了解 API Gateway 提供的不同类型 API，请参阅《Amazon API Gateway 开发人员指南》**的以下部分： + [API Gateway REST API](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-rest-api.html) + [API Gateway HTTP API](https://docs.amazonaws.cn/apigateway/latest/developerguide/http-api.html) + [API Gateway WebSocket API](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-websocket-api.html) + 试用《Amazon API Gateway 开发人员指南》**的[教程和研讨会](https://docs.amazonaws.cn/apigateway/latest/developerguide/api-gateway-tutorials.html)部分中的一个或多个示例。 ------