AWS SAM入門｜template.yamlの書き方とbuild・deploy

AWS SAM（Serverless Application Model）は、Lambda と API Gateway などのサーバーレスの構成を、短い YAML で書いて作るための仕組みです。 template.yaml に AWS::Serverless::Function を1つ書くと、SAM がそれを CloudFormation のリソースに展開します。この記事の例では、関数1つと API 1つの記述から、6つのリソースができました。

確認環境：SAM CLI 1.168.0、aws-sam-translator 1.114.0、Python 3.11（Linux）。AWS の認証情報を外した状態で確かめました（確認日 2026年10月12日）。

1. SAM CLI を入れる

この記事では、SAM CLI を pip（pip install aws-sam-cli）で入れました。

sam --version
# SAM CLI, version 1.168.0

2. template.yaml を書く

フォルダの構成は次のとおりです。 sam init でひな形を作ることもできますが、ここでは中身が分かるように手で書きます。

app/
├── template.yaml
└── src/
    ├── app.py
    └── requirements.txt     ← requests

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: hello api

Globals:
  Function:
    Runtime: python3.13
    Timeout: 10
    MemorySize: 128

Resources:
  HelloFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: app.lambda_handler
      Events:
        HelloApi:
          Type: Api
          Properties:
            Path: /hello
            Method: get

Outputs:
  HelloApiUrl:
    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello"

関数のコード（src/app.py）です。

import json
import requests

def lambda_handler(event, context):
    name = (event.get("queryStringParameters") or {}).get("name", "world")
    return {
        "statusCode": 200,
        "headers": {"Content-Type": "application/json"},
        "body": json.dumps({"message": f"hello {name}", "requests": requests.__version__}),
    }

3. SAM が展開するリソース

SAM の変換処理（aws-sam-translator）でこのテンプレートを変換すると、次の6つのリソースになりました。

自動で作られた実行ロールには、CloudWatch Logs にログを書くための AWSLambdaBasicExecutionRole が付いていました。

"ManagedPolicyArns": ["arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"]

S3 や DynamoDB を使うときは、Policies に SAM のポリシーテンプレート（S3ReadPolicy など）を書き足します。

      Policies:
        - S3ReadPolicy:
            BucketName: my-bucket

変換すると、実行ロールに次の操作を許すポリシーが足されました。

s3:GetObject, s3:ListBucket, s3:GetBucketLocation, s3:GetObjectVersion, s3:GetLifecycleConfiguration

4. sam validate と --lint で確かめる

sam validate
# template.yaml is a valid SAM Template. This is according to basic SAM Validation, for additional validation, please run with "--lint" option

sam validate --lint
# template.yaml is a valid SAM Template

sam validate だけでは見つからない誤りが、--lint で見つかりました。 ランタイムに終了した python3.7 を書くと、sam validate は通り、--lint では止まりました。

[[E2531: Validate if lambda runtime is deprecated] (Runtime 'python3.7' was deprecated on '2023-12-04'. Creation was disabled on '2024-01-09' and update on '2027-03-03'. Please consider updating to 'python3.14') matched 4]
Error: Linting failed. At least one linting rule was matched to the provided template.

書いたら sam validate --lint を習慣にすると、デプロイの前に気づけます。

5. sam build：依存を入れてまとめる

sam build

Building codeuri: /…/app/src runtime: python3.13 architecture: x86_64 functions: HelloFunction
 Running PythonPipBuilder:ResolveDependencies
 Running PythonPipBuilder:CopySource

Build Succeeded

Built Artifacts  : .aws-sam/build
Built Template   : .aws-sam/build/template.yaml

.aws-sam/build/HelloFunction に、app.py と、requirements.txt に書いた requests とその依存（certifi・charset_normalizer・idna）が入っていました。 Lambda で「No module named 'requests'」になる入れ忘れが、これで起きにくくなります。

.aws-sam/build/HelloFunction/
├── app.py
├── requests/   requests-2.34.2.dist-info/
├── certifi/    charset_normalizer/   idna/
└── requirements.txt

ビルドしたフォルダを、Lambda のランタイムクライアント（awslambdaric）で手元で動かすと、次の応答が返りました。

{"statusCode": 200, "headers": {"Content-Type": "application/json"},
 "body": "{\"message\": \"hello world\", \"requests\": \"2.34.2\"}"}

C や Rust で書かれた部分を持つライブラリ（pydantic など）を使うときは、sam build --use-container にすると、AWS のドキュメントのとおり Lambda に近い Docker コンテナの中でビルドされます。Mac で入れたライブラリが Lambda で読み込めない問題は、関連記事「Lambda Unable to import moduleの直し方｜Python」で扱っています。

6. sam local invoke（Docker が要る）

Docker が無い環境で sam local invoke を実行すると、次のメッセージで止まりました。

Error: Running AWS SAM projects locally requires a container runtime. Do you have Docker or Finch installed and running?

sam local invoke・sam local start-api は、Lambda に近いコンテナで関数を動かすので、Docker（または Finch）が要ります。

sam local invoke HelloFunction --event events/event.json
sam local start-api      # http://127.0.0.1:3000/hello で呼べる

7. sam deploy：初回は --guided

認証情報が無い状態で sam deploy を実行すると、次のメッセージで止まりました。

Error: Unable to locate credentials

認証情報を設定してから、初回は --guided で、質問に答えながらデプロイします。

sam deploy --guided

認証情報を外した状態で sam deploy --guided を実行すると、次の順に聞かれ、答え終わったあとに「Unable to locate credentials」で止まりました。

AWS のドキュメントでは、設定ファイルの既定は、プロジェクト直下の samconfig.toml です。 2回目からは sam deploy だけで同じ設定が使われます。

認証情報の設定は、関連記事「AWS CLI Unable to locate credentialsの直し方」で扱っています。

SAM と CDK・CloudFormation の違い

CDK は関連記事「AWS CDK入門｜TypeScriptでS3とLambdaを作りsynthまで」で扱っています。

よくある質問

Q. Transform を書き忘れるとどうなりますか。 A. Transform の行だけを消して sam validate --lint を実行すると、E3038（'AWS::Serverless::Function' type used without the serverless transform 'AWS::Serverless-2016-10-31'）や、'Globals' was unexpected で止まりました。AWS::Serverless::Function も Globals も SAM の書き方なので、Transform が要ります。

Q. sam build のあと、.aws-sam は Git に入れますか。 A. ビルドのたびに作り直すフォルダなので、.gitignore に入れておくのが一般的です。samconfig.toml は、チームで同じ設定を使うなら入れます。

Q. API の URL はどこで分かりますか。 A. Outputs に書いた HelloApiUrl が、sam deploy の最後に表示されます。CloudFormation コンソールの「出力」タブでも見られます。

Q. sam validate は通ったのに、デプロイで失敗しました。 A. sam validate は基本的な形だけを確かめます。--lint を付けると、ランタイムの終了なども見つけられます。それでも見つからない誤り（権限や名前の重複など）は、CloudFormation の「イベント」タブで、最初に失敗したリソースの理由を見ます。

まとめ

• SAM は Transform を付けた YAML で、Lambda と API を短く書く仕組み
• 関数1つ・API 1つの記述から、ロール・API・ステージ・許可を含む6つのリソースに展開された
• sam validate --lint で、sam validate では通る誤り（終了したランタイム）が見つかった
• sam build は requirements.txt の依存を入れてまとめる。ネイティブ拡張は --use-container
• sam local は Docker が要る、sam deploy は 認証情報が要る。初回は --guided

参考・出典

確認日はいずれも 2026年10月12日です。

• AWS SAM デベロッパーガイド「sam build」：https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-build.html
• AWS SAM デベロッパーガイド「sam deploy」：https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-deploy.html
• SAM CLI 1.168.0・aws-sam-translator 1.114.0（sam validate・sam build・sam local invoke・sam deploy の出力、変換結果）

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。