本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
測試簡介 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步驟來安裝:
在使用之前sam local start-api
,我們建議對以下內容進行基本了解:
使用山姆本地啟動 API
當您執行時sam local start-api
,會 AWS SAMCLI假設您目前的工作目錄是專案的根目錄。 AWS SAMCLI將首先查找子template.[yaml|yml]
文件.aws-sam
夾中的文件。如果找不到, AWS SAMCLI會在您目前的工作目錄中尋找template.[yaml|yml]
檔案。
若要啟動本機 HTTP 伺服器
-
從專案的根目錄中,執行下列命令:
$
sam local start-api
<options>
-
這會在本機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 -
您可以透過瀏覽器或命令提示字元叫用 Lambda 函數。以下是範例:
sam-app$
curl http://127.0.0.1:3000/hello
{"message": "Hello world!"}% -
當您變更 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。