使用 進行測試的簡介 sam local start-api - AWS Serverless Application Model
使用 sam 本機 start-api選項最佳實務進一步了解

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 進行測試的簡介 sam local start-api

使用 AWS Serverless Application Model 命令列介面 （AWS SAM CLI） sam local start-api子命令，以在本機執行函數 AWS Lambda ，並透過本機HTTP伺服器主機進行測試。這種類型的測試對 Amazon API Gateway 端點調用的 Lambda 函數很有幫助。

若要使用 sam local start-api，請安裝 AWS SAM CLI 完成下列操作：

在使用 之前sam local start-api，建議您對下列項目有基本的了解：

使用 sam 本機 start-api

當您執行 時sam local start-api， AWS SAM CLI 假設您目前的工作目錄是專案的根目錄。的 AWS SAM CLI 首先會尋找.aws-sam子資料夾內的template.[yaml|yml]檔案。如果找不到，則 AWS SAM CLI 會在您目前的工作目錄中尋找template.[yaml|yml]檔案。

啟動本機HTTP伺服器

  1. 從專案的根目錄中，執行下列動作：

    $ sam local start-api <options>

  2. 的 AWS SAM CLI 在本機 中建置 Lambda 函數 Docker 容器。然後，它會輸出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目錄，且您的函數使用解譯語言，則 AWS SAM CLI 會自動更新函數，方法是建立新的容器並託管它。

    • 如果您的應用程式有.aws-sam目錄，則需要執行 sam build以更新函數。然後sam local start-api再次執行 以託管函數。

    • 如果您的函數使用編譯的語言，或您的專案需要複雜的封裝支援，請執行您自己的建置解決方案來更新函數。然後sam local start-api再次執行 以託管函數。

使用 Lambda 授權方的 Lambda 函數

注意

此功能是 中的新功能 AWS SAM CLI 1.80.0 版。若要升級，請參閱升級 AWS SAMCLI。

對於使用 Lambda 授權方的 Lambda 函數， AWS 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 函數端點時， AWS SAM CLI 首先調用您的 Lambda 授權方。如果授權成功， AWS 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 -

選項

持續重複使用容器以加快本機函數叫用

根據預設， AWS SAM CLI 每次透過本機HTTP伺服器叫用函數時， 都會建立新的容器。使用 --warm-containers選項自動重複使用容器進行函數調用。這可加快 所需的時間 AWS SAM CLI 準備您的 Lambda 函數以進行本機調用。您可以提供 eager或 lazy引數，進一步自訂此選項。

  • eager – 所有函數的容器會在啟動時載入，並在叫用之間保留。

  • lazy – 容器只有在第一次叫用每個函數時才會載入。然後，它們會持續進行其他調用。

以下是範例：

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

使用--warm-containers和修改 Lambda 函數程式碼時：

  • 如果您的應用程式有.aws-sam目錄，請執行 sam build 以更新應用程式建置成品中的函數程式碼。

  • 偵測到程式碼變更時， AWS SAM CLI 會自動關閉 Lambda 函數容器。

  • 當您再次叫用函數時， AWS SAM CLI 會自動建立新的容器。

指定要用於 Lambda 函數的容器映像

根據預設， AWS 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

指定要本機測試的範本

若要指定 的範本 AWS SAM CLI 若要參考，請使用 --template選項。的 AWS SAM CLI 只會載入該 AWS SAM 範本及其指向的資源。以下是範例：

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

指定 Lambda 函數的主機開發環境

根據預設，sam local start-api子命令會使用 localhost 建立具有 IP 地址 的HTTP伺服器127.0.0.1。如果本機開發環境與本機機器隔離，您可以自訂這些值。

使用 --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

最佳實務

如果您的應用程式具有執行 的.aws-sam目錄sam build，請務必sam build在每次更新函數程式碼時執行 。然後，執行 sam local start-api以本機測試您更新的函數程式碼。

本機測試是部署至雲端之前快速開發和測試的絕佳解決方案。不過，本機測試不會驗證所有項目，例如雲端中資源之間的許可。盡可能在雲端測試您的應用程式。建議使用 sam sync 來加速雲端測試工作流程。

進一步了解

如需所有sam local start-api選項的清單，請參閱 sam local start-api。