Zenn
🦁

AWS SAMのチュートリアル使ってみた

2025/02/16に公開
AWS
チュートリアル
AWS SAM
サーバーレスアプリケーション
tech

はじめに

この記事では、AWS SAM（Serverless Application Model）というツールを使って、実際にサーバーレスアプリケーションを作成・デプロイするまでの流れを記録しています。

【ポイント】
・画面に出てくる数字（例：python3.13等）は環境によって異なる場合があるので、自分の環境に合わせて読み替えてください。
・この記事に記載されているコマンドは、実際にコピー＆ペーストしても使えるようになっています。安心して操作してください。

チュートリアル

AWS SAMのチュートリアル
公式のチュートリアルに沿って作業しています。このリンク先も併せて参照することで、より深く理解できるでしょう。

チュートリアルの内容

1. チュートリアルの概要

AWS SAMは、AWS上でサーバーレスなリソース（Lambda関数やAPI Gatewayなど）を簡単に定義・構築・デプロイするためのツールです。
今回のチュートリアルでは以下の流れで作業を進めました。

  1. プロジェクトの初期化（sam init コマンド）
  2. プロジェクト構造の確認
  3. アプリケーションのビルド（sam build コマンド）と、もし発生したエラーへの対処（Pythonのバージョン修正）
  4. アプリケーションのデプロイ（sam deploy --guided コマンド）
  5. デプロイ結果の確認（APIエンドポイントにアクセス）
  6. 最後にリソースのクリーンアップ（sam delete コマンド）

【ここでのポイント】
・操作の一つ一つがどのような意味を持つか、初めての人でもイメージしやすいように解説します。

2. チュートリアルの内容

基本的な流れは上記のとおりですが、コマンドを入力する際はCloudShellなど自分のターミナル環境で操作するので、画面に表示される指示に従って「ポチポチ」と操作していきます。

3. 実際にやってみる

プロジェクト初期化

前提条件として、個人用のAWSアカウントを使い、CloudShellで作業を行います。
以下の写真は、実際のCloudShellでの画面イメージです。

まずは、サーバーレスアプリケーションの初期化を行います。初めての場合は、ターミナルで以下のコマンドを実行してください。

sam init

実行すると、以下のような出力が表示されます。
（※表示内容は日本語に翻訳されており、使いやすい雰囲気になっています。）

~ $ sam init
        SAM CLIは現在、お客様のニーズをより良く理解するためにテレメトリを収集しています。
        シェルで環境変数 SAM_CLI_TELEMETRY=0 を設定することで、
        テレメトリの収集をOPT OUTして無効化することができます。
        ご協力ありがとうございます！
        詳細はこちら: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-telemetry.html
`sam init`の使用時に、特定のランタイムやパッケージタイプを事前に選択することができます。
詳しくは`sam init --help`をご参照ください.
使用したいテンプレートソースを選択してください：
        1 - AWS クイックスタートテンプレート
        2 - カスタムテンプレートの場所
選択:

ここでは、「1」 を選択して、AWSがあらかじめ用意したクイックスタートテンプレートを利用します。
その後、さらに具体的なサンプル（例：「Hello World サンプル」）やランタイム（例：Python）が選択肢として提示されます。
初めての場合は、画面の指示に従い、数字や y、ENTER を入力するだけです。

sam init
...
使用したいテンプレートソースを選択してください：
   1 - AWS クイックスタートテンプレート
   2 - カスタムテンプレートの場所
選択: 1
AWS Quick Startアプリケーションテンプレートを選択してください
   1 - Hello World サンプル
   2 - マルチステップワークフロー
   3 - サーバーレスAPI
   4 - スケジュールタスク
   5 - スタンドアロン関数
   6 - データ処理
   7 - Powertoolsを使用したHello Worldサンプル
   8 - インフラストラクチャイベント管理
   9 - Serverless Connector Hello Worldサンプル
   10 - コネクタを使用したマルチステップワークフロー
   11 - Lambda EFSサンプル
   12 - DynamoDBサンプル
   13 - 機械学習
テンプレート: 1
最も一般的なランタイムとパッケージタイプを使用しますか？(Pythonおよびzip形式) [y/N]: y
アプリケーション内の関数でX-Rayトレースを有効にしますか？ [y/N]: ENTER
CloudWatch Application Insightsを使用したモニタリングを有効にしますか？
詳細については、以下をご参照ください：
https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-application-insights.html [y/N]: ENTER

Lambda関数で構造化ロギング（JSON形式）を設定しますか？ [y/N]: ENTER
プロジェクト名 [sam-app]: ENTER

これで、プロジェクトが sam-app というディレクトリに自動生成されます。

プロジェクト構造の確認

生成された sam-app ディレクトリに移動して、プロジェクトの構造を確認してみましょう。

cd sam-app

ls -R // CloudShellなので`tree`じゃなくて`ls`コマンドを使います。

~ $ cd sam-app
sam-app $ tree
bash: tree: command not found
sam-app $ ls -R
.:
events  hello_world  __init__.py  README.md  samconfig.toml  template.yaml  tests

./events:
event.json

./hello_world:
app.py  __init__.py  requirements.txt

./tests:
__init__.py  integration  requirements.txt  unit

./tests/integration:
__init__.py  test_api_gateway.py

./tests/unit:
__init__.py  test_handler.py

【ここでのポイント】

  • events/: Lambda関数に渡すテスト用データが保存されています。
  • hello_world/: 実際のLambda関数の実装（app.py）と依存関係（requirements.txt）が配置されています。
  • tests/: ユニットテストや統合テスト用のコードが入っています。
    各ディレクトリの役割を理解すると、後で自分で変更や追加を行うときに役立ちます。

アプリケーションのビルド

次に、アプリケーションをビルドして実際に動かす準備を行います。

sam build

【初心者向け解説】
ビルドとは、コードの依存関係をまとめて、AWSにデプロイするための形式に変換する作業です。
もしビルド時に以下のようなエラーが出た場合は注意してください。

sam-app $ sam build
キャッシュを使用してビルドを開始しています
マニフェストファイルが変更されている（新しいハッシュ: 3298f13XXXXXXa37ca931dd4d421）か、依存関係フォルダ（.aws-sam/deps/5b411477XXXXXXXXXea64）が（HelloWorldFunction）に対して見つからないため、依存関係をダウンロードしてソースをコピー/ビルドしています
ビルド対象 - コードURI: /home/cloudshell-user/sam-app/hello_world ランタイム: python3.13 アーキテクチャ: x86_64 関数: HelloWorldFunction
ビルド失敗
エラー: PythonPipBuilder:バリデーション - Pythonのバイナリ検証に失敗しました。以下の場所でpythonを検索しましたが、ランタイム python3.13 の要件を満たしませんでした: ['/usr/bin/python', '/bin/python', '/usr/bin/python3', '/bin/python3']。ランタイム python3.13 用のPythonがPATHに設定されていますか？

このエラーは、環境に python3.13 が存在しない場合に起こります。多くの場合、AWS CloudShellや一般的なLinux環境では python3.9 などのバージョンがインストールされているためです。

Pythonバージョンの修正

まず、template.yaml を確認して、ランタイムが python3.13 になっている部分を修正します。

sam-app $ cat template.yaml

Runtime: python3.13 // これを3.9に変更します

手動で修正しても良いですが、下記のように sed コマンドを使って自動修正することも可能です。

sed -i 's/python3.13/python3.9/g' template.yaml

修正後、再度ビルドを実行します。

sam build

ビルドが成功すると、以下のような出力が得られます。

sam-app $ sam build
キャッシュを使用してビルドを開始しています
マニフェストファイルが変更されている（新しいハッシュ: 3298f13049d19cffaa37ca931dd4d421）か、依存関係フォルダが見つからないため、依存関係をダウンロードしてソースをコピー/ビルドしています
ビルド対象 - コードURI: /home/cloudshell-user/sam-app/hello_world ランタイム: python3.9 アーキテクチャ: x86_64 関数: HelloWorldFunction
...
ビルド成功
成果物のビルド先  : .aws-sam/build
テンプレートのビルド先   : .aws-sam/build/template.yaml

【補足】
画面に出てくるハッシュ値やパスはシステム内部の情報なので、特に意識する必要はありません。

アプリケーションのデプロイ

次は、AWSクラウド上にアプリケーションをデプロイします。

sam deploy --guided

【デプロイの流れ】

  • 対話形式での入力：
    画面に表示される設定項目に対して、基本はそのままENTERキーを押すか数字を入力します。
    例：スタック名は「sam-app」、リージョンは「ap-northeast-1」（東京リージョン）など。

  • IAMロールの作成について：
    IAMロールの自動作成を許可するかの選択があるので、特に変更しなければそのまま進みます。

以下は、実際に入力した例になります。

sam-app sam deploy --guided
SAMデプロイの設定
======================
    設定ファイル[samconfig.toml]を探しています :  見つかりました
    デフォルト引数を読み込んでいます    :  成功
    'sam deploy'のデフォルト引数を設定しています
    =========================================
    スタック名[sam-app]: ENTER
    AWSリージョン[ap-northeast-1]: ENTER
    #デプロイする際のリソースの変更を表示し、'Y'の入力で続行します
    デプロイ前に変更を確認しますか [Y/n]: n
    #SAMがテンプレート内のリソースに接続するためのロールを作成する権限が必要です
    SAM CLIによるIAMロールの作成を許可しますか [Y/n]: ENTER
    #操作が失敗した際に、以前にプロビジョニングされたリソースの状態を保持します
    ロールバックを無効にしますか [y/N]: ENTER
    HelloWorldFunctionに認可が定義されていない可能性があります。これでよろしいですか？ [y/N]: y
    設定ファイルに引数を保存しますか [Y/n]: ENTER
    SAM設定ファイル [samconfig.toml]: ENTER
    SAM設定環境 [default]: ENTER

デプロイ処理が進むと、AWS CloudFormationが作成したリソースの情報（API Gatewayのエンドポイントなど）が表示されます。

デプロイされたスタックからのCloudFormation出力
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
キー                HelloWorldApi
説明                Hello World関数のProdステージ用APIゲートウェイエンドポイントURL
値                  https://r1s2XXXX23i.execute-api.ap-northeast-1.amazonaws.com/Prod/hello/

このURLが、あなたがデプロイしたアプリケーションの入り口になります。

動作確認

実際に上記で表示されたURLにWebブラウザでアクセスしてみてください。

【解説】
アクセスして返ってくる内容（例：「Hello World」や、シンプルなJSON形式のレスポンス）を確認することで、無事に動作しているかどうかが分かります。
また、AWSのマネジメントコンソールで、Lambda、API Gateway、IAMロールなどのリソースが正しく作成されていることも確認できます。すげぇ！



最後にお掃除します

使い終わったAWSリソースは、料金が発生しないように削除するのが基本です。
以下のコマンドを実行して、クラウド上のリソースを削除します。

sam delete

リージョンap-northeast-1のスタックsam-appを削除してもよろしいですか？ [y/N]: y
        成果物を含むS3フォルダsam-appを削除してもよろしいですか？ [y/N]: y
        - キーsam-app/ba9b03be9c3c5b75a3b9f6f376c533e9のS3オブジェクトを削除中
        - キーsam-app/b9d37a3d8766d3b7b0a6775624c3a295.templateのS3オブジェクトを削除中
        - CloudFormationスタックsam-appを削除中
削除が正常に完了しました

sam-app $ cd ../ // これで、sam-appディレクトリから出ます。
~ $ rm -rf sam-app // これで、sam-appディレクトリが削除されます。
~ $ ls -R // これで、ディレクトリが削除されたことを確認できます。
.:

削除が完了すると、以下のように画面に一覧が出力され、リソースが綺麗になっているのが確認できます。

【注意点】
・削除の際、S3上のオブジェクトの削除など時間がかかる場合がありますが、最終的に不要なリソースが削除されるので安心してください。

まとめ

今回のチュートリアルでは、以下の工程を通してAWS SAMによるサーバーレスアプリケーションの作成から削除までの流れを体験しました。

  1. プロジェクト初期化
    • sam init コマンドで雛形を作成（対話形式で操作）
  2. プロジェクト構造の確認
    • 各ディレクトリ（events, hello_world, tests）の役割を確認
  3. ビルド
    • sam build の実行と、Pythonバージョンエラーへの対応（template.yaml の修正）
  4. デプロイ
    • sam deploy --guided に従い、クラウド上にリソース作成
  5. 動作確認
    • API GatewayエンドポイントにWebブラウザでアクセスし、動作を確認
  6. クリーンアップ
    • sam delete コマンドで全リソースを削除し、コスト管理

【初心者向けのポイント】

  • コマンドをそのまま入力して、指示に従うだけで大丈夫です。
  • 分からないエラーが出た場合は、エラーメッセージに書かれている内容を確認し、PythonやAWSの公式ドキュメントも参考にしてください。
  • 固有名詞や数字（例：sam-app, python3.13）はそのままなので、迷わず入力しましょう。

以上で、AWS SAMのチュートリアル体験記と初心者向けの詳細解説を終了します。実際に手を動かしながら、AWSでのアプリケーション作成の流れを学んでみてください！

Discussion