Github: https://github.com/awslabs/aws-sam-cli
SAM CLI(ベータ版)
スラックのSAM開発者チャンネル(#samdev)に参加して、仲間のコミュニティメンバーやAWS SAMチームと協力してください。
“ sam“は、AWS Serverless Application Model(SAM)で書かれたServerlessアプリケーションを管理するためのAWS CLIツールです。 SAM CLIを使用すると、ローカルで機能をテストしたり、SAMテンプレートからローカルAPIゲートウェイを開始したり、SAMテンプレートを検証したり、さまざまなイベントソースのサンプルペイロードを生成したり、好きなLambdaランタイムでSAMプロジェクトを生成できます。
主な特徴
-
sam local
とDockerを使ってLambda関数をローカルで開発し、テストする - Amazon S3、Amazon DynamoDB、Amazon Kinesisなどの既知のイベントソースから関数を呼び出します。
- SAMテンプレートからローカルAPIゲートウェイを開始し、ホットリロードを使用して機能を迅速に反復処理する
- SAMテンプレートの検証
- 選択したLambda Runtime
sam init
で定型サーバーレスサービスを開始する
インストール
前提条件
SAM CLIを使用してサーバレスのプロジェクトと機能をローカルで実行するには、Dockerをインストールして実行する必要があります。 SAM CLIはDOCKER_HOST
環境変数を使用してドッカーデーモンに接続します。
- macOS: Docker for Mac
- Windows: Docker Toolbox
- Linux:ディストリビューションのパッケージマネージャー(yum install dockerなど)を確認してください。
macOSとWindowsユーザの場合:SAM CLIでは、プロジェクトディレクトリ(または親ディレクトリ)がDockerファイル共有オプションにリストされている必要があります。
dockerが動作していること、およびdockerコマンドをCLI(例えば、 ‘docker ps’)で実行できることを確認してください。 任意のコンテナをインストール/フェッチ/プルする必要はありません。SAM CLIは必要に応じて自動的に行います。
バージョン0.2.11またはそれ以下からのアップグレード
以前のCLIバージョンのアンインストール
npm uninstall -g aws-sam-local
バージョン0.3.0以上にアップグレードするには、以下の手順に従ってください:
Windows、Linux、PIP対応macOS [推奨]
Pythonのバージョンが2.7であることを確認します。
“ sam“をインストールする最も簡単な方法は、 PIPを使うことです。
pip install --user aws-sam-cli
インストールが機能していることを確認します。
sam --version
pipによるアップグレード
pipで一度インストールされた“ sam“を更新するには:
pip install --user --upgrade aws-sam-cli
ソースからビルド
最初に、あなたのマシンにPython(2.7)をインストールし、以下を実行してください:
# Clone the repository
$ git clone git@github.com:awslabs/aws-sam-cli.git
# cd into the git
$ cd aws-sam-cli
# pip install the repository
$ pip install --user -e .
PyEnvでインストールする
# Install PyEnv (https://github.com/pyenv/pyenv#installation)
$ brew update
$ brew install pyenv
# Initialize pyenv using bash_profile
$ echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -)"\nfi\nexport PATH="~/.pyenv/bin:$PATH"' >> ~/.bash_profile
# or using zshrc
$ echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -)"\nfi\nexport PATH="~/.pyenv/bin:$PATH"' >> ~/.zshrc
# restart the shell
$ exec "$SHELL"
# Install Python 2.7
$ pyenv install 2.7.14
$ pyenv local 2.7.14
# Install the CLI
$ pip install --user aws-sam-cli
# Verify your installation worked
$ sam –version
トラブルシューティング
Macの問題
- [Errno 13] Permission denied Homebrewを使ってPythonをインストールした場合、SAM CLIをインストールするには
sudo
を使う必要があります:
sudo pip install aws-sam-cli
- TLSV1_ALERT_PROTOCOL_VERSION :
次のようなエラーが発生した場合:
Could not fetch URL https://pypi.python.org/simple/click/: There was a problem confirming the ssl certificate: [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590) - skipping
あなたのMacに付属のPythonのデフォルトバージョンを使用している可能性があります。 これは時代遅れです。 ですから、homebrewを使ってPythonを再インストールして、もう一度やり直してください:
brew install python@2
に続く:
pip install --user aws-sam-cli
使用法
“ sam“はローカルであなたの関数を呼び出す方法を知るためにSAMテンプレートが必要です。また、API Gatewayをローカルに起動する場合も同じです。テンプレートが指定されていない場合、代わりにtemplate.yaml
が使用されます。
サンプルSAMテンプレートは、このリポジトリにある“ samples“またはSAM公式リポジトリにアクセスして見つけることができます。
関数をローカルに呼び出す
SAM論理IDとイベント・ファイルを渡すことで、ローカルで関数を呼び出すことができます。 あるいは、 sam local invoke
はstdinをイベントとして受け付けます。
Resources:
Ratings: # <-- Logical ID
Type: 'AWS::Serverless::Function'
...
構文
# Invoking function with event file
$ sam local invoke "Ratings" -e event.json
# Invoking function with event via stdin
$ echo '{"message": "Hey, are you there?" }' | sam local invoke "Ratings"
# For more options
$ sam local invoke --help
サンプルのイベントソースペイロードを生成する
ラムダ関数のローカル開発とテストを容易にするために、以下のサービスの模擬/サンプルイベントペイロードを生成することができます。
- S3
- キネシス
- DynamoDB
- Cloudwatchスケジュールイベント
- クラウドトレイル
- APIゲートウェイ
構文
sam local generate-event <service>
また、サンプル・イベント・ペイロードからローカルに個々のラムダ関数を呼び出すこともできます。次に、S3を使用した例を示します。
sam local generate-event s3 --bucket <bucket> --key <key> | sam local invoke <function logical id>
その他のオプションについては、 sam local generate-event --help
参照してください。
ローカルでAPIゲートウェイを実行する
sam local start-api
は、HTTP要求/応答機能をテストするためのローカルAPIゲートウェイを生成します。 ホットリロード機能を使用すると、機能を迅速に開発して反復することができます。
構文
sam local start-api
“ sam“は、 Api
イベントソースが定義されているSAMテンプレート内の関数を自動的に見つけ出し、定義されたHTTPパスにマウントします。
以下の例では、 Ratings
関数はGET
要求の/ratings
でratings.py:handler()
をマウントします。
Ratings:
Type: AWS::Serverless::Function
Properties:
Handler: ratings.handler
Runtime: python3.6
Events:
Api:
Type: Api
Properties:
Path: /ratings
Method: get
デフォルトでは、SAMはプロキシ統合を使用し、ラムダ関数からの応答に、 statusCode
、 headers
、 body
うちの1つ以上を含める必要があります。
例えば:
// Example of a Proxy Integration response
exports.handler = (event, context, callback) => {
callback(null, {
statusCode: 200,
headers: { "x-custom-header" : "my custom header value" },
body: "hello world"
});
}
他のAWSラムダ言語の例については、 このページを参照してください 。
関数が有効なプロキシ統合応答を返さない場合は、関数にアクセスするときにHTTP 500(内部サーバーエラー)が発生します。 SAM CLIは、問題の診断に役立つ次のエラーログメッセージも出力します。
ERROR: Function ExampleFunction returned an invalid response (must include one of: body, headers or statusCode in the response object)
アプリケーションのデバッグ
sam local invoke
とsam local start-api
どちらも、関数のローカルデバッグをサポートしています。
デバッグサポートを有効にしてSAM Localを実行するには、コマンドラインで--debug-port
または-d
を指定するだけです。
# Invoke a function locally in debug mode on port 5858
$ sam local invoke -d 5858 <function logical id>
# Start local API Gateway in debug mode on port 5858
$ sam local start-api -d 5858
注意: sam local start-api
を使用している場合、ローカルAPIゲートウェイはすべてのラムダ関数を公開しますが、1つのデバッグポートを指定できるので、一度に1つの関数しかデバッグできません。 SAM CLIがポートにバインドしてからデバッガを接続できるようにするには、APIを起動する必要があります。
次に、Microsoft Visual Studio Codeを使用してNodeJS関数をデバッグする方法の例を示します。
AWS SAM CLIを使用してデバッグするためのVisual Studioコードをセットアップするには、次の起動設定を使用します。
{ "version": "0.2.0", "configurations": [ { "name": "Attach to SAM Local", "type": "node", "request": "attach", "address": "localhost", "port": 5858, "localRoot": "${workspaceRoot}", "remoteRoot": "/var/task", "protocol": "legacy" } ] }
注:Node.jsバージョン7以降(Node.js 4.3およびNode.js 6.10など)ではlegacy
プロトコルが使用され、Node.jsバージョン7以降(Node.js 8.10など)ではinspector
プロトコルが使用されます。 起動設定のprotocol
エントリに対応するプロトコルを指定してください。
Python関数のデバッグ
Node.JSとJavaとは異なり、Pythonはラムダ関数コードでリモートデバッグを有効にする必要があります。 Pythonランタイムの1つを使用する関数に--debug-port
または-d
を--debug-port
デバッグを有効にすると、SAM CLIはそのポートを介してホストマシンからLambdaランタイムコンテナにマップします。 機能コードでリモートデバッグを有効にする必要があります。 これを行うには、 remote-pdbなどのpythonパッケージを使用します。 デバッガがあなたのコードでリッスンするホストを設定するときは、 0.0.0.0
ではなく127.0.0.1
を使用して、Dockerがポートを介してホストマシンにマップできるようにしてください。
このIDEでPythonアプリケーションをデバッグしようとすると、Visual Studio Codeのオープンバグにより、
Debug adapter process has terminated unexpectedly
エラーが発生することがあります。 更新のためにGitHubの問題を追跡してください。
追加の実行時デバッグ引数の受け渡し
関数のデバッグ時に追加のランタイム引数を渡すには、環境変数DEBUGGER_ARGUMENTS
使用します。 これにより、SAM CLIが関数を開始するために使用する実行コマンドに引数の文字列が直接渡されます。
たとえば、Python関数の実行時にiKPdbのようなデバッガをロードする場合は、次のようにDEBUGGER_ARGUMENTS
渡すことができDEBUGGER_ARGUMENTS
。 -m ikpdb --ikpdb-port=5858 --ikpdb-working-directory=/var/task/ --ikpdb-client-working-directory=/myApp --ikpdb-address=0.0.0.0
です。 これにより、実行時に指定した他の引数とともにiKPdbがロードされます。 この場合、完全なSAM CLIコマンドは次のようになります。
$ DEBUGGER_ARGUMENTS="-m ikpdb --ikpdb-port=5858 --ikpdb-working-directory=/var/task/ --ikpdb-client-working-directory=/myApp --ikpdb-address=0.0.0.0" echo {} | sam local invoke -d 5858 myFunction
デバッガの引数をすべてのランタイムの関数に渡すことができます。
ドッカーネットワークに接続する
sam local invoke
とsam local start-api
サポートは、ラムダドッカーコンテナを既存のドッカーネットワークに接続することをサポートします。
コンテナを既存のドッカーネットワークに接続するには、接続するドッカーネットワークの名前またはIDとともに、– --docker-network
コマンドライン引数またはSAM_DOCKER_NETWORK
環境変数を使用できます。
# Invoke a function locally and connect to a docker network
$ sam local invoke --docker-network my-custom-network <function logical id>
# Start local API Gateway and connect all containers to a docker network
$ sam local start-api --docker-network b91847306671 -d 5858
SAMテンプレートの検証
$ sam validate
テンプレートを検証します。 現在、このコマンドは、指定されたテンプレートが有効なJSON / YAMLであることを検証します。 ほとんどのSAM CLIコマンドと同様に、現在の作業ディレクトリのtemplate.[yaml|yml]
ファイルをデフォルトで探します。 -t
または--template
オプションを使用して、別のテンプレートファイル/場所を指定することができます。
構文
$ sam validate
<path-to-file>/template.yml is a valid SAM Template
注意:validateコマンドを使用するには、AWS資格情報を設定する必要があります。 IAMCreds_を参照してください。
ラムダへのパッケージ化と展開
Serverlessアプリケーションをローカルで開発してテストしたら、 sam package
およびsam deploy
コマンドを使用してLambdaにデプロイできます。 package
コマンドを実行すると、コード成果物が圧縮され、S3にアップロードされ、AWS CloudFormationを使用してLambdaにデプロイできるSAMファイルが生成されます。 deploy
コマンドは、パッケージ化されたSAMテンプレートをCloudFormationにデプロイします。 sam package
とsam deploy
両方のsam deploy
はAWS CLIの同等のコマンドと同じです`aws cloudformation package
< http://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html > `__と`aws cloudformation deploy
< http://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html > `__それぞれ。 使用方法については、AWS CLIコマンドのドキュメントを参照してください。
例:
# Package SAM template
$ sam package --template-file sam.yaml --s3-bucket mybucket --output-template-file packaged.yaml
# Deploy packaged SAM template
$ sam deploy --template-file ./packaged.yaml --stack-name mystack --capabilities CAPABILITY_IAM
入門
- 詳細はHOWTOガイドセクションを参照してください。
上級
コンパイルされた言語(Java)
パッケージ化された成果物(JARやZIPなど)を必要とするJavaなどのコンパイル言語でSAM CLIを使用するには、SAMテンプレートのAWS::Serverless::Function
CodeUri
AWS::Serverless::Function
CodeUri
プロパティを使用して成果物の場所を指定できます。
例えば:
AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::Serverless-2016-10-31 Resources: ExampleJavaFunction: Type: AWS::Serverless::Function Properties: Handler: com.example.HelloWorldHandler CodeUri: ./target/HelloWorld-1.0.jar Runtime: java8
通常のビルドプロセスを使用してJARファイルをビルドする必要があります。 AWS Lambdaで使用されるJARファイルは、すべての関数の依存関係を含む影付きのJARファイル(またはuber jar)である必要があります。
// Build the JAR file $ mvn package shade:shade // Invoke with SAM Local $ echo '{ "some": "input" }' | sam local invoke // Or start local API Gateway simulator $ sam local start-api
samples / javaフォルダに完全なJava サンプルがあります
IAM資格情報
SAM CLIは、ローカルに設定されたIAM資格情報を使用して機能を呼び出します。
AWS CLIおよびSDKと同様に、SAM CLIは次の順序で資格を検索します。
- 環境変数(
AWS_ACCESS_KEY_ID
、AWS_SECRET_ACCESS_KEY
)。 - AWS資格ファイル(Linux、macOS、Unixの
~/.aws/credentials
、またはWindowsの場合はC:\Users\USERNAME \.aws\credentials
にあります)。 - インスタンスプロファイルの資格情報(Amazon EC2上でインスタンスロールが割り当てられている場合)
AWS資格ファイルからデフォルト以外のプロファイルを使用してAPIゲートウェイをテストするには、 – profile --profile <profile name>
をstart-api
コマンドに追加します。
// Test API Gateway locally with a credential profile. $ sam local start-api --profile some_profile
詳細は、「AWS CLIの設定 」を参照してください。
ラムダ環境変数
ラムダ関数が環境変数を使用する場合は、Dockerコンテナに渡される値を指定できます。 あなたのやり方は次のとおりです:
たとえば、SAMテンプレートのスニペットを考えてみましょう。
Resources:
MyFunction1:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: nodejs4.3
Environment:
Variables:
TABLE_NAME: prodtable
BUCKET_NAME: prodbucket
MyFunction2:
Type: AWS::Serverless::Function
Properties:
Handler: app.handler
Runtime: nodejs4.3
Environment:
Variables:
STAGE: prod
TABLE_NAME: prodtable
環境変数ファイル
関数で定義された環境変数の値を含むJSONファイルを提供するには、 invoke
またはstart-api
コマンドの--env-vars
引数を使用します。 このファイルは次のように構成されている必要があります。
{
"MyFunction1": {
"TABLE_NAME": "localtable",
"BUCKET_NAME": "testBucket"
},
"MyFunction2": {
"TABLE_NAME": "localtable",
"STAGE": "dev"
},
}
$ sam local start-api --env-vars env.json
シェル環境
シェルの環境で定義された変数は、ラムダ関数の変数にマップされている場合、Dockerコンテナに渡されます。 シェル変数は関数にグローバルに適用可能です。 2つの関数にTABLE_NAME
という変数がある場合、Shellの環境から提供されたTABLE_NAME
の値は両方の関数で使用できます。
次のコマンドを実行すると、 mytable
値をMyFunction1
とMyFunction2
両方で使用できるようになりMyFunction2
$ TABLE_NAME=mytable sam local start-api
シェルと環境の組み合わせ変数ファイル
より詳細な制御のために、シェル変数と外部環境変数の組み合わせファイルを使用することができます。 変数が両方の場所で定義されている場合、ファイルからの変数はシェルをオーバーライドします。 優先度の高い順に並べます。 優先度の高いものは低いものを上書きします。
- 環境変数ファイル
- シェルの環境
- テンプレートからハードコードされた値
ラムダ関数コードからのローカル実行の識別
SAM CLIを使用してラムダ関数を呼び出すと、Dockerコンテナに環境変数AWS_SAM_LOCAL=true
が設定されます。 ラムダ関数は、このプロパティを使用して、ローカル開発で意味をなさない機能を有効または無効にすることができます。 例:CloudWatchへのメトリックの送信を無効にする(または)詳細ログなどを有効にする
静的資産
サーバレスアプリケーションを開発する際に静的資産(CSS / HTML / Javascriptなど)を提供することはしばしば役に立ちます。 AWSでは、これは通常CloudFront / S3で行われます。 SAM CLIはデフォルトでSAMプロジェクトディレクトリ内の./public/
ディレクトリを検索し、 sam local start-api
を使用する場合はHTTPサーバーのルートにあるすべてのファイルを提供します。 -s
または--static-dir
コマンドラインフラグを使用すると、デフォルトの静的資産ディレクトリを上書きできます。 また、 --static-dir ""
設定することで、この動作を完全に無効にすることもできます。
ローカルロギング
invoke
コマンドとstart-api
コマンドを使用すると、ログを関数の呼び出しからファイルにパイプすることができます。 これは、SAM CLIに対して自動化されたテストを実行し、分析のためにログを取得する場合に便利です。
例:
$ sam local invoke --log-file ./output.log
リモートドッカー
Sam CLIはファイルシステムをDockerボリュームにマウントすることによって機能コードをロードします。 その結果、プロジェクトディレクトリは、Dockerが実行されているリモートホストにあらかじめマウントされている必要があります。
マウントされている場合、通常は--docker-volume-basedir
または環境変数SAM_DOCKER_VOLUME_BASEDIR
を使用してリモートドッカーを使用できます。
例 – Dockerツールボックス(Windows):
Docker Toolboxをインストールして実行すると、Docker付きLinux VMが仮想ボックスに自動的にインストールされます。
このLinux VMの/ c /パスは、ホストマシン上のC:と自動的に共有されます。
sam local invoke --docker-volume-basedir /c/Users/shlee322/projects/test "Ratings"
プロジェクトのステータス
- [] Pythonバージョンでのサポート
- [x] Python 2.7
- [] Python 3.6
- []サポートされているAWSラムダランタイム
- [x]
nodejs
- [x]
nodejs4.3
- [x]
nodejs6.10
- [x]
nodejs8.10
- [x]
java8
- [x]
python2.7
- [x]
python3.6
- []
dotnetcore1.0
- [x]
dotnetcore2.0
- [x]
- [x] AWS資格情報のサポート
- [x]デバッグのサポート
- [x] SAMテンプレート内のインラインスワッガーのサポート
- [x] SAMテンプレートをローカルで検証する
- [x]定型テンプレートの生成
- [x]
nodejs
- [x]
nodejs4.3
- [x]
nodejs6.10
- [x]
nodejs8.10
- [x]
java8
- [x]
python2.7
- [x]
python3.6
- [x]
dotnetcore1.0
- [x]
dotnetcore2.0
- [x]
貢献する
貢献とフィードバックは大歓迎です! プロポーザルとプルリクエストが考慮され、対応されます。 詳細は、 CONTRIBUTINGファイルを参照してください。
特別なあなたに感謝
SAM CLIは、[@mhart]( https://github.com/mhart )によって作成されたオープンソースのdocker-lambda Dockerイメージを使用します 。
例
このREADMEで使用されているサンプル関数コードとSAMテンプレートは、このレポ内のサンプルフォルダの下にあります。
[…] https://githubja.com/awslabs/aws-sam-cli […]