を使用したテストの概要 sam local start-api - AWS Serverless Application Model
sam local start-api の使用オプションベストプラクティス詳細

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

を使用したテストの概要 sam local start-api

AWS Serverless Application Model コマンドラインインターフェイス (AWS SAM CLI) sam local start-apiサブコマンドを使用して関数をローカルで実行し、ローカルHTTPサーバーホストを介してテストします AWS Lambda 。このタイプのテストは、Amazon API Gateway エンドポイントによって呼び出される Lambda 関数に役立ちます。

を使用するにはsam local start-api、 をインストールします。 AWS SAM CLI 以下を完了します。

sam local start-api を使用する前に、次の基本を理解しておくことをお勧めします。

sam local 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 SAM CLI のアップグレード を参照してください。

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サブコマンドは IP アドレス localhost を使用して を使用して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」を参照してください。