sam local start-api を使用する - AWS Serverless Application Model

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

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 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 SAM CLI は、その AWS SAM テンプレートとそれがポイントするリソースのみをロードします。以下に例を示します。

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

Lambda 関数のホスト開発環境を指定する

デフォルトでは、sam local start-api サブコマンドは IP アドレス 127.0.0.1localhost を使用して 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」を参照してください。