sam build - AWS Serverless Application Model

sam build

サーバーレスアプリケーションを構築し、アプリケーションのローカルでのテスト、または AWS クラウドへのデプロイなどのワークフロー内の後続ステップのためにアプリケーションを準備します。ユーザーが RESOURCE_LOGICAL_ID を提供する場合、AWS SAM はそのリソースのみを構築します。ネストされたアプリケーションまたはスタックのリソースを構築するには、StackLogicalId/ResourceLogicalId 形式を使用して、リソースの論理 ID と共に、アプリケーションまたはスタックの論理 ID を提供できます。

sam build コマンドは、AWS SAM テンプレートファイル、アプリケーションコード、および該当する言語固有のファイルと依存関係を処理します。このコマンドは、ワークフローの後続ステップに期待される形式と場所へのビルドアーティファクトのコピーも実行します。依存関係は、アプリケーションに含めるマニフェストファイル (Python 関数の場合は requirements.txt、または Node.js 関数の場合は package.json など) で指定します。

アプリケーションのビルドアーティファクトの形式は、そのパッケージタイプに応じて異なります。AWS Lambda 関数のパッケージタイプは、PackageType プロパティを使って指定します。オプションは以下のとおりです。

  • Zip - アプリケーションコードとその依存関係が含まれる.zip ファイルアーカイブ。コードを .zip ファイルアーカイブとしてパッケージ化する場合は、関数の Lambda ランタイムを指定する必要があります。

  • Image - アプリケーションコードとその依存関係に加えて、ベースオペレーティングシステム、ランタイム、および拡張機能が含まれているコンテナイメージ。

Lambda パッケージタイプに関する詳細については、AWS Lambda デベロッパーガイドの「Lambda デプロイパッケージ」を参照してください。

リソースに BuildMethod エントリがある Metadata リソース属性が含まれている場合、sam buildBuildMethod エントリの値に従ってそのリソースを構築します。BuildMethod の有効な値は、1) Lambda ランタイムの識別子の 1 つ、または 2) makefile 識別子です。

  • Lambda ランタイム識別子 - Lambda ランタイムに対してリソースを構築します。サポートされているランタイム識別子のリストについては、AWS Lambda デベロッパーガイドの「Lambda ランタイム」を参照してください。

  • makefile 識別子 — リソース用のビルドターゲットのコマンドを実行します。この場合、makefile が Makefile と命名されており、build-resource-logical-id という名前のビルドターゲットが含まれている必要があります。

レイヤーとカスタムランタイムの構築には、BuildMethod エントリがある Metadata リソース属性を使用することもできます。レイヤーの構築については、「レイヤーの構築」を参照してください。カスタムランタイムの構築については、「カスタムランタイムの構築」を参照してください。

Image パッケージタイプを使用するサーバーレス関数リソースには、コンテナイメージの構築に必要な Docker イメージの設定に Metadata リソース属性を使用します。コンテナイメージの構築に関する詳細については、「コンテナイメージの構築」を参照してください。

ローカルでのテストと AWS へのデプロイを含めた、このコマンドを使用する完全な例については、「チュートリアル: Hello World アプリケーションのデプロイ」を参照してください。sam build コマンドは ステップ 2: アプリケーションを構築する の一部です。

使用方法:

sam build [OPTIONS] [RESOURCE_LOGICAL_ID]

例:

To use these commands, update your SAM template to specify the path to your function's source code in the resource's Code or CodeUri property. To build on your workstation, run this command in the directory containing your SAM template. Built artifacts are written to the .aws-sam/build directory. $ sam build To build inside a Lambda-like Docker container $ sam build --use-container To build with environment variables passed to the build container from the command line $ sam build --use-container --container-env-var Function1.GITHUB_TOKEN=<token1> --container-env-var GLOBAL_ENV_VAR=<global-token> To build with environment variables passed to the build container from a file $ sam build --use-container --container-env-var-file <env-file.json> Build a Node.js 12 application using a container image pulled from DockerHub $ sam build --use-container --build-image amazon/aws-sam-cli-build-image-nodejs12.x Build a function resource using the Python 3.8 container image pulled from DockerHub $ sam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.8 To build and run your functions locally $ sam build && sam local invoke To build and package for deployment $ sam build && sam package --s3-bucket <bucketname> To build the 'MyFunction' resource $ sam build MyFunction To build the 'MyFunction' resource of the 'MyNestedStack' nested stack $ sam build MyNestedStack/MyFunction

引数:

引数 説明
RESOURCE_LOGICAL_ID (オプション)。AWS SAM テンプレートで宣言された単一のリソースを構築するよう AWS SAM に指示します。指定されたリソースのビルドアーティファクトは、ワークフローの後続コマンド (つまり、sam packagesam deploy) に使用できる唯一のアーティファクトになります。

オプション:

オプション 説明
-b, --build-dir DIRECTORY ビルドアーティファクトが保存されているディレクトリへのパスです。このオプションを使用すると、このディレクトリとそのコンテンツのすべてが削除されます。
-s, --base-dir DIRECTORY 関数またはレイヤーのソースコードへの相対パスを、このディレクトリを基準にして解決します。このオプションは、ソースコードフォルダへの相対パスの解決方法を変更したい場合に使用します。デフォルトで、相対パスは AWS SAM テンプレートの場所を基準にして解決されます。

このオプションは、構築しているルートアプリケーションまたはスタックのリソースに加えて、ネストされたアプリケーションまたはスタックにも適用されます。

このオプションは、以下のリソースタイプとプロパティに適用されます。

  • リソースタイプ: AWS::Serverless::Function プロパティ: CodeUri

  • リソースタイプ: AWS::Serverless::Function リソース属性: Metadata エントリ: DockerContext

  • リソースタイプ: AWS::Serverless::LayerVersion プロパティ: ContentUri

  • リソースタイプ: AWS::Lambda::Function プロパティ: Code

  • リソースタイプ: AWS::Lambda::LayerVersion プロパティ: Content

-u, --use-container 関数がネイティブにコンパイルされた依存関係を持つパッケージに依存する場合は、このオプションを使用して、Lambda に似た Docker コンテナ内で関数を構築します。
-e, --container-env-var TEXT ビルドコンテナに渡す環境変数です。このオプションは複数回指定できます。このオプションの各インスタンスは、キーバリューペアを使用します。このペアのキーはリソースと環境変数で、値は環境変数の値です。例: --container-env-var Function1.GITHUB_TOKEN=TOKEN1 --container-env-var Function2.GITHUB_TOKEN=TOKEN2

このオプションは、--use-container オプションが指定されている場合のみに適用され、指定されていない場合はエラーが発生します。

-ef, --container-env-var-file PATH コンテナの環境変数の値が含まれる JSON ファイルのパスとファイル名です。コンテナ環境変数ファイルの詳細については、「コンテナ環境変数ファイル」を参照してください。

このオプションは、--use-container オプションが指定されている場合のみに適用され、指定されていない場合はエラーが発生します。

--build-image TEXT

ビルド用にプルするコンテナイメージの URI です。デフォルトで、AWS SAM は Amazon ECR Public からコンテナイメージをプルします。このオプションは、別の場所からイメージをプルするために使用します。

このオプションは複数回指定できます。このオプションの各インスタンスには、文字列またはキーバリューペアを使用できます。文字列を指定する場合は、アプリケーション内のすべてのリソースに使用するコンテナイメージの URI になります。例えば、sam build --use-container --build-image amazon/aws-sam-cli-build-image-python3.8 です。キーバリューペアを指定する場合、キーはリソース名で、値はそのリソースに使用するコンテナイメージの URI です。例えば、sam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.8 です。キーバリューペアを使用すると、異なるリソースに異なるコンテナイメージを指定できます。

このオプションは、--use-container オプションが指定されている場合のみに適用され、指定されていない場合はエラーが発生します。

-m, --manifest PATH デフォルトの代わりに使用する、カスタム依存関係のマニフェストファイル (package.json など) へのパスです。
-t, --template-file, --template PATH AWS SAM テンプレートファイル [default: template.[yaml|yml]] のパスと名前です。
--parameter-overrides (オプション) キーバリューペアとしてエンコードされた、AWS CloudFormation パラメータオーバーライドが含まれる文字列です。AWS Command Line Interface (AWS CLI) と同じ形式を使用します。例えば、「ParameterKey=KeyPairName, ParameterValue=MyKey ParameterKey=InstanceType, ParameterValue=t1.micro」などです。
--skip-pull-image コマンドが Lambda ランタイム用の最新 Docker イメージのプルダウンをスキップするべきかどうかを指定します。
--docker-network TEXT デフォルトのブリッジネットワークと共に、Lambda Docker コンテナが接続する必要がある既存の Docker ネットワークの名前または ID を指定します。指定されていない場合、Lambda コンテナはデフォルトのブリッジ Docker ネットワークのみに接続します。
--parallel 並列ビルドを有効にします。このオプションを使用して、AWS SAM テンプレートの関数とレイヤーを並列的に作成します。デフォルトで、関数とレイヤーは順番に構築されます。
--cached キャッシュされたビルドを有効にします。このオプションは、以前のビルドから変更されていないビルドアーティファクトを再利用するために使用します。AWS SAM は、プロジェクトディレクトリ内のファイルが変更されたかどうかを評価します。注意: AWS SAM は、特定のバージョンが提供されていない場合、プロジェクトが依存するサードパーティーモジュールが変更されたかどうかを評価しません。例えば、Python 関数に requests=1.x エントリがある requirements.txt ファイルが含まれていて、リクエストモジュールの最新バージョンが 1.1 から 1.2 に変更される場合、AWS SAM はキャッシュされていないビルドが実行されるまで最新バージョンをプルしません。
--cache-dir --cached が指定されている場合にキャッシュアーティファクトが保存されるディレクトリです。デフォルトのキャッシュディレクトリは .aws-sam/cache です。
--profile TEXT AWS 認証情報を取得する、認証情報ファイルから特定のプロファイルです。
--region TEXT デプロイ先の AWS リージョンです。例えば、us-east-1 などです。
--config-file PATH 使用するデフォルトのパラメータ値が含まれる設定ファイルのパスとファイル名です。デフォルト値は、プロジェクトディレクトリのルートにある「samconfig.toml」です。設定ファイルの詳細については、「AWS SAM CLI の設定ファイル」を参照してください。
--config-env TEXT 使用する設定ファイル内のデフォルトパラメータ値を指定する環境名です。デフォルト値は「default」です。設定ファイルの詳細については、「AWS SAM CLI の設定ファイル」を参照してください。
--debug デバッグロギングをオンにして、AWS SAM CLI が生成するメッセージを出力表示し、タイムスタンプを表示します。
--help このメッセージを表示して終了します。

Lambda ランタイム識別子を使用したリソースの構築

以下は、Lambda ランタイム識別子を使用してリソースを構築する方法を示す AWS SAM テンプレートの例です。

Resources: MyLayer: Type: AWS::Serverless::LayerVersion Properties: ContentUri: my_layer CompatibleRuntimes: - python3.6 Metadata: BuildMethod: python3.6

このテンプレートを使用して、以下のコマンドが Python 3.6 ランタイム環境に対して MyLayer リソースを構築します。

sam build MyLayer

makefile 識別子を使用したリソースの構築

以下は、makefile 識別子を使用してリソースを構築する方法を示すサンプル AWS SAM です。

Resources: MyLayer: Type: AWS::Serverless::LayerVersion Properties: ContentUri: my_layer CompatibleRuntimes: - python3.8 Metadata: BuildMethod: makefile

これは、関連する makefile の例です。ファイルは Makefile と命名し、実行するコマンドを使用したビルドターゲットが含まれている必要があります。

build-MyLayer: mkdir -p "$(ARTIFACTS_DIR)/python" cp *.py "$(ARTIFACTS_DIR)/python" python -m pip install -r requirements.txt -t "$(ARTIFACTS_DIR)/python"

このテンプレートと makefile を使用して、以下のコマンドが build-MyLayer ターゲットのコマンドを実行します。

sam build MyLayer

ビルドコンテナへの環境変数のパス

以下は、ファイルを使用してビルドコンテナに環境変数を渡す方法を示す例です。

まず、以下の内容で env.json という名前のファイルを作成します。

{ "MyFunction1": { "GITHUB_TOKEN": "TOKEN1" }, "MyFunction2": { "GITHUB_TOKEN": "TOKEN2" } }

次に、以下のコマンドを実行します。

sam build --use-container --container-env-var-file env.json

コンテナ環境変数ファイルの詳細については、「コンテナ環境変数ファイル」を参照してください。