Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

在 Amazon API Gateway 中利用 Lambda 集成创建 REST API

您可以使用本演练在 Amazon API Gateway 中通过 Lambda 代理集成和 Lambda 非代理集成创建并部署 REST API。

在 Lambda 集成中,来自客户端的 HTTP 方法请求将映射到后端 Lambda 函数调用

Lambda 代理集成 中,整个客户端请求将按原样发送到后端 Lambda 函数,只不过未保留请求参数的顺序。API Gateway 会将整个客户端请求映射到后端 Lambda 函数的输入 event 参数。Lambda 函数的输出(包括状态代码、标头和正文)将按原样返回到客户端。对于许多使用案例,这是首选的集成类型。有关更多信息,请参阅在 API Gateway 中设置 Lambda 代理集成

Lambda 非代理集成(也称为“自定义集成”)中,您可以配置将客户端请求的参数、标头和正文转换为您的 Lambda 函数要求的格式的方式,还可以配置将 Lambda 函数输出转换回客户端要求的格式的方式。有关更多信息,请参阅设置 API Gateway 中的 Lambda 的自定义集成

根据您的使用案例,您可以选择在 API Gateway API 中使用 Lambda 代理集成和/或 Lambda 非代理集成。

步骤 1:在 Lambda 控制台中创建 Lambda 函数

在此步骤中,您使用 AWS Lambda 控制台创建简单的 Lambda 函数。您将在后续步骤中使用此函数。

  1. 如果您尚未这样做,请完成先决条件:在 API Gateway 中为构建 API 做好准备中的步骤。

  2. 完成 AWS Lambda Developer Guide的创建 Lambda 函数中的步骤。

步骤 2:在 API Gateway 控制台中创建 REST API

在此步骤中,您在 API Gateway 控制台中创建简单的 REST API 并向其附加您的 Lambda 函数以作为后端。

  1. Services (服务) 菜单中,选择 API Gateway 以转到 API Gateway 控制台。

  2. 如果这是您首次使用 API Gateway,则您会看到一个介绍服务功能的页面。选择 Get Started (入门)。当 Create Example API (创建示例 API) 弹出框出现时,选择 OK (确定)

    如果这不是您首次使用 API Gateway,请选择 Create API (创建 API)

    
                        API Gateway 入门
  3. Choose the protocol (选择协议) 下,选择 REST

  4. Create a new API (创建新 API) 下,选择 New API (新建 API)

  5. Settings (设置) 下:

    • 对于 API name (API 名称),输入 my-api

    • 如果需要,在 Description (说明) 字段中输入说明;否则,将其保留为空。

    • Endpoint Type (终端节点类型) 设置为 Regional (区域)

  6. 选择 Create API (创建 API)

  7. Resources (资源) 下,您将看不到 / 以外的任何内容。这是根级资源,对应于您的 API 的基本路径 API (https://b123abcde4.execute-api.us-west-2.amazonaws.com/{stage-name})

    Actions (操作) 下拉菜单中,选择 Create Method (创建方法)

  8. 在资源名称 (/) 下,您将看到一个下拉菜单。选择 GET,然后选中复选标记图标以保存您的选择。

  9. / – GET – Setup 窗格中,对于 Integration type (集成类型),选择 Lambda Function (Lambda 函数)

  10. 选择 Use Lambda proxy integration (使用 Lambda 代理集成)

  11. 对于 Lambda Region (Lambda 区域),选择您在其中创建了 Lambda 函数的区域。

  12. Lambda Function (Lambda 函数) 字段中,键入任何字符,然后从下拉菜单中选择 my-function(或者您为上一步中创建的函数提供的任何名称)。(如果下拉菜单未出现,请删除您刚刚键入的字符以使下拉菜单出现。) 将 Use Default Timeout (使用默认超时) 保持选中状态。选择 Save (保存) 以保存您的选择。

  13. Add Permission to Lambda Function (向 Lambda 函数添加权限) 弹出框出现时(显示 "You are about to give API Gateway permission to invoke your Lambda function…"(“您即将向 API Gateway 授予调用您的 Lambda 函数的权限...)),选择 OK (确定) 以向 API Gateway 授予该权限。

现在您将看到一个 / – GET – Method Execution (/ – GET – 方法执行) 窗格:


                “API Gateway Method Execution (/ – GET – 方法执行)”窗格

Method Execution (方法执行) 窗格按顺时针顺序包含以下项:

  • Client (客户端):此框表示调用您的 API 的 GET 方法的客户端(浏览器或应用程序)。如果您选择 Test (测试) 链接,然后选择 Test (测试),这将模拟来自客户端的 GET 请求。

  • Method Request (方法请求):此框表示客户端的 GET 请求(当被 API Gateway 接收时)。如果您选择了 Method Request (方法请求),则在授权和修改方法请求等内容的设置被作为集成请求传递到后端之前,您将看到它们。在此步骤中,将所有内容的设置保留为默认值。

  • Integration Request (集成请求):此框表示 GET 请求(当被传递到后端时)。在此处,设置取决于所选的 Integration Type (集成类型)URL Path Parameters (URL 路径参数)URL Query String Parameters (URL 查询字符串参数)HTTP Headers (HTTP 标头)Mapping Templates (映射模板) 设置用于根据特定后端的需求修改方法请求。将 Integration Type (集成类型) 设为 Lambda function (Lambda 函数),并将其他设置设为默认值。

  • Lambda my-function:此框表示您在步骤 1 中创建的后端 Lambda 函数。如果您选择 my-function,这将在 Lambda 控制台打开 my-function Lambda 函数。

  • Integration Response (集成响应):此框表示来自后端的响应(在作为方法响应传递到客户端之前)。对于 Lambda 代理集成,此整个框将灰显,因为代理集成将按原样返回 Lambda 函数的输出。对于 Lambda 非代理集成,您可以将集成响应配置为将 Lambda 函数的输出转换为适合客户端应用程序的形式。您稍后将在本演练中了解如何执行此操作。

    对于本入门过程,请将所有内容的设置保留为默认值。

  • Method Response (方法响应):此框表示作为 HTTP 状态代码、可选响应标头和可选响应正文返回到客户端的方法响应。默认情况下,由您的 Lambda 函数返回的响应正文将按原样作为 JSON 文档传递,因此,响应正文默认设置为带空模型的 application/json(表示正文将按原样传递)。在此处也将所有内容的设置保留为默认值。

步骤 3:在 API Gateway 控制台中部署 REST API

在完成步骤 2 后,您已创建了一个 API,但实际上仍无法使用它。这是因为需要部署它。

  1. Actions (操作) 下拉菜单中,选择 Deploy API (部署 API)

  2. Deployment stage (部署阶段) 下拉菜单中,选择 [New Stage] ([新阶段])

  3. 对于 Stage name (阶段名称),输入 prod

  4. 选择 Deploy

  5. prod Stage Editor (阶段编辑器) 中,记下顶部的 Invoke URL (调用 URL)。它应采用以下格式:(https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod)。如果您选择 Invoke URL (调用 URL),它将打开一个包含该 URL 的新浏览器标签。如果您刷新了这个新浏览器标签,您将看到返回的消息正文 ("Hello from Lambda!")。

对于实际的 API 测试,您将使用 cURLPOSTMAN 等工具来测试您的 API。例如,如果您已在计算机上安装 cURL,则可以按下面所示测试您的 API:

  1. 打开终端窗口。

  2. 复制以下 cURL 命令并将其粘贴到终端窗口中,同时将 b123abcde4 替换为您的 API 的 API ID 并将 us-west-2 替换为部署您的 API 的区域。

    Linux or MacintoshWindows
    Linux or Macintosh
    curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod'
    Windows
    curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod"

    此命令将返回以下输出:"Hello from Lambda!"

步骤 4:在 Lambda 控制台创建另一个 Lambda 函数

在此步骤中,您将创建另一个后端 Lambda 函数。此函数采用输入参数。在步骤 5 中,您将在您的 API 中创建一个具有自己的 GET 方法的子资源,您可将该资源配置为将参数值传递到此新函数。

  1. Services (服务) 菜单中选择 Lambda 以转到 Lambda 控制台。

  2. 选择 Create function (创建函数)

  3. 选择 Author from scratch (从头开始创作)

  4. 对于 Function name (函数名称),输入 my-function2

  5. Runtime (运行时) 下,选择 Node.js 8.10Python 3.7

  6. Permissions (权限) 下,展开 Choose or create an execution role (选择或创建执行角色)。从 Execution role (执行角色) 下拉列表中,选择 Use an existing role (使用现有角色)。从 Existing role (现有角色) 中,选择您的上一个 Lambda 函数中的角色。该角色的名称将采用形式 service-role/my-function-a1b23c4d。或者选择 Create a new role with basic Lambda permissions (创建具有基本 Lambda 权限的新角色)

  7. 选择 Create function (创建函数)

  8. Function code (函数代码) 窗格中,您将看到默认的“Hello from Lambda!”函数。将整个函数替换为以下内容:

    Node.js 8.10Python 3.7
    Node.js 8.10
    exports.handler = async (event) => { let myParam = event.myParam; const response = { statusCode: 200, body: JSON.stringify(myParam) }; return response; };
    Python 3.7
    import json def lambda_handler(event, context): myParam = event['myParam'] return { 'statusCode': 200, 'body': json.dumps(myParam) }
  9. 选择 Save (保存)

步骤 5:在 API Gateway 控制台中向 REST API 添加资源、方法和参数

资源和方法是您的 REST API 的名词和动词。在此步骤中,您将为该 API 创建一个子资源并将 GET 方法添加到该资源。您将查询字符串参数添加到新方法以匹配您在步骤 4 中创建的 Lambda 函数的输入参数。您会将新函数与方法集成以说明如何获取用户输入(简单的“Hello from API Gateway!”文本字符串)并将其映射到 Lambda 函数的输入(也是简单的字符串)。

  1. Services (服务) 菜单中选择 API Gateway 以转到 API Gateway 控制台。

  2. APIs 列表中,选择 my-api

  3. Resources (资源) 下,选择 /

  4. Actions (操作) 下拉菜单中,选择 Create Resource (创建资源)

  5. 对于 Resource Name (资源名称),输入 my-resource。请注意,Resource Path (资源路径) 字段将自动填充资源名称。

  6. 选择 Create Resource (创建资源)

  7. Actions (操作) 下拉菜单中,选择 Create Method (创建方法)

  8. 在资源名称 (my-resource) 下,您将看到一个下拉菜单。选择 GET,然后选中复选标记图标以保存您的选择。

  9. /my-resource – GET – Setup (/my-resource – GET – 设置) 窗格中,对于 Integration type (集成类型),选择 Lambda Function (Lambda 函数)

  10. 对于 Lambda Region (Lambda 区域),选择您创建了 Lambda 函数的区域。

  11. Lambda Function (Lambda) 框中,键入任何字符,然后从下拉菜单中选择 my-function2。(如果下拉菜单未出现,请删除您刚刚键入的字符以使下拉菜单出现。) 选择 Save (保存) 以保存您的选择。

  12. Add Permission to Lambda Function (向 Lambda 函数添加权限) 弹出框出现时(显示 "You are about to give API Gateway permission to invoke your Lambda function…" (“您即将向 API Gateway 授予调用您的 Lambda 函数的权限...”)),选择“OK (确定)”以向 API Gateway 授予该权限。

  13. 您现在将看到一个 /my-resource – GET – Method Execution (my-resource – GET – 方法执行) 窗格。请注意,这次 Integration Response (集成响应) 框未灰显。

    选择 Integration Request (集成请求)

    
                        “API Gateway Method Execution (/ – GET – 方法执行)”窗格
  14. 展开 Mapping Templates (映射模板)

  15. Request body passthrough (请求正文传递) 设置为 When there are no templates defined (当未定义模板时)

  16. 选择 Add mapping template (添加映射模板)

  17. 对于 Content-Type,输入 application/json 并选中复选标记图标以保存您的选择。

  18. 如果 Change passthrough behavior (更改传递行为) 弹出框出现,请选择 Yes, secure this integration。这将确保您的集成仅允许与您刚刚定义的 Content-Type 匹配的请求。

  19. 在模板窗口中,输入以下内容:

    { "myParam": "$input.params('myParam')" }

    这是输入事件对象的正文中将传递到您的 Lambda 函数的 JSON 文档。右侧指示 API Gateway 要在您的输入查询字符串中查找的内容。左侧将其存储在您即将添加到您的 Lambda 函数的参数中。

  20. 选择 Save

  21. Actions (操作) 下拉菜单中,选择 Deploy API (部署 API)

  22. Deployment stage (部署阶段) 下拉菜单中,选择 prod

  23. 选择 Deploy

按下面所示测试您的 API:

  1. 打开终端窗口。

  2. 复制以下 cURL 命令并将其粘贴到终端窗口中,同时将 b123abcde4 替换为您的 API 的 API ID 并将 us-west-2 替换为部署您的 API 的区域。

    Linux or MacintoshWindows
    Linux or Macintosh
    curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod'
    Windows
    curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod"

    这将调用您的 API,而且您将看到“Hello from Lambda!”返回。这是因为您的新 Lambda 函数 my-function2 未附加到根资源 (/)。它将附加到您创建的新资源 my-resource。因此,您刚刚调用的 Lambda 函数是您之前创建的“Hello from Lambda!”函数 my-function

  3. 在 cURL 命令行中的 prod 后面键入 /my-resource?myParam=Hello%20from%20API%20Gateway!。完整的命令应如下所示:

    Linux or MacintoshWindows
    Linux or Macintosh
    curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/my-resource?myParam=Hello%20from%20API%20Gateway!'
    Windows
    curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/my-resource?myParam=Hello%20from%20API%20Gateway!"

    现在,您应看到返回的正确响应:{"statusCode": 200, "body": "\"Hello from API Gateway!\""}

后续步骤

探索下列任何一个或全部主题,进一步熟悉 Amazon API Gateway。

了解相关更多信息 转到
将输入传递到后端 Lambda 函数 用于代理集成的 Lambda 函数的输入格式
从后端 Lambda 函数返回输出 用于代理集成的 Lambda 函数的输出格式
为您的 API 设置自定义域名 为 API Gateway 中的 API 设置自定义域名
将 Lambda 授权方函数添加到您的 API 使用 API Gateway Lambda 授权方
将 Amazon Cognito 用户池授权方添加到您的 API 使用 Amazon Cognito 用户池 作为授权方控制对 REST API 的访问权限
为您的 API 启用 CORS 为 API Gateway REST API 资源启用 CORS

要从社区中获取 Amazon API Gateway 帮助,请参阅 API Gateway 开发论坛。(当您进入此论坛时,AWS 可能会要求您登录。)

要从 AWS 直接获得 API Gateway 帮助,请参阅 AWS Support 页中的支持选项。

另请参阅我们的常见问题 (FAQ),或者直接与我们联系