Github: https://github.com/awslabs/aws-sam-cli

AWS SAM CLI

🐿

Serverlessアプリケーションのローカル開発およびテストのためのCLIツールです。

SAM CLI（ベータ版）

スラックのSAM開発者チャンネル（#samdev）に参加して、仲間のコミュニティメンバーやAWS SAMチームと協力してください。

“ sam“は、AWS Serverless Application Model（SAM）で書かれたServerlessアプリケーションを管理するためのAWS CLIツールです。 SAM CLIを使用すると、ローカルで機能をテストしたり、SAMテンプレートからローカルAPIゲートウェイを開始したり、SAMテンプレートを検証したり、さまざまなイベントソースのサンプルペイロードを生成したり、好きなLambdaランタイムでSAMプロジェクトを生成できます。

SAM CLI（ベータ版）

主な特徴

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 CLI呼び出しサンプル

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 CLI開始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関数をデバッグする方法の例を示します。

SAMローカルデバッグの例

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] 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

貢献する

貢献とフィードバックは大歓迎です！プロポーザルとプルリクエストが考慮され、対応されます。詳細は、 CONTRIBUTINGファイルを参照してください。

特別なあなたに感謝

SAM CLIは、[@mhart]（ https://github.com/mhart ）によって作成されたオープンソースのdocker-lambda Dockerイメージを使用します。

例

このREADMEで使用されているサンプル関数コードとSAMテンプレートは、このレポ内のサンプルフォルダの下にあります。

aws-sam-cli – AWS SAM CLI 🐿 Serverlessアプリケーションのローカル開発およびテストのためのCLIツール