使用 sam local start-api - Amazon Serverless Application Model
使用 sam local start-apiOptions最佳实践了解更多信息
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 sam local start-api

使用 Amazon Serverless Application Model 命令行界面 (Amazon SAM CLI) sam local start-api 子命令在本地运行 Amazon Lambda 函数并通过本地 HTTP 服务器主机进行测试。此类测试对由 Amazon API Gateway 端点调用的 Lambda 函数很有用。

要使用 sam local start-api，请完成以下操作安装 Amazon SAM CLI。

我们建议您在使用 sam local start-api 之前初步了解以下主题：

使用 sam local start-api

当您运行 sam local start-api 时，Amazon SAM CLI 会假设当前工作目录是项目的根目录。Amazon SAM CLI 会首先在 .aws-sam 子文件夹中查找 template.[yaml|yml] 文件。如果找不到，Amazon SAM CLI 会在当前工作目录中查找 template.[yaml|yml] 文件。

启动本地 HTTP 服务器

  1. 从项目的根目录中，运行以下命令：

    $ sam local start-api <options>

  2. Amazon SAM CLI 会在本地 Docker 容器中构建 Lambda 函数。然后，它会输出 HTTP 服务器端点的本地地址。以下是 示例：

    $ sam local start-api

Initializing the lambda functions containers.
Local image is up-to-date
Using local image: public.ecr.aws/lambda/python:3.9-rapid-x86_64.

Mounting /Users/.../sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated, inside runtime container
Containers Initialization is done.
Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]
You can now browse to the above endpoints to invoke your functions. You do not need to restart/reload SAM CLI while working on your functions, changes will be reflected instantly/automatically. If you used sam build before running local commands, you will need to re-run sam build for the changes to be picked up. You only need to restart SAM CLI if you update your AWS SAM template
2023-04-12 14:41:05 WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:3000

  3. 您可以通过浏览器或命令提示符调用 Lambda 函数。以下是 示例：

    sam-app$ curl http://127.0.0.1:3000/hello
{"message": "Hello world!"}%

  4. 如果您更改了 Lambda 函数代码，在刷新本地 HTTP 服务器时，请考虑以下几点：

    • 如果应用程序没有 .aws-sam 目录，并且函数使用解释性语言，则 Amazon SAM CLI 会通过创建并托管新容器来自动更新函数。

    • 如果应用程序有 .aws-sam 目录，则您需要运行 sam build 以更新函数。然后再次运行 sam local start-api 以托管函数。

    • 如果函数使用编译语言，或者项目需要复杂的打包支持，请运行您自己的构建解决方案来更新函数。然后再次运行 sam local start-api 以托管函数。

使用 Lambda 授权方的 Lambda 函数

注意

这是 Amazon SAM CLI 版本 1.80.0 中的新功能 要升级，请参阅 升级 Amazon SAM CLI。

对于使用 Lambda 授权方的 Lambda 函数，Amazon SAM CLI 会在调用 Lambda 函数端点之前自动调用 Lambda 授权方。

以下示例说明了如何为使用 Lambda 授权方的函数启动本地 HTTP 服务器：

$ sam local start-api
2023-04-17 15:02:13 Attaching import module proxy for analyzing dynamic imports

AWS SAM CLI does not guarantee 100% fidelity between authorizers locally
and authorizers deployed on AWS. Any application critical behavior should
be validated thoroughly before deploying to production.

Testing application behaviour against authorizers deployed on AWS can be done using the sam sync command.

Mounting HelloWorldFunction at http://127.0.0.1:3000/authorized-request [GET]
You can now browse to the above endpoints to invoke your functions. You do not need to restart/reload SAM CLI while working on your functions, changes will be reflected instantly/automatically. If you used sam build before running local commands, you will need to re-run sam build for the changes to be picked up. You only need to restart SAM CLI if you update your AWS SAM template
2023-04-17 15:02:13 WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:3000
2023-04-17 15:02:13 Press CTRL+C to quit

当您通过本地 HTTP 服务器调用 Lambda 函数端点时，Amazon SAM CLI 会先调用 Lambda 授权方。如果授权成功，Amazon SAM CLI 就会调用 Lambda 函数端点。以下是 示例：

$ curl http://127.0.0.1:3000/authorized-request --header "header:my_token"
{"message": "from authorizer"}%

Invoking app.authorizer_handler (python3.8)
Local image is up-to-date
Using local image: public.ecr.aws/lambda/python:3.8-rapid-x86_64.

Mounting /Users/.../sam-app/... as /var/task:ro,delegated, inside runtime container
START RequestId: 38d3b472-a2c8-4ea6-9a77-9b386989bef0 Version: $LATEST
END RequestId: 38d3b472-a2c8-4ea6-9a77-9b386989bef0
REPORT RequestId: 38d3b472-a2c8-4ea6-9a77-9b386989bef0    Init Duration: 1.08 ms    Duration: 628.26 msBilled Duration: 629 ms    Memory Size: 128 MB    Max Memory Used: 128 MB
Invoking app.request_handler (python3.8)
Using local image: public.ecr.aws/lambda/python:3.8-rapid-x86_64.

Mounting /Users/.../sam-app/... as /var/task:ro,delegated, inside runtime container
START RequestId: fdc12255-79a3-4365-97e9-9459d06446ff Version: $LATEST
END RequestId: fdc12255-79a3-4365-97e9-9459d06446ff
REPORT RequestId: fdc12255-79a3-4365-97e9-9459d06446ff    Init Duration: 0.95 ms    Duration: 659.13 msBilled Duration: 660 ms    Memory Size: 128 MB    Max Memory Used: 128 MB
No Content-Type given. Defaulting to 'application/json'.
2023-04-17 15:03:03 127.0.0.1 - - [17/Apr/2023 15:03:03] "GET /authorized-request HTTP/1.1" 200 -

Options

持续重用容器以加快本地函数调用

默认情况下，每次通过本地 HTTP 服务器调用函数时，Amazon SAM CLI 都会创建新容器。使用 --warm-containers 选项可自动重用容器进行函数调用。这会缩短 Amazon SAM CLI 为本地调用准备 Lambda 函数所需的时间。您可以通过提供 eager 或 lazy 参数进一步自定义此选项。

  • eager - 在启动时加载所有函数的容器，且并在调用之间持久存在。

  • lazy - 仅在首次调用每个函数时加载容器。加载的容器会保持不变，以供用于其他调用。

以下是 示例：

$ sam local start-api --warm-containers eager

使用 --warm-containers 和修改 Lambda 函数代码时：

  • 如果应用程序有 .aws-sam 目录，请运行 sam build 以更新应用程序构建构件中的函数代码。

  • 如果检测到代码更改，Amazon SAM CLI 会自动关闭 Lambda 函数容器。

  • 当您再次调用函数时，Amazon SAM CLI 会自动创建新容器。

指定要用于 Lambda 函数的容器映像

默认情况下，Amazon SAM CLI 使用 Amazon Elastic Container Registry (Amazon ECR) 中的 Lambda 基本映像在本地调用函数。使用 --invoke-image 选项引用自定义容器映像。以下是 示例：

$ sam local start-api --invoke-image public.ecr.aws/sam/emu-python3.8

您可以指定要与自定义容器映像一起使用的函数。以下是 示例：

$ sam local start-api --invoke-image Function1=amazon/aws/sam-cli-emulation-image-python3.8

指定模板以在本地进行测试

要为 Amazon SAM CLI 指定要引用的模板，请使用 --template 选项。Amazon SAM CLI 只会加载该 Amazon SAM 模板及其指向的资源。以下是 示例：

$ sam local start-api --template myTemplate.yaml

指定 Lambda 函数的主机开发环境

默认情况下，sam local start-api 子命令使用带有 IP 地址 127.0.0.1 的 localhost 来创建 HTTP 服务器。如果本地开发环境与本地计算机隔离，则可以自定义这些值。

使用 --container-host 选项指定主机。以下是 示例：

$ sam local start-api --container-host host.docker.internal

使用 --container-host-interface 选项指定应与容器端口绑定的主机网络的 IP 地址。以下是 示例：

$ sam local start-api --container-host-interface 0.0.0.0

最佳实践

如果应用程序有无法运行 sam build 的 .aws-sam 目录，请务必在每次更新函数代码时都运行 sam build。然后，运行 sam local start-api，以在本地测试更新后的函数代码。

本地测试是部署到云中之前进行快速开发和测试的理想解决方案。但是，本地测试并不能验证所有内容，例如，不能验证云端资源之间的权限。尽可能在云端测试应用程序。我们建议使用 sam sync 来加快云测试工作流程。

了解更多信息

有关全部 sam local start-api 选项的列表，请参阅 sam local start-api。