測試簡介 sam local start-api

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

• 如需「」的簡介 AWS SAMCLI，請參閱什麼是 AWS SAMCLI？。

• 如需指sam local start-api令選項的清單，請參閱sam local start-api。

• 如需在典型開發工作流程sam local start-api期間使用的範例，請參閱步驟 7：（可選）在本地測試您的應用程序。

必要條件

若要使用sam local start-api，請完成下列 AWS SAMCLI步驟來安裝：

• AWS SAM 前提.

• 安裝 AWS SAMCLI.

在使用之前sam local start-api，我們建議對以下內容進行基本了解：

• 配置 AWS SAMCLI.

• 使用sam init指令建立您的應用程式.

• 使用sam build指令建立簡介.

• 使用sam deploy指令部署簡介.

使用山姆本地啟動 API

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

若要啟動本機 HTTP 伺服器

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

   $ sam local start-api <options>

2. 這會在本機Docker容器中 AWS SAMCLI建置您的 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目錄，並且您的函數使用解釋型語言，則 AWS SAMCLI會通過創建新容器並託管它來自動更新您的函數。

   • 如果您的應用程序確實有一個.aws-sam目錄，則需要運行sam build以更新您的功能。然後sam local start-api再次運行以託管該函數。

   • 如果您的函數使用已編譯的語言，或者您的項目需要複雜的包裝支持，請運行自己的構建解決方案來更新您的函數。然後sam local start-api再次運行以託管該函數。

使用 Lambda 授權器的 Lambda 函數

注意

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

對於使用 Lambda 授權器的 Lambda 函數，在叫用 Lambda 函數端點之前， AWS SAMCLI會自動叫用您的 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 SAMCLI第一個會叫用您的 Lambda 授權者。如果授權成功， AWS SAMCLI將會叫用您的 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 -

選項

不斷重用容器以加速本地函數調用

默認情況下，每次通過本地 HTTP 服務器調用函數時 AWS SAMCLI創建一個新的容器。使用--warm-containers此選項可自動重複使用容器進行函數叫用。這可加快準備 Lambda 函數 AWS SAMCLI以進行本機叫用所需的時間。您可以透過提供eager或lazy引數來進一步自訂此選項。

• eager— 所有函數的容器都會在啟動時載入，並在呼叫之間持續存在。

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

以下是範例：

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

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

• 如果您的應用程序具有.aws-sam目錄，請運行sam build以更新應用程序構建成品中的函數代碼。

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

• 當您再次調用該函數時， AWS SAMCLI會自動創建一個新的容器。

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

預設情況下， AWS SAMCLI使用來自亞馬遜彈性容器登錄 (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 SAMCLI的範本，請使用--template選項。 AWS SAMCLI將只加載該 AWS SAM 模板及其指向的資源。以下是範例：

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

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

根據預設，sam local start-api子指令會使用 localhost IP 位址127.0.0.1建立 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

最佳實務

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

本地測試是部署到雲之前快速開發和測試的絕佳解決方案。但是，本地測試不會驗證所有內容，例如雲中資源之間的權限。請盡可能在雲端中測試您的應用程式。我們建議您使sam sync用以加速雲端測試工作流程。

進一步了解

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