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

AWS Serverless Application Model コマンドラインインターフェイス (AWS SAMCLI) sam local start-apiサブコマンドを使用して、関数をローカルで実行し、ローカル HTTP サーバーホストを介してテストします AWS Lambda 。このタイプのテストは、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 SAM CLI をインストールします。

• AWS SAM 前提条件.

• AWS SAM CLI のインストール.

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

• AWS SAM CLI の設定.

• sam init コマンドを使用してアプリケーションを作成する.

• sam build コマンドを使用した構築の概要.

• sam deploy コマンドを使用したデプロイの概要.

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 -

オプション

コンテナを継続的に再利用してローカル関数の呼び出しを高速化する

デフォルトでは、ローカル HTTP サーバー経由で関数が呼び出されるたびに、 AWS SAM CLI は新しいコンテナを作成します。関数呼び出しのためにコンテナを自動的に再利用する --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 SAMCLI は、その AWS 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

ベストプラクティス

アプリケーションに .aws-sam を実行している sam build ディレクトリがある場合は、関数コードを更新するたびに必ず sam build を実行してください。その後、更新された関数コードをローカルでテストするために sam local start-api を実行します。

ローカルテストは、クラウドにデプロイする前に迅速な開発とテストを行うための優れたソリューションです。ただし、ローカルテストでは、クラウド内のリソース間の許可など、すべてが検証されるわけではありません。可能な限り、アプリケーションをクラウドでテストします。クラウドテストのワークフローを高速化するために sam sync を使用することをお勧めします。

詳細はこちら

すべての sam local start-api オプションのリストについては、「sam local start-api」を参照してください。