Amazon API Gateway本番運用Vol1｜REST/HTTP/WebSocket

1. Amazon API Gateway 全体像と本記事の射程・API種別選定指針

1-1. 本記事のゴール

本記事を読み終えた後、次のことができるようになることを目標にしています。

• API 種別の選定: REST / HTTP / WebSocket API の機能分界を理解し、要件に応じて根拠を持って選定できます
• 統合方式の設計: Lambda proxy/non-proxy・VPC Link・AWS サービス直接統合の使い分けと VTL マッピングテンプレートを設計できます
• 認可方式の選択: IAM / Cognito User Pools / Lambda Authorizer / JWT Authorizer を API 種別と組み合わせて正しく選択できます
• 使用量プランの設計: APIキー・スロットリング（rate/burst）・クォータで外部向け API を収益化・流量制御できます
• mTLS の設定: Regional カスタムドメイン・truststore・ACM 証明書の関係を正確に把握して設定できます
• 可観測性の構築: CloudWatch メトリクス・X-Ray・アクセスログで問題を早期検知できます
• カナリアリリースの実施: ステージ単位でトラフィックを段階的に切り替え、安全にデプロイできます

Amazon API Gateway は「Lambda の前段に置くマネージドプロキシ」という理解にとどまらず、使用量プラン（API 収益化）・mTLS（ゼロトラスト認証）・カナリアリリース（安全な段階的デプロイ）まで幅広くカバーする API 公開基盤です。本記事ではその全体像を設計視点で解説します。

1-2. 読者像

本記事が想定する読者は次のような方です。

• API をスケーラブルに外部公開したいアプリケーション開発者・プラットフォーム担当者
• 認可設計（Cognito / Lambda Authorizer）やスロットリング設計に課題を抱えるバックエンドエンジニア
• mTLS やカスタムドメイン設定を正確に行いたいインフラ・SRE エンジニア
• REST API と HTTP API の違いを整理したうえで設計判断をしたい方
• 外部開発者向けに API を有償公開・収益化することを検討しているアーキテクト

前提知識として AWS IAM・AWS Lambda・HTTP/REST の基礎を把握していることを想定しています。API Gateway を初めて触る方には、まず公式の「API Gateway の開始方法」チュートリアルを先に参照することをお勧めします。

1-3. REST / HTTP / WebSocket の選定指針

Amazon API Gateway は 3 種類の API タイプを提供しています。API 種別の選定を誤ると、あとで必要な機能が使えないと分かり API の再設計が必要になります。設計初期段階で API 種別を確定させることが本番運用における最重要の判断です。後から種別を変更するには API 定義の再作成が必要になるため、選定に使う機能要件の洗い出しを設計の最初に行ってください。

API 種別の機能比較

REST API を選ぶべきケース

以下の機能を 1 つでも必要とする場合は REST API を選択してください。HTTP API ではこれらの機能を利用できません。

• 使用量プラン・APIキー・クォータ: 外部開発者向け API の収益化・テナント別流量制御（本記事 §4 で詳述）
• AWS WAF 直接統合: SQL インジェクション・XSS 防御・IP 制限を Gateway 層で実装（本記事 §5 で詳述）
• APIキャッシュ: バックエンド呼び出しを削減してレイテンシ改善とコスト削減（本記事 §4 で詳述）
• X-Ray アクティブトレーシング: Lambda 統合を含むエンドツーエンドの分散トレーシング（本記事 §6 で詳述）
• カナリアリリース: ステージ単位でトラフィックの一部を新デプロイへ段階的に流す（本記事 §7 で詳述）
• ネイティブ Cognito User Pools Authorizer: Lambda 実装なしで Cognito トークンを検証（本記事 §3 で詳述）
• Edge-optimized / Private エンドポイント: グローバル配信または VPC 専用閉域 API
• VTL マッピングテンプレート: Lambda を介さずにリクエスト/レスポンスボディを変換

HTTP API を選ぶべきケース

上記の REST 専用機能が不要な場合、HTTP API を優先して選択してください。約 71% のコスト削減と低レイテンシが得られます。

• シンプルな Lambda プロキシ統合または HTTP バックエンドへの転送
• JWT Authorizer（Cognito / Auth0 / Okta 対応）を使った OIDC 認証（HTTP API 専用）
• $default ステージの自動デプロイで CI/CD パイプラインを簡素化（HTTP API 専用）
• AWS Cloud Map 統合によるサービスディスカバリー（HTTP API 専用）

WebSocket API を選ぶべきケース

クライアント・サーバー間の双方向リアルタイム通信が必要な場合に選択します。チャット・通知配信・リアルタイムダッシュボード・オンラインゲームなどのユースケースが該当します。

WebSocket API ではルートでメッセージを振り分けます。$connect（接続時）・$disconnect（切断時）・$default（ルート選択式が評価不能または JSON 以外のペイロード時）に加えて、カスタムルートを定義できます。ルート選択式（例: ${request.body.action}）で JSON フィールドを評価してルーティングします。

サーバーからクライアントへのプッシュ送信は、@connections API（POST /@connections/{connectionId}）を SigV4 IAM 署名で呼び出します。接続確立前または切断後に送信すると GoneException（410）が返ります。@connections を呼び出す Lambda には execute-api:ManageConnections 権限が必要です。

接続に関する主なハード上限は次のとおりです（いずれも調整不可）。

1-4. 本記事の差別化と前提知識

本記事は API Gateway 全体を本番設計の観点で体系化することを軸にしています。既存の「Lambda Authorizer 実装 how-to 記事」や「Serverless 構成での Lambda 中心記事」とは棲み分けを明確にしています。Lambda Authorizer の実装詳細（IAM ポリシー返却形式・シンプルレスポンス形式・コールドスタート対策）については専門記事に委譲し、本記事は API Gateway 全体の設計判断にフォーカスします。API Gateway を「フルマネージドの API 公開基盤」として位置付け、その設計要素を網羅的に解説します。

前提知識として以下を把握していることを想定しています。

• AWS IAM（ポリシー・ロール・SigV4 署名の概念）
• AWS Lambda（関数の作成・デプロイ・実行モデルの基礎）
• HTTP/REST の基礎（メソッド・ステータスコード・ヘッダー・ペイロード）

Lambda Authorizer 実装詳細はこちら →

2. 統合方式設計：Lambda/HTTP/VPC Link/AWSサービス統合

2-1. 統合方式の全体像

統合（Integration）は、API Gateway がクライアントからのリクエストをどのバックエンドへどのように転送するかを定義します。統合タイプの選択が、バックエンドの柔軟性・レイテンシ・VTL マッピングテンプレートの使用可否を左右します。

REST API の統合タイプ一覧

REST API では以下の統合タイプを選択できます。

重要: AWS タイプは Lambda 非プロキシ統合と AWS サービス直接統合（S3・SQS・DynamoDB 等）の両方を兼ねる単一の統合タイプです。「Lambda 非プロキシ用の別タイプが存在する」という誤解がありますが正しくありません。

HTTP API の統合タイプ

HTTP API では統合タイプの種類が異なります。

HTTP API では Mock 統合は利用できません。また、VTL マッピングテンプレートによるボディ変換も HTTP API では使用できません。CORS プリフライトには専用の cors 設定ブロックで対応します。

2-2. Lambda統合（proxy / non-proxy）

Lambda 統合は最も多く使われる統合方式です。AWS_PROXY（Lambda プロキシ統合）と AWS タイプを使った Lambda 非プロキシ統合では、リクエスト/レスポンスの処理方法が大きく異なります。

Lambda プロキシ統合（AWS_PROXY）

AWS_PROXY では、API Gateway がリクエスト全体を構造化した JSON オブジェクトとして Lambda 関数に渡します。API Gateway はリクエスト/レスポンスを変換しません。Lambda 関数がレスポンスのステータスコード・ヘッダー・ボディを完全にコントロールします。

Lambda 関数が受け取るイベントの構造（REST API）は次のとおりです。

{
  "resource": "/items/{id}",
  "path": "/items/123",
  "httpMethod": "GET",
  "headers": { "Authorization": "Bearer xxx" },
  "queryStringParameters": { "filter": "active" },
  "pathParameters": { "id": "123" },
  "requestContext": {
 "stage": "prod",
 "identity": { "sourceIp": "203.0.113.1" }
  },
  "body": null,
  "isBase64Encoded": false
}

Lambda 関数は次の形式で応答する必要があります。

def handler(event, context):
 return {
  "statusCode": 200,
  "headers": {
"Content-Type": "application/json",
"Access-Control-Allow-Origin": "*"
  },
  "body": '{"id": "123", "status": "active"}'
 }

statusCode が必須で、headers と body は任意です。body は必ず文字列として返す必要があります（JSON オブジェクトを直接返すと 502 Bad Gateway になります）。

Lambda プロキシ統合では統合リクエスト/統合レスポンスの設定は不要で、シンプルにセットアップを完了できます。新規構築では AWS_PROXY を優先して選択することをお勧めします。

Lambda 非プロキシ統合（AWS タイプ）

AWS タイプを Lambda に対して使う場合（非プロキシ統合）、API Gateway が VTL（Velocity Template Language）マッピングテンプレートでリクエストとレスポンスを変換します。Lambda 関数には変換済みの値のみが届きます。

非プロキシ統合を選ぶ主な理由は次のとおりです。

• Lambda 関数への入力を必要最小限に絞り込みたい（セキュリティ・コスト観点）
• バックエンドの関数シグネチャを変えずに API の入出力形式だけを変換したい
• レスポンスのステータスコードを Lambda の出力値から動的にマッピングしたい

統合リクエストのマッピングテンプレート例（VTL）

## パスパラメータとクエリ文字列を Lambda が期待する形式に変換
{
  "itemId": "$input.params('id')",
  "filter": "$input.params('filter')",
  "userId": "$context.authorizer.claims.sub"
}

統合レスポンスのマッピングテンプレート例（VTL）

非プロキシ統合では、Lambda の戻り値をレスポンスにマッピングする「統合レスポンス」も設定します。選択式（例: $integration.response.body.errorType）で Lambda の出力フィールドを評価し、HTTP ステータスコードを決定します。

## Lambda が { "errorType": "NotFound" } を返した場合に 404 へマッピング
選択式: $integration.response.body.errorType
マッピング: NotFound → HTTP 404

VTL では $util ユーティリティや $input・$context 変数が使えます。主なユーティリティを以下に示します。

非プロキシ統合はセットアップが複雑なため、VTL 変換が不要なケースでは AWS_PROXY を選ぶことを推奨します。

2-3. VPC Link（プライベート統合）

VPC Link は、インターネットに公開していない VPC 内のプライベートリソースを API Gateway から呼び出す仕組みです。バックエンドが VPC 内の ECS サービス・EC2・社内マイクロサービスなどの場合に使用します。API Gateway はインターネットを経由せず、AWS の内部ネットワーク経由でプライベートリソースと通信します。

REST API の VPC Link

REST API の VPC Link は NLB（Network Load Balancer）を経由してプライベートリソースに接続します。ALB への直接接続は 2025年11月に追加された比較的新しい機能です。

REST API での VPC Link 設定フローは次のとおりです。

1. NLB を作成: バックエンドサービスを NLB のターゲットグループに登録します。NLB のリスナーポートとターゲットのポートを合わせます
2. VPC Link を作成: API Gateway コンソールの「VPC リンク」から作成し、NLB の ARN を指定します。作成完了まで数分かかります（ステータスが AVAILABLE になるまで待機します）
3. 統合設定: 統合タイプを VPC_LINK にして、作成した VPC Link を選択します。エンドポイント URL には NLB の DNS 名を指定します

# CLI で VPC Link を作成（REST API 用）
aws apigateway create-vpc-link \
  --name "my-vpc-link" \
  --target-arns "arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:loadbalancer/net/my-nlb/xxxx"

HTTP API の VPC Link

HTTP API の VPC Link は NLB・ALB・AWS Cloud Map の 3 種類のバックエンドに対応しています（REST API より幅広いバックエンドをサポートしています）。

AWS Cloud Map 統合は HTTP API 専用の機能です。ECS サービスをサービスディスカバリーで登録し、Cloud Map を通じてコンテナに直接ルーティングできます。NLB を介さずコンテナへ直接接続できるため、マイクロサービス構成に最適です。

VPC Link のセキュリティ設計

NLB はセキュリティグループを持ちません（ALB はセキュリティグループを持ちます）。NLB を使う場合、ターゲットグループのインスタンス（EC2・ECS タスク等）のセキュリティグループで、VPC Link のネットワークインターフェースが属するサブネット CIDR からのインバウンドを許可します。

VPC Link のエンドポイントが受け取る送信元 IP はバックエンドから見ると VPC Link の ENI の IP になります。ターゲット側のセキュリティグループを設定する際は VPC のサブネット CIDR 全体を許可するか、特定の ENI の IP を指定してください。

2-4. AWSサービス統合・HTTP統合・Mock

AWSサービス直接統合（AWS タイプ）

AWS タイプでは Lambda を介さずに、API Gateway が直接 AWS サービスの API を呼び出せます。Lambda のコールドスタートがなく Lambda 実行コストも不要です。ステートレスな変換・キューイング・ストレージ操作を高効率に処理できます。

よく使われる AWSサービス直接統合のパターンを示します。

SQS への直接エンキュー

API Gateway が受け取ったリクエストを Lambda を介さずに SQS キューへ送信するパターンです。非同期ジョブ投入・イベント受付 API に適しています。

統合タイプ: AWS
サービス: SQS
アクション: SendMessage
IAMロール: SQS SendMessage 権限を持つロール

統合リクエスト（VTL）:
Action=SendMessage&MessageBody=$util.urlEncode($input.body)&QueueUrl=$util.urlEncode('https://sqs.ap-northeast-1.amazonaws.com/123456789012/my-queue')

$util.urlEncode() が必須です。SQS の QueryString 形式にエンコードしないとリクエストが失敗します。

DynamoDB への直接 PutItem

{
  "TableName": "Orders",
  "Item": {
 "orderId": { "S": "$context.requestId" },
 "payload": { "S": "$util.escapeJavaScript($input.body)" },
 "createdAt": { "S": "$context.requestTime" }
  }
}

AWSサービス統合では、API Gateway に IAM ロール（実行ロール）を付与して対象サービスへの権限を与える必要があります。IAM ロールの信頼ポリシーでは apigateway.amazonaws.com を Principal に指定します。

{
  "Version": "2012-10-17",
  "Statement": [{
 "Effect": "Allow",
 "Principal": { "Service": "apigateway.amazonaws.com" },
 "Action": "sts:AssumeRole"
  }]
}

HTTP統合・HTTP_PROXY 統合

HTTP 統合は、バックエンドとして AWS 外部の HTTP/HTTPS エンドポイントを指定する統合方式です。

• HTTP_PROXY: クライアントのリクエストをバックエンドにそのまま転送します。変換なしのリバースプロキシとして機能し、設定が最もシンプルです
• HTTP: VTL マッピングテンプレートでリクエスト/レスポンスを変換します。バックエンドの API 仕様と API Gateway で公開するインターフェースを分離したい場合に使います

エンドポイント URL は固定 URL（https://api.example.com/items）またはステージ変数（https://${stageVariables.backendUrl}/items）で指定できます。ステージ変数を使うと、環境（dev/staging/prod）ごとにバックエンド URL を切り替えられます。

Mock統合（REST API 専用）

Mock 統合はバックエンドを呼び出さずに固定レスポンスを返す統合タイプです。Mock 統合は REST API のみで利用できます。HTTP API では利用できないため、CORS プリフライト対応など Mock 統合が必要な場合は REST API を選択してください。

フロントエンド開発のモックサーバーとして、または CORS プリフライト（OPTIONS メソッド）の応答に活用します。

CORS OPTIONS メソッドの Mock 統合設定例

統合タイプ: MOCK
統合リクエスト マッピングテンプレート:
{"statusCode": 200}

統合レスポンス（200）のレスポンスヘッダー:
Access-Control-Allow-Origin: '*'
Access-Control-Allow-Methods: 'GET,POST,PUT,DELETE,OPTIONS'
Access-Control-Allow-Headers: 'Content-Type,Authorization,x-api-key'

HTTP API では CORS 設定専用の cors ブロックが用意されており、OPTIONS メソッドの Mock 統合を手動で作成しなくても CORS プリフライトに自動応答できます。

3. 認可方式：IAM/Cognito/Lambda Authorizer・委譲設計

3-1. 認可方式の選定

Amazon API Gatewayには4種類の認可方式があります。REST APIとHTTP APIで対応する認可方式が異なるため、API種別の選定と合わせて認可設計を行うことが重要です。

重要な分界: COGNITO_USER_POOLS typeのネイティブCognito統合はREST APIのみの機能です。HTTP APIでCognitoのJWTを使いたい場合は、JWT authorizerを選択します。HTTP APIにはネイティブのCognito User Pools typeは存在しません。

また、JWT authorizerはHTTP API専用の機能です。REST APIにネイティブのJWT authorizerはなく、REST APIでJWTを検証したい場合はLambda Authorizerで実装します。

API種別の変更（REST → HTTP、またはその逆）は認可方式の再設計を伴います。設計初期段階でAPI種別と認可方式を一緒に確定させることを推奨します。

認可方式の選定基準

以下の基準で認可方式を選定します。

1. AWSサービス間・社内API（AWSリソースが呼び出し元） → IAM（SigV4）を推奨します。AWS署名検証をAPI Gatewayが担うため、バックエンド側に検証コードが不要です。
2. ユーザー認証（Cognitoユーザーが呼び出し元）・REST API → COGNITO_USER_POOLS typeを推奨します。設定のみで完結し、Lambda実装が不要です。
3. ユーザー認証（Cognitoユーザーが呼び出し元）・HTTP API → JWT authorizerを選択します。Cognito User Pool IDとクライアントIDを設定します。
4. カスタム認証ロジックが必要（独自トークン・複合条件） → Lambda Authorizerを選択します。AWSはTOKEN型よりREQUEST型を推奨しています。
5. マルチIDプロバイダー・ゼロトラスト・レガシー統合 → Lambda Authorizer REQUEST型でカバーします。

3-2. IAM認可（SigV4）

IAM認可では、呼び出し元がAWS Signature Version 4（SigV4）でリクエストを署名します。API Gatewayが署名を検証し、IAMポリシーのexecute-api:Invokeアクションで許可確認を行います。

SigV4署名の仕組み

SigV4では、HTTPメソッド・パス・クエリパラメータ・ヘッダーをまとめて署名します。署名にはAWS認証情報（アクセスキーID・シークレットアクセスキー・セッショントークン）を使用します。EC2・Lambda・ECS等のAWSリソースはIAMロールから認証情報を自動取得できるため、クレデンシャル管理が簡潔です。

# boto3によるSigV4署名の例（Lambda → API Gateway 呼び出し）
import boto3
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
import requests

session = boto3.Session()
credentials = session.get_credentials()
region = 'ap-northeast-1'

request = AWSRequest(
 method='GET',
 url='https://{api-id}.execute-api.ap-northeast-1.amazonaws.com/prod/items',
)
SigV4Auth(credentials, 'execute-api', region).add_auth(request)

response = requests.get(
 request.url,
 headers=dict(request.headers),
)

IAM認可はAWSサービス間の呼び出しに最適です。Lambda・ECS・EC2等がexecute-api:Invoke権限を持つIAMロールで動作している場合、追加の認証コードなしでAPIを呼び出せます。

リソースポリシー

API Gatewayのリソースポリシーを使うと、IAM認可と組み合わせてVPCエンドポイント・IPアドレス・IAMプリンシパルによる詳細なアクセス制御が可能です。

{
  "Version": "2012-10-17",
  "Statement": [
 {
"Effect": "Allow",
"Principal": {
  "AWS": "arn:aws:iam::111122223333:role/MyServiceRole"
},
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:ap-northeast-1:*:*/prod/GET/items"
 },
 {
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:ap-northeast-1:*:*/prod/*",
"Condition": {
  "NotIpAddress": {
 "aws:SourceIp": ["203.0.113.0/24"]
  }
}
 }
  ]
}

リソースポリシーはEdge-optimized・Regional・Private全タイプで利用できます。Private APIではリソースポリシーによるVPCエンドポイント許可が必須です。

クロスアカウント呼び出し

クロスアカウントでのIAM認可には2つのアプローチがあります。

• アプローチ1: 呼び出し元アカウントのIAMロールにexecute-api:Invoke権限を付与し、API Gatewayのリソースポリシーで呼び出し元アカウントのプリンシパルを明示的に許可します。
• アプローチ2: STSのAssumeRoleで被呼び出しアカウントのロールを引き受け、そのロールでSigV4署名します。

どちらの方式でも、リソースポリシーに呼び出し元のARN（arn:aws:iam::{account-id}:...）を記述してアクセスを許可します。

クロスアカウント呼び出しでは、IAM認可とリソースポリシーの両方が「Allow」でなければリクエストは拒否されます。片方だけAllow・もう片方が評価されていない状態ではアクセスできないため、両方の設定を確認します。

3-3. Cognito User Pools authorizer

Cognito User Pools authorizerは、Cognitoが発行するJWTトークン（IDトークンまたはアクセストークン）をAPI Gatewayが検証する認可方式です。

REST API: COGNITO_USER_POOLS type

REST APIではAPIメソッドにCOGNITO_USER_POOLS typeのAuthorizerを設定します。クライアントはAuthorizationヘッダーにCognitoのIDトークンまたはアクセストークンを送信します（Bearerプレフィックスは不要です）。API GatewayはCognito JWKSエンドポイントでトークンの署名・有効期限を検証し、検証成功時のみバックエンドにリクエストを転送します。

設定項目は以下の通りです。

• User Pool ARN: 認証に使用するCognito User Poolを指定します
• Token Source: トークンを受け取るヘッダー名（デフォルト: Authorization）
• OAuth Scope: スコープベースの検証が必要な場合に設定します（任意）

ネイティブCognito統合はREST APIのみの機能です。Lambda実装が不要なため、ユーザー認証を伴うREST APIでは最もシンプルな選択肢です。

HTTP API: JWT authorizer

HTTP APIでCognitoのトークンを検証するにはJWT authorizerを使用します。JWT authorizerはCognitoに限らず、Auth0・Okta等の標準的なOIDCプロバイダーにも対応しています。

{
  "identitySource": "$request.header.Authorization",
  "jwtConfiguration": {
 "issuer": "https://cognito-idp.ap-northeast-1.amazonaws.com/{user-pool-id}",
 "audience": ["{app-client-id}"]
  }
}

JWT authorizerはissuerが提供するJWKSエンドポイントからRSA公開鍵を取得し、JWTの署名を検証します。audienceにはCognitoアプリクライアントIDを指定します。CognitoのIDトークンを使う場合、audienceはクライアントID・アクセストークンを使う場合はaudienceの検証をJWT authorizerは行わないため、Lambda Authorizerでの追加検証を検討します。

注意: JWT authorizerはHTTP API専用の機能です。REST APIではJWT authorizerを選択できません。REST APIでJWTを検証したい場合はLambda Authorizerを実装します。

Hosted UI連携

Cognito Hosted UIを使ったOAuthフロー（Authorization Code Grant）では、ユーザーがログイン後にIDトークン・アクセストークン・リフレッシュトークンを受け取ります。APIクライアントはIDトークン（またはアクセストークン）をAuthorizationヘッダーに設定してAPIを呼び出します。

トークンの有効期限（デフォルトでIDトークン・アクセストークンともに1時間）に注意し、クライアント側でリフレッシュトークンを使った自動更新を実装します。リフレッシュトークンの有効期限は最大365日で設定可能です。

3-4. Lambda Authorizer（TOKEN/REQUEST）と委譲

Lambda Authorizerは、独自の認証ロジックをLambda関数として実装する認可方式です。旧称「custom authorizer」とも呼ばれます（同一機能です）。社内認証基盤との統合・レガシーシステム連携・複合条件の認可など、標準的な認可方式では対応しきれないシナリオで使用します。

TOKEN型とREQUEST型の比較

AWSが推奨するのはREQUEST型です。 TOKEN型はAuthorizationヘッダーの値（Bearerトークン）のみをLambda関数に渡しますが、REQUEST型はリクエスト全体（ヘッダー・クエリパラメータ・パスパラメータ・コンテキスト変数）を渡します。これにより、IPアドレス・カスタムヘッダー・クエリパラメータを組み合わせた複合条件の認可が実装できます。

IdentityValidationExpressionはTOKEN型専用のオプションです。^Bearer [A-Za-z0-9\-_\.]+$のような正規表現を設定すると、Lambda関数を呼び出す前にトークン形式を事前フィルタリングし、不正形式のリクエストを即座に拒否できます。REQUEST型にはこのオプションは存在しません。

ポリシーキャッシュ

Lambda Authorizerが返すIAMポリシーはAPI Gatewayにキャッシュされます。デフォルトTTLは300秒（5分）で、0〜3600秒の範囲で設定可能です。

キャッシュキーは認可方式によって異なります。

• TOKEN型: Authorizationヘッダー等のトークン文字列
• REQUEST型: Authorizer設定で指定したidentity source（ヘッダー名・クエリパラメータ名等）の値の組み合わせ

キャッシュを有効にすると、同一トークン/identity sourceを持つリクエストでLambda関数の再呼び出しを回避でき、レイテンシ低減とコスト削減に効果があります。即時失効を要するセキュリティ要件では、TTLを0に設定します（全リクエストでLambda呼び出しが発生します）。

ステージ間でキャッシュは共有されません。production・staging等のステージごとに独立したキャッシュが維持されます。また、複数のAPIが同一のLambda Authorizer関数を参照している場合でも、キャッシュは各APIのステージごとに分離されます。

Lambda Authorizer実装の詳細について

Lambda Authorizerの実装詳細（IAMポリシーの返却形式・シンプルレスポンス形式・エラーハンドリング・コールドスタート対策・テスト手法）については、以下の専門記事に詳しく解説しています。本記事ではAPI Gateway全体の認可設計にフォーカスし、実装の深掘りは専門記事に委譲します。

Lambda Authorizer 実装ガイドを読む →

4. 使用量プラン・APIキー・スロットリング・クォータ・収益化設計

4-1. 使用量プランとAPIキー（REST API専用）

使用量プランおよびAPIキーは REST API 専用の機能です。 HTTP API・WebSocket API では利用できません。外部開発者向けのAPI公開やテナント別のアクセス制御を設計する場合は、必ず REST API を選択してください。

APIキーの役割と重要な注意点

APIキーは、クライアントがリクエスト時に x-api-key ヘッダで送信する文字列です。API Gateway はリクエストを受信すると APIキーの有効性と、紐付く使用量プランのスロットリング・クォータ状態を確認します。

APIキーは認証・認可の手段ではありません。 AWS公式ドキュメントでも「Don’t use API keys for authentication or authorization」と明示されています。同一の使用量プランに属する有効なAPIキーを保持するクライアントは、そのプランが許可するすべての API メソッドにアクセスできます。認証・認可には IAM認可・Cognito User Pools Authorizer・Lambda Authorizer を組み合わせて使用してください。APIキーはあくまでアクセスの計測・スロットリング・クォータ管理のための識別子です。

APIキーの作成と有効化手順

1. コンソールまたは CLI で APIキーを作成します（文字列は自動生成またはカスタム指定が可能です）。
2. 使用量プランを作成し、スロットリング設定（rate / burst）とクォータを定義します。
3. 使用量プランに APIキーを追加します。
4. 使用量プランに API ステージ（API ID + ステージ名）を関連付けます。
5. APIメソッドの「APIキー必須」を有効化します（apiKeyRequired: true）。

apiKeyRequired: true を設定していないメソッドは APIキーなしでもアクセスできます。外部向け API ではすべての公開メソッドにこの設定を忘れずに行ってください。

使用量プランの構造

使用量プランには次の3要素を設定します。

複数の APIキーを同一使用量プランに紐付けてプラン全体でスロットリング・クォータを共有する構成も、各キーを別プランに割り当てて個別上限を設定する構成も選べます。外部開発者向けの階層型プラン（無料枠 / スタンダード / プレミアム）を使用量プランで表現するのが一般的なパターンです。

APIキーの管理とセキュリティプラクティス

APIキーはソースコードにハードコードせず、AWS Secrets Manager や Parameter Store（SecureString）に格納し、アプリ起動時に取得するパターンをお勧めします。本番・ステージング・開発環境でキーを分離しておくと、漏洩時の影響範囲をステージ単位に限定できます。定期的なキーのローテーション（APIキーを無効化→新規発行→クライアントへ配布）を運用フローに組み込み、漏洩リスクを最小化してください。

4-2. スロットリングの階層

API Gateway のスロットリングはトークンバケットアルゴリズムで実装されています。rate は1秒あたりのバケット補充レート（RPS: リクエスト毎秒）、burst はバケット容量（瞬間的に許容できるリクエスト数の上限）です。burst を超えたリクエストは HTTP 429 TooManyRequestsException を返します。

スロットリングの適用優先順位（高い順）

スロットリングは複数の層で設定でき、より細かいスコープの設定が優先されます。

1. 使用量プランの per-client / per-method スロットリング（APIキー単位のプラン設定）
2. ステージの per-method スロットリング（ステージ > リソース > メソッドごとの上書き）
3. アカウントレベルスロットリング（AWS アカウント × リージョン単位・全 API タイプ合算）
4. AWS リージョナルスロットリング（AWS インフラ全体の最終防衛ライン）

アカウントレベルスロットリングの詳細

アカウントレベルのデフォルト値は次のとおりです。

このアカウントレベルの上限は、アカウント × リージョン単位で REST / HTTP / WebSocket を含む全 API タイプのリクエストを合算して適用されます。東京リージョン（ap-northeast-1）は 10,000 RPS / 5,000 burst の標準値が適用されます（一部リージョンは低いデフォルト値が設定されています）。

rate の引上げが必要な場合は、AWS コンソールの Service Quotas から「Amazon API Gateway」>「Throttle」(L-8A5B8E43) でクォータ増加リクエストを申請します。burst は Service Quotas では変更できず、必要な場合は AWS サポートへの問い合わせが必要です。

ステージレベル・メソッドレベルのスロットリング

ステージのデフォルトスロットリングをベースに、特定のリソース・メソッドだけ値を上書きできます。たとえば POST /orders は rate 100 RPS に制限しつつ GET /products は rate 1,000 RPS にするといった細粒度の制御が可能です。

REST API では AWS Management Console の「ステージ」>「デフォルトのスロットリング」と「メソッドのスロットリング」で設定します。IaC（Terraform / CloudFormation）を使う場合は aws_api_gateway_stage リソースの default_route_settings と route_settings ブロックで定義します。

使用量プランのスロットリングは、プランへ紐付く APIキーごとに適用されます。プランで rate 500 RPS を設定した場合でも、ステージレベルで rate 200 RPS が設定されていればステージ設定が優先されます。ただし、使用量プランで rate をステージ設定より低く設定した場合は使用量プランが優先されます。常により制限の厳しい（細かい）設定が有効になると理解しておくと設計ミスを防げます。

4-3. クォータ（日・週・月の上限）と収益化設計

クォータは使用量プランに設定するリクエスト総数の上限です。日次・週次・月次から選択します。クォータを超えたリクエストは HTTP 429 を返し、上限は期間終了時にリセットされます。

スロットリングが「瞬間的なリクエストレート」を制御するのに対し、クォータは「累計リクエスト数」を制御します。スロットリングはバックエンドへの過負荷を防ぎ、クォータは無制限消費によるコスト爆発を防ぐという役割分担です。

収益化・テナント別プラン設計の例

外部開発者向けに API を有償提供する場合の典型的な3層設計例を示します。

各テナント（開発者アカウント）に APIキーを発行し、対応する使用量プランに紐付けることでテナント別の流量を個別管理できます。開発者ポータル（Amplify / AWS Marketplace ベースのポータル等）と組み合わせると、APIキーの発行・失効・プラン変更のセルフサービス化が可能です。

スロットリング・クォータはベストエフォートの適用であり、厳密な上限保証ではありません。コスト制御の補完として AWS Budgets によるアラートと AWS WAF による不正リクエストの遮断を組み合わせることをお勧めします。

クォータ残量のモニタリング

各テナントのクォータ消費状況は Usage Plan の使用量 API で取得できます。クォータが残り少なくなっているテナントへの事前通知や、クォータ超過前のプラン変更案内を自動化する場合は次のエンドポイントを利用します。

# APIキーごとの使用量を取得（日次・例）
aws apigateway get-usage \
  --usage-plan-id <plan-id> \
  --key-id <api-key-id> \
  --start-date 2026-06-01 \
  --end-date 2026-06-30

返却値の remainingValue（残余リクエスト数）をもとに、クォータ残量が閾値を下回った場合に Amazon SNS や SES でテナントへ通知するワークフローを EventBridge Scheduler + Lambda で組み込むと運用を自動化できます。

4-4. WAF連携・APIキャッシュ

WAF連携（REST API専用）

AWS WAF（Web Application Firewall）は REST API に直接統合できます。HTTP API では WebACL の直接統合には対応しておらず、CloudFront 経由での WAF 適用が必要になります。

REST API への WAF 統合手順は次のとおりです。

1. AWS WAF コンソールで Web ACL を作成し、リソースタイプに「Amazon API Gateway REST API」を選択します。
2. 適用したいルール（マネージドルールグループ・レートベースルール・カスタム IP ルール等）を追加します。
3. Web ACL に REST API の ARN（arn:aws:apigateway:{region}::/restapis/{api-id}/stages/{stage}）を関連付けます。

WAF を利用することで次のシナリオをカバーできます。

• 特定の IP アドレス・地域からのリクエストをブロックします。
• SQL インジェクション・XSS などの OWASP トップ10対策を組み込めます。
• レートベースルールによる追加の DDoS 緩和が可能です（API Gateway のスロットリングは IP を問わず全体へ作用するため、IP 単位の制限は WAF で行います）。
• 特定の UserAgent やリクエストパターンを遮断できます。

APIキャッシュ（REST API専用）

APIキャッシュも REST API専用の機能です。HTTP API にはキャッシュ機能がありません。キャッシュを有効化すると、指定の TTL（Time To Live）内は同じリクエストに対してバックエンドを呼び出さずキャッシュから応答します。

Cache-Control: max-age=0 によるキャッシュ無効化はデフォルトで任意のクライアントから実行できます。意図しない無効化を防ぐには、ステージ設定の「クライアントからのキャッシュ制御ヘッダ」を「認可が必要」に変更し、execute-api:InvalidateCache アクションを持つ IAM ポリシーを付与したクライアントのみに制限してください。

キャッシュキーの設計も重要です。デフォルトではパスのみがキーになりますが、クエリ文字列パラメータ（例: ?userId=xxx）やカスタムヘッダをキーに含めることで、テナント別・ユーザー別のキャッシュが可能になります。ただしキーの多様性が高すぎると実質的にキャッシュが効かなくなるため、キャッシュキーは最小限の識別子に絞ることをお勧めします。

4-5. 429対策とバックオフ

スロットリングに起因する HTTP 429 TooManyRequestsException を受けたクライアントは、指数バックオフ（Exponential Backoff）と Jitter（ランダムな遅延）を組み合わせたリトライを実装することが標準的なパターンです。

import time
import random
import urllib.request
import urllib.error

def call_api_with_backoff(url, api_key, max_retries=5):
 delay = 0.5  # 初期待機秒
 for attempt in range(max_retries):
  req = urllib.request.Request(url, headers={"x-api-key": api_key})
  try:
response = urllib.request.urlopen(req)
return response.read()
  except urllib.error.HTTPError as e:
if e.code == 429 and attempt < max_retries - 1:
 jitter = random.uniform(0, delay)
 time.sleep(delay + jitter)
 delay = min(delay * 2, 30)  # 最大30秒まで指数増加
else:
 raise

AWS SDK（boto3 等）は Retry 設定で mode='adaptive' または mode='standard' を指定することで、429 レスポンスへの自動リトライを組み込めます。mode='adaptive' は前回のリトライ結果を学習してバックオフを動的に調整します。高負荷なバースト期間が短い場合は standard で十分ですが、定常的なスロットリングが発生する運用では adaptive が有効です。

クライアント側のリトライ実装と合わせて、サーバー側でスロットリング設定が適切かをモニタリングすることも重要です。CloudWatch の 4XXError メトリクスと Count メトリクスを組み合わせ、スロットリング率（4XX / Count）をダッシュボードで可視化すると設計の妥当性を継続的に評価できます。スロットリング率が常時高い場合は使用量プランの rate 設定やアカウントレベル上限の引上げを検討してください。

5. mTLS・カスタムドメイン・ACM・エッジ vs リージョナル

5-1. エンドポイントタイプ（Edge-optimized/Regional/Private）

REST API のエンドポイントタイプは Edge-optimized・Regional・Private の 3 種類です。API の利用者分布・セキュリティ要件・mTLS の有無に応じて選択します。

Edge-optimized（エッジ最適化）

Edge-optimized は REST API 作成時のデフォルトエンドポイントタイプです。リクエストは AWS の CloudFront エッジロケーション（世界 400 か所以上）を経由してから、API Gateway が配置されているリージョンに届きます。

• リクエスト経路: クライアント → 最寄りの CloudFront エッジ → API Gateway（東京など）
• 利点: グローバルに分散したクライアントへの低レイテンシ、CloudFront の大規模ネットワーク活用
• 制約: mTLS は利用できません（後述の Regional 必須制約の帰結）。また、カスタムドメインに関連付ける ACM 証明書は us-east-1（バージニア北部） で発行したものが必要です。CloudFront の仕様でリージョン横断参照ができないためです

Regional（リージョナル）

Regional エンドポイントは CloudFront を介さず、API Gateway が配置されたリージョンに直接リクエストが到達します。同一 VPC 内サービスや同一リージョンのクライアントからの呼び出しに適しています。

• リクエスト経路: クライアント → API Gateway（同一リージョン）
• 利点: mTLS に対応。ACM 証明書は API と同一リージョンで完結（例：東京の REST API には ap-northeast-1 の ACM 証明書を使用）
• 独自の CloudFront ディストリビューションを前段に置いてエッジキャッシュを組み合わせることも可能です

Private

Private エンドポイントは VPC 内の Interface VPC Endpoint（PrivateLink）経由のみでアクセスできます。インターネットには公開されない完全なプライベート API です。

• アクセス方法: com.amazonaws.[region].execute-api の VPC Endpoint 経由のみ
• リソースポリシーで許可する VPC/VPC Endpoint を明示する必要があります
• mTLS には対応していません

HTTP API は Regional のみ対応（Edge-optimized・Private は選択不可）です。WebSocket API も Regional のみです。

5-2. カスタムドメインとACM証明書

カスタムドメインを設定することで、api.example.com のような独自ドメインで API を公開できます。設定手順はエンドポイントタイプによって異なります。

ACM 証明書リージョンの使い分け（最重要）

最も間違えやすいポイントが ACM 証明書のリージョンです。

• Edge-optimized の場合: 証明書は us-east-1（バージニア北部） で発行・管理します。Edge-optimized が内部的に CloudFront を使用しており、CloudFront は us-east-1 の ACM 証明書しか参照できない仕様だからです。東京（ap-northeast-1）で作成した証明書を Edge-optimized カスタムドメインに関連付けることはできません
• Regional の場合: 証明書は API と同じリージョンで発行します。東京リージョンの Regional API には ap-northeast-1 の ACM 証明書を使用します

「ACM 証明書は常に us-east-1 に作成すればよい」という誤解がありますが、Regional エンドポイントにはその証明書を使用できません。エンドポイントタイプに応じてリージョンを使い分けてください。

ワイルドカード証明書 vs 単一ドメイン証明書

ACM では用途に応じた証明書タイプを選択できます。

• 単一ドメイン証明書（api.example.com）: 特定のサブドメイン専用。API ごとに証明書を分離管理したい場合に適しています
• ワイルドカード証明書（*.example.com）: 同一ドメイン配下の複数サブドメインに 1 枚で対応できます。api.example.com・admin.example.com など複数の API カスタムドメインを同一ドメイン配下へ置く場合にコスト効率が向上します

なお、ワイルドカード証明書は 1 階層のみに有効（*.example.com は api.example.com に有効だが a.api.example.com には無効）です。マルチテナント設計でテナントごとに 2 階層以上のサブドメインを切る場合は個別証明書を発行してください。

Route 53 + カスタムドメイン設定手順

1. ACM で証明書を発行します（DNS 検証方式を推奨。Route 53 ホストゾーンがあれば CNAME レコードを自動作成できます）
2. API Gateway コンソールの「カスタムドメイン名」でドメインを作成し、ACM 証明書を選択します
3. 作成後に表示される CloudFront ドメイン名（Edge-optimized）または API Gateway ドメイン名（Regional: d-xxxxxxxxxx.execute-api.[region].amazonaws.com）をメモします
4. Route 53 のホストゾーンで エイリアスレコード（A/AAAA） を作成し、上記ドメイン名をターゲットに設定します

Route 53 のエイリアスレコードは CNAME より推奨です。Route 53 クエリ料金が発生しない・Zone Apex（example.com そのもの）でも設定可能という利点があります。

ベースパスマッピング

カスタムドメインと実際の API/ステージを結びつける仕組みがベースパスマッピングです。

api.example.com/v1  → MyRestAPI / prod ステージ
api.example.com/v2  → MyRestAPI / v2 ステージ
api.example.com/ws  → MyWebSocketAPI / prod ステージ

• 1 つのカスタムドメインに複数のベースパスマッピングを設定できます
• ベースパスを空（/）にすると、カスタムドメインのルートが特定の API/ステージに直接マッピングされます
• カスタムドメインのベースパスマッピングを切り替えることで、API バージョン移行をドメインレベルで実現できます（§7-4 で詳述）

5-3. mTLS（相互TLS認証）

mTLS（Mutual TLS：相互 TLS 認証）は、サーバー証明書によるサーバー認証に加えて、クライアント証明書でクライアントを認証する方式です。API Gateway では REST API・HTTP API の両方で mTLS に対応しています。

mTLS の前提条件：Regional カスタムドメイン必須

mTLS を有効にするには Regional カスタムドメインが必須です。Edge-optimized エンドポイントおよび Private エンドポイントでは mTLS は利用できません。mTLS 対応を明文化した公式ドキュメントの記述上は「Regional 必須」という帰結として示されており、Edge-optimized での mTLS は構成上実現できません。

既存の Edge-optimized API に mTLS を追加したい場合は、エンドポイントタイプを Regional に変更し、Regional カスタムドメインを設定し直す必要があります。

truststore の設定

mTLS の核心は truststore（信頼ストア） の設定です。API Gateway は truststore に登録された CA（認証局）が署名したクライアント証明書のみを受け入れます。

• truststore は S3 バケットに格納した PEM 形式の CA 証明書バンドルとして定義します
• 証明書バンドルはルート CA まで完全な信頼チェーンを含める必要があります。中間 CA のみでは機能しません
• 信頼チェーンの最大長は 4 段です（例: ルート CA → 中間 CA → 発行 CA → クライアント証明書）
• API Gateway カスタムドメインの mutualTlsAuthentication.truststoreUri に S3 URI（s3://bucket/truststore.pem）とオブジェクトバージョンを指定します
• S3 バージョニングを有効にしておくと、truststore 更新後に旧バージョンへのロールバックが容易になります

クライアント証明書の検証フロー

クライアント
 │  TLS ハンドシェイク時にクライアント証明書を提示
 ▼
API Gateway（Regional カスタムドメイン）
 │  truststore（S3 の CA 証明書バンドル）で署名チェーン全体を検証
 │  ─ 検証成功: 認証通過 → バックエンドへリクエスト転送
 │  ─ 検証失敗: 403 Forbidden（TLS ハンドシェイク段階で拒否）
 ▼
バックエンド（Lambda・HTTP 統合など）

CLI による mTLS カスタムドメインの作成

Regional カスタムドメインを作成して mTLS を有効化するには、次の AWS CLI コマンドを使用します。regionalCertificateArn には API と同一リージョンの ACM 証明書 ARN を指定します。

# Regional カスタムドメインに mTLS を設定（AWS CLI）
aws apigateway create-domain-name \
  --domain-name "api.example.com" \
  --regional-certificate-arn \
 "arn:aws:acm:ap-northeast-1:123456789012:certificate/xxxx-xxxx" \
  --endpoint-configuration '{"types":["REGIONAL"]}' \
  --mutual-tls-authentication \
 '{"truststoreUri":"s3://my-truststore-bucket/truststore.pem",
"truststoreVersion":"<s3-version-id>"}'

truststore の CA 証明書バンドル（PEM ファイル）を更新する場合は、S3 に新しい PEM をアップロードして S3 バージョン ID を取得してから、ドメイン設定を更新します。S3 バージョニングを有効にしておくと旧バンドルへのロールバックが即時に行えます。

# truststore CA バンドルのバージョンを更新する
aws apigateway update-domain-name \
  --domain-name "api.example.com" \
  --patch-operations \
 op=replace,path=/mutualTlsAuthentication/truststoreVersion,value=<new-s3-version-id>

更新前に OpenSSL で証明書チェーンが完全につながっているかを検証することを推奨します。openssl verify -CAfile truststore.pem client.crt でクライアント証明書がバンドル内の CA で検証できるかを事前確認できます。

証明書失効（CRL/OCSP）の取り扱い

API Gateway の mTLS は CRL（証明書失効リスト）や OCSP（Online Certificate Status Protocol）による失効確認を自動では行いません。truststore に登録された CA の署名が有効であれば、失効済み証明書でも mTLS 認証を通過します。

失効した証明書を拒否する必要がある場合は、Lambda Authorizer と組み合わせて実装します。Lambda Authorizer のリクエストコンテキストにはクライアント証明書情報（$context.identity.clientCert.serialNumber・$context.identity.clientCert.subjectDN など）が含まれており、シリアル番号を CRL と照合するロジックを追加できます。

mTLS の強制：default execute-api エンドポイントの無効化

カスタムドメインで mTLS を設定しても、デフォルトの execute-api エンドポイント（https://[api-id].execute-api.[region].amazonaws.com/[stage]）は引き続きクライアント証明書なしでアクセス可能です。mTLS を実質的に強制するには、このデフォルトエンドポイントを無効化する必要があります。

API の設定で disableExecuteApiEndpoint: true を指定すると、execute-api エンドポイントへのアクセスが 403 で拒否されます。これによりすべてのクライアントがカスタムドメイン（mTLS 有効）経由でのみ API にアクセスできる状態を強制できます。

truststore（クライアント信頼 CA）と ACM サーバー証明書は別物

混乱しやすいポイントとして、2 種類の証明書の役割を整理します。

• ACM サーバー証明書: カスタムドメインに関連付けるドメイン証明書（api.example.com のサーバー証明書）。API Gateway がサーバーとして提示します
• truststore（S3 の CA 証明書バンドル）: クライアント証明書を誰が発行したかを検証するための CA 証明書群。API Gateway がクライアントを検証するために使用します

これらは完全に別の証明書管理です。ACM 証明書を truststore に流用することはありません。

5-4. WAF/Shield連携（REST API）

AWS WAF との統合

AWS WAF（Web Application Firewall）を API Gateway と直接統合できるのは REST API のみです。HTTP API・WebSocket API への AWS WAF 直接統合は対応していません。

REST API への WAF 設定手順は以下のとおりです。

1. AWS WAF コンソールで Web ACL を作成します（リソースタイプ: Regional resources を選択）
2. WAF Web ACL に必要なルールを追加します（AWSManagedRulesCommonRuleSet などのマネージドルールグループ、IP セット、レートベースルールなど）
3. API Gateway の REST API ステージに Web ACL を アソシエイトします

HTTP API で WAF が必要な場合は、API Gateway の前段に CloudFront ディストリビューションを配置し、CloudFront に WAF をアタッチする構成で代替します。この構成では CloudFront のキャッシュ機能も併用できます。

AWS Shield との関係

• AWS Shield Standard: すべての AWS リソースに自動適用されます。追加設定不要で L3/L4 レベルの DDoS 攻撃（SYN フラッド・UDP 反射攻撃など）からの保護が有効です
• AWS Shield Advanced: 有償オプション。API Gateway の REST API を保護対象リソースとして登録することで、L7 DDoS 攻撃の自動軽減・DDoS コスト保護（急増した AWS 料金の免除申請）・24×7 の DRT（DDoS Response Team）サポートを利用できます

mTLS + WAF の組み合わせ

mTLS と WAF を同時に利用する構成（Regional エンドポイント + カスタムドメイン + mTLS + WAF）は、ゼロトラスト志向のアクセス制御を実現する一般的なパターンです。クライアント証明書で「誰がアクセスしてよいか」を認証し、WAF で「どのようなリクエストを許可するか」をフィルタリングします。API キーや IP 制限だけでは対応できない高いセキュリティ要件に対して有効な組み合わせです。

6. 可観測性：CloudWatch/X-Ray・アクセスログ・エラー分類

6-1. CloudWatch メトリクス

API Gateway はリクエストを受け取るたびにメトリクスを CloudWatch へ自動送信します。ただし REST API と HTTP API ではメトリクス名・ディメンション名が異なるため、アラーム設計時に混用しないよう注意が必要です。

REST API メトリクス（名前空間: AWS/ApiGateway）

Latency と IntegrationLatency の関係

Latency − IntegrationLatency がゲートウェイ自体のオーバーヘッドを表します。IntegrationLatency が急増している場合はバックエンド（Lambda / 外部 HTTP）側のボトルネックを疑います。Latency だけが増加している場合は API Gateway の処理やネットワーク経路を調査してください。

エラー率の算出

4XXError / 5XXError のエラー率を確認するには Average 統計を使います。SampleCount を用いると件数になるため、パーセンテージでアラームを設定する場合は Average を指定してください。

HTTP API メトリクス（名前空間: AWS/ApiGateway）

HTTP API は REST API とメトリクス名が異なります。アラームを作成する際に混用すると意図しない結果になるため、注意してください。

REST API 用に作成した 4XXError アラームをそのまま HTTP API へ流用できません。HTTP API でアラームを設定する際は 4xx / 5xx（小文字）を使い、ディメンションには ApiId を指定してください。

メソッドレベルの詳細メトリクス

デフォルトでは API・ステージ単位のメトリクスのみが送信されます。メソッド・リソース単位の詳細メトリクスを取得するには Detailed metrics（詳細メトリクス） を有効にする必要があります。有効化すると追加コストが発生するため、大規模な API では監視対象のリソースを絞り込むことを推奨します。

6-2. 実行ログとアクセスログ

API Gateway のログには「実行ログ（Execution Logs）」と「アクセスログ（Access Logs）」の 2 種類があります。それぞれ役割が異なり、両方を適切に設定することで可観測性が高まります。

IAM ロールの設定（前提条件）

実行ログを CloudWatch Logs に書き込むには、API Gateway が logs:CreateLogGroup / logs:PutLogEvents 等の権限を持つ IAM ロールを アカウントレベル（API Gateway コンソール → Settings → CloudWatch log role ARN）で設定する必要があります。このロールはアカウント内の全 REST API で共有されます。設定を忘れると実行ログが一切出力されないため、セットアップ初期に確認してください。

実行ログ（Execution Logs）

実行ログはリクエストの処理フローを詳細に記録します。ステージ設定の Logging level で 3 段階を選択できます。

実行ログのロググループは /aws/apigateway/{api-id}/{stage} 形式で自動作成されます。Lambda Authorizer の呼び出し結果やリクエスト/レスポンスの変換内容も含まれるため、認可フローのトラブルシューティングに有効です。

アクセスログ（Access Logs）

アクセスログは各リクエストの記録を $context 変数 でカスタマイズできます。出力形式は CLF / JSON / XML / CSV から選択できます。本番運用では JSON 形式が CloudWatch Logs Insights や外部 SIEM への取り込みに適しています。

設定場所はステージの Log Format フィールドです。よく使われる $context 変数の例を以下に示します。

{
  "requestId": "$context.requestId",
  "ip": "$context.identity.sourceIp",
  "httpMethod": "$context.httpMethod",
  "resourcePath": "$context.resourcePath",
  "status": "$context.status",
  "responseLength": "$context.responseLength",
  "integrationLatency": "$context.integrationLatency",
  "responseLatency": "$context.responseLatency",
  "errorMessage": "$context.error.message"
}

$context.integrationLatency と $context.responseLatency を記録しておくことで、ゲートウェイのオーバーヘッドをログから直接算出できます。宛先の CloudWatch Logs グループは事前に作成しておき、ARN をステージ設定の Access log destination ARN に指定してください。

実行ログとアクセスログは独立して設定するため、両方を有効にすることを推奨します。

CloudWatch Logs Insights でのログ分析

JSON 形式のアクセスログは CloudWatch Logs Insights でそのまま集計・可視化できます。以下は運用でよく使うクエリ例です。

上位エラーリクエストの特定（5XX 絞り込み）

fields @timestamp, httpMethod, resourcePath, status, errorMessage, ip
| filter status >= 500
| sort @timestamp desc
| limit 50

エンドポイント別の平均レイテンシ確認

fields resourcePath, integrationLatency, responseLatency
| stats avg(integrationLatency) as avgInteg,
  avg(responseLatency) as avgTotal,
  count(*) as reqCount
  by resourcePath
| sort avgTotal desc

429 スロットリングのタイムライン確認

fields @timestamp, ip, resourcePath
| filter status = 429
| stats count(*) as throttled by bin(1m)
| sort @timestamp asc

これらのクエリは CloudWatch Logs Insights コンソールの「クエリ」タブから実行できます。Logs Insights はスキャンしたデータ量に応じた従量課金のため、時間範囲を必要最小限に絞ってから実行することをお勧めします。

6-3. X-Ray トレーシング（REST API 専用）

X-Ray を使った分散トレーシングは REST API のみで利用できます。HTTP API および WebSocket API には対応していません。

REST API での X-Ray 有効化

ステージ設定の X-Ray Tracing をオンにするだけで有効になります。追加コードは不要です。有効化すると API Gateway がリクエストに X-Amzn-Trace-Id ヘッダーを付与し、バックエンド（Lambda 等）へ伝播します。Lambda 側でも X-Ray が有効であれば、エンドツーエンドのサービスマップが自動生成されます。

サンプリング

デフォルトのサンプリングレートは 最初の 1 リクエスト/秒 + それ以降の 5% です。高トラフィック環境では全リクエストをトレースするとコストが増大するため、X-Ray コンソールの Sampling rules でサービス名やパスに応じてレートを調整することを推奨します。

トレース ID の伝播

API Gateway は X-Amzn-Trace-Id ヘッダーにトレース ID を付与してバックエンドに転送します。Lambda 関数が X-Ray 対応であれば自動的にトレースが連結されます。独自の HTTP 統合先でも同ヘッダーを受け取り伝播させることで、サービスマップを繋げることができます。

サービスマップとアナリティクス

X-Ray コンソールのサービスマップでは、API Gateway → Lambda → DynamoDB 等の呼び出しグラフが可視化されます。各ノードのレスポンスタイムや 4XX/5XX 件数のフィルタリングも可能です。トレースアナリティクスを活用すると、特定エラーが集中するリクエストのパターン（ユーザー IP・リソースパス等）を素早く特定できます。

HTTP API / WebSocket API での代替手段

HTTP API や WebSocket API で分散トレーシングを実現するには、以下の方法を検討してください。

• Lambda 側での X-Ray SDK / ADOT 実装: Lambda 関数内でトレースを開始し、ダウンストリームの呼び出しへ伝播させます。
• CloudWatch ServiceLens: CloudWatch コンソールから Lambda / API Gateway の関連メトリクスとログをまとめて確認できます。API Gateway のアクセスログと Lambda の X-Ray トレースを組み合わせることで、エンドツーエンドの可観測性を実現できます。

6-4. エラー分類とアラート設計

API Gateway のエラーは クライアント起因（4XX） と サーバー/統合起因（5XX） に大別されます。どちらのカテゴリかを把握することがトラブルシューティングの出発点です。

4XX エラー（クライアントエラー）

429 はスロットリング検知の主要シグナルです。急増時はアカウントレベルのレート上限（デフォルト 10,000 RPS）または使用量プランのクォータ・バースト設定を確認してください。Service Quotas でレート上限の引き上げが可能です。

5XX エラー（サーバー/統合エラー）

504 は Lambda の処理時間が REST API のタイムアウト上限（29 秒 / HTTP API は 30 秒）を超えた場合に発生します。継続して発生する場合はバックエンドの処理時間最適化や、SQS を使った非同期化を検討してください。

CloudWatch Alarms の設計

エラー率アラーム

4XXError または 5XXError の Average 統計を使い、5 分間の平均が閾値（例: 0.01 = 1%）を超えた場合にアラームを発火します。閾値はシステムの許容エラー率に応じて調整してください。

429 スロットリング専用アラーム

4XXError はスロットリング以外のクライアントエラーも含みます。スロットリング専用の検知には、アクセスログ（$context.status）から 429 のみをフィルタリングする CloudWatch Logs メトリクスフィルタを作成する方法が有効です。REST API では X-Ray アナリティクスでも 429 を抽出できます。

Latency アラーム

Latency の p99 が目標値（例: 3,000 ms）を超えた場合にアラームを発火します。IntegrationLatency を並行して監視することで、ボトルネックがゲートウェイ側かバックエンド側かを切り分けられます。

アラームアクション

AlarmActions に SNS トピックを設定し、PagerDuty / Slack 等のインシデント管理ツールと連携させることを推奨します。

7. デプロイ・ステージ変数・カナリアリリース・ブルーグリーン

7-1. デプロイとステージ

REST APIでは、APIの設定（リソース定義・メソッド設定・統合設定）をデプロイする際に明示的なデプロイ操作が必要です。デプロイとは、その時点のAPI設定スナップショットを作成し、特定のステージに関連付ける操作を指します。

ステージはAPIの発行版（dev / staging / prod など）を表す論理的な単位です。同一のAPIデプロイメントを複数ステージへ関連付けることも可能です。ステージの設定変更（スロットリング設定・ログ設定・キャッシュ設定など）は、再デプロイなしに反映されます。

# REST API の明示デプロイ（AWS CLI）
aws apigateway create-deployment \
  --rest-api-id "abc123" \
  --stage-name "prod" \
  --description "2026-06-29 リリース: カナリア設定追加"

一方、HTTP APIでは自動デプロイが利用できます。HTTP APIには$defaultステージが用意されており、AutoDeployオプションを有効にするとルート変更が自動的に即時反映されます。デフォルトはfalse（手動デプロイ）ですが、開発・検証環境ではtrueに設定すると利便性が高まります。

# HTTP API の自動デプロイ有効化（既存ステージ更新）
aws apigatewayv2 update-stage \
  --api-id "xyz789" \
  --stage-name "\$default" \
  --auto-deploy

REST APIのステージには実行ログとアクセスログを個別に設定できます。実行ログはアカウント単位のCloudWatch Logs Role（IAMロール）の設定が前提です。この設定を忘れるとログが出力されないため、初期セットアップ時に必ず確認してください。

7-2. ステージ変数

ステージ変数は、ステージごとに異なる値を保持するキー・バリュー形式の設定です。Lambda関数のARN（エイリアス）・HTTPエンドポイントURL・データベース接続文字列などを環境ごとに切り替える用途で活用します。

# ステージ変数の例（dev / prod 環境ごとに別設定）
lambdaAlias = "prod"
backendUrl  = "https://api.internal.example.com"

Lambda統合でステージ変数を使う場合、統合URIにプレースホルダーを埋め込みます。

統合URI: arn:aws:lambda:ap-northeast-1:123456789:function:MyFunc:${stageVariables.lambdaAlias}

この設定により、devステージではlambdaAlias=devを、prodステージではlambdaAlias=prodを参照し、API定義を変更せずに環境を切り替えられます。

# ステージ変数の設定・更新（REST API）
aws apigateway update-stage \
  --rest-api-id "abc123" \
  --stage-name "prod" \
  --patch-operations \
 op=replace,path=/variables/lambdaAlias,value=prod

ステージ変数を使う際の注意点：

• ステージ変数は秘匿のための機構ではありません。パスワード・シークレットなどの機密情報はAWS Secrets ManagerまたはSSM Parameter Store（SecureString型）に格納し、LambdaランタイムからSDK経由で取得してください。
• ステージ変数で参照するLambda ARN（エイリアス）を変更した場合、新しいLambda ARNに対するlambda:InvokeFunction権限がリソースベースポリシーに存在するかを確認してください。変数変更のみではポリシーが自動更新されません。
• stageVariableOverrides（カナリア設定で利用）はステージ変数の「上書き（置換ではなく追記上書き）」です。カナリア向けトラフィックにだけ異なるLambdaエイリアスを向ける際に有効です。

ステージ変数の代表的な活用パターン

パターン1: Lambdaエイリアスによる環境切替

1つのREST APIをdev・staging・prodの3ステージで共有し、ステージ変数lambdaAliasでLambdaのバージョン（エイリアス）を切り替えるパターンです。API定義を変更せずにdevステージではLambdaの$LATESTを、prodステージでは安定エイリアスv2を参照できます。

dev  ステージ: lambdaAlias = $LATEST  → Lambda:$LATEST（最新開発版）
staging ステージ: lambdaAlias = v2 → Lambda:v2（検証済み版）
prod ステージ: lambdaAlias = stable→ Lambda:stable（本番版）

パターン2: HTTPバックエンドの環境切替

HTTPプロキシ統合でバックエンドURLをステージごとに変える場合にも有効です。

dev  ステージ: backendUrl = https://dev-api.internal.example.com
prod ステージ: backendUrl = https://api.internal.example.com

統合URIをhttps://${stageVariables.backendUrl}/pathと設定しておくことで、ステージ変数の切替のみで接続先を変えられます。

パターン3: 機能フラグの代替

軽量な機能フラグ的使い方として、featureXEnabled = trueのようなブール値をステージ変数に持つ場合もあります。ただしステージ変数はAPI Gateway側の設定であり、Lambda内のロジック分岐はリクエストコンテキスト経由での受け渡し（VTLマッピングまたはプロキシ統合のevent）が必要です。より柔軟な機能フラグ管理が必要な場合はAWS AppConfigを検討してください。

7-3. カナリアリリースデプロイ（REST API専用）

カナリアリリースはREST API専用の機能です。HTTP APIにはカナリアリリース機能が存在しないため、設計の出発点でAPIタイプを確定してください。

カナリアリリースでは、ステージのトラフィックを本番（既存デプロイメント）とカナリア（新デプロイメント）に分割します。比率はpercentTrafficで指定し、0.0〜100.0の浮動小数で設定します。

# カナリアデプロイの作成（新しいデプロイメントをカナリア10%で投入）
aws apigateway create-deployment \
  --rest-api-id "abc123" \
  --stage-name "prod" \
  --canary-settings '{
 "percentTraffic": 10.0,
 "useStageCache": false
  }'

カナリアに送られたリクエストのログは、通常ステージのログ（/prod）とは独立したカナリア専用ログ（/prod/Canary）に出力されます。これにより、カナリアリリース中のエラー率・レイテンシを本番トラフィックと分けてモニタリングできます。

カナリア変数（stageVariableOverrides）を使うと、カナリア向けトラフィックのみ異なるステージ変数を上書き適用できます。Lambda エイリアスを環境ごとに切り替えるパターンで特に有効です。

# カナリア変数上書き設定の例
aws apigateway create-deployment \
  --rest-api-id "abc123" \
  --stage-name "prod" \
  --canary-settings '{
 "percentTraffic": 10.0,
 "stageVariableOverrides": {
"lambdaAlias": "canary"
 },
 "useStageCache": false
  }'

カナリア中のデプロイロック：アクティブなカナリアが存在するステージへの通常デプロイ（非カナリアデプロイ）はロックされます。カナリアを本番昇格またはロールバックで解除してから、次のリリース操作を実施してください。

# カナリア → 本番昇格（percentTrafficを100に設定して昇格）
aws apigateway update-stage \
  --rest-api-id "abc123" \
  --stage-name "prod" \
  --patch-operations \
 op=replace,path=/canarySettings/percentTraffic,value=100.0

# ロールバック（カナリアを無効化して旧デプロイメントに戻す）
aws apigateway delete-stage-canary \
  --rest-api-id "abc123" \
  --stage-name "prod"

カナリアリリースの推奨フロー：

1. 新コードをLambda関数（canaryエイリアス）へデプロイします。
2. API Gatewayのカナリア設定でpercentTraffic=5.0〜10.0から開始します。
3. CloudWatchメトリクスとアラームで新バージョンのエラー率・レイテンシを監視します。
4. 問題がなければpercentTrafficを段階的に引き上げ（25→50→100）、最終的に本番昇格します。
5. 問題が発生した場合はdelete-stage-canaryでロールバックし、旧バージョンへ即座に戻します。

7-4. ブルーグリーン的な切替戦略

API Gatewayには専用のブルーグリーンデプロイ機能はありませんが、カスタムドメインとベースパスマッピングを活用することで同等の切替を実現できます。

基本構成：

カスタムドメイン: api.example.com
  ├── /v1 → Blue API（prod ステージ）  ← 現在の本番
  └── /v2 → Green API（prod ステージ） ← 新バージョン（検証中）

Green APIの検証が完了したら、ベースパスマッピングを更新して/v1をGreen APIへ切り替えます。

# ベースパスマッピングの更新（Blue → Green 切替）
aws apigateway update-base-path-mapping \
  --domain-name "api.example.com" \
  --base-path "v1" \
  --patch-operations \
 op=replace,path=/restapiId,value=<green-api-id>

この切替はAPIレベルでのほぼアトミックな操作であり、DNS TTLを待たずに即時反映されます。ロールバックも同様のコマンドで旧Blue APIのIDを再指定するだけです。

カナリアリリースとブルーグリーンの使い分け：

8. まとめ・コスト最適化・運用ベストプラクティス

8-1. API Gateway 本番運用の全体像（再掲）

本記事ではAmazon API Gatewayを「Lambdaの前段」ではなく「API公開基盤」として捉え、以下の設計要素を体系化しました。

本記事全体を通じて、REST APIとHTTP APIで機能の対応範囲が大きく異なる点こそ最重要事項です。設計の初期段階でAPI種別を確定し、後から移行コストが発生しないよう計画してください。

8-2. コストの考え方

API GatewayのコストはAPIタイプによって大きく異なります。

REST API vs HTTP API のコスト差（US East-1 第1層・2026年時点の参考値）：

東京リージョン（ap-northeast-1）の単価はUS East-1と異なります。実際の見積もりはAWS公式料金ページの東京タブで最新値をご確認ください（本記事の数値は参考値です）。

WebSocket APIはメッセージ数と接続時間（分単位）で課金されます。双方向通信が必要なユースケースで選択しますが、クライアントが接続を維持するだけでもアイドル接続時間の料金が発生する点に注意してください。

コスト削減のポイント：

• 使用量プラン・APIキャッシュ・WAF直接統合・カナリアリリース・X-Rayが不要であれば、REST APIではなくHTTP APIを採用することで約71%のリクエスト料金削減が見込めます。
• REST APIのAPIキャッシュを有効化すると、同一リクエストのバックエンド呼び出しをスキップできます。Lambda実行コスト・バックエンド負荷の削減効果とキャッシュ料金（GB・時間単位）を比較した上で判断してください。
• AWS Budgetsでコスト上限アラートを設定し、想定外の課金増加を早期検知できる体制を整えてください。トラフィック急増時には使用量プランのクォータがコスト制御の最終防衛ラインになります。

8-3. 運用ベストプラクティスまとめ

API種別選定：設計の最初にAPI種別（REST / HTTP / WebSocket）を確定してください。使用量プラン・APIキャッシュ・WAF直接統合・カナリアリリース・X-Rayが必要な場合はREST APIを選択します。低コスト・低レイテンシでJWT認可を使いたい場合はHTTP APIが最適です。後から種別を変更するにはAPI定義の再作成が必要になります。

認可設計：APIキーは認証・認可の手段ではありません（AWSドキュメントに明記）。同一使用量プラン内の有効なAPIキー保持者はそのプランに紐づく全APIへアクセスできます。アクセス制御にはIAM認可・Lambda Authorizer・Cognitoを使用し、APIキーはスロットリングと使用量の計測目的に限定してください。

スロットリング設計：アカウントレベルのデフォルト（rate: 10,000 RPS / burst: 5,000）はアカウント全体のリクエストに適用される上限です。本番トラフィックが大きいAPIでは、使用量プランのper-methodスロットリングでAPI単位に保護してください。必要に応じてService Quotas（クォータID: L-8A5B8E43）でアカウントレベルの上限引き上げを申請できます。

タイムアウト設計：API Gatewayの統合タイムアウト上限は29秒です（調整不可）。バックエンド処理が29秒を超えるユースケースでは、非同期パターン（SQSキュー受付→Lambda非同期実行→ポーリングまたはWebSocket結果通知）への設計変更を検討してください。

mTLS・エンドポイント設計：mTLSを採用する場合はRegionalカスタムドメインが必須です。Edge-optimizedエンドポイントではmTLSを使用できません。ACM証明書は、Edge-optimizedにはus-east-1リージョン、RegionalにはAPIと同一リージョンの証明書が必要です（Edge-optimizedでも東京の証明書では動作しません）。

可観測性：X-RayトレースはREST API専用です。HTTP APIやWebSocket APIのトレースにはアプリケーション層でのOpenTelemetry実装などを検討してください。CloudWatchメトリクスではREST APIの4XXError（大文字）とHTTP APIの4xx（小文字）はメトリクス名が異なります。アラーム設定時に混同しないよう注意してください。

カナリアリリース：本番LambdaのエイリアスとAPI Gatewayのカナリアリリースを組み合わせることで、安全な段階的デプロイが実現できます。カナリアはREST API専用であるため、HTTP APIを採用している場合はRoute 53加重ルーティングやAWS App Meshなど、アプリケーション層でのカナリア設計を検討してください。

8-4. 次巻予告

Vol2では、本記事で固めた設計基盤をスケールアップするための発展テーマを扱う予定です。

• OpenAPI定義 & IaC（AWS CDK / SAM / Terraform）による自動化：API GatewayをInfrastructure as Codeで管理し、デプロイパイプラインへ組み込む実践的な設計
• マルチテナントAPI設計：テナントごとの使用量プラン・スロットリング・ログ分離設計とコスト配賦の考え方
• API GatewayとAppSync（GraphQL）の使い分け：REST APIとGraphQL APIのユースケース分離指針と移行パターン

Lambda Authorizer の実装詳細はこちら