はじめに

「チャットボットの会話ログをAPIで受け取り、AWSに蓄積したい」——そんな要件を実現する構成が API Gateway + Lambda + CloudWatch Logs の組み合わせです。

この記事では、AWSコンソールのみを使って、チャットボットの会話ログを記録・取得するREST APIをゼロから構築するハンズオンを紹介します。

クライアント
  ↓ POST /logs（会話ログを送信）
API Gateway（REST API）
  ↓ Lambda プロキシ統合
Lambda（ChatLogFunction / Python 3.12）
  ↓ boto3 logs.put_log_events()
CloudWatch Log Group（/chatbot/chatbot-logs）
  ↓ Metric Filter（level = "error" のログを検出）
CloudWatch カスタムメトリクス（ChatErrorCount）

このハンズオンで体験できること：

• API Gateway REST API のリソース・メソッド作成と Lambda プロキシ統合
• CloudWatch Logs カスタムロググループへのログ書き込み（put_log_events）
• Metric Filter によるエラーログの自動メトリクス変換
• CloudWatch Logs Insights でのログクエリ実行

この記事は SAM版ハンズオン の比較記事です。
コンソール操作でAPI Gateway・Lambda・CloudWatch Logsの連携を視覚的に学び、SAM と何が違うのかを比較したい方向けです。

Amazon検索[本 AWS 開発]

キーワード解説

使用するAWSサービス

全体の作業順序

① CloudWatch Log Group を作成する
      ↓
② CloudWatch Metric Filter を作成する（error ログ → メトリクス）
      ↓
③ Lambda 関数を作成する（コード・環境変数・タイムアウト設定）
      ↓
④ Lambda の実行ロールに権限を追加する
  （CloudWatch Logs: 書き込み・読み取り / CloudWatch: PutMetricData）
      ↓
⑤ API Gateway REST API を作成する（POST /logs, GET /logs）
      ↓
⑥ 動作テスト（curl でログ送信 → コンソールで確認）
      ↓
⑦ リソースの削除

Log Group を先に作る理由：
Metric Filter の作成にはロググループが必要なため、最初に作成します。

① CloudWatch Log Group を作成する

AWSコンソール → CloudWatch → ロググループ → 「ロググループの作成」

「作成」をクリック。

控えておく情報:

• ロググループ名: /chatbot/chatbot-logs

② CloudWatch Metric Filter を作成する

エラーログを自動的にカスタムメトリクスに変換するフィルターを設定します。

CloudWatch → ロググループ → /chatbot/chatbot-logs → 「メトリクスフィルター」タブ → 「メトリクスフィルターを作成」

フィルターパターンの設定

「パターンのテスト」でテストデータを入力して確認できます（任意）。「次へ」をクリック。

メトリクスの設定

「次へ」→「メトリクスフィルターを作成」。

Metric Filter の仕組み:
CloudWatch Logs に届いたログが { $.level = "error" } にマッチするたびに、
ChatBot/chatbot-logs 名前空間の ChatErrorCount に 1 が加算されます。
ログに {"level": "error", ...} という JSON が含まれていればマッチします。

③ Lambda 関数を作成する

AWSコンソール → Lambda → 「関数の作成」

「関数の作成」をクリック。

タイムアウトの設定

「設定」タブ → 「一般設定」→「編集」

「保存」をクリック。

環境変数の設定

「設定」タブ → 「環境変数」→「編集」→「環境変数を追加」

「保存」をクリック。

コードの入力

「コード」タブ → lambda_function.py を開いて既存の内容を全て置き換えます。

import json
import os
import time
import uuid

import boto3
from botocore.exceptions import ClientError

logs_client = boto3.client("logs")
cloudwatch = boto3.client("cloudwatch")

LOG_GROUP_NAME = os.environ["LOG_GROUP_NAME"]
METRIC_NAMESPACE = "ChatBot/" + LOG_GROUP_NAME.split("/")[-1]  # "ChatBot/chatbot-logs"


def lambda_handler(event, context):
    http_method = event.get("httpMethod", "")
    resource = event.get("resource", "/")

    if http_method == "POST" and resource == "/logs":
        return post_log(event)
    elif http_method == "GET" and resource == "/logs":
        return get_logs(event)
    else:
        return _response(404, {"error": "Not Found"})


def post_log(event):
    try:
        body = json.loads(event.get("body") or "{}")
    except json.JSONDecodeError:
        return _response(400, {"error": "Invalid JSON"})

    session_id = body.get("session_id") or str(uuid.uuid4())
    user_id = body.get("user_id", "anonymous")
    message = body.get("message", "")
    response_text = body.get("response", "")
    level = body.get("level", "info")

    log_entry = {
        "session_id": session_id,
        "user_id": user_id,
        "message": message,
        "response": response_text,
        "level": level,
    }

    log_stream_name = f"session/{session_id}"
    _ensure_log_stream(log_stream_name)  # ストリームを作成（既存なら無視）
    logs_client.put_log_events(
        logGroupName=LOG_GROUP_NAME,
        logStreamName=log_stream_name,
        logEvents=[
            {
                "timestamp": int(time.time() * 1000),  # ミリ秒単位の Unix 時間
                "message": json.dumps(log_entry, ensure_ascii=False),
            }
        ],
    )

    cloudwatch.put_metric_data(
        Namespace=METRIC_NAMESPACE,
        MetricData=[
            {
                "MetricName": "MessageCount",
                "Dimensions": [{"Name": "Level", "Value": level}],
                "Value": 1,
                "Unit": "Count",
            }
        ],
    )

    return _response(200, {
        "session_id": session_id,
        "log_stream": log_stream_name,
        "message": "ログを記録した",
    })


def get_logs(event):
    params = event.get("queryStringParameters") or {}
    session_id = params.get("session_id")
    limit = min(int(params.get("limit", "20")), 100)

    if not session_id:
        return _response(400, {"error": "session_id クエリパラメーターは必須"})

    log_stream_name = f"session/{session_id}"

    try:
        resp = logs_client.get_log_events(
            logGroupName=LOG_GROUP_NAME,
            logStreamName=log_stream_name,
            limit=limit,
            startFromHead=False,  # 最新のログから取得
        )
        events = []
        for e in resp["events"]:
            try:
                msg = json.loads(e["message"])
            except json.JSONDecodeError:
                msg = e["message"]
            events.append({"timestamp_ms": e["timestamp"], "log": msg})
    except ClientError as e:
        if e.response["Error"]["Code"] == "ResourceNotFoundException":
            events = []  # ログストリームが存在しない場合は空リストを返す
        else:
            raise

    return _response(200, {
        "session_id": session_id,
        "log_count": len(events),
        "logs": events,
    })


def _ensure_log_stream(log_stream_name: str) -> None:
    try:
        logs_client.create_log_stream(
            logGroupName=LOG_GROUP_NAME,
            logStreamName=log_stream_name,
        )
    except ClientError as e:
        if e.response["Error"]["Code"] != "ResourceAlreadyExistsException":
            raise  # 既存ストリームは無視、それ以外のエラーは再送出


def _response(status_code: int, body: dict) -> dict:
    return {
        "statusCode": status_code,
        "headers": {"Content-Type": "application/json"},
        "body": json.dumps(body, ensure_ascii=False),
    }

「Deploy」ボタンをクリックしてコードを保存します。

④ Lambda の実行ロールに権限を追加する

デフォルトの実行ロールは CloudWatch Logs への書き込み（Lambdaの実行ログ出力）のみです。
今回はカスタムロググループへの書き込み・読み取りと、カスタムメトリクスへの書き込み権限を追加します。

Lambda → ChatLogFunction → 「設定」タブ → 「アクセス権限」→ 実行ロール名のリンクをクリック

（例: ChatLogFunction-role-XXXX）→ IAM コンソールのロール画面が開きます。

CloudWatch Logs と CloudWatch の権限をまとめて追加する

「許可を追加」→「インラインポリシーを作成」→「JSON」タブを選択して以下を入力します。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:GetLogEvents",
        "logs:DescribeLogStreams"
      ],
      "Resource": [
        "arn:aws:logs:ap-northeast-1:YOUR_ACCOUNT_ID:log-group:/chatbot/chatbot-logs",
        "arn:aws:logs:ap-northeast-1:YOUR_ACCOUNT_ID:log-group:/chatbot/chatbot-logs:*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "cloudwatch:PutMetricData",
      "Resource": "*"
    }
  ]
}

YOUR_ACCOUNT_ID を自分の AWS アカウント ID（12桁）に置き換えてください。
アカウント ID は aws sts get-caller-identity で確認できます。

「次へ」→ ポリシー名: ChatLogPolicy → 「ポリシーを作成」。

なぜ 2 種類の権限が必要か:

• logs:PutLogEvents — put_log_events() でカスタムロググループにログを書き込む
• logs:GetLogEvents — get_log_events() でログを読み取る
• cloudwatch:PutMetricData — put_metric_data() でカスタムメトリクスを記録する

⑤ API Gateway REST API を作成する

5-1. API の作成

AWSコンソール → API Gateway → 「APIを作成」→ 「REST API」→「構築」

「API を作成」をクリック。

5-2. /logs リソースを作成する

「リソース」→「リソースを作成」

「リソースを作成」をクリック。

5-3. POST メソッドを作成する（ログ書き込み）

/logs リソースを選択した状態で「メソッドを作成」。

「メソッドを作成」をクリック。

5-4. GET メソッドを作成する（ログ取得）

同様に GET メソッドを追加します。設定は POST と同じ（Lambda 関数: ChatLogFunction）。

5-5. API をデプロイする

「API をデプロイ」→

「デプロイ」をクリック。

デプロイ後に表示される URL を控えておきます:

https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod

⑥ 動作テスト

事前準備: API URL を変数に設定する

set API_URL=https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod

XXXXXXXXXX を ⑤ でデプロイ後に表示された URL の値に置き換えてください。

テスト 1: ログを記録する（POST /logs）

curl -X POST "%API_URL%/logs" ^
  -H "Content-Type: application/json" ^
  -d "{\"session_id\": \"session-001\", \"user_id\": \"user001\", \"message\": \"今日の天気は？\", \"response\": \"東京は晴れです\", \"level\": \"info\"}"

期待するレスポンス:

{
  "session_id": "session-001",
  "log_stream": "session/session-001",
  "message": "ログを記録した"
}

テスト 2: エラーログを記録する（Metric Filter のテスト）

curl -X POST "%API_URL%/logs" ^
  -H "Content-Type: application/json" ^
  -d "{\"session_id\": \"session-001\", \"user_id\": \"user001\", \"message\": \"注文履歴を見せて\", \"response\": \"エラーが発生しました\", \"level\": \"error\"}"

このリクエスト後、CloudWatch メトリクス ChatBot/chatbot-logs > ChatErrorCount が +1 されます。
反映まで数分かかることがあります。

テスト 3: ログを取得する（GET /logs）

curl "%API_URL%/logs?session_id=session-001"

期待するレスポンス:

{
  "session_id": "session-001",
  "log_count": 2,
  "logs": [
    {
      "timestamp_ms": 1700000000000,
      "log": {
        "session_id": "session-001",
        "user_id": "user001",
        "message": "今日の天気は？",
        "response": "東京は晴れです",
        "level": "info"
      }
    }
  ]
}

CloudWatch でログを確認する

CloudWatch → ロググループ → /chatbot/chatbot-logs → ログストリーム

• session/session-001 ストリームをクリック
• 送信した会話ログが JSON 形式で記録されていることを確認します

CloudWatch Logs Insights でクエリを実行する（任意）

CloudWatch → Logs Insights

ロググループに /chatbot/chatbot-logs を選択し、時間範囲を「直近1時間」など幅のある範囲に設定してから以下のクエリを実行します。

注意: 開始時刻と終了時刻が同じだとエラー Query's end date and time is either before the log groups creation time... が出ます。カレンダーアイコンで時間幅を確保してください。

fields @timestamp, session_id, user_id, level, message
| filter level = "error"
| sort @timestamp desc
| limit 20

エラーログだけを抽出して確認できます。

カスタムメトリクスを確認する（任意）

CloudWatch → メトリクス → すべてのメトリクス → カスタム名前空間 → ChatBot/chatbot-logs

⑦ リソースの削除

課金を止めるために、ハンズオン完了後は必ず削除してください。

1. API Gateway を削除する

API Gateway → API → ChatLogAPI → 「削除」→ API 名を入力 → 「削除」

2. Lambda 関数を削除する

Lambda → 関数 → ChatLogFunction → 「アクション」→「削除」

3. CloudWatch Log Group を削除する

CloudWatch → ロググループ → /chatbot/chatbot-logs → 「アクション」→「ロググループを削除」

Metric Filter はロググループを削除すると自動的に削除されます。

4. IAM ロールを削除する（任意）

IAM → ロール → ChatLogFunction-role-XXXX を削除

5. CloudWatch Lambda ロググループを削除する（任意）

CloudWatch → ロগগループ → /aws/lambda/ChatLogFunction → 削除

SAM との対比

コンソール版のつまずきポイント:
IAM のインラインポリシーに YOUR_ACCOUNT_ID を自分のアカウントIDに書き換えるのを忘れると AccessDeniedException が発生します。
SAM版では !GetAtt ChatLogGroup.Arn で自動解決されるため、この手作業が不要です。

トラブルシューティング

まとめ

今回のハンズオンで体験できたこと：

コンソール版で実感できたポイント

• API Gateway のリソース・メソッド・デプロイという3段階の設定が視覚的に理解できる
• IAM ポリシーのリソース ARN を手動で記述することで、権限スコープの意味が身につく
• Metric Filter の仕組みを GUI で設定することで、JSON フィルター構文の動作が理解できる

コンソール版と SAM 版を比較してみる

コンソールで API Gateway + Lambda + CloudWatch Logs の連携を理解したら、SAM で同じ構成をコードで定義することで「SAM が何を自動化しているか」が明確になります。IAM ポリシーの ARN 解決や Log Group の保持期間設定など、コンソールでの手動操作がコードに対応しています。

関連記事

Amazon検索[本 AWS 開発]

The post AWSコンソールでチャットボットログAPIを構築する手順【API Gateway + Lambda + CloudWatch Logs ハンズオン / SAM版との比較付き】 first appeared on CayTech Lab.

はじめに

「チャットボットのログ収集基盤をコードで管理して、同じ環境を何度でも再現したい」という要件に、AWS SAM（Serverless Application Model） は最適な選択肢のひとつです。

この記事では、AWS SAM を使って、API Gateway + Lambda + CloudWatch Logs によるチャットボットログAPIをゼロから構築するハンズオンを紹介します。

クライアント
  ↓ POST /logs（会話ログを送信）
API Gateway（REST API / Prod ステージ）
  ↓ Lambda プロキシ統合
Lambda（ChatLogFunction / Python 3.12）
  ↓ boto3 logs.put_log_events()           boto3 cloudwatch.put_metric_data()
CloudWatch Log Group                      CloudWatch カスタムメトリクス
（/chatbot/STACK_NAME）                   （ChatBot/STACK_NAME）
  ↓ Metric Filter（$.level = "error"）         ↑ 自動変換
CloudWatch ChatErrorCount メトリクス ─────────┘

このハンズオンで体験できること：

• AWS::Logs::LogGroup / AWS::Logs::MetricFilter の SAM 定義
• SAM 組み込みポリシーがない場合の Statement 直接記述による権限付与
• !Sub / !GetAtt / !Ref を使ったリソース間参照
• sam build + sam deploy の 2コマンドで全リソースをデプロイ

このハンズオンの特徴：

• API Gateway + Lambda × 1 + CloudWatch Log Group + Metric Filter + IAM ロールを template.yaml 1ファイルで管理
• sam delete で全リソースを一括削除（コンソール版では API Gateway / Lambda / Log Group / IAM を個別に削除）

Amazon検索[本 AWS 開発]

SAM vs コンソール：どれだけ違うか

キーワード解説

前提条件

AWS認証確認:

aws sts get-caller-identity

アカウントIDが表示されれば認証設定済みです。

使用するAWSサービス

Step 1: プロジェクトフォルダを開く

cd C:\my-aws\aws-learning-projects\chatbot-log-api

フォルダ構造

chatbot-log-api/
├── template.yaml       # SAMテンプレート（API Gateway + Lambda + CloudWatch）
├── samconfig.toml      # デプロイ設定（gitignore 対象・毎回手動作成が必要）
├── docs/
│   ├── 1_console.md    # AWSコンソール版手順
│   └── 2_sam.md        # SAM版手順
└── src/
    └── app.py          # Lambda 関数（POST /logs, GET /logs）

Step 2: SAMテンプレートの確認（template.yaml）

template.yaml は全 AWSリソースの設計図です。コンソール版との違いに注目しながらポイントを確認します。

Log Group と Metric Filter の定義

Resources:
  ChatLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub "/chatbot/${AWS::StackName}"
      RetentionInDays: 7

  # Metric Filter: error ログを ChatErrorCount メトリクスに自動変換
  ErrorMetricFilter:
    Type: AWS::Logs::MetricFilter
    Properties:
      LogGroupName: !Ref ChatLogGroup
      FilterPattern: '{ $.level = "error" }'
      MetricTransformations:
        - MetricName: ChatErrorCount
          MetricNamespace: !Sub "ChatBot/${AWS::StackName}"
          MetricValue: "1"
          DefaultValue: 0

AWS::Logs::LogGroup を明示定義する理由:
未定義のまま Lambda を実行すると、Lambda が自動でロググループを作成しますが保持期間が無期限になります。
SAM で明示的に定義することで RetentionInDays: 7 が確実に適用されます。

Lambda 関数の定義（IAMポリシーとAPIトリガー）

  ChatLogFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: app.lambda_handler
      Runtime: python3.12
      Timeout: 10
      Environment:
        Variables:
          LOG_GROUP_NAME: !Ref ChatLogGroup  # "/chatbot/スタック名"
      Policies:
        - Statement:
            # カスタムロググループへの書き込み・読み取り（スコープを特定グループに限定）
            - Action: [logs:CreateLogStream, logs:PutLogEvents, logs:GetLogEvents, logs:DescribeLogStreams]
              Effect: Allow
              Resource: [!GetAtt ChatLogGroup.Arn, !Sub "${ChatLogGroup.Arn}:*"]
            # カスタムメトリクスの書き込み
            - Action: cloudwatch:PutMetricData
              Effect: Allow
              Resource: "*"
      Events:
        PostLog:
          Type: Api
          Properties:
            Path: /logs
            Method: post
        GetLogs:
          Type: Api
          Properties:
            Path: /logs
            Method: get

template.yaml のポイント:

Step 3: Lambda コードの確認（src/app.py）

コードはすでに作成済みです。各関数の役割とポイントを確認しておきます。

LOG_GROUP_NAME = os.environ["LOG_GROUP_NAME"]           # "/chatbot/スタック名"
METRIC_NAMESPACE = "ChatBot/" + LOG_GROUP_NAME.split("/")[-1]  # "ChatBot/スタック名"

def post_log(event):
    # リクエストボディを解析
    body = json.loads(event.get("body") or "{}")
    session_id = body.get("session_id") or str(uuid.uuid4())

    # セッション単位のログストリームに書き込む
    log_stream_name = f"session/{session_id}"
    _ensure_log_stream(log_stream_name)       # ストリームを作成（既存なら無視）
    logs_client.put_log_events(...)           # ログを書き込む

    # カスタムメトリクスを記録
    cloudwatch.put_metric_data(
        Namespace=METRIC_NAMESPACE,
        MetricData=[{"MetricName": "MessageCount", "Dimensions": [...], "Value": 1}],
    )

def get_logs(event):
    # session_id でログストリームを指定して取得
    logs_client.get_log_events(logGroupName=..., logStreamName=f"session/{session_id}")

app.py のポイント:

• _ensure_log_stream(): create_log_stream() は既存ストリームに対して ResourceAlreadyExistsException を返します。botocore.exceptions.ClientError でキャッチして無視することで冪等性を確保します
• int(time.time() * 1000): CloudWatch Logs の timestamp はミリ秒単位の Unix 時間（整数）です
• startFromHead=False: 最新のログから取得します（デフォルトは古いものから）
• METRIC_NAMESPACE: 環境変数の LOG_GROUP_NAME からスタック名を抽出して名前空間に使います

Step 4: samconfig.toml を作成する

samconfig.toml は .gitignore で管理外のため、毎回手動で作成する必要があります。

chatbot-log-api/samconfig.toml を新規作成して以下を貼り付けます。

version = 0.1

[default.deploy.parameters]
stack_name = "chatbot-log-api-stack"
resolve_s3 = true
s3_prefix = "chatbot-log-api-stack"
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_IAM"
disable_rollback = true
image_repositories = []

[default.global.parameters]
region = "ap-northeast-1"

samconfig.toml の置き場所:
chatbot-log-api/ フォルダの直下に置く必要があります。

Step 5: sam build（ビルド）

cd C:\my-aws\aws-learning-projects\chatbot-log-api
sam build

成功すると以下のように表示されます。

Build Succeeded

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

sam build が行っていること:
src/ フォルダを ZIP パッケージ化して .aws-sam/build/ に配置し、Lambda デプロイの準備を整えます。

Step 6: sam deploy（デプロイ）

sam deploy

変更内容が表示されて確認を求められます。

Deploy this changeset? [y/N]: y

y を入力して進めます。数分でデプロイが完了します。

デプロイ完了の確認

ターミナルに Outputs が表示されます。

Outputs
----------------------------------------------------------------------
Key    ApiUrl
Value  https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod

Key    LogGroupName
Value  /chatbot/chatbot-log-api-stack

Key    MetricNamespace
Value  ChatBot/chatbot-log-api-stack
----------------------------------------------------------------------

ApiUrl を控えておきます。

デプロイされるリソース一覧

API Gateway REST API × 1  : chatbot-log-api-stack
Lambda 関数 × 1           : chatbot-log-api-stack-ChatLogFunction-XXXX
CloudWatch Log Group × 1  : /chatbot/chatbot-log-api-stack
CloudWatch Metric Filter   : ChatErrorFilter（error ログ検出）
IAM ロール × 1            : Lambda 用
S3                         : SAM デプロイパッケージ

Step 7: 動作テスト

事前準備: API URL を変数に設定する

set API_URL=https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod

XXXXXXXXXX を Outputs の ApiUrl の値に置き換えてください。

テスト 1: ログを記録する（POST /logs）

curl -X POST "%API_URL%/logs" ^
  -H "Content-Type: application/json" ^
  -d "{\"session_id\": \"session-001\", \"user_id\": \"user001\", \"message\": \"今日の天気は？\", \"response\": \"東京は晴れです\", \"level\": \"info\"}"

期待するレスポンス:

{
  "session_id": "session-001",
  "log_stream": "session/session-001",
  "message": "ログを記録した"
}

テスト 2: エラーログを記録する（Metric Filter のテスト）

curl -X POST "%API_URL%/logs" ^
  -H "Content-Type: application/json" ^
  -d "{\"session_id\": \"session-001\", \"user_id\": \"user001\", \"message\": \"注文履歴を見せて\", \"response\": \"エラーが発生しました\", \"level\": \"error\"}"

level: "error" のログが CloudWatch Logs に書き込まれると、
Metric Filter が反応して ChatErrorCount メトリクスが +1 されます（数分後に反映）。

テスト 3: ログを取得する（GET /logs）

curl "%API_URL%/logs?session_id=session-001"

期待するレスポンス:

{
  "session_id": "session-001",
  "log_count": 2,
  "logs": [
    {
      "timestamp_ms": 1700000000000,
      "log": {
        "session_id": "session-001",
        "user_id": "user001",
        "message": "今日の天気は？",
        "response": "東京は晴れです",
        "level": "info"
      }
    },
    {
      "timestamp_ms": 1700000010000,
      "log": {
        "session_id": "session-001",
        "user_id": "user001",
        "message": "注文履歴を見せて",
        "response": "エラーが発生しました",
        "level": "error"
      }
    }
  ]
}

Step 8: AWSコンソールで確認（任意）

SAMでデプロイしたリソースはコンソールでも確認できます。

CloudWatch Logs でログを確認する

CloudWatch → ロググループ → /chatbot/chatbot-log-api-stack → ログストリーム

• session/session-001 ストリームに会話ログが JSON で記録されています

CloudWatch Logs Insights でクエリを実行する

CloudWatch → Logs Insights → ロググループに /chatbot/chatbot-log-api-stack を選択

時間範囲を「直近1時間」など幅のある範囲に設定してからクエリを実行します。

注意: 開始時刻と終了時刻が同じだとエラー Query's end date and time is either before the log groups creation time... が出ます。カレンダーアイコンで時間幅を確保してください。

エラーログだけを抽出するクエリ:

fields @timestamp, session_id, user_id, level, message
| filter level = "error"
| sort @timestamp desc
| limit 20

セッション別メッセージ数を集計するクエリ:

stats count(*) as message_count by session_id
| sort message_count desc

カスタムメトリクスを確認する

CloudWatch → メトリクス → すべてのメトリクス → カスタム名前空間 → ChatBot/chatbot-log-api-stack

Step 9: リソースの削除

課金を止めるために、ハンズオン完了後は必ずリソースを削除してください。

sam delete --stack-name chatbot-log-api-stack --region ap-northeast-1

Are you sure you want to delete the stack chatbot-log-api-stack? [y/N]: y
Are you sure you want to delete the folder chatbot-log-api-stack in S3? [y/N]: y

削除完了の確認:

aws cloudformation describe-stacks --stack-name chatbot-log-api-stack --region ap-northeast-1

Stack with id chatbot-log-api-stack does not exist が表示されれば削除完了。

削除されるリソース一覧（sam delete で自動削除）:

• API Gateway（REST API + Prod ステージ）
• Lambda 関数
• CloudWatch Log Group（/chatbot/chatbot-log-api-stack）— ログも含めて削除
• CloudWatch Metric Filter
• IAM ロール

手動削除が必要なリソース:

• Lambda 実行ログ（/aws/lambda/chatbot-log-api-stack-ChatLogFunction-xxxx）
  Lambda が初回実行時に自動作成するロググループで、CloudFormation の管理外のため sam delete では削除されません。
  CloudWatch → ログ管理 → 該当ロググループを選択 → アクション → 削除 で手動削除します。
• CloudWatch カスタムメトリクス（MessageCount、ChatErrorCount）は独立して管理されます。
  不要な場合は CloudWatch → メトリクス → アクション → 削除で個別に削除します（コストはかかりにくいため省略可）。

トラブルシューティング

まとめ

今回のハンズオンで実現したこと：

SAMのメリットを実感できたポイント

• !GetAtt ChatLogGroup.Arn により、IAM ポリシーの ARN をハードコードせず動的に解決できる
• RetentionInDays や Metric Filter をコードで管理することで、設定漏れ・設定ミスを防げる
• sam delete でコンソール版では手動削除が必要な複数リソースを1コマンドで削除できる

コンソール版と比較してみる

SAMが裏で何をやっているか、同じ構成をAWSコンソールのみで構築する手順をまとめました。コンソール版では IAM インラインポリシーの ARN を手動入力する必要がある仕組みや、Metric Filter の GUI 設定方法など、コンソールならではの操作を解説しています。

関連記事

Amazon検索[本 AWS 開発]

The post AWS SAM でチャットボットログAPIを構築しよう【API Gateway + Lambda + CloudWatch Logs ハンズオン / コンソール版との比較付き】 first appeared on CayTech Lab.

はじめに

「画像認識の仕組みをコードで管理して、いつでも同じ環境を再現できるようにしたい」という要件に、AWS SAM（Serverless Application Model） は最適な選択肢のひとつです。

この記事では、AWS SAM を使って、S3 + Lambda + Rekognition による画像認識パイプラインをゼロから構築するハンズオンを紹介します。

ユーザー
  ↓ aws s3 cp image.jpg s3://bucket/
S3 バケット（STACK-upload-ACCOUNT_ID）
  ↓ ObjectCreated イベント（自動）
Lambda（DetectFunction / Python 3.12）
  ↓ boto3 rekognition.detect_labels(S3Object={...})
Amazon Rekognition
  ↓ Labels: [{Name, Confidence}, ...]
Lambda
  ↓ print(json.dumps(result))
CloudWatch Logs

このハンズオンで体験できること：

• AWS::S3::Bucket / AWS::Serverless::Function の SAM 定義
• S3ReadPolicy / RekognitionDetectOnlyPolicy — SAM 組み込みポリシーによる1行での権限付与
• Events: Type: S3（ObjectCreated）— Lambda の S3 トリガーをコードで定義する方法
• コンソール版との権限設定の違いを体感

このハンズオンの特徴：

• sam build + sam deploy の 2コマンドで全リソースをデプロイ
• S3 バケット + Lambda + IAM ロールを template.yaml 1ファイルで管理
• sam delete で全リソースを一括削除（コンソール版では S3 / Lambda / IAM / ロググループを個別に削除）

Amazon検索[本 AWS 開発]

SAM vs コンソール：どれだけ違うか

キーワード解説

前提条件

AWS認証確認:

aws sts get-caller-identity

アカウントIDが表示されれば認証設定済みです。

使用するAWSサービス

Step 1: プロジェクトフォルダを開く

cd C:\my-aws\aws-learning-projects\rekognition-image-pipeline

フォルダ構造

rekognition-image-pipeline/
├── template.yaml       # SAMテンプレート（S3 + Lambda + Rekognition 定義）
├── samconfig.toml      # デプロイ設定（gitignore 対象・毎回手動作成が必要）
├── docs/
│   ├── 1_console.md    # AWSコンソール版手順
│   └── 2_sam.md        # SAM版手順
└── src/
    └── app.py          # Lambda 関数（detect_labels + ログ出力）

Step 2: SAMテンプレートの確認（template.yaml）

template.yaml は全 AWSリソースの設計図です。コンソール版との違いに注目しながらポイントを確認します。

Resources:
  UploadBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub "${AWS::StackName}-upload-${AWS::AccountId}"

  # Lambda 関数
  DetectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Policies:
        # SAM 組み込みポリシー: 特定バケットへの s3:GetObject を付与
        - S3ReadPolicy:
            BucketName: !Sub "${AWS::StackName}-upload-${AWS::AccountId}"
        # SAM 組み込みポリシー: DetectLabels / DetectFaces / DetectText などを付与
        - RekognitionDetectOnlyPolicy: {}
      Events:
        S3UploadEvent:
          Type: S3
          Properties:
            Bucket: !Ref UploadBucket
            Events: s3:ObjectCreated:*

template.yaml のポイント:

Step 3: Lambda コードの確認（src/app.py）

コードはすでに作成済みです。構造を把握しておきます。

import json
import urllib.parse
import boto3

rekognition = boto3.client("rekognition")   # Lambda 起動時に1回だけ初期化


def lambda_handler(event, context):
    for record in event["Records"]:
        bucket = record["s3"]["bucket"]["name"]
        key = urllib.parse.unquote_plus(record["s3"]["object"]["key"])  # 日本語対応

        response = rekognition.detect_labels(
            Image={"S3Object": {"Bucket": bucket, "Name": key}},
            MaxLabels=10,      # 最大10ラベル
            MinConfidence=70,  # 70%以上のラベルのみ返す
        )

        labels = [{"name": l["Name"], "confidence": round(l["Confidence"], 1)}
                  for l in response["Labels"]]

        print(json.dumps({"key": key, "label_count": len(labels), "labels": labels},
                         ensure_ascii=False))

    return {"processedCount": len(event["Records"])}

app.py のポイント:

• S3Object 参照: 画像データを Lambda のメモリに転送せず S3 の場所を Rekognition に渡す。メモリ効率が良い
• urllib.parse.unquote_plus(key): 日本語や空白を含むファイル名は S3 イベントで URL エンコードされる
• boto3.client("rekognition") をグローバルスコープに置く: Lambda のコールドスタート時に1回だけ初期化され、ウォームスタート時は再利用される（パフォーマンス向上）

Step 4: samconfig.toml を作成する

samconfig.toml は .gitignore で管理外のため、毎回手動で作成する必要があります。

rekognition-image-pipeline/samconfig.toml を新規作成して以下を貼り付けます。

version = 0.1

[default.deploy.parameters]
stack_name = "rekognition-image-pipeline-stack"
resolve_s3 = true
s3_prefix = "rekognition-image-pipeline-stack"
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_IAM"
disable_rollback = true
image_repositories = []

[default.global.parameters]
region = "ap-northeast-1"

samconfig.toml の置き場所：
rekognition-image-pipeline/ フォルダの直下に置く必要があります。

Step 5: sam build（ビルド）

cd C:\my-aws\aws-learning-projects\rekognition-image-pipeline
sam build

成功すると以下のように表示されます。

Build Succeeded

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

sam build が行っていること：
src/ フォルダを ZIP パッケージ化して .aws-sam/build/ に配置し、Lambda デプロイの準備を整えます。

Step 6: sam deploy（デプロイ）

sam deploy

変更内容が表示されて確認を求められます。

Deploy this changeset? [y/N]: y

y を入力して進めます。数分でデプロイが完了します。

デプロイ完了の確認

ターミナルに Outputs が表示されます。

Outputs
----------------------------------------------------------------------
Key    BucketName
Value  rekognition-image-pipeline-stack-upload-123456789012

Key    DetectFunctionArn
Value  arn:aws:lambda:ap-northeast-1:123456789012:function:rekognition-image-pipeline-stack-DetectFunction-XXXX
----------------------------------------------------------------------

BucketName を控えておきます。

デプロイされるリソース一覧

S3 バケット × 1        : rekognition-image-pipeline-stack-upload-ACCOUNT_ID
Lambda 関数 × 1        : rekognition-image-pipeline-stack-DetectFunction-XXXX
IAM ロール × 1         : Lambda 用（S3 GetObject + Rekognition DetectLabels 権限付き）
S3（SAM用）            : デプロイパッケージ
CloudWatch Logs        : Lambda 自動生成ログ

Step 7: 動作テスト

事前準備: バケット名を変数に設定する

set BUCKET=rekognition-image-pipeline-stack-upload-123456789012

123456789012 を自分のアカウントIDに置き換える（Outputs の値をそのままコピー）。

テスト1: 画像をアップロードしてラベルを確認する

任意の JPEG または PNG 画像（15MB 以下）を用意してアップロードする。

aws s3 cp "C:\Users\yourname\Pictures\dog.jpg" s3://%BUCKET%/ --region ap-northeast-1

アップロード直後（数秒以内）に Lambda が自動起動する。

CloudWatch Logs でラベル検出結果を確認:

aws logs tail /aws/lambda/rekognition-image-pipeline-stack-DetectFunction-XXXX --follow

期待するログ出力:

{"status": "start", "bucket": "rekognition-image-pipeline-stack-upload-...", "key": "dog.jpg"}
{
  "key": "dog.jpg",
  "label_count": 8,
  "labels": [
    {"name": "Dog", "confidence": 98.5},
    {"name": "Pet", "confidence": 98.5},
    {"name": "Animal", "confidence": 98.5},
    {"name": "Canine", "confidence": 98.5},
    {"name": "Mammal", "confidence": 97.2},
    {"name": "Golden Retriever", "confidence": 85.3},
    {"name": "Grass", "confidence": 76.1},
    {"name": "Outdoors", "confidence": 71.4}
  ]
}
{"processedCount": 1}

テスト2: 複数枚アップロードして無料枠を確認する

aws s3 cp "C:\Users\yourname\Pictures\cat.jpg"  s3://%BUCKET%/ --region ap-northeast-1
aws s3 cp "C:\Users\yourname\Pictures\city.jpg" s3://%BUCKET%/ --region ap-northeast-1

各ファイルのアップロードごとに Lambda が起動し、それぞれのラベル検出結果がログに記録される。

無料枠の管理：
AWS コンソール → Billing → 無料利用枠 → 「Amazon Rekognition」で当月の使用枚数を確認できます。

Step 8: AWSコンソールで確認（任意）

SAMでデプロイしたリソースはコンソールでも確認できます。

• S3: S3 → rekognition-image-pipeline-stack-upload-... → アップロードしたファイルを確認
• Lambda: Lambda → 関数 → DetectFunction-XXXX → 「設定」→「トリガー」で S3 トリガーを確認
• IAM: IAM → ロール → Lambda のロールに S3ReadPolicy / RekognitionDetectOnlyPolicy が適用されていることを確認
• CloudWatch Logs: Lambda → 「モニタリング」→「CloudWatch Logs を表示」でログ詳細を確認

Step 9: リソースの削除

課金を止めるために、ハンズオン完了後は必ず削除してください。

【注意】 S3 バケットにオブジェクトが残っていると sam delete が失敗します。
先にバケットを空にしてから実行してください。

rem Step 1: バケットを空にする
aws s3 rm s3://%BUCKET% --recursive --region ap-northeast-1

rem Step 2: スタック削除
sam delete --stack-name rekognition-image-pipeline-stack --region ap-northeast-1

Are you sure you want to delete the stack rekognition-image-pipeline-stack? [y/N]: y
Are you sure you want to delete the folder rekognition-image-pipeline-stack in S3? [y/N]: y

削除完了の確認:

aws cloudformation describe-stacks --stack-name rekognition-image-pipeline-stack --region ap-northeast-1

Stack with id rekognition-image-pipeline-stack does not exist が表示されれば削除完了。

削除されるリソース一覧:

• S3 バケット（事前に空にした場合）
• Lambda 関数
• IAM ロール
• CloudWatch Logs ロググループ

Rekognition はサービス自体（バケット・コレクション等）を作成しないため、削除作業は不要です。

トラブルシューティング

まとめ

今回のハンズオンで実現したこと：

SAMのメリットを実感できたポイント

• RekognitionDetectOnlyPolicy: {} と S3ReadPolicy により IAM 権限設定がワンライナーで完結
• S3 バケット名に !Sub "${AWS::StackName}-upload-${AWS::AccountId}" を使うことでグローバルユニークを自動保証
• sam delete で S3 / Lambda / IAM を一括削除。コンソール版のような個別削除が不要

コンソール版と比較してみる

SAMが裏で何をやっているか、同じ構成をAWSコンソールのみで構築する手順をまとめました。コンソール版では IAM の権限追加を S3 用・Rekognition 用と2回行う必要があるなど、SAMの組み込みポリシーがどれだけ手間を削減しているかが明確に分かります。

関連記事

Amazon検索[本 AWS 開発]

The post AWS SAM で画像認識パイプライン（S3 + Lambda + Rekognition）を構築しよう【コンソール版との比較付き】 first appeared on CayTech Lab.

はじめに

「S3に画像をアップロードしたら、自動で中身を分析してほしい」——そんな仕組みを、AWSコンソールのみでゼロから構築するハンズオンです。

Amazon Rekognition の DetectLabels API を使うと、画像に写っている物体・シーン・動物などを自動で検出できます。犬の写真をアップロードすれば「Dog（信頼度98%）」「Animal（97%）」といったラベルが返ってきます。

ユーザー
  ↓ JPEG / PNG をアップロード
S3 バケット（UploadBucket）
  ↓ ObjectCreated イベント（自動）
Lambda（DetectFunction）
  ↓ rekognition:DetectLabels（S3Object を指定）
Amazon Rekognition
  ↓ [{"name": "Dog", "confidence": 98.5}, ...] を返す
Lambda
  ↓ print（JSON）
CloudWatch Logs

このハンズオンで体験できること：

• S3 トリガー — S3 へのアップロードを契機に Lambda を自動起動する仕組み
• Rekognition DetectLabels — 画像内の物体・シーン・動物を検出してラベルと信頼度を返す API
• IAM 権限管理 — Lambda から S3・Rekognition を呼び出すために必要な権限の追加手順
• S3Object 参照 — 画像データを Lambda に転送せず S3 の場所を直接 Rekognition に渡す効率的な方法

この記事は SAM版ハンズオン の比較記事です。
コンソール操作で S3・Lambda・Rekognition の連携を視覚的に学び、SAM と何が違うのかを比較したい方向けです。

Amazon検索[本 AWS 開発]

キーワード解説

使用するAWSサービス

全体の作業順序

① S3 バケットを作成する
      ↓
② Lambda 関数を作成する（コード入力・タイムアウト設定）
      ↓
③ Lambda の実行ロールに権限を追加する
  （S3: GetObject / Rekognition: DetectLabels）
      ↓
④ Lambda に S3 トリガーを追加する
      ↓
⑤ 動作テスト（画像をアップロード → ログを確認）
      ↓
⑥ リソースの削除

① S3 バケットを作成する

AWSコンソール → S3 → 「バケットを作成」

「バケットを作成」をクリック。

控えておく情報:

• バケット名（削除時・IAMポリシー設定時に使用）

バケット名のグローバルユニークについて：
S3 のバケット名は全 AWS アカウントで一意である必要があります。my-rekognition-upload- に自分のアカウントIDや日付を追加すると重複を避けられます。

② Lambda 関数を作成する

AWSコンソール → Lambda → 「関数の作成」

「関数の作成」をクリック。

タイムアウトの設定

「設定」タブ → 「一般設定」→「編集」

「保存」をクリック。

タイムアウトを 30 秒にする理由：
Rekognition API の呼び出しには数秒かかることがあります。デフォルト（3秒）では Rekognition のレスポンスを待ちきれずタイムアウトするため、余裕を持って 30 秒に設定します。

コードの入力

「コード」タブ → lambda_function.py を開いて既存の内容を全て置き換える。

import json
import urllib.parse
import boto3

rekognition = boto3.client("rekognition")


def lambda_handler(event, context):
    for record in event["Records"]:
        bucket = record["s3"]["bucket"]["name"]
        key = urllib.parse.unquote_plus(record["s3"]["object"]["key"])

        print(json.dumps({"status": "start", "bucket": bucket, "key": key}))

        response = rekognition.detect_labels(
            Image={
                "S3Object": {
                    "Bucket": bucket,
                    "Name": key,
                }
            },
            MaxLabels=10,
            MinConfidence=70,
        )

        labels = [
            {
                "name": label["Name"],
                "confidence": round(label["Confidence"], 1),
            }
            for label in response["Labels"]
        ]

        result = {
            "bucket": bucket,
            "key": key,
            "label_count": len(labels),
            "labels": labels,
        }
        print(json.dumps(result, ensure_ascii=False))

    return {"processedCount": len(event["Records"])}

「Deploy」ボタンをクリックしてコードを保存する。

コードのポイント:

③ Lambda の実行ロールに権限を追加する

デフォルトの実行ロールは CloudWatch Logs への書き込みのみ。
S3 からの読み取りと Rekognition の呼び出し権限を追加する。

Lambda → DetectFunction → 「設定」タブ → 「アクセス権限」→ 実行ロール名のリンクをクリック

（例: DetectFunction-role-XXXX）→ IAM コンソールのロール画面が開く。

3-1. Rekognition 権限を追加する

「許可を追加」→「ポリシーをアタッチ」

検索ボックスに Rekognition と入力 → AmazonRekognitionReadOnlyAccess にチェック → 「許可を追加」。

AmazonRekognitionReadOnlyAccess に含まれる主な権限:

• rekognition:DetectLabels — ラベル検出（今回使用）
• rekognition:DetectFaces — 顔検出
• rekognition:DetectText — テキスト検出

3-2. S3 GetObject 権限を追加する

「許可を追加」→「インラインポリシーを作成」

「JSON」タブを選択して以下を入力する（my-rekognition-upload を ① のバケット名に変更）:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::my-rekognition-upload/*"
    }
  ]
}

「次へ」→ ポリシー名: S3ReadForRekognition → 「ポリシーを作成」。

なぜ S3 の権限が必要か:
Rekognition に S3Object を指定した場合、Rekognition が Lambda の IAM ロールを借りて
S3 からオブジェクトを取得します。Lambda ロールに s3:GetObject がないと 403 エラーになります。

SAM版では S3ReadPolicy（SAM 組み込みポリシー）が特定バケットのみに s3:GetObject を自動付与します。
コンソール版では手動でインラインポリシーを作成する必要があります。

④ Lambda に S3 トリガーを追加する

Lambda → DetectFunction → 「設定」タブ → 「トリガー」→「トリガーを追加」

「再帰呼び出し」の確認チェックボックスにチェック → 「追加」をクリック。

再帰呼び出しについて：
Lambda の実行結果を同じバケットに書き込む構成にすると、S3 イベントが再発火して無限ループになります。
今回は S3 への書き込みを行わないため問題ありません。

⑤ 動作テスト

テスト用画像の準備

任意の JPEG または PNG 画像を用意する（例: 犬・猫・風景など）。
ファイルサイズは 15MB 以下 であることを確認する。

画像をアップロードする

方法 A: S3 コンソール

S3 → my-rekognition-upload → 「アップロード」→ ファイルをドラッグ＆ドロップ → 「アップロード」

方法 B: AWS CLI

aws s3 cp "C:\Users\yourname\Pictures\dog.jpg" s3://my-rekognition-upload/ --region ap-northeast-1

CloudWatch Logs でラベル検出結果を確認する

Lambda → DetectFunction → 「モニタリング」タブ → 「CloudWatch Logs を表示」

最新のロットストリームを開いて以下のような出力を確認する。

{"status": "start", "bucket": "my-rekognition-upload", "key": "dog.jpg"}
{
  "bucket": "my-rekognition-upload",
  "key": "dog.jpg",
  "label_count": 8,
  "labels": [
    {"name": "Dog", "confidence": 98.5},
    {"name": "Pet", "confidence": 98.5},
    {"name": "Animal", "confidence": 98.5},
    {"name": "Canine", "confidence": 98.5},
    {"name": "Mammal", "confidence": 97.2},
    {"name": "Golden Retriever", "confidence": 85.3},
    {"name": "Grass", "confidence": 76.1},
    {"name": "Outdoors", "confidence": 71.4}
  ]
}
{"processedCount": 1}

MinConfidence: 70 の効果：
信頼度 70% 未満のラベルは結果に含まれません。
全ラベルを確認したい場合は MinConfidence=0 に変更して「Deploy」する。

複数枚でテストする

aws s3 cp "C:\Users\yourname\Pictures\cat.jpg"  s3://my-rekognition-upload/ --region ap-northeast-1
aws s3 cp "C:\Users\yourname\Pictures\city.jpg" s3://my-rekognition-upload/ --region ap-northeast-1

各ファイルのアップロードごとに Lambda が起動し、それぞれのラベル検出結果がログに記録される。

無料枠の管理：
AWS コンソール → Billing → 無料利用枠 → 「Amazon Rekognition」で当月の使用枚数を確認できます。
月5,000枚まで無料のため、学習目的のハンズオンでは通常課金されません。

⑥ リソースの削除

課金を止めるために、ハンズオン完了後は必ず削除してください。

1. S3 バケットのオブジェクトを全て削除する

aws s3 rm s3://my-rekognition-upload --recursive --region ap-northeast-1

2. S3 バケットを削除する

S3 → my-rekognition-upload → 「削除」→ バケット名を入力 → 「削除」

3. Lambda のトリガーを削除する

Lambda → DetectFunction → 「設定」→「トリガー」→ S3 トリガーを選択 → 「削除」

4. Lambda 関数を削除する

Lambda → 関数 → DetectFunction → 「アクション」→「削除」

5. IAM ロールを削除する（任意）

IAM → ロール → DetectFunction-role-XXXX を削除

6. CloudWatch Logs のロググループを削除する（任意）

CloudWatch → ロググループ → /aws/lambda/DetectFunction → 削除

SAM版との大きな違い（SAMのメリット）：
SAM版では sam delete 1コマンドで上記すべてのリソースを一括削除できます。

SAMとの対比

コンソール版のつまずきポイント：
AccessDeniedException が出た場合、S3 の GetObject 権限（インラインポリシー）と Rekognition の DetectLabels 権限（AmazonRekognitionReadOnlyAccess）の両方が揃っているか確認しましょう。どちらか一方が欠けていてもエラーになります。

トラブルシューティング

まとめ

今回のハンズオンで体験できたこと：

コンソール版で実感できたポイント

• S3 → Lambda → Rekognition という3つのサービスのデータの流れが視覚的に理解できる
• 実行ロールに必要な権限を1つずつ追加することで、IAM の仕組みが身につく
• リソースを個別に作成・削除することで、各サービスの独立性と依存関係が明確になる

コンソール版と SAM 版を比較してみる

コンソールで S3・Lambda・Rekognition の連携を理解したら、SAM で同じ構成をコードで定義することで「SAM が何を自動化しているか」が明確になります。S3ReadPolicy や RekognitionDetectOnlyPolicy による1行での権限付与など、コンソールでの手動操作がコードに対応しています。

関連記事

Amazon検索[本 AWS 開発]

The post AWSコンソールだけで画像認識パイプラインを構築する手順【S3 + Lambda + Rekognition / SAM版との比較付き】 first appeared on CayTech Lab.

はじめに

「通知システムをコードで管理して、チームで同じ環境を再現できるようにしたい」という要件に、AWS SAM（Serverless Application Model） は最適な選択肢のひとつです。

この記事では、AWS SAM を使って、SNS + SQS + Lambda によるPub/Sub通知システム（ファンアウトパターン）をゼロから構築するハンズオンを紹介します。

Publisher（aws sns publish）
  ↓ メッセージを1回発行するだけ
SNS Topic（sns-sqs-lambda-stack-topic）
  │
  ├─ サブスクリプション（フィルターなし）
  │    → LogQueue → LogFunction → CloudWatch Logs（全メッセージを記録）
  │
  └─ サブスクリプション（level=warning/critical のみ）
       → AlertQueue → AlertFunction → CloudWatch Logs（アラート処理）
                          ↓ 失敗（maxReceiveCount=3）
                        AlertDLQ

このハンズオンで体験できること：

• AWS::SNS::Topic / AWS::SQS::Queue / AWS::SNS::Subscription の SAM 定義
• AWS::SQS::QueuePolicy — コンソールでは自動追加されるが SAM では明示的な定義が必要な理由
• FilterPolicy で SNS フィルターポリシーを JSON 文字列で指定する方法
• SQSPollerPolicy による1行での SQS ポーリング権限付与

このハンズオンの特徴：

• sam build + sam deploy の 2コマンドで全リソースをデプロイ
• SNS Topic + SQS キュー × 3 + Lambda × 2 + IAM ロール × 2 を template.yaml 1ファイルで管理
• sam delete で全リソースを一括削除（コンソール版では SNS / SQS × 3 / Lambda × 2 / IAM / ロググループを個別に削除）

Amazon検索[本 AWS 開発]

SAM vs コンソール：どれだけ違うか

キーワード解説

前提条件

AWS認証確認:

aws sts get-caller-identity

アカウントIDが表示されれば認証設定済みです。

使用するAWSサービス

Step 1: プロジェクトフォルダを開く

cd C:\my-aws\aws-learning-projects\sns-sqs-lambda

フォルダ構造

sns-sqs-lambda/
├── template.yaml           # SAMテンプレート（SNS + SQS × 3 + Lambda × 2）
├── samconfig.toml          # デプロイ設定（gitignore 対象・毎回手動作成が必要）
├── docs/
│   ├── 1_console.md        # AWSコンソール版手順
│   └── 2_sam.md            # SAM版手順
└── src/
    ├── log_handler.py      # 全ログ処理 Lambda（LogQueue 用）
    └── alert_handler.py    # アラート処理 Lambda（AlertQueue 用・DLQ テスト機能付き）

Step 2: SAMテンプレートの確認（template.yaml）

template.yaml は全 AWSリソースの設計図です。コンソール版との違いに注目しながらポイントを確認します。

SNS Topic とキューの定義

Resources:
  NotificationTopic:
    Type: AWS::SNS::Topic          # メッセージの発行点

  LogQueue:
    Type: AWS::SQS::Queue
    Properties:
      VisibilityTimeout: 180       # 可視性タイムアウト（DLQテストで 180秒×3回 待つ）

  AlertDLQ:
    Type: AWS::SQS::Queue          # AlertFunction が 3回失敗したメッセージの退避先

  AlertQueue:
    Type: AWS::SQS::Queue
    Properties:
      VisibilityTimeout: 180
      RedrivePolicy:
        deadLetterTargetArn: !GetAtt AlertDLQ.Arn
        maxReceiveCount: 3         # 3回失敗で DLQ へ

SQS キューポリシー（SNS からの受信許可）

SAM版で最も注意が必要なポイントです。コンソールでは SNS サブスクリプション作成時に自動追加されますが、CloudFormation/SAM では明示的な定義が必要です。

  LogQueuePolicy:
    Type: AWS::SQS::QueuePolicy    # SNS が LogQueue に送信することを許可
    Properties:
      Queues:
        - !Ref LogQueue
      PolicyDocument:
        Statement:
          - Effect: Allow
            Principal:
              Service: sns.amazonaws.com
            Action: sqs:SendMessage
            Resource: !GetAtt LogQueue.Arn
            Condition:
              ArnEquals:
                aws:SourceArn: !Ref NotificationTopic   # この Topic からのみ許可

  AlertQueuePolicy:
    Type: AWS::SQS::QueuePolicy    # SNS が AlertQueue に送信することを許可
    Properties:
      Queues:
        - !Ref AlertQueue
      PolicyDocument:
        Statement:
          - Effect: Allow
            Principal:
              Service: sns.amazonaws.com
            Action: sqs:SendMessage
            Resource: !GetAtt AlertQueue.Arn
            Condition:
              ArnEquals:
                aws:SourceArn: !Ref NotificationTopic

Condition: ArnEquals を付ける理由：
この条件がないと、同じ AWS アカウント内の他の SNS Topicからも SQS にメッセージを送れてしまいます。セキュリティのベストプラクティスとして、特定の Topic からのみ許可するよう制限します。

SNS サブスクリプション（ファンアウトとフィルター）

  LogQueueSubscription:
    Type: AWS::SNS::Subscription
    Properties:
      Protocol: sqs
      TopicArn: !Ref NotificationTopic
      Endpoint: !GetAtt LogQueue.Arn
      # FilterPolicy なし → 全メッセージが届く

  # フィルターあり: level=warning/critical のみ AlertQueue に配信
  AlertQueueSubscription:
    Type: AWS::SNS::Subscription
    Properties:
      Protocol: sqs
      TopicArn: !Ref NotificationTopic
      Endpoint: !GetAtt AlertQueue.Arn
      FilterPolicy: '{"level": ["warning", "critical"]}'
      FilterPolicyScope: MessageAttributes   # メッセージ属性でフィルター（デフォルト）

FilterPolicy は JSON 文字列として指定：
YAML 内では '{"level": ["warning", "critical"]}' のようにシングルクォートで囲んだ JSON 文字列として記述します。オブジェクト形式ではないことに注意してください。

Lambda 関数の定義

  LogFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: log_handler.lambda_handler
      Runtime: python3.12
      Timeout: 30
      Policies:
        - SQSPollerPolicy:               # ReceiveMessage / DeleteMessage を自動付与
            QueueName: !GetAtt LogQueue.QueueName
      Events:
        LogQueueEvent:
          Type: SQS
          Properties:
            Queue: !GetAtt LogQueue.Arn
            BatchSize: 5                 # 1回の呼び出しで最大5件処理

  AlertFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: alert_handler.lambda_handler
      Runtime: python3.12
      Timeout: 30
      Policies:
        - SQSPollerPolicy:
            QueueName: !GetAtt AlertQueue.QueueName
      Events:
        AlertQueueEvent:
          Type: SQS
          Properties:
            Queue: !GetAtt AlertQueue.Arn
            BatchSize: 1    # 1件失敗しても他のメッセージに影響しないよう 1 に設定

template.yaml のポイント:

Step 3: Lambda コードの確認（src/）

コードはすでに作成済みです。各ファイルの役割を確認しておきます。

log_handler.py のポイント

for record in event["Records"]:
    # SNS → SQS 配信では、SQS のボディに SNS エンベロープ（JSON文字列）が格納される
    sns_envelope = json.loads(record["body"])   # ← json.loads が必要
    message = sns_envelope["Message"]           # 実際のメッセージ本文
    attributes = sns_envelope.get("MessageAttributes", {})
    level = attributes.get("level", {}).get("Value", "info")

SNS エンベロープの構造（SQS に届く body の中身）：

{
  "Type": "Notification",
  "MessageId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "TopicArn": "arn:aws:sns:ap-northeast-1:...:topic",
  "Message": "警告メッセージ",
  "MessageAttributes": {
    "level": {"Type": "String", "Value": "warning"}
  }
}

SQS を直接使う場合（record["body"] がそのまま文字列）とは構造が異なります。
SNS 経由の場合は必ず json.loads してエンベロープを展開してください。

alert_handler.py のポイント

• message == "error" の場合は意図的に ValueError を発生させる（DLQ テスト用）
• BatchSize: 1 のため、1件失敗すると AlertQueue に戻り、3回試行後 AlertDLQ へ移動する

Step 4: samconfig.toml を作成する

samconfig.toml は .gitignore で管理外のため、毎回手動で作成する必要があります。

sns-sqs-lambda/samconfig.toml を新規作成して以下を貼り付けます。

version = 0.1

[default.deploy.parameters]
stack_name = "sns-sqs-lambda-stack"
resolve_s3 = true
s3_prefix = "sns-sqs-lambda-stack"
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_IAM"
disable_rollback = true
image_repositories = []

[default.global.parameters]
region = "ap-northeast-1"

samconfig.toml の置き場所：
sns-sqs-lambda/ フォルダの直下に置く必要があります。

Step 5: sam build（ビルド）

cd C:\my-aws\aws-learning-projects\sns-sqs-lambda
sam build

成功すると以下のように表示されます。

Build Succeeded

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

sam build が行っていること：
src/ フォルダを ZIP パッケージ化して .aws-sam/build/ に配置し、Lambda デプロイの準備を整えます。

Step 6: sam deploy（デプロイ）

sam deploy

変更内容が表示されて確認を求められます。

Deploy this changeset? [y/N]: y

y を入力して進めます。数分でデプロイが完了します。

デプロイ完了の確認

ターミナルに Outputs が表示されます。

Outputs
----------------------------------------------------------------------
Key    TopicArn
Value  arn:aws:sns:ap-northeast-1:123456789012:sns-sqs-lambda-stack-topic

Key    LogQueueUrl
Value  https://sqs.ap-northeast-1.amazonaws.com/123456789012/sns-sqs-lambda-stack-log-queue

Key    AlertQueueUrl
Value  https://sqs.ap-northeast-1.amazonaws.com/123456789012/sns-sqs-lambda-stack-alert-queue

Key    AlertDLQUrl
Value  https://sqs.ap-northeast-1.amazonaws.com/123456789012/sns-sqs-lambda-stack-alert-dlq
----------------------------------------------------------------------

TopicArn を控えておきます。

デプロイされるリソース一覧

SNS Topic × 1          : sns-sqs-lambda-stack-topic
SNS サブスクリプション × 2  : LogQueue用（フィルターなし）/ AlertQueue用（フィルターあり）
SQS キュー × 3          : LogQueue / AlertQueue / AlertDLQ
Lambda 関数 × 2        : sns-sqs-lambda-stack-LogFunction-XXXX 他
IAM ロール × 2          : Lambda 用
S3                     : SAM デプロイパッケージ
CloudWatch Logs        : Lambda 自動生成ログ × 2

Step 7: 動作テスト

事前準備: ARN を変数に設定する

set TOPIC_ARN=arn:aws:sns:ap-northeast-1:123456789012:sns-sqs-lambda-stack-topic
set ALERT_DLQ_URL=https://sqs.ap-northeast-1.amazonaws.com/123456789012/sns-sqs-lambda-stack-alert-dlq

123456789012 を自分のアカウントIDに置き換えてください（Outputs の値をそのままコピーすればよいです）。

テスト1: level=info（LogFunction のみ受信）

aws sns publish ^
  --topic-arn %TOPIC_ARN% ^
  --message "情報メッセージ" ^
  --message-attributes "{\"level\":{\"DataType\":\"String\",\"StringValue\":\"info\"}}" ^
  --region ap-northeast-1

レスポンス例:

{
    "MessageId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

CloudWatch Logs で LogFunction を確認（数秒後）:

aws logs tail /aws/lambda/sns-sqs-lambda-stack-LogFunction-XXXX --follow

{"queue": "log", "level": "info", "message": "情報メッセージ"}
{"processedCount": 1}

AlertFunction は動作しないことを確認:

Lambda コンソールで AlertFunction の呼び出し回数が増えていないことを確認します。

テスト2: level=warning（ファンアウト確認）

aws sns publish ^
  --topic-arn %TOPIC_ARN% ^
  --message "警告メッセージ" ^
  --message-attributes "{\"level\":{\"DataType\":\"String\",\"StringValue\":\"warning\"}}" ^
  --region ap-northeast-1

期待する動作: 1回の publish で LogFunction と AlertFunction の両方が動作する（ファンアウト）

LogFunction のログ:

{"queue": "log", "level": "warning", "message": "警告メッセージ"}

AlertFunction のログ:

{"queue": "alert", "level": "warning", "message": "警告メッセージ", "alert_triggered": true}

テスト3: level=warning + body=error（DLQ テスト）

aws sns publish ^
  --topic-arn %TOPIC_ARN% ^
  --message "error" ^
  --message-attributes "{\"level\":{\"DataType\":\"String\",\"StringValue\":\"warning\"}}" ^
  --region ap-northeast-1

期待する動作:

• LogFunction → 正常完了
• AlertFunction → ValueError で失敗 → 180秒後に再試行 × 3回 → AlertDLQ に移動

DLQ に移動するまでの待機時間: 最大 180秒 × 3回 ≒ 9分。
CloudWatch Logs で AlertFunction に [ERROR] ValueError が 3回記録されたことを確認してから DLQ を確認するとよいです。

DLQ にメッセージが届いたか確認:

aws sqs receive-message ^
  --queue-url %ALERT_DLQ_URL% ^
  --region ap-northeast-1

レスポンスの "Body" フィールドに SNS エンベロープが格納されていれば DLQ 動作確認完了。

Step 8: AWSコンソールで確認（任意）

SAMでデプロイしたリソースはコンソールでも確認できます。

• SNS: SNS → sns-sqs-lambda-stack-topic → 「サブスクリプション」タブ → 2つのサブスクリプションと各フィルターポリシーを確認
• SQS: SQS → sns-sqs-lambda-stack-alert-queue → 「デッドレターキュー」タブ → AlertDLQ の ARN が設定されていることを確認
• Lambda: CloudWatch Logs で LogFunction / AlertFunction の呼び出し履歴を比較確認

Step 9: リソースの削除

課金を止めるために、ハンズオン完了後は必ずリソースを削除してください。

sam delete --stack-name sns-sqs-lambda-stack --region ap-northeast-1

Are you sure you want to delete the stack sns-sqs-lambda-stack? [y/N]: y
Are you sure you want to delete the folder sns-sqs-lambda-stack in S3? [y/N]: y

削除完了の確認:

aws cloudformation describe-stacks --stack-name sns-sqs-lambda-stack --region ap-northeast-1

Stack with id sns-sqs-lambda-stack does not exist が表示されれば削除完了。

sam delete で削除されるリソース一覧

コンソール版との大きな違い（SAMのメリット）：
コンソール版では SNS / SQS × 3 / Lambda × 2 / IAM / ロググループを個別に削除する必要があります。
SAMでは sam delete 1コマンドで全リソースを一括削除できます。

トラブルシューティング

まとめ

今回のハンズオンで実現したこと：

SAMのメリットを実感できたポイント

• SQSPollerPolicy により Lambda の SQS ポーリング権限が1行で完結
• FilterPolicy で SNS フィルターポリシーをコードとして管理
• sam delete で SNS / SQS × 3 / Lambda × 2 / IAM を一括削除

コンソール版と比較してみる

SAMが裏で何をやっているか、同じ構成をAWSコンソールのみで構築する手順をまとめました。コンソール版では SNS サブスクリプション作成時にキューポリシーが自動追加される仕組みや、フィルターポリシーの GUI 入力方法など、コンソールならではの操作を解説しています。

関連記事

Amazon検索[本 AWS 開発]

The post AWS SAM で SNS + SQS + Lambda 通知システムを構築しよう【Pub/Sub・ファンアウト・DLQ / コンソール版との比較付き】 first appeared on CayTech Lab.

はじめに

「1回メッセージを送るだけで、複数のシステムに同時に通知したい」——そんな要件を実現する設計パターンが Pub/Sub（パブリッシュ・サブスクライブ） と ファンアウト です。

この記事では、AWSコンソールのみを使って、SNS + SQS + Lambda による通知システムをゼロから構築するハンズオンを紹介します。

Publisher（aws sns publish）
  ↓ メッセージを1回発行するだけ
SNS Topic（NotificationTopic）
  │
  ├─ サブスクリプション（フィルターなし）
  │    → LogQueue → LogFunction → CloudWatch Logs（全メッセージを記録）
  │
  └─ サブスクリプション（level=warning/critical のみ）
       → AlertQueue → AlertFunction → CloudWatch Logs（アラート処理）
                          ↓ 処理失敗（3回）
                        AlertDLQ

このハンズオンで体験できること：

• Pub/Sub パターン — Publisher と Subscriber が疎結合で通信する仕組み
• ファンアウト — 1回の publish で複数の Lambda が並行して動作する体験
• SNS フィルターポリシー — メッセージ属性で配信先を絞り込む設定
• DLQ（デッドレターキュー） — 処理失敗メッセージの退避先を実際に確認

この記事は SAM版ハンズオン の比較記事です。
コンソール操作で SNS・SQS・Lambda の連携を視覚的に学び、SAM と何が違うのかを比較したい方向けです。

Amazon検索[本 AWS 開発]

キーワード解説

使用するAWSサービス

全体の作業順序

① SNS Topic を作成する
      ↓
② SQS キューを3つ作成する（AlertDLQ / LogQueue / AlertQueue）
      ↓
③ SNS → SQS サブスクリプションを2つ作成する
  （LogQueue: フィルターなし / AlertQueue: フィルターあり）
      ↓
④ Lambda 関数を2つ作成する
      ↓
⑤ SQS トリガーを各 Lambda に追加する
      ↓
⑥ 動作テスト（3パターン）
      ↓
⑦ リソースの削除

AlertDLQ を先に作成する理由：
AlertQueue の作成時に DLQ として AlertDLQ の ARN を指定するため、AlertDLQ を先に作る必要があります。

① SNS Topic を作成する

AWSコンソール → SNS → 「トピック」→「トピックを作成」

その他の設定はデフォルトのまま。「トピックを作成」をクリック。

控えておく情報:

• トピック ARN（例: arn:aws:sns:ap-northeast-1:123456789012:NotificationTopic）

スタンダードとFIFOの違い：
スタンダードは順序保証なし・高スループット。FIFO は順序保証あり・1回限りの配信が必要な場合に使用します。今回のログ/アラート通知にはスタンダードが適しています。

② SQS キューを3つ作成する

AWSコンソール → SQS → 「キューを作成」

2-1. AlertDLQ（デッドレターキュー）を先に作成する

「キューを作成」をクリック。

控えておく情報:

• AlertDLQ の ARN（例: arn:aws:sqs:ap-northeast-1:123456789012:AlertDLQ）

2-2. LogQueue を作成する（フィルターなし・全メッセージ用）

「キューを作成」をクリック。

可視性タイムアウトを 180 秒にする理由：
Lambda のデフォルトタイムアウト（3秒）より長く設定することで、処理中に他のコンシューマーがメッセージを二重取得するのを防ぎます。DLQ テストでは 180秒 × 3回 ≒ 9分待つことになります。

2-3. AlertQueue を作成する（フィルターあり・アラート用）

「デッドレターキュー」セクション:

「キューを作成」をクリック。

控えておく情報:

• LogQueue の ARN
• AlertQueue の ARN

③ SNS → SQS サブスクリプションを2つ作成する

SQS キューポリシーの自動追加について：
コンソールで SNS → SQS サブスクリプションを作成すると、
SNS が SQS キューのアクセスポリシーに sns.amazonaws.com からの sqs:SendMessage 権限を自動追加します。
手動でのポリシー設定は不要です（SAM版では AWS::SQS::QueuePolicy を明示的に定義する必要があります）。

3-1. LogQueue サブスクリプション（フィルターなし）

SNS → NotificationTopic → 「サブスクリプション」タブ → 「サブスクリプションを作成」

「サブスクリプションを作成」をクリック。

3-2. AlertQueue サブスクリプション（フィルターあり）

SNS → NotificationTopic → 「サブスクリプション」タブ → 「サブスクリプションを作成」

「サブスクリプションフィルターポリシー」セクション:

{
  "level": ["warning", "critical"]
}

フィルターポリシーの意味：
level メッセージ属性の値が "warning" または "critical" のメッセージのみ AlertQueue に配信します。
level=info のメッセージは AlertQueue に届かない（LogQueue には届く）。

よくある間違い（フィルターが動作しない場合）：

• スコープが「メッセージ本文」になっている → **「メッセージ属性」**に変更する
• JSON のスペルミス（"warning" のクォートが抜けている等）

「サブスクリプションを作成」をクリック。

④ Lambda 関数を2つ作成する

AWSコンソール → Lambda → 「関数の作成」（共通設定）

コードを貼り付けたあと、必ず 「Deploy」 ボタンを押してコードを保存します。

4-1. LogFunction（全ログ処理）

関数名: LogFunction

コードエディタで lambda_function.py を開き、以下を貼り付けて「Deploy」をクリック。

import json


def lambda_handler(event, context):
    results = []

    for record in event["Records"]:
        sns_envelope = json.loads(record["body"])
        message = sns_envelope["Message"]  # 実際のメッセージ本文
        attributes = sns_envelope.get("MessageAttributes", {})
        level = attributes.get("level", {}).get("Value", "info")

        result = {
            "queue": "log",
            "level": level,
            "message": message,
        }
        print(json.dumps(result, ensure_ascii=False))
        results.append(result)

    print(json.dumps({"processedCount": len(results)}, ensure_ascii=False))
    return {"processedCount": len(results)}

json.loads(record["body"]) が必要な理由：
SNS → SQS 配信では、SQS のメッセージボディに SNS エンベロープ（JSON文字列）が格納されます。
そのため record["body"] はそのまま使えず、json.loads でパースする必要があります。

{
  "Type": "Notification",
  "TopicArn": "arn:aws:sns:...:NotificationTopic",
  "Message": "警告メッセージ",
  "MessageAttributes": {
    "level": {"Type": "String", "Value": "warning"}
  }
}

4-2. AlertFunction（アラート処理・DLQ テスト機能付き）

関数名: AlertFunction

import json


def lambda_handler(event, context):
    results = []

    for record in event["Records"]:
        sns_envelope = json.loads(record["body"])
        message = sns_envelope["Message"]
        attributes = sns_envelope.get("MessageAttributes", {})
        level = attributes.get("level", {}).get("Value", "unknown")

        # DLQテスト用: "error" というメッセージを受信したら意図的に例外発生
        if message.strip().lower() == "error":
            raise ValueError(
                f"アラート処理に失敗: level={level}, message={message}"
            )

        result = {
            "queue": "alert",
            "level": level,
            "message": message,
            "alert_triggered": True,
        }
        print(json.dumps(result, ensure_ascii=False))
        results.append(result)

    print(json.dumps({"processedCount": len(results)}, ensure_ascii=False))
    return {"processedCount": len(results)}

DLQ テストのしくみ：
message == "error" のとき意図的に ValueError を発生させています。
SQS は処理失敗を検知してメッセージをキューに戻し、可視性タイムアウト（180秒）後に再試行します。
これを3回繰り返すと AlertDLQ に移動します。

⑤ SQS トリガーを各 Lambda に追加する

5-1. LogFunction に LogQueue トリガーを追加する

Lambda → LogFunction → 「設定」タブ → 「トリガー」→「トリガーを追加」

「追加」をクリック。

権限の追加:

Lambda → LogFunction → 「設定」タブ → 「アクセス権限」→ 実行ロール名をクリック（IAM コンソールへ）
→「許可を追加」→「ポリシーをアタッチ」→ AWSLambdaSQSQueueExecutionRole をアタッチ。

AWSLambdaSQSQueueExecutionRole が必要な理由：
Lambda が SQS からメッセージを受信（sqs:ReceiveMessage）・削除（sqs:DeleteMessage）するために必要な権限がまとまったポリシーです。これがないと Lambda がメッセージを取得できません。

5-2. AlertFunction に AlertQueue トリガーを追加する

Lambda → AlertFunction → 「設定」タブ → 「トリガー」→「トリガーを追加」

「追加」をクリック。権限の追加（AWSLambdaSQSQueueExecutionRole）も同様に実施する。

AlertFunction のバッチサイズを 1 にする理由：
1件ずつ処理することで、1件が失敗しても他のメッセージに影響が出ません。
DLQ へ移動するメッセージを1件に限定できるため、テストが分かりやすくなります。

⑥ 動作テスト

3つのシナリオで SNS フィルター・ファンアウト・DLQ の動作を確認します。

テスト1: level=info（LogFunction のみ受信）

aws sns publish ^
  --topic-arn arn:aws:sns:ap-northeast-1:123456789012:NotificationTopic ^
  --message "情報メッセージ" ^
  --message-attributes "{\"level\":{\"DataType\":\"String\",\"StringValue\":\"info\"}}" ^
  --region ap-northeast-1

123456789012 を自分のアカウントIDに置き換えてください。

期待する動作:

• LogFunction が処理 → CloudWatch Logs にログが記録される
• AlertFunction は動作しない（フィルターで除外）

CloudWatch Logs で確認:

Lambda → LogFunction → 「モニタリング」タブ → 「CloudWatch Logs を表示」

{"queue": "log", "level": "info", "message": "情報メッセージ"}
{"processedCount": 1}

テスト2: level=warning（両 Lambda が受信 ＝ ファンアウト）

aws sns publish ^
  --topic-arn arn:aws:sns:ap-northeast-1:123456789012:NotificationTopic ^
  --message "警告メッセージ" ^
  --message-attributes "{\"level\":{\"DataType\":\"String\",\"StringValue\":\"warning\"}}" ^
  --region ap-northeast-1

期待する動作:

• LogFunction が処理（level=warning を受信）
• AlertFunction も処理（フィルターを通過）
• 1回の publish で 2つの Lambda が並行して動作する ← ファンアウトのポイント

LogFunction のログ:

{"queue": "log", "level": "warning", "message": "警告メッセージ"}

AlertFunction のログ:

{"queue": "alert", "level": "warning", "message": "警告メッセージ", "alert_triggered": true}

テスト3: level=warning + body=error（AlertFunction 失敗 → DLQ）

aws sns publish ^
  --topic-arn arn:aws:sns:ap-northeast-1:123456789012:NotificationTopic ^
  --message "error" ^
  --message-attributes "{\"level\":{\"DataType\":\"String\",\"StringValue\":\"warning\"}}" ^
  --region ap-northeast-1

期待する動作:

• LogFunction → 正常処理（message=error でも例外なし）
• AlertFunction → ValueError 発生
• AlertQueue の可視性タイムアウト（180秒）後に再試行 × 3回 → AlertDLQ に移動

DLQ に移動するまでの待機時間: 最大 180秒 × 3回 ≒ 9分かかります。
CloudWatch Logs で AlertFunction に [ERROR] ValueError が 3回記録されたことを確認してから DLQ をポーリングするとよいです。

DLQ にメッセージが届いたか確認:

SQS → AlertDLQ → 「メッセージを送受信」→「メッセージをポーリング」

"error" のメッセージ（SNS エンベロープ形式）が表示されれば DLQ 動作確認完了。

⑦ リソースの削除

課金を止めるために、ハンズオン完了後は必ず削除してください。

1. Lambda のトリガーを削除する

• Lambda → LogFunction → 「設定」→「トリガー」→ SQS トリガーを削除
• Lambda → AlertFunction → 同様に削除

2. Lambda 関数を削除する

• LogFunction / AlertFunction を削除

3. SNS サブスクリプションを削除する

SNS → NotificationTopic → 「サブスクリプション」タブ → 2つのサブスクリプションを削除

4. SNS Topic を削除する

SNS → トピック → NotificationTopic → 「削除」

5. SQS キューを3つ削除する

SQS → LogQueue / AlertQueue / AlertDLQ を各々削除

6. IAM ロールを削除する（任意）

IAM → ロール → LogFunction-role-XXXX / AlertFunction-role-XXXX を削除

7. CloudWatch Logs のロググループを削除する（任意）

CloudWatch → ロググループ → /aws/lambda/LogFunction / /aws/lambda/AlertFunction を削除

SAM版との大きな違い（SAMのメリット）：
SAM版では sam delete 1コマンドで上記すべてのリソースを一括削除できます。

SAMとの対比

コンソール版の最大のつまずきポイント：
SNS の「サブスクリプション」を作り忘れると、SNS publish しても SQS キューにメッセージが届きません。
「キューにメッセージが来ない」と感じたら、まずサブスクリプションが正しく作成されているか確認しましょう。

トラブルシューティング

まとめ

今回のハンズオンで体験できたこと：

コンソール版で実感できたポイント

• SNS Topic / SQS キュー / Lambda という3つのリソースの組み合わせ方が視覚的に理解できる
• SNS サブスクリプションのフィルターポリシーJSON を直接入力することで、ルールの書き方が身につく
• リソースを1つずつ作成することで、各サービスの役割と依存関係が明確になる

コンソール版と SAM 版を比較してみる

コンソールで SNS + SQS + Lambda の連携を理解したら、SAM で同じ構成をコードで定義することで「SAM が何を自動化しているか」が明確になります。AWS::SQS::QueuePolicy の明示的な記述や SQSPollerPolicy によるワンライン権限付与など、コンソールでの手動操作がコードに対応しています。

関連記事

Amazon検索[本 AWS 開発]

The post AWSコンソールだけでSNS + SQS + Lambda 通知システムを構築する手順【Pub/Sub・ファンアウト・DLQ / SAM版との比較付き】 first appeared on CayTech Lab.

はじめに

「ログインしたユーザーだけが使えるAPIを作りたい」——そんな要件を、Amazon Cognito + API Gateway + Lambda はサーバー側の認証コードをほぼ書かずに実現します。

この記事では、AWSコンソールのみを使って、以下の構成の認証付き REST API をゼロから構築するハンズオンを紹介します。

クライアント（curl）
  │
  ├─ GET /hello  → 認証不要 → Lambda → 200 OK
  │
  └─ GET /profile
        ├─ Authorizationヘッダーなし → API Gateway が 401 を返す（Lambda は呼ばれない）
        └─ Authorization: <IDトークン>
              → Cognito Authorizer が JWT を検証（Lambda 不要）
              → Lambda → email / sub を返す → 200 OK

このハンズオンで体験できること：

• Amazon Cognito User Pool によるユーザー管理と JWT 発行
• API Gateway の Cognito Authorizer を使ったエンドポイントごとの認証制御
• Lambda 側で認証コードを書かずに claims（ユーザー情報）を取得するパターン
• 新UI対応 — Cognito コンソールの大幅変更点と、操作でハマりやすいポイント

この記事は SAM版ハンズオン の比較記事です。
コンソール操作でCognitoとAPI Gatewayの連携を視覚的に学び、SAMと何が違うのかを比較したい方向けです。

Amazon検索[本 AWS 開発]

Cognito 新UIで戸惑いやすいポイント（先読み）

操作を始める前に、2026年時点の新UIで戸惑いやすい変更点を把握しておきましょう。

最大のハマりポイント（クライアントシークレット）：
新UIの「アプリケーションを作成」で「従来のウェブアプリケーション」を選ぶと、クライアントシークレットが自動で付与されます。シークレットありのクライアントで initiate-auth を実行すると SECRET_HASH was not received エラーが出て詰まります。
このハンズオンでは②の手順でシークレットなしのクライアントを別途作成します。

キーワード解説

前提条件

AWS CLI がない場合は、テスト操作に AWSコンソールの CloudShell を代用できます（後述）。

使用するAWSサービス

全体の作業順序

① Cognito User Pool を作成する（新UI対応）
      ↓
② テスト用アプリクライアントを作成する（シークレットなし）
      ↓
③ Lambda 関数を作成する
      ↓
④ API Gateway REST API を作成する
  （/hello・/profile エンドポイント + Cognito Authorizer 設定）
      ↓
⑤ テストユーザーを作成する
      ↓
⑥ 動作テスト（401確認 → JWTトークン取得 → 認証成功）
      ↓
⑦ リソースの削除

① Cognito User Pool を作成する

AWSコンソール → Cognito → 「アプリケーションを作成」

新UIの注意：
旧UIにあった「ユーザープールを作成」ボタンは廃止されています。現在は「アプリケーションを作成」からウィザードで User Pool とクライアントをまとめて作成します。

1-1. アプリケーションを定義する

1-2. オプションを設定する

サインイン識別子は作成後に変更不可。 「メールアドレス」のみ選択しておくことを推奨します。

1-3. リターン URL（スキップ）

「リターン URL を追加」は入力不要（今回はマネージドログインページを使わないため）。

画面下部の「ユーザーディレクトリを作成する」をクリック。

控えておく情報

作成後、User Pool の概要ページが開きます。

• ユーザープール ID（例: ap-northeast-1_XXXXXXXX）
  → 概要ページの「ユーザープール情報」欄に表示
• クライアント ID（例: XXXXXXXXXXXXXXXXXXXXXXXXXX）
  → 左サイドバー「アプリケーション」→「アプリケーションクライアント」→ MyWebApp をクリック → 「クライアント ID」欄

注意： 概要ページの「レコメンデーション」欄にも MyWebApp のリンクが表示されますが、これは Quick Setup ガイドへの誘導です。クライアント ID は左サイドバーから辿ってください。

User Pool 名について：
新UIでは、アプリ名の前に User pool - が自動で付きます（例: User pool - MyWebApp）。以降の手順では「作成した User Pool」と表記します。

② テスト用アプリクライアントを作成する

新UIの「アプリケーションを作成」で自動作成された MyWebApp クライアントにはクライアントシークレットが自動付与されています。シークレットありのクライアントで CLI から initiate-auth を実行すると SECRET_HASH was not received エラーが出ます。

そのため、シークレットなし・ALLOW_USER_PASSWORD_AUTH 有効の新しいクライアントを別途作成します。

Cognito → 作成した User Pool → 左サイドバー「アプリケーション」→「アプリケーションクライアント」→「アプリケーションクライアントを作成」

2-1. アプリケーションを定義する

「SPA」を選ぶ理由：
新UIでは「従来のウェブアプリケーション」を選ぶとクライアントシークレットが必須になります。「SPA」を選ぶとシークレットなしで作成できます。CLI テスト目的ではこちらを使います。

2-2. リターン URL（スキップ）

入力不要。

2-3. Client secret configuration

SPA を選択した場合、この欄は表示されません（シークレットなしで自動確定）。

「アプリケーションクライアントを作成」をクリック。

2-4. 認証フローを確認する

作成後、MyWebAppClient をクリックして詳細画面を開きます。

「認証フロー」セクションに ALLOW_USER_PASSWORD_AUTH が含まれていることを確認します。

含まれていない場合は「編集」→「ALLOW_USER_PASSWORD_AUTH」にチェック → 「変更を保存」。

ALLOW_USER_PASSWORD_AUTH とは：
CLI から username と password を直接指定して認証する「ユーザーパスワード認証」フローです。テスト用に有効化します（本番環境では SRP フローが推奨）。

控えておく情報（更新）：

• クライアント ID → 新しく作成した MyWebAppClient のクライアント ID を使う（① の MyWebApp のクライアント ID は使わない）

③ Lambda 関数を作成する

AWSコンソール → Lambda → 「関数の作成」

「関数の作成」をクリック。

コードの入力

関数ページ → 「コード」タブ → lambda_function.py を開いて既存の内容を全て置き換えて以下を貼り付けます。

import json


def lambda_handler(event, context):
    resource = event.get("resource", "/")  # API Gateway プロキシ統合: リクエストパスが "resource" に入る

    if resource == "/hello":
        return {
            "statusCode": 200,
            "headers": {"Content-Type": "application/json"},
            "body": json.dumps({"message": "Hello! This is a public endpoint."}),
        }

    if resource == "/profile":
        # event["requestContext"]["authorizer"]["claims"] に JWT ペイロードが格納される
        claims = (
            event.get("requestContext", {})
            .get("authorizer", {})
            .get("claims", {})
        )
        return {
            "statusCode": 200,
            "headers": {"Content-Type": "application/json"},
            "body": json.dumps(
                {
                    "message": "認証成功",
                    "email": claims.get("email"),
                    "sub": claims.get("sub"),          # Cognito が生成したユーザーの一意 ID
                    "token_use": claims.get("token_use"),  # "id" が返る（IDトークンを使っているため）
                },
                ensure_ascii=False,
            ),
        }

    return {
        "statusCode": 404,
        "headers": {"Content-Type": "application/json"},
        "body": json.dumps({"message": "Not Found"}),
    }

「Deploy」ボタンをクリックしてコードを保存します。

Lambda 側で認証コードが不要な理由：
API Gateway の Cognito Authorizer が IDトークン（JWT）の検証をすべて担っています。Lambda が呼ばれた時点では認証済みであることが保証されており、検証済みの claims だけを受け取って使えばよい設計です。

④ API Gateway REST API を作成する

AWSコンソール → API Gateway → 「APIを作成」

4-1. API タイプの選択

「REST API」の「構築」をクリック。

「APIを作成」をクリック。

4-2. リソース /hello を作成する

左のリソースツリーで /（ルート）を選択 → 「リソースを作成」ボタンをクリック

新UIの注意点：
「リソースパス」はリソースを作成する親パスの選択（/ = ルート配下という意味）です。/hello と入力する欄ではありません。「リソース名」に hello と入力するだけで OK です。

「リソースを作成」をクリック。

/hello を選択した状態で → 「メソッドを作成」→ メソッドタイプ GET を選択

「保存」→「OK」（Lambda 呼び出し権限の追加確認）。

4-3. リソース /profile を作成する

左のリソースツリーで /（ルート）を選択 → 「リソースを作成」

「リソースを作成」をクリック。

/profile を選択した状態で → 「メソッドを作成」→ メソッドタイプ GET を選択

「保存」をクリック。

4-4. Cognito Authorizer を作成する

左側メニューの「オーソライザー」→「オーソライザーを作成」

新UIの注意点：
「トークンのソース」はデフォルトで空欄になっています。Authorization と入力しないと動作しません。入力を忘れると全リクエストが 401 になります。

「オーソライザーを作成」をクリック。

動作確認：

「オーソライザーのテスト」→ テスト用トークン欄に適当な文字を入力 → 「テスト」→ 401 が返れば正常（正しいトークンがないため 401 が正解）。

4-5. /profile GET メソッドに Authorizer を設定する

左のリソースツリーで /profile → GET を選択 → 「メソッドリクエストの設定」セクションの「編集」ボタンをクリック

「認可」ドロップダウンを開き、Cognito ユーザープールオーソライザー の配下にある CognitoAuthorizer を選択 → 「保存」

新UIの注意点：
選択肢は なし / AWS IAM / Cognito ユーザープールオーソライザー（カテゴリ）→ CognitoAuthorizer の階層構造になっています。
CognitoAuthorizer はカテゴリ名ではなく、その下にインデントされた項目を選んでください。

ポイント：
/hello GET には Authorizer を設定しない（認証不要）。
/profile GET にのみ CognitoAuthorizer を設定することで、エンドポイントごとに認証要件を分けます。

4-6. API をデプロイする

「アクション」→「API のデプロイ」

「デプロイ」をクリック。

控えておく情報：

「Prod ステージエディター」に表示される URL の呼び出し（例: https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod）をコピーします。

⑤ テストユーザーを作成する

Cognito → 作成した User Pool → 左サイドバー「ユーザー管理」→「ユーザー」→「ユーザーを作成」

パスワードポリシー（新UIのデフォルト）：
最小8文字 / 数字・小文字・大文字・特殊文字をそれぞれ1文字以上含むこと。
TestPass1 は特殊文字がないため不可。TestPass1! を使ってください。

「ユーザーを作成」をクリック。

ユーザーの「確認ステータス」列に 「パスワードを強制的に変更」 と表示されます（= FORCE_CHANGE_PASSWORD 状態）。
この状態で initiate-auth を実行してもトークンが返らず NEW_PASSWORD_REQUIRED チャレンジが返されます。
次の CLI コマンドで永続パスワードを設定して「確認済み」（CONFIRMED）に変更します。

CLI で永続パスワードを設定する：

方法 A: CloudShell（コンソール版ハンズオンにおすすめ）

AWSコンソール画面下部の「CloudShell」をクリックして起動します。コンソールと同じ認証情報が自動で使われるため追加設定は不要。

aws cognito-idp admin-set-user-password \
  --user-pool-id ap-northeast-1_XXXXXXXX \
  --username test@example.com \
  --password 'TestPass1!' \
  --permanent \
  --region ap-northeast-1

CloudShell は Linux シェルのため \ で改行します。! を含むパスワードはシングルクォート '...' で囲んでください（ダブルクォートだと bash がエラーになる場合があります）。

方法 B: ローカルの AWS CLI（コマンドプロンプト）

aws cognito-idp admin-set-user-password ^
  --user-pool-id ap-northeast-1_XXXXXXXX ^
  --username test@example.com ^
  --password TestPass1! ^
  --permanent ^
  --region ap-northeast-1

ap-northeast-1_XXXXXXXX を ① で控えたユーザープール ID に置き換えてください。

コマンドが出力なしで返れば成功です。コンソールでユーザーの「確認ステータス」が**「確認済み」**に変わったことを確認してください。

⑥ 動作テスト

テスト1: 公開エンドポイント（/hello）→ 200

curl https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod/hello

期待するレスポンス:

{"message": "Hello! This is a public endpoint."}

テスト2: 未認証でプライベートエンドポイント（/profile）→ 401

curl https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod/profile

期待するレスポンス（API Gateway が返す。Lambda は呼ばれていない）:

{"message": "Unauthorized"}

テスト3: IDトークンを取得する

aws cognito-idp initiate-auth ^
  --auth-flow USER_PASSWORD_AUTH ^
  --auth-parameters "USERNAME=test@example.com,PASSWORD=TestPass1!" ^
  --client-id XXXXXXXXXXXXXXXXXXXXXXXXXX ^
  --region ap-northeast-1

XXXXXXXXXXXXXXXXXXXXXXXXXX を ② で控えた MyWebAppClient のクライアント ID に置き換えてください（① の MyWebApp のクライアント ID ではありません）。

レスポンス例（抜粋）:

{
    "AuthenticationResult": {
        "AccessToken": "eyJra...",
        "ExpiresIn": 3600,
        "TokenType": "Bearer",
        "RefreshToken": "eyJjb...",
        "IdToken": "eyJra..."
    }
}

IdToken の値をコピーしておきます（次のテストで使用）。

IdToken と AccessToken の違い：

トークン	用途	含まれる情報
IdToken	ユーザー認証（今回使用）	email / sub など
AccessToken	Cognito API へのアクセス	sub / scope など

API Gateway の Cognito Authorizer に渡すのは IdToken。AccessToken を渡しても 403 になります。

テスト4: 認証ありでプライベートエンドポイント（/profile）→ 200

IdToken は非常に長いため、変数に格納してから実行します。

方法 A: CloudShell（おすすめ）

TOKEN="eyJra...（IdToken全体を貼り付ける）"
curl -H "Authorization: $TOKEN" https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod/profile

方法 B: Windows CMD（変数使用）

set TOKEN=eyJra...（IdToken全体を貼り付ける）
curl -H "Authorization: %TOKEN%" https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod/profile

重要： CMD では変数展開に %TOKEN% を使います。$TOKEN（bash 構文）を CMD で使うと文字列 $TOKEN がそのまま送られ 401 になります。
また Bearer プレフィックスは不要です。raw JWT をそのまま Authorization ヘッダーに指定してください。

期待するレスポンス:

{
  "message": "認証成功",
  "email": "test@example.com",
  "sub": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "token_use": "id"
}

sub は Cognito が自動生成したユーザーの一意 ID です。
token_use: "id" は IDトークンを使っていることを示します。

⑦ リソースの削除

課金を止めるために、ハンズオン完了後は必ずリソースを削除してください。

1. API Gateway を削除する

API Gateway → APIs → CognitoSampleApi を選択 → 「アクション」→「APIの削除」

2. Lambda 関数を削除する

Lambda → 関数 → CognitoApiFunction を選択 → 「アクション」→「削除」

3. Cognito User Pool を削除する

Cognito → 作成した User Pool → 右上の「ユーザープールを削除」ボタン → ユーザープール名を入力 → 「削除」

ユーザーとアプリクライアントも一緒に削除されます。

4. IAM ロールを削除する（任意）

IAM → ロール → CognitoApiFunction-role-XXXX を検索して削除

5. CloudWatch Logs のロググループを削除する（任意）

CloudWatch → ロググループ → /aws/lambda/CognitoApiFunction → 削除

SAMとの対比

トラブルシューティング

まとめ

今回のハンズオンで体験できたこと：

コンソール版とSAM版を比較してみる

コンソールでCognitoとAPI Gatewayの連携を理解したら、SAMで同じ構成をコードで定義することで「SAMが何を自動化しているか」が明確になります。DefaultAuthorizer によるワンライン認証設定や、ALLOW_USER_PASSWORD_AUTH の自動有効化など、コンソールでの手動操作がコードに対応しています。

関連記事

Amazon検索[本 AWS 開発]

The post AWSコンソールだけでCognito + API Gateway + Lambda の認証付きAPIを構築する手順【SAM版との比較付き / 新UI対応】 first appeared on CayTech Lab.

はじめに

「認証付きAPIの構成をコードで管理して、チームで再現できるようにしたい」——そんな要件に、AWS SAM（Serverless Application Model） は最適な選択肢のひとつです。

この記事では、AWS SAM を使って、Cognito + API Gateway + Lambda による認証付き REST API をゼロから構築するハンズオンを紹介します。

クライアント（curl）
  │
  ├─ GET /hello  → API Gateway（認証なし）→ Lambda → 200 OK
  │
  └─ GET /profile
        ├─ Authorization ヘッダーなし → API Gateway が 401 を返す
        └─ Authorization: <IDトークン>
              → Cognito Authorizer が JWT を検証（Lambda 不要）
              → Lambda → email / sub を返す → 200 OK

このハンズオンで体験できること：

• AWS::Cognito::UserPool と AWS::Cognito::UserPoolClient の SAM 定義
• DefaultAuthorizer を使ったエンドポイント単位の認証制御（1行で全エンドポイントに認証を適用）
• Authorizer: NONE で特定エンドポイントだけ認証を除外するパターン
• CLI でのテスト実行（ユーザー作成 → IDトークン取得 → 認証済みリクエスト）

このハンズオンの特徴：

• sam build + sam deploy の 2コマンドで全リソースをデプロイ
• Cognito User Pool / User Pool Client / API Gateway / Lambda / IAM ロールを template.yaml 1ファイルで管理
• sam delete で全リソースを一括削除（コンソール版では各リソースを個別に削除する必要がある）

Amazon検索[本 AWS 開発]

SAM vs コンソール：どれだけ違うか

キーワード解説

前提条件

aws sts get-caller-identity

アカウントIDが表示されれば認証設定済みです。

使用するAWSサービス

Step 1: プロジェクトフォルダを開く

cd C:\my-aws\aws-learning-projects\cognito-api-lambda

フォルダ構造

cognito-api-lambda/
├── template.yaml       # SAMテンプレート（Cognito + API Gateway + Lambda 定義）
├── samconfig.toml      # デプロイ設定（gitignore 対象・毎回手動作成が必要）
├── docs/
│   ├── 1_console.md    # AWSコンソール版手順
│   └── 2_sam.md        # SAM版手順
└── src/
    └── app.py          # Lambda 関数（/hello と /profile を処理）

Step 2: SAMテンプレートの確認（template.yaml）

template.yaml は全 AWSリソースの設計図です。ポイントを確認しておきます。

Cognito リソースの定義

Resources:
  UserPool:
    Type: AWS::Cognito::UserPool
    Properties:
      UsernameAttributes: [email]     # メールアドレスでログイン
      Policies:
        PasswordPolicy:
          MinimumLength: 8            # 記号・大文字不要（テスト用に緩和）

  # アプリクライアント: CLI から initiate-auth で使う
  UserPoolClient:
    Type: AWS::Cognito::UserPoolClient
    Properties:
      GenerateSecret: false           # シークレットなし（CLI テスト用）
      ExplicitAuthFlows:
        - ALLOW_USER_PASSWORD_AUTH    # username/password で直接認証（テスト用）
        - ALLOW_REFRESH_TOKEN_AUTH

API Gateway と Cognito Authorizer の定義

  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Auth:
        # DefaultAuthorizer を指定 → 全エンドポイントにデフォルトで認証が必要になる
        DefaultAuthorizer: CognitoAuthorizer
        Authorizers:
          CognitoAuthorizer:
            UserPoolArn: !GetAtt UserPool.Arn  # User Pool と自動的に紐付け
            Identity:
              Header: Authorization            # JWT を Authorization ヘッダーで受け取る

Lambda 関数とエンドポイントの定義

  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      Events:
        PublicEndpoint:              # /hello: 公開エンドポイント
          Type: Api
          Properties:
            Path: /hello
            Method: get
            Auth:
              Authorizer: NONE       # DefaultAuthorizer を明示的に無効化

        PrivateEndpoint:             # /profile: 認証必須
          Type: Api
          Properties:
            Path: /profile
            Method: get
            # Auth 指定なし → DefaultAuthorizer（CognitoAuthorizer）が自動適用

template.yaml のポイント解説

Step 3: Lambda コードの確認（src/app.py）

src/app.py の構造を把握しておきます。

import json


def lambda_handler(event, context):
    resource = event.get("resource", "/")   # API Gateway プロキシ統合: リクエストパスが入る

    if resource == "/hello":
        return {"statusCode": 200, "body": json.dumps({"message": "Hello! This is a public endpoint."})}

    if resource == "/profile":
        # Cognito Authorizer が JWT を検証済み
        # JWT ペイロードが event["requestContext"]["authorizer"]["claims"] に格納される
        claims = (
            event.get("requestContext", {})
            .get("authorizer", {})
            .get("claims", {})
        )
        return {
            "statusCode": 200,
            "headers": {"Content-Type": "application/json"},
            "body": json.dumps(
                {
                    "message": "認証成功",
                    "email": claims.get("email"),
                    "sub": claims.get("sub"),          # Cognito が生成したユーザーの一意 ID
                    "token_use": claims.get("token_use"),  # "id" が返る（IDトークンを使っているため）
                },
                ensure_ascii=False,
            ),
        }

    return {"statusCode": 404, "body": json.dumps({"message": "Not Found"})}

app.py のポイント：

• Lambda 側でトークン検証は一切不要。Cognito Authorizer が自動で行う
• claims には email / sub / token_use など JWT ペイロードの全フィールドが格納される
• /hello への呼び出しでは claims は空（Authorizer が動作しないため）

各コードの全文はコンソール版記事を参照してください。
SAM版・コンソール版で使用する Lambda コードは共通です。コンソール版では手順とあわせてコードを全文掲載しています。

→ AWSコンソールだけでCognito + API Gateway + Lambda の認証付きAPIを構築する手順

Step 4: samconfig.toml を作成する

samconfig.toml は .gitignore で管理外のため、毎回手動で作成する必要があります。

cognito-api-lambda/samconfig.toml を新規作成して以下を貼り付けます。

version = 0.1

[default.deploy.parameters]
stack_name = "cognito-api-lambda-stack"
resolve_s3 = true
s3_prefix = "cognito-api-lambda-stack"
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_IAM"
disable_rollback = true
image_repositories = []

[default.global.parameters]
region = "ap-northeast-1"

samconfig.toml の置き場所：
cognito-api-lambda/ フォルダの直下に置く必要があります。

Step 5: sam build（ビルド）

cd C:\my-aws\aws-learning-projects\cognito-api-lambda
sam build

成功すると以下のように表示されます。

Build Succeeded

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

sam build が行っていること：

• src/ フォルダを ZIP パッケージ化して .aws-sam/build/ に配置
• template.yaml を .aws-sam/build/template.yaml にコピー
• Lambda デプロイの準備を整える

Step 6: sam deploy（デプロイ）

sam deploy

変更内容が表示されて確認を求められます。

Deploy this changeset? [y/N]: y

y を入力して進めます。数分でデプロイが完了します。

デプロイ完了の確認

ターミナルに Outputs が表示されます。

Outputs
----------------------------------------------------------------------
Key    ApiUrl
Value  https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod

Key    UserPoolId
Value  ap-northeast-1_XXXXXXXX

Key    UserPoolClientId
Value  XXXXXXXXXXXXXXXXXXXXXXXXXX
----------------------------------------------------------------------

3つの値を全て控えておきます。（テスト実行コマンドで使用）

デプロイされるリソース一覧

Cognito User Pool × 1              : cognito-api-lambda-stack-user-pool
Cognito User Pool Client × 1       : シークレットなし（ALLOW_USER_PASSWORD_AUTH 有効）
API Gateway REST API × 1           : cognito-api-lambda-stack + Prod ステージ
Lambda 関数 × 1                    : cognito-api-lambda-stack-ApiFunction-XXXX
IAM ロール × 1                     : Lambda 実行ロール
S3                                 : SAM デプロイパッケージ
CloudWatch Logs                    : Lambda 自動生成ログ × 1

Step 7: 動作テスト

事前準備: 変数を設定する

set API_URL=https://XXXXXXXXXX.execute-api.ap-northeast-1.amazonaws.com/Prod
set USER_POOL_ID=ap-northeast-1_XXXXXXXX
set CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXX

テスト1: テストユーザーを作成する

aws cognito-idp admin-create-user ^
  --user-pool-id %USER_POOL_ID% ^
  --username test@example.com ^
  --region ap-northeast-1

ユーザーが FORCE_CHANGE_PASSWORD 状態で作成されます。次のコマンドで永続パスワードを設定して CONFIRMED 状態にします。

aws cognito-idp admin-set-user-password ^
  --user-pool-id %USER_POOL_ID% ^
  --username test@example.com ^
  --password TestPass1 ^
  --permanent ^
  --region ap-northeast-1

レスポンスなし（エラーが出なければ成功）。

FORCE_CHANGE_PASSWORD 状態とは：
Cognito で管理者が作成したユーザーの初期状態です。この状態で initiate-auth を実行すると NEW_PASSWORD_REQUIRED チャレンジが返されてトークンが取得できません。--permanent フラグを付けて admin-set-user-password を実行することで CONFIRMED（認証済み）状態に変えられます。

テスト2: 公開エンドポイントのテスト（/hello）→ 200

curl %API_URL%/hello

期待するレスポンス:

{"message": "Hello! This is a public endpoint."}

テスト3: 未認証でプライベートエンドポイント（/profile）→ 401

curl %API_URL%/profile

期待するレスポンス（API Gateway が返す。Lambda は呼ばれていない）:

{"message": "Unauthorized"}

テスト4: IDトークンを取得する

aws cognito-idp initiate-auth ^
  --auth-flow USER_PASSWORD_AUTH ^
  --auth-parameters "USERNAME=test@example.com,PASSWORD=TestPass1" ^
  --client-id %CLIENT_ID% ^
  --region ap-northeast-1

レスポンス例（抜粋）:

{
    "AuthenticationResult": {
        "IdToken": "eyJra...",
        "AccessToken": "eyJra...",
        "RefreshToken": "eyJjb...",
        "ExpiresIn": 3600,
        "TokenType": "Bearer"
    }
}

IdToken の値をコピーします（次のテストで使用）。

IdToken と AccessToken の違い：

トークン	用途	JWT ペイロード
IdToken	ユーザー認証（今回使用）	email / sub など
AccessToken	Cognito API へのアクセス	sub / scope など

API Gateway の Cognito Authorizer に渡すのは IdToken。AccessToken を渡すと 403 になります。

テスト5: 認証ありでプライベートエンドポイント（/profile）→ 200

set ID_TOKEN=eyJra...（上記で取得した IdToken の値）

curl -H "Authorization: %ID_TOKEN%" %API_URL%/profile

重要： Bearer プレフィックスは不要です。raw JWT（eyJra...）をそのまま Authorization ヘッダーに指定してください。

期待するレスポンス:

{
  "message": "認証成功",
  "email": "test@example.com",
  "sub": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "token_use": "id"
}

Step 8: AWSコンソールで確認（任意）

SAM でデプロイしたリソースはコンソールでも確認できます。

• API Gateway: APIs → cognito-api-lambda-stack → オーソライザー → CognitoAuthorizer が作成されていることを確認
• Cognito: ユーザープール → 作成された User Pool → ユーザー一覧で test@example.com が「確認済み」になっていることを確認
• Lambda: Lambda → 関数 → cognito-api-lambda-stack-ApiFunction-XXXX → 「モニタリング」タブ → テスト5実行後に呼び出し回数が増加していることを確認

Step 9: リソースの削除

課金を止めるために、ハンズオン完了後は必ずリソースを削除してください。

sam delete --stack-name cognito-api-lambda-stack --region ap-northeast-1

対話式で確認が入ります。両方 y で進めます。

Are you sure you want to delete the stack cognito-api-lambda-stack? [y/N]: y
Are you sure you want to delete the folder cognito-api-lambda-stack in S3? [y/N]: y

削除完了の確認

aws cloudformation describe-stacks --stack-name cognito-api-lambda-stack --region ap-northeast-1

An error occurred (ValidationError): Stack with id cognito-api-lambda-stack does not exist

このメッセージが表示されれば削除完了です。

sam delete で削除されるリソース一覧

コンソール版との大きな違い（SAMのメリット）：
コンソール版では API Gateway / Lambda / Cognito / IAM ロール / ロググループを個別に削除する必要があります。
SAMでは sam delete 1コマンドで全リソースを一括削除できます。

トラブルシューティング

まとめ

今回のハンズオンで実現したこと：

SAMのメリットを実感できたポイント

• GenerateSecret: false + ExplicitAuthFlows でシークレットなしクライアントを定義（コンソール版では SPA タイプのクライアントを別途手動作成）
• DefaultAuthorizer の1行で全エンドポイントに Cognito 認証を適用（コンソール版では各エンドポイントに手動設定）
• UserPoolArn: !GetAtt UserPool.Arn で Cognito Authorizer と User Pool を自動連携（コンソール版では手動選択 + トークンのソースを手入力）

コンソール版と比較してみる

SAMが裏で何をやっているか、同じ構成をAWSコンソールのみで構築する手順をまとめました。Cognitoの新UIで変わった操作（「アプリケーションを作成」からのウィザード、シークレットなしクライアントの作成方法、Authorizer のトークンソース設定）など、コンソール版ならではのつまずきポイントを解説しています。

関連記事

Amazon検索[本 AWS 開発]

The post AWSハンズオン - Cognito + API Gateway + Lambda で認証付きAPIをSAMで構築しよう【コンソール版との比較付き】 first appeared on CayTech Lab.

はじめに

「複数のLambda関数をオーケストレーションするワークフローを、コードで管理したい」という要件に、AWS SAM（Serverless Application Model） は最適な選択肢のひとつです。

この記事では、AWS SAM を使って、受注処理ワークフロー（注文検証 → 在庫確認・支払い並列処理 → 注文確定）をゼロから構築するハンズオンを紹介します。

入力: {"order_id": "ORD-001", "item_id": "item-001", "quantity": 2}
  ↓
[ValidateOrder] 注文検証（Retry + Catch）
  ↓ 成功
[ProcessInParallel] 並列処理（Catch）
  ├─ [CheckInventory] 在庫確認
  └─ [ProcessPayment] 支払い処理
  ↓ 成功（結果リスト: [inventory_result, payment_result]）
[ConfirmOrder] 注文確定
  ↓
終了（成功）

[HandleError] エラー処理（Catch 先）
  ↓
終了（エラー通知済み）

このハンズオンで体験できること：

• AWS::Serverless::StateMachine を使った Step Functions の SAM 定義
• DefinitionSubstitutions で ASL 内の Lambda ARN を 自動差し込みする仕組み
• LambdaInvokePolicy による1行での権限付与（コンソール版ではIAMロールを自動生成）
• CLI でのテスト実行 + コンソールの実行グラフで視覚的に確認

このハンズオンの特徴：

• sam build + sam deploy の 2コマンドで全リソースをデプロイ
• Step Functions（ステートマシン）+ Lambda × 5 + IAM ロール × 6 を template.yaml 1ファイルで管理
• sam delete で全リソースを一括削除（コンソール版では5つのLambda・ステートマシン・IAMロールを個別に削除）

Amazon検索[本 AWS 開発]

SAM vs コンソール：どれだけ違うか

キーワード解説

前提条件

aws sts get-caller-identity

アカウントIDが表示されれば認証設定済みです。

使用するAWSサービス

Step 1: プロジェクトフォルダを開く

cd C:\my-aws\aws-learning-projects\step-functions-lambda

フォルダ構造

step-functions-lambda/
├── template.yaml           # SAMテンプレート（Step Functions + Lambda 定義）
├── samconfig.toml          # デプロイ設定（gitignore 対象・毎回手動作成が必要）
├── docs/
│   ├── 1_console.md        # AWSコンソール版手順
│   └── 2_sam.md            # SAM版手順
└── src/
    ├── validate.py         # 注文検証 Lambda
    ├── inventory.py        # 在庫確認 Lambda
    ├── payment.py          # 支払い処理 Lambda
    ├── confirm.py          # 注文確定 Lambda
    └── error_handler.py    # エラー処理 Lambda

Step 2: SAMテンプレートの確認（template.yaml）

template.yaml は全 AWSリソースの設計図です。ポイントを確認しておきます。

Lambda 関数の定義

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

Resources:
  ValidateFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/           # src/ 配下の全 .py を1つのパッケージとしてデプロイ
      Handler: validate.lambda_handler

  InventoryFunction:          # 在庫確認（Parallel ブランチ 1）
  PaymentFunction:            # 支払い処理（Parallel ブランチ 2）
  ConfirmFunction:            # 注文確定
  ErrorHandlerFunction:       # エラー処理（Catch 先）

ポイント: 5つの Lambda 関数が全て CodeUri: src/ を共有しています。SAM は src/ フォルダを1つの ZIP パッケージとして S3 にアップロードし、各関数は Handler でどのファイル・関数を使うかを指定します。

ステートマシンの定義

  OrderWorkflow:
    Type: AWS::Serverless::StateMachine
    Properties:
      Type: STANDARD
      Definition:
        StartAt: ValidateOrder
        States:
          ValidateOrder:
            Type: Task
            Resource: "${ValidateFunctionArn}"   # DefinitionSubstitutions で実際の ARN に置換
            Next: ProcessInParallel
            Retry:
              - ErrorEquals: [States.ALL]
                IntervalSeconds: 2
                MaxAttempts: 1
                BackoffRate: 2.0
            Catch:
              - ErrorEquals: [States.ALL]
                Next: HandleError
                ResultPath: "$.error"

          ProcessInParallel:
            Type: Parallel
            Branches:
              - StartAt: CheckInventory
                States:
                  CheckInventory:
                    Type: Task
                    Resource: "${InventoryFunctionArn}"
                    End: true
              - StartAt: ProcessPayment
                States:
                  ProcessPayment:
                    Type: Task
                    Resource: "${PaymentFunctionArn}"
                    End: true
            Next: ConfirmOrder
            Catch:
              - ErrorEquals: [States.ALL]
                Next: HandleError
                ResultPath: "$.error"

          ConfirmOrder:
            Type: Task
            Resource: "${ConfirmFunctionArn}"
            End: true

          HandleError:
            Type: Task
            Resource: "${ErrorHandlerFunctionArn}"
            End: true

      DefinitionSubstitutions:           # ${変数名} を実際の ARN に自動置換
        ValidateFunctionArn: !GetAtt ValidateFunction.Arn
        InventoryFunctionArn: !GetAtt InventoryFunction.Arn
        PaymentFunctionArn: !GetAtt PaymentFunction.Arn
        ConfirmFunctionArn: !GetAtt ConfirmFunction.Arn
        ErrorHandlerFunctionArn: !GetAtt ErrorHandlerFunction.Arn

      Policies:                          # ステートマシンが Lambda を呼び出す IAM 権限
        - LambdaInvokePolicy:
            FunctionName: !Ref ValidateFunction
        - LambdaInvokePolicy:
            FunctionName: !Ref InventoryFunction
        - LambdaInvokePolicy:
            FunctionName: !Ref PaymentFunction
        - LambdaInvokePolicy:
            FunctionName: !Ref ConfirmFunction
        - LambdaInvokePolicy:
            FunctionName: !Ref ErrorHandlerFunction

template.yaml のポイント解説

Step 3: Lambda コードの確認（src/）

各ファイルの役割を確認しておきます。

各 Python コードの全文はコンソール版記事を参照してください。
SAM版・コンソール版で使用する Lambda コードは共通です。コンソール版では各関数ごとにコードを貼り付ける手順とあわせて全文を掲載しています。

→ AWSコンソールだけでStep Functions + Lambdaワークフローを構築する手順【SAM版との比較付き / 新UI対応】

confirm.py の event[0] / event[1] について：
Parallel ステートが成功すると、各ブランチの出力が**配列（リスト）**にまとめられて次のステートに渡されます。このため ConfirmFunction は event[0] で在庫確認結果、event[1] で支払い結果にアクセスしています。この仕様を知らないと list indices must be integers エラーで詰まります。

Step 4: samconfig.toml を作成する

samconfig.toml は .gitignore で管理外のため、毎回手動で作成する必要があります。

step-functions-lambda/samconfig.toml を新規作成して以下を貼り付けます。

version = 0.1

[default.deploy.parameters]
stack_name = "step-functions-lambda-stack"
resolve_s3 = true
s3_prefix = "step-functions-lambda-stack"
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_IAM"
disable_rollback = true
image_repositories = []

[default.global.parameters]
region = "ap-northeast-1"

samconfig.toml の置き場所：
step-functions-lambda/ フォルダの直下に置く必要があります。

Step 5: sam build（ビルド）

cd C:\my-aws\aws-learning-projects\step-functions-lambda
sam build

成功すると以下のように表示されます。

Build Succeeded

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

sam build が行っていること：

• src/ フォルダを ZIP パッケージ化して .aws-sam/build/ に配置
• template.yaml を .aws-sam/build/template.yaml にコピー
• Lambda デプロイの準備を整える

Step 6: sam deploy（デプロイ）

sam deploy

変更内容が表示されて確認を求められます。

Deploy this changeset? [y/N]: y

y を入力して進めます。数分でデプロイが完了します。

デプロイ完了の確認

ターミナルに Outputs が表示されます。

Outputs
----------------------------------------------------------------------
Key    OrderWorkflowArn
Value  arn:aws:states:ap-northeast-1:123456789012:stateMachine:step-functions-lambda-stack-order-workflow

Key    OrderWorkflowName
Value  step-functions-lambda-stack-order-workflow
----------------------------------------------------------------------

OrderWorkflowArn を控えておきます。（テスト実行コマンドで使用）

デプロイされるリソース一覧

Step Functions ステートマシン × 1  : step-functions-lambda-stack-order-workflow
Lambda 関数 × 5                    : step-functions-lambda-stack-ValidateFunction-XXXX 他
IAM ロール × 6                     : ステートマシン用 × 1 / Lambda 用 × 5
S3                                 : SAM デプロイパッケージ
CloudWatch Logs                    : Lambda 自動生成ログ × 5

Step 7: 動作テスト

事前準備: ARN を変数に設定する

set SM_ARN=arn:aws:states:ap-northeast-1:123456789012:stateMachine:step-functions-lambda-stack-order-workflow

123456789012 を自分のアカウントIDに置き換えてください（Outputs の値をそのままコピーすればよいです）。

テスト1: 正常処理

aws stepfunctions start-execution ^
  --state-machine-arn %SM_ARN% ^
  --name "test-normal-1" ^
  --input "{\"order_id\": \"ORD-001\", \"item_id\": \"item-001\", \"quantity\": 2}" ^
  --region ap-northeast-1

レスポンス例:

{
    "executionArn": "arn:aws:states:ap-northeast-1:123456789012:execution:...:test-normal-1",
    "startDate": "2026-03-01T10:00:00.000000+09:00"
}

実行結果を確認（数秒後）:

aws stepfunctions describe-execution ^
  --execution-arn "上記の executionArn" ^
  --region ap-northeast-1

"status": "SUCCEEDED" と以下のような出力が表示されます。

{
  "order_id": "ORD-001",
  "item_id": "item-001",
  "quantity": 2,
  "amount": 2000,
  "confirmed_at": "2026-03-01T01:00:00.000000+00:00",
  "status": "confirmed"
}

AWSコンソールで実行グラフを確認（任意）:

Step Functions → ステートマシン → step-functions-lambda-stack-order-workflow → 実行一覧 → test-normal-1 をクリックすると、全ステートが緑色になり ProcessInParallel の2ブランチが同時に実行されたことを視覚的に確認できます。

テスト2: 在庫切れエラー（ProcessInParallel Catch の確認）

aws stepfunctions start-execution ^
  --state-machine-arn %SM_ARN% ^
  --name "test-inventory-error" ^
  --input "{\"order_id\": \"ORD-002\", \"item_id\": \"item-999\", \"quantity\": 1}" ^
  --region ap-northeast-1

期待する動作:

1. ValidateOrder → 成功
2. ProcessInParallel → CheckInventory が ValueError（在庫切れ）を発生させる
3. ProcessInParallel の Catch が動作 → HandleError へ遷移
4. 実行ステータス: SUCCEEDED（HandleError が正常完了）

出力例:

{
  "status": "error",
  "error_type": "ValueError",
  "error_cause": "在庫不足: item_id=item-999",
  "original_input": {
    "order_id": "ORD-002",
    "item_id": "item-999",
    "quantity": 1,
    "validated": true
  }
}

実行ステータスが SUCCEEDED になる理由：
HandleError 関数が正常終了（return result）しているため、ステートマシン全体としては「成功」扱いになります。エラーが「処理されずに残った」場合は FAILED になります。

テスト3: 支払い失敗エラー（ProcessInParallel Catch の確認）

aws stepfunctions start-execution ^
  --state-machine-arn %SM_ARN% ^
  --name "test-payment-error" ^
  --input "{\"order_id\": \"ORD-003\", \"item_id\": \"item-001\", \"quantity\": 2, \"fail_payment\": true}" ^
  --region ap-northeast-1

ProcessPayment が RuntimeError を発生させ、同様に HandleError へ遷移します。

テスト4: 検証エラー（ValidateOrder Retry + Catch の確認）

aws stepfunctions start-execution ^
  --state-machine-arn %SM_ARN% ^
  --name "test-validate-error" ^
  --input "{\"item_id\": \"item-001\", \"quantity\": 2}" ^
  --region ap-northeast-1

order_id を省略しているため ValidateOrder が ValueError を発生させます。

Retry の確認（AWSコンソール）:

Step Functions コンソールの実行グラフで ValidateOrder を選択 → 「イベント」タブ で以下の順序を確認します：

TaskStateEntered → TaskScheduled → TaskStarted → TaskFailed
  → TaskScheduled（リトライ1回目）→ TaskStarted → TaskFailed
  → TaskStateExited（Catch 発動）→ HandleError へ

ValidateFunction が合計2回呼ばれてから HandleError へ遷移することが分かります。

Step 8: AWSコンソールで確認（任意）

SAMでデプロイしたリソースはコンソールで確認できます。

• Step Functions: ステートマシン一覧 → step-functions-lambda-stack-order-workflow → 各実行のグラフを確認
• Lambda: Lambda → 関数 → step-functions-lambda-stack-ValidateFunction-XXXX → 「モニタリング」→ 呼び出し回数を確認
• CloudWatch Logs: Lambda → 対象関数 → 「モニタリング」タブ → 「CloudWatch Logs を表示」

Step 9: リソースの削除

課金を止めるために、ハンズオン完了後は必ずリソースを削除してください。

sam delete --stack-name step-functions-lambda-stack --region ap-northeast-1

対話式で確認が入ります。両方 y で進めます。

Are you sure you want to delete the stack step-functions-lambda-stack? [y/N]: y
Are you sure you want to delete the folder step-functions-lambda-stack in S3? [y/N]: y

削除完了の確認

aws cloudformation describe-stacks --stack-name step-functions-lambda-stack --region ap-northeast-1

An error occurred (ValidationError): Stack with id step-functions-lambda-stack does not exist

このメッセージが表示されれば削除完了です。

sam delete で削除されるリソース一覧

コンソール版との大きな違い（SAMのメリット）：
コンソール版では Lambda × 5 / ステートマシン / IAM ロール × 6 / ロググループを個別に削除する必要があります。
SAMでは sam delete 1コマンドで全リソースを一括削除できます。

トラブルシューティング

まとめ

今回のハンズオンで実現したこと：

SAMのメリットを実感できたポイント

• DefinitionSubstitutions により Lambda ARN のコピー貼り付けが不要
• LambdaInvokePolicy × 5 で IAM 権限設定が1行ずつで完結
• sam delete でステートマシン・Lambda 5つ・IAM ロール 6つを一括削除

コンソール版と比較してみる

SAMが裏で何をやっているか、同じ構成をAWSコンソールのみで構築する手順をまとめました。Workflow Studioの新UI（3択モーダル・「{ } コード」タブ）での操作方法や、コンソール版ならではのつまずきポイントを解説しています。

関連記事

Amazon検索[本 AWS 開発]

The post AWSハンズオン - Step Functions + Lambda で受注処理ワークフローをSAMで構築しよう【コンソール版との比較付き】 first appeared on CayTech Lab.

はじめに

「ウェブサイトを公開したいけど、サーバーは持ちたくない」「静的なHTMLサイトを世界中から速く見せたい」という要件に、S3 + CloudFront の組み合わせはベストな選択肢のひとつです。

この記事では、AWS SAM（Serverless Application Model） を使って、S3バケットにHTMLを配置してCloudFront CDN経由で配信する静的サイトホスティング環境をゼロから構築するハンズオンを紹介します。

ブラウザ
  ↓ HTTPS（HTTPは自動リダイレクト）
CloudFront（CDN・エッジキャッシュ）
  ↓ OAC（AWS Signature v4 署名付きリクエスト）
S3 バケット（非公開・パブリックアクセスブロック）
  └── index.html / error.html

このハンズオンで体験できること：

• S3バケットを非公開のまま CloudFront 経由でのみ公開する OAC（Origin Access Control） の仕組み
• HTTP → HTTPS の自動リダイレクト
• カスタム 404 エラーページ（error.html）
• CDN キャッシュの動作と、更新時の キャッシュ無効化（Invalidation） の操作

このハンズオンの特徴：

• Lambda 関数なしの SAM ハンズオン — SAMはCloudFormationの拡張のため、Lambdaなしの純粋なインフラ構成もそのままデプロイできます
• S3・OAC・CloudFront・バケットポリシーの4リソースを1ファイルで定義し、依存関係をSAMが自動解決
• sam delete でCloudFront含む全リソースを一括削除（コンソール版の「月末まで待つ」問題がない）

Amazon検索[本 AWS 開発]

CDN と OAC の仕組みを理解する

キーワード解説

なぜ S3 を非公開にして CloudFront 経由で配信するのか

S3 バケットを直接公開することもできますが、現在の推奨構成は S3 を非公開 + CloudFront OAC 経由 です。

前提条件

Python は不要： 今回は Lambda 関数がないため Python のインストールは必要ありません。

aws sts get-caller-identity

使用するAWSサービス

Step 1: プロジェクトフォルダを開く

cd C:\my-aws\aws-learning-projects\s3-cloudfront-hosting

フォルダ構造

s3-cloudfront-hosting/
├── template.yaml       # SAMテンプレート（S3 + OAC + CloudFront + バケットポリシー）
├── samconfig.toml      # デプロイ設定（gitignore対象・毎回手動作成が必要）
├── website/
│   ├── index.html      # トップページ
│   └── error.html      # カスタム 404 ページ
└── docs/
    ├── 1_console.md    # AWSコンソール版手順
    └── 2_sam.md        # SAM版手順

Step 2: SAMテンプレートの確認（template.yaml）

template.yaml が4つのAWSリソース全体の設計図です。それぞれのリソースに依存関係があるため、SAMが自動的に正しい順序で作成します。

リソースの依存関係

WebsiteBucket（S3バケット）
    ↓ バケット名を参照
CloudFrontOAC（Origin Access Control）
    ↓ バケット名 + OAC ID を参照
WebsiteDistribution（CloudFrontディストリビューション）
    ↓ バケット名 + ディストリビューションARN を参照
WebsiteBucketPolicy（S3バケットポリシー）

template.yaml の主要部分

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: S3 + CloudFront static site hosting with OAC

Resources:
  WebsiteBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub "${AWS::StackName}-website-${AWS::AccountId}"  # アカウントIDでユニーク化
    DeletionPolicy: Delete   # sam delete 時にバケットも削除（空の場合のみ）

  # OAC: CloudFrontがS3に署名付きリクエストを送るための設定
  CloudFrontOAC:
    Type: AWS::CloudFront::OriginAccessControl
    Properties:
      OriginAccessControlConfig:
        Name: !Sub "${AWS::StackName}-oac"
        OriginAccessControlOriginType: s3
        SigningBehavior: always      # 常に署名付きで送信
        SigningProtocol: sigv4       # AWS Signature Version 4

  # CloudFront ディストリビューション
  WebsiteDistribution:
    Type: AWS::CloudFront::Distribution
    Properties:
      DistributionConfig:
        DefaultRootObject: index.html                    # / → index.html
        Enabled: true
        Origins:
          - DomainName: !GetAtt WebsiteBucket.RegionalDomainName  # リージョナルドメインを使用
            Id: S3Origin
            S3OriginConfig:
              OriginAccessIdentity: ""                   # OAC使用時は空文字列が必須
            OriginAccessControlId: !GetAtt CloudFrontOAC.Id
        DefaultCacheBehavior:
          ViewerProtocolPolicy: redirect-to-https        # HTTP → HTTPS リダイレクト
          CachePolicyId: 658327ea-f89d-4fab-a63d-7e88639e58f6  # Managed-CachingOptimized
          AllowedMethods: [GET, HEAD]
          TargetOriginId: S3Origin
        CustomErrorResponses:
          - ErrorCode: 403             # S3が非公開のため404ではなく403が返る場合がある
            ResponseCode: 404
            ResponsePagePath: /error.html
          - ErrorCode: 404
            ResponseCode: 404
            ResponsePagePath: /error.html

  # バケットポリシー: このCloudFrontディストリビューションからのみ GetObject を許可
  WebsiteBucketPolicy:
    Type: AWS::S3::BucketPolicy
    Properties:
      Bucket: !Ref WebsiteBucket
      PolicyDocument:
        Statement:
          - Effect: Allow
            Principal:
              Service: cloudfront.amazonaws.com
            Action: s3:GetObject
            Resource: !Sub "arn:aws:s3:::${WebsiteBucket}/*"
            Condition:
              StringEquals:
                AWS:SourceArn: !Sub "arn:aws:cloudfront::${AWS::AccountId}:distribution/${WebsiteDistribution}"

Outputs:
  BucketName:
    Value: !Ref WebsiteBucket
  CloudFrontDomain:
    Value: !Sub "https://${WebsiteDistribution.DomainName}"
  DistributionId:
    Value: !Ref WebsiteDistribution

template.yaml のポイント解説

!GetAtt WebsiteBucket.RegionalDomainName（リージョナルドメインを使用）
OACを使う場合、S3オリジンのドメイン名はリージョナルドメイン（バケット名.s3.ap-northeast-1.amazonaws.com）を使用する必要があります。S3ウェブサイトエンドポイント（バケット名.s3-website-ap-northeast-1.amazonaws.com）は使えません。

S3OriginConfig.OriginAccessIdentity: ""（空文字列）
OACを使う場合は、旧方式（OAI）のフィールドに空文字列を設定することがCloudFormationの仕様上必要です。

ErrorCode: 403 → 404のマッピング
S3バケットが非公開のため、存在しないパスへのアクセスは 403 Forbidden が返ります。それを 404 Not Found にマッピングして error.html を表示します。

CachePolicyId: 658327ea-...（Managed-CachingOptimized）
AWSが提供するマネージドキャッシュポリシー「CachingOptimized」のIDです。S3の静的コンテンツ配信に最適化されたTTL設定が含まれています。

Step 3: website/ の確認

website/index.html と website/error.html はプロジェクトに既に含まれています。内容を確認しておきます。

website/index.html（トップページ）

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>S3 + CloudFront ハンズオン</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
      max-width: 640px;
      margin: 60px auto;
      padding: 20px;
      color: #333;
    }
    h1 { color: #232f3e; }
    .badge {
      background: #ff9900;
      color: white;
      padding: 3px 10px;
      border-radius: 4px;
      font-size: 0.85em;
      font-weight: bold;
    }
    .info {
      background: #f4f6f8;
      border-left: 4px solid #ff9900;
      padding: 12px 16px;
      margin: 20px 0;
      border-radius: 0 4px 4px 0;
    }
  </style>
</head>
<body>
  <h1>デプロイ成功！</h1>
  <p>
    <span class="badge">CloudFront CDN</span> 経由でこのページが配信されています。
  </p>
  <div class="info">
    <strong>このページの配信構成:</strong><br>
    S3 バケット（オリジン） → CloudFront（CDN）→ あなたのブラウザ
  </div>
  <p>S3 + CloudFront による静的サイトホスティングのハンズオンです。</p>
</body>
</html>

website/error.html（カスタム404ページ）

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <title>404 - ページが見つかりません</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
      max-width: 640px;
      margin: 60px auto;
      padding: 20px;
      color: #333;
      text-align: center;
    }
    h1 { color: #cc0000; }
    a { color: #ff9900; }
  </style>
</head>
<body>
  <h1>404 - ページが見つかりません</h1>
  <p>お探しのページは存在しないか、移動・削除された可能性があります。</p>
  <p><a href="/">トップページへ戻る</a></p>
</body>
</html>

重要: sam deploy ではHTMLファイルはS3にアップロードされません。
SAMデプロイはインフラ（S3バケット・CloudFront等）を作成するだけです。
HTMLファイルは Step 7 で別途 aws s3 sync コマンドでアップロードします。

Step 4: samconfig.toml を作成する

samconfig.toml は .gitignore で管理外のため、毎回手動で作成する必要があります。

s3-cloudfront-hosting/samconfig.toml を新規作成して以下を貼り付けてください。

version = 0.1

[default.deploy.parameters]
stack_name = "s3-cloudfront-hosting-stack"
resolve_s3 = true
s3_prefix = "s3-cloudfront-hosting-stack"
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_IAM"
disable_rollback = true
image_repositories = []

[default.global.parameters]
region = "ap-northeast-1"

Step 5: sam build（ビルド）

cd C:\my-aws\aws-learning-projects\s3-cloudfront-hosting
sam build

Lambda関数がないため、ビルド処理は短時間で完了します。

Build Succeeded

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

Step 6: sam deploy（デプロイ）

sam deploy

Deploy this changeset? [y/N]: y

y を入力して進めます。

CloudFront のデプロイには 5〜15分かかります。
CloudFront はグローバルに世界中のエッジロケーションに設定を反映するため、他のプロジェクトよりデプロイ完了に時間がかかります。ターミナルがフリーズしているように見えても正常に処理中ですので、そのまま待ちます。

デプロイ完了の確認

CloudFormation outputs from deployed stack
----------------------------------------------------------------------
Outputs
----------------------------------------------------------------------
Key    BucketName
Value  s3-cloudfront-hosting-stack-website-123456789012

Key    CloudFrontDomain
Value  https://xxxxxxxxxxxx.cloudfront.net

Key    DistributionId
Value  EXXXXXXXXXXXXXXXXX
----------------------------------------------------------------------

BucketName と CloudFrontDomain（と DistributionId）を控えておきます。

Step 7: HTMLファイルをアップロード

インフラのデプロイが完了したら、HTMLファイルをS3バケットにアップロードします。

set BUCKET=s3-cloudfront-hosting-stack-website-123456789012

aws s3 sync C:\my-aws\aws-learning-projects\s3-cloudfront-hosting\website\ ^
  s3://%BUCKET%/ ^
  --region ap-northeast-1

upload: website\error.html to s3://s3-cloudfront-hosting-stack-website-123456789012/error.html
upload: website\index.html to s3://s3-cloudfront-hosting-stack-website-123456789012/index.html

Step 8: 動作テスト

8-1. トップページの確認

ブラウザでCloudFrontドメインにアクセスします。

https://xxxxxxxxxxxx.cloudfront.net

index.html の内容が表示されれば成功です。

8-2. HTTP → HTTPS リダイレクトの確認

http://xxxxxxxxxxxx.cloudfront.net

HTTPでアクセスすると自動的にHTTPSにリダイレクトされることを確認します。ブラウザのアドレスバーが https:// に変わるのを確認してください。

8-3. カスタム 404 ページの確認

https://xxxxxxxxxxxx.cloudfront.net/notfound

存在しないパスにアクセスすると error.html の内容（「404 - ページが見つかりません」）が表示されることを確認します。

8-4. CDN キャッシュのテスト（任意）

CloudFront CDNの重要な概念「キャッシュ」と「無効化（Invalidation）」を体験します。

① index.html を更新して再アップロード

aws s3 cp C:\my-aws\aws-learning-projects\s3-cloudfront-hosting\website\index.html ^
  s3://%BUCKET%/index.html ^
  --region ap-northeast-1

ブラウザで CloudFront URL にアクセスしても、古いキャッシュが表示される場合があります（TTLが切れるまで）。

② キャッシュを無効化（Invalidation）する

set DIST_ID=EXXXXXXXXXXXXXXXXX

aws cloudfront create-invalidation ^
  --distribution-id %DIST_ID% ^
  --paths "/*" ^
  --region ap-northeast-1

レスポンス例：

{
    "Invalidation": {
        "Id": "IXXXXXXXXXXXXXXXXX",
        "Status": "InProgress"
    }
}

③ 無効化の完了確認（1〜5分後）

aws cloudfront get-invalidation ^
  --distribution-id %DIST_ID% ^
  --id IXXXXXXXXXXXXXXXXX ^
  --region ap-northeast-1

"Status": "Completed" になったらブラウザを強制リロード（Ctrl+Shift+R）して最新版が表示されることを確認します。

キャッシュ無効化の料金：
毎月最初の 1,000 パスは無料。それ以降は $0.005/パス。
/* は「1パス」としてカウントされるため、ハンズオン数回程度なら無料枠内です。

Step 9: AWSコンソールで確認（任意）

• S3: S3 → s3-cloudfront-hosting-stack-website-XXXX → index.html / error.html が存在することを確認
• S3 バケットポリシー: S3 → バケット → 「アクセス許可」タブ → バケットポリシーにOACの条件が含まれていることを確認
• CloudFront: CloudFront → ディストリビューション → ステータスが「有効」、「オリジン」タブでOACが設定されていることを確認

Step 10: リソースの削除

課金を止めるために、ハンズオン完了後は必ずリソースを削除してください。

削除時の注意点 2つ：

1. S3バケットにオブジェクトが残っていると sam delete が失敗 → 先に空にする
2. CloudFrontの削除には 15〜20分かかります（グローバルに反映を待つため）

① S3バケットを先に空にする

aws s3 rm s3://%BUCKET% --recursive --region ap-northeast-1

② スタックを削除する

sam delete --stack-name s3-cloudfront-hosting-stack --region ap-northeast-1

Are you sure you want to delete the stack s3-cloudfront-hosting-stack? [y/N]: y
Are you sure you want to delete the folder s3-cloudfront-hosting-stack in S3? [y/N]: y

CloudFrontの削除処理が走るため、完了まで15〜20分かかる場合があります。ターミナルはそのまま待ちます。

削除完了の確認

aws cloudformation describe-stacks --stack-name s3-cloudfront-hosting-stack --region ap-northeast-1

An error occurred (ValidationError): Stack with id s3-cloudfront-hosting-stack does not exist

コンソール版との大きな違い（SAMのメリット）：
コンソールの新UIで作成したディストリビューションは「Pricing plan」に加入するため、プランキャンセル後に月末まで削除できない制約があります。
SAMで作成したディストリビューションにはPricing planの概念がなく、sam delete 1コマンドで即座に削除手続きが完了します。

トラブルシューティング

まとめ

今回のハンズオンで実現したこと：

SAMのメリットを実感できたポイント

• 4リソース（S3・OAC・CloudFront・バケットポリシー）の依存関係をSAMが自動解決
• !GetAtt WebsiteDistribution.DomainName でディストリビューションのドメインを自動参照（コンソール版では手動でコピー）
• sam delete でPricing planなしに即座に削除手続き完了（コンソール版は月末まで待機が必要）

コンソール操作と比較してみる

SAMが裏で何をやっているか、同じ構成をAWSコンソールのみで構築する手順をまとめました。2026年のCloudFront新UI（6ステップウィザード形式）での手順と、削除時に新たに必要になった「Pricing planキャンセル」など、コンソールならではのつまずきポイントを解説しています。

• AWSコンソールだけでS3 + CloudFront静的サイトホスティングを構築する手順【SAM版との比較付き / 新UI対応】

AWSコンソールだけでS3 + CloudFront静的サイトホスティングを構築する手順【SAM版との比較付き / 新UI対応】

はじめにこの記事は、SAM版ハンズオン記事の比較版です。SAM版ではコマンド数本でS3・OAC・CloudFront・バケットポリシーが一括デプロイできましたが、実際にコンソールで操作してみると思わぬハマりポイントがいくつかあります。特に ...

caymezon.com

2026.02.23

関連記事

Amazon検索[本 AWS 開発]

The post AWSハンズオン - S3 + CloudFrontで静的サイトをCDN配信しよう【SAM版 / Windows対応】 first appeared on CayTech Lab.