チュートリアル: Hello World アプリケーションのデプロイ
このガイドでは、AWS SAM を使用してサンプルの Hello World アプリケーションをダウンロード、構築、およびデプロイします。その後、AWS クラウドでアプリケーションをテストし、必要に応じて開発ホストでローカルにテストします。
このアプリケーションには、簡単な API バックエンドが実装されています。これは、API Gateway エンドポイントと Lambda 関数で構成されています。API
Gateway エンドポイントに GET リクエストを送信すると、Lambda 関数が呼び出されます。この関数は、hello world メッセージを返します。
次の図は、このアプリケーションのコンポーネントを示しています。
以下は、Hello World アプリケーションを作成するために実行するコマンドのプレビューです。各コマンドの詳細については、このページの後半のセクションを参照してください。
#Step 1 - Download a sample applicationsam init#Step 2 - Build your applicationcd sam-appsam build#Step 3 - Deploy your applicationsam deploy --guided
前提条件
このガイドは、ご使用の OS で「AWS SAM CLI のインストール」のステップを完了していることを前提としています。また、以下を完了していることを前提としています。
-
AWS アカウントの作成。
-
IAM アクセス許可の設定。
-
Docker のインストール。注: Docker は、アプリケーションをローカルでテストするための唯一の前提条件です。
-
Homebrew のインストール。注: Homebrew は、Linux と macOS の唯一の前提条件です。
-
AWS SAM CLI のインストール。注: バージョン 0.33.0 以降を使用していることを確認してください。コマンド
sam --versionを実行すると、使用しているバージョンを確認できます。
ステップ 1: サンプル AWS SAM アプリケーションをダウンロードする
実行するコマンド:
sam init
画面に表示される指示に従ってください。このチュートリアルでは、AWS クイックスタートテンプレート、任意のランタイム、Hello World の例を選択することをお勧めします。
出力例:
-----------------------
Generating application:
-----------------------
Name: sam-app
Runtime: python3.7
Dependency Manager: pip
Application Template: hello-world
Output Directory: .
Next steps can be found in the README file at ./sam-app/README.md
AWS SAM で実行される処理:
このコマンドにより、プロジェクト名として指定した名前のディレクトリが作成されます。プロジェクトディレクトリの内容は、次のようになります (この内容は、Python ランタイムの 1 つと Hello World の例を選択したときに作成されます)。
sam-app/
├── README.md
├── events/
│ └── event.json
├── hello_world/
│ ├── __init__.py
│ ├── app.py #Contains your AWS Lambda handler logic.
│ └── requirements.txt #Contains any Python dependencies the application requires, used for sam build
├── template.yaml #Contains the AWS SAM template defining your application's AWS resources.
└── tests/
└── unit/
├── __init__.py
└── test_handler.py
以下の 3 つのファイルは特に重要です。
-
template.yaml: アプリケーションの AWS リソースを定義する AWS SAM テンプレートが含まれます。 -
hello_world/app.py: 実際の Lambda ハンドラロジックが含まれます。 -
hello_world/requirements.txt: アプリケーションが必要とするすべての Python 依存関係が含まれ、sam buildに使用されます。
ステップ 2: アプリケーションを構築する
実行するコマンド:
まず、プロジェクトディレクトリ (サンプルアプリケーションの template.yaml ファイルが置かれているディレクトリ。デフォルトは sam-app です) に変更してから、次のコマンドを実行します。
sam build
出力例:
Build Succeeded
Built Artifacts : .aws-sam/build
Built Template : .aws-sam/build/template.yaml
Commands you can use next
=========================
[*] Invoke Function: sam local invoke
[*] Deploy: sam deploy --guided
AWS SAM で実行される処理:
AWS SAM CLI には、依存関係を構築するための Lambda ランタイムの抽象化が多数含まれており、ソースコードをステージングフォルダにコピーして、すべてをパッケージ化してデプロイできるようにします。sam build コマンドでは、アプリケーションが持つ依存関係を構築し、アプリケーションのソースコードを aws-sam/build の下のフォルダにコピーして圧縮し、Lambda にアップロードします。
次の最上位のツリーが .aws-sam の下に表示されます。
.aws_sam/
└── build/
├── HelloWorldFunction/
└── template.yaml
HelloWorldFunction は、app.py ファイルと、アプリケーションで使用するサードパーティーの依存関係を含むディレクトリです。
ステップ 3: アプリケーションを AWS クラウドにデプロイする
実行するコマンド:
sam deploy --guided
画面に表示される指示に従ってください。Enter で応答するだけで、インタラクティブな形式で提供されるデフォルトのオプションを受け入れることができます。
出力例:
Deploying with following values
===============================
Stack name : sam-app
Region : us-east-1
Confirm changeset : False
Deployment s3 bucket : sam-bucket
Capabilities : ["CAPABILITY_IAM"]
Parameter overrides : {}
Initiating deployment
=====================
Waiting for changeset to be created..
CloudFormation stack changeset
---------------------------------------------------------------------------------------------------------------------------------------------------
Operation LogicalResourceId ResourceType
---------------------------------------------------------------------------------------------------------------------------------------------------
+ Add HelloWorldFunctionHelloWorldPermissionProd AWS::Lambda::Permission
+ Add ServerlessRestApiDeployment47fc2d5f9d AWS::ApiGateway::Deployment
+ Add ServerlessRestApiProdStage AWS::ApiGateway::Stage
+ Add ServerlessRestApi AWS::ApiGateway::RestApi
* Modify HelloWorldFunctionRole AWS::IAM::Role
* Modify HelloWorldFunction AWS::Lambda::Function
---------------------------------------------------------------------------------------------------------------------------------------------------
2019-11-21 14:33:24 - Waiting for stack create/update to complete
CloudFormation events from changeset
-------------------------------------------------------------------------------------------------------------------------------------------------
ResourceStatus ResourceType LogicalResourceId ResourceStatusReason
-------------------------------------------------------------------------------------------------------------------------------------------------
UPDATE_IN_PROGRESS AWS::IAM::Role HelloWorldFunctionRole -
UPDATE_COMPLETE AWS::IAM::Role HelloWorldFunctionRole -
UPDATE_IN_PROGRESS AWS::Lambda::Function HelloWorldFunction -
UPDATE_COMPLETE AWS::Lambda::Function HelloWorldFunction -
CREATE_IN_PROGRESS AWS::ApiGateway::RestApi ServerlessRestApi -
CREATE_COMPLETE AWS::ApiGateway::RestApi ServerlessRestApi -
CREATE_IN_PROGRESS AWS::ApiGateway::RestApi ServerlessRestApi Resource creation Initiated
CREATE_IN_PROGRESS AWS::ApiGateway::Deployment ServerlessRestApiDeployment47fc2d5 Resource creation Initiated
f9d
CREATE_IN_PROGRESS AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermis Resource creation Initiated
sionProd
CREATE_IN_PROGRESS AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermis -
sionProd
CREATE_IN_PROGRESS AWS::ApiGateway::Deployment ServerlessRestApiDeployment47fc2d5 -
f9d
CREATE_COMPLETE AWS::ApiGateway::Deployment ServerlessRestApiDeployment47fc2d5 -
f9d
CREATE_IN_PROGRESS AWS::ApiGateway::Stage ServerlessRestApiProdStage -
CREATE_IN_PROGRESS AWS::ApiGateway::Stage ServerlessRestApiProdStage Resource creation Initiated
CREATE_COMPLETE AWS::ApiGateway::Stage ServerlessRestApiProdStage -
CREATE_COMPLETE AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermis -
sionProd
UPDATE_COMPLETE_CLEANUP_IN_PROGRES AWS::CloudFormation::Stack sam-app -
S
UPDATE_COMPLETE AWS::CloudFormation::Stack sam-app -
-------------------------------------------------------------------------------------------------------------------------------------------------
Stack sam-app outputs:
---------------------------------------------------------------------------------------------------------------------------------------------------
OutputKey-Description OutputValue
---------------------------------------------------------------------------------------------------------------------------------------------------
HelloWorldFunctionIamRole - Implicit IAM Role created for Hello World arn:aws:iam::123456789012:role/sam-app-
function HelloWorldFunctionRole-104VTJ0TST7M0
HelloWorldApi - API Gateway endpoint URL for Prod stage for Hello World https://0ks2zue0zh.execute-api.us-east-1.amazonaws.com/Prod/hello/
function
HelloWorldFunction - Hello World Lambda Function ARN arn:aws:lambda:us-east-1:123456789012:function:sam-app-
HelloWorldFunction-1TY92MJX0BXU5
---------------------------------------------------------------------------------------------------------------------------------------------------
Successfully created/updated stack - sam-app in us-east-1
AWS SAM で実行される処理:
このコマンドでは、アプリケーションを AWS クラウドにデプロイします。sam build コマンドで構築したデプロイアーティファクトを取得し、パッケージ化して、AWS SAM CLI で作成された Amazon S3 バケットにアップロードします。また、AWS
CloudFormation を使用してアプリケーションをデプロイします。デプロイコマンドの出力では、AWS CloudFormation スタックに加えられた変更を確認できます。
アプリケーションによって HTTP エンドポイントが作成された場合、sam
deploy で生成された出力には、テストアプリケーションのエンドポイント URL も表示されます。curl を使用すると、そのエンドポイント URL を使用してアプリケーションにリクエストを送信できます。次に例を示します。
curlhttps://<restapiid>.execute-api.us-east-1.amazonaws.com/Prod/hello/
アプリケーションを正常にデプロイすると、次のような出力が表示されます。
{"message": "hello world"}
curl コマンドの実行後に {"message": "hello world"} が表示された場合、それは、サーバーレスアプリケーションが AWS に正常にデプロイされ、実行中の Lambda 関数が呼び出されていることを意味します。表示されない場合は、このチュートリアルの後半にある「トラブルシューティング」セクションを参照してください。
ステップ 4: アプリケーションをローカルでテストする (オプション)
アプリケーションを開発しているときは、ローカルでテストすると便利です。AWS SAM CLI には、Docker コンテナを使用してアプリケーションを実行する sam local コマンドが用意されており、Lambda の実行環境をシミュレートできます。これには、次の 2 つのオプションがあります。
-
API をローカルでホストする
-
Lambda 関数を直接呼び出す
このステップでは、両方のオプションについて説明します。
API をローカルでホストする
実行するコマンド:
sam local start-api
出力例:
2019-07-12 15:27:58 Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]
2019-07-12 15:27:58 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. You only need to restart SAM CLI if you update your AWS SAM template
2019-07-12 15:27:58 * Running on http://127.0.0.1:3000/ (Press CTRL+C to quit)
Fetching lambci/lambda:python3.7 Docker container image......................................................................................................................................................................................
2019-07-12 15:28:56 Mounting /<working-development-path>/sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated inside runtime container
START RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 Version: $LATEST
END RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72
REPORT RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 Duration: 4.42 ms Billed Duration: 100 ms Memory Size: 128 MB Max Memory Used: 22 MB
2019-07-12 15:28:58 No Content-Type given. Defaulting to 'application/json'.
2019-07-12 15:28:58 127.0.0.1 - - [12/Jul/2019 15:28:58] "GET /hello HTTP/1.1" 200 -
Docker イメージが読み込まれるまでに時間がかかる場合があります。読み込まれたら、curl を使用して、ローカルホストで実行されているアプリケーションにリクエストを送信できます。
curl http://127.0.0.1:3000/hello
出力例:
2019-07-12 15:29:57 Invoking app.lambda_handler (python3.7) 2019-07-12 15:29:57 Found credentials in shared credentials file: ~/.aws/credentials Fetching lambci/lambda:python3.7 Docker container image...... 2019-07-12 15:29:58 Mounting /<working-development-path>/sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated inside runtime container START RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 Version: $LATEST END RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 REPORT RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 Duration: 7.92 ms Billed Duration: 100 ms Memory Size: 128 MB Max Memory Used: 22 MB {"statusCode":200,"body":"{\"message\": \"hello world\"}"}
AWS SAM で実行される処理:
start-api コマンドは、REST API エンドポイントをレプリケートするローカルエンドポイントを起動します。関数をローカルで実行できる実行コンテナをダウンロードします。最終的な結果は、AWS
クラウドで関数を呼び出したときと同じ出力になります。
1 回限りの呼び出しを実行する
実行するコマンド:
sam local invoke "HelloWorldFunction" -e events/event.json
出力例:
2019-07-01 14:08:42 Found credentials in shared credentials file: ~/.aws/credentials 2019-07-01 14:08:42 Invoking app.lambda_handler (python3.7) Fetching lambci/lambda:python3.7 Docker container image............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 2019-07-01 14:09:39 Mounting /<working-development-path>/sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated inside runtime container START RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 Version: $LATEST END RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 REPORT RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 Duration: 3.51 ms Billed Duration: 100 ms Memory Size: 128 MB Max Memory Used: 22 MB {"statusCode":200,"body":"{\"message\": \"hello world\"}"}
AWS SAM で実行される処理:
invoke コマンドは Lambda 関数を直接呼び出し、指定した入力イベントペイロードを渡すことができます。このコマンドでは、サンプルアプリケーションによって提供されるファイル
event.json にイベントペイロードを渡します。
初期化したアプリケーションには、API Gateway 用にデフォルトの aws-proxy イベントが付属しています。いくつかの値が事前に入力されています。この場合、HelloWorldFunction は特定の値を認識しないため、スタブされたリクエストは OK になります。実際のリクエストに期待するものをシミュレートするために、リクエストに代入する値をいくつか指定できます。以下は、独自の入力イベントを生成し、出力をデフォルトの
event.json オブジェクトと比較する例です。
sam local generate-event apigateway aws-proxy --body "" --path "hello" --method GET > api-event.json diff api-event.json event.json
出力例:
< "body": "",
---
> "body": "{\"message\": \"hello world\"}",
4,6c4,6
< "path": "/hello",
< "httpMethod": "GET",
< "isBase64Encoded": true,
---
> "path": "/path/to/resource",
> "httpMethod": "POST",
> "isBase64Encoded": false,
11c11
< "proxy": "/hello"
---
> "proxy": "/path/to/resource"
56c56
< "path": "/prod/hello",
---
> "path": "/prod/path/to/resource",
58c58
< "httpMethod": "GET",
---
> "httpMethod": "POST",
トラブルシューティング
SAM CLI エラー: "no such option: --app-template"
sam init を実行すると、次のエラーが表示されます。
Error: no such option: --app-template
これは、--app-template パラメータをサポートしていない古いバージョンの AWS SAM CLI を使用していることを意味します。この問題を解決するには、AWS SAM CLI のバージョンを
0.33.0 以降に更新するか、sam init コマンドから --app-template パラメータを削除します。
SAM CLI エラー: "no such option: --guided"
sam deploy を実行すると、次のエラーが表示されます。
Error: no such option: --guided
これは、--guided パラメータをサポートしていない古いバージョンの AWS SAM CLI を使用していることを意味します。この問題を解決するには、AWS SAM CLI のバージョンを
0.33.0 以降に更新するか、sam deploy コマンドから --guided パラメータを削除します。
Curl エラー: "Missing Authentication Token"
API Gateway エンドポイントを呼び出すと、次のエラーが表示されます。
{"message":"Missing Authentication Token"}
これは、正しいドメインにリクエストを送信しようとしたものの、URI で認識できないことを意味します。この問題を解決するには、完全な URL を確認し、正しい URL
で curl コマンドを更新します。
Curl エラー: "curl: (6) Could not resolve: ..."
API Gateway エンドポイントを呼び出すと、次のエラーが表示されます。
curl: (6) Could not resolve: endpointdomain (Domain name not found)
これは、無効なドメインにリクエストを送信しようとしたことを意味します。これは、サーバーレスアプリケーションが正常にデプロイできなかった場合、または curl コマンドにタイプミスがある場合に発生します。AWS CloudFormation コンソールまたは AWS CLI を使用して、アプリケーションが正常にデプロイされたこと、および
curl コマンドが正しいことを確認します。
クリーンアップ
このチュートリアルを実行して作成した AWS リソースが不要になった場合は、デプロイした AWS CloudFormation スタックを削除することでリソースを削除できます。
AWS マネジメントコンソール を使用してこのチュートリアルで作成した AWS CloudFormation スタックを削除するには、以下のステップを実行します。
-
AWS マネジメントコンソール にサインインして、https://console.aws.amazon.com/cloudformation
で AWS CloudFormation コンソールを開きます。 -
左のナビゲーションペインで [スタック] を選択します。
-
スタックのリストで、[aws-sam-getting-started] を選択します。
-
[削除] を選択します。
完了すると、スタックのステータスが DELETE_COMPLETE に変わります。
または、次の AWS CLI コマンドを実行して AWS CloudFormation スタックを削除することもできます。
aws cloudformation delete-stack --stack-name aws-sam-getting-started --regionregion
削除されたスタックを確認する
どちらの方法でも、AWS CloudFormation スタックが削除されていることを確認するには、https://console.aws.amazon.com/cloudformation
結論
このチュートリアルでは、以下の作業を行いました。
-
AWS SAM を使用して、サーバーレスアプリケーションを作成、構築し、AWS にデプロイする。
-
AWS SAM CLI と Docker を使用してアプリケーションをローカルでテストする。
-
不要になった AWS リソースを削除する。
次のステップ
これで、AWS SAM CLI を使用して独自のアプリケーションの構築を開始する準備が整いました。
AWS SAM GitHub リポジトリからサンプルアプリケーションをダウンロードすると、開始しやすくなります。このリポジトリにアクセスするには、「AWS SAM サンプルアプリケーション
