AWS Serverless デジタルバッジを取得する⑧ API Gateway編

このデジタルバッジ取得のために、AWS Skill Builderのこのコースを学習している記録

自分のスキルレベルは以下。

• SAAは取得
  • 4年前ぐらい
• 実務利用なし
  • 趣味レベルではあり

Amazon API Gateway for Serverless Applications (日本語字幕版)

API Gateway の紹介

今更！？

API 管理の課題

• サーバーレスアプリケーションでの API コールの処理
• 複数の API バージョンおよび環境での使用
• アクセスの制御と認可
• トラフィックの急上昇の管理
• サードパーティーのアクセスのモニタリング

API Gateway を API のフロントドアとして使用する

• 活用の例
  • 気象局 API
  • ソーシャルアイデンティティプロバイダー API

API Gateway の機能

• API Gateway のデベロッパー向け機能
  • APIの複数バージョンを同時実行
  • 迅速なSDKの作成
    • REST API を使用している場合、いくつかのプラットフォーム向けのクライアントソフトウェア開発キット (SDK) を生成可能
    • AWS CLIのget-sdkコマンドで生成
      • Java
      • JavaScript
      • Java for Android
      • iOS 用の Objective-C
      • Swift
      • Ruby
  • リクエスト・レスポンスデータの変換・検証
    • 受信・送信リクエストを変換・検証可能
    • バックエンドに渡す前処理として。
• API アクセスを管理する機能
  • レイテンシーの提言とトラフィックのスロットル
    • CloudFront
  • 組み込みの柔軟な認可オプション
    • IAM
    • Cognito
    • Lambdaオーソライザー
  • サードパーティー用のAPIキー
    • API Gatewayで作成したAPIキーにアクセス許可を設定し、サードパーティーへの配信が可能

ユースケースに最適な API タイプを選択する

• REST API
  • Representational State Transfer の略
  • ステートレス
  • GET・PUT・DELETEなどの機能を定義
  • APIプロキシ機能とAPI管理機能を提供
  • 使用量プランやAPIキーの管理、APIの収益化も可能
• HTTP API
  • REST API よりも低レイテンシー・低コストの RESTful API を作成可能
  • Lambda 関数・HTTP バックエンドにプロキシする API を構築するために最適化されており、サーバーレスワークロードに最適
    • API 管理機能未提供
• WEBSOCKET API
  • 双方向の通信が可能
  • リアルタイムのアプリケーション
    • チャットアプリケーション
    • コラボレーションプラットフォーム
    • マルチプレイヤーゲーム
    • 金融取引プラットフォーム
  • 接続したクライアントからのメッセージを受信した際に呼び出される Lambda 関数、Amazon Kinesis、HTTP エンドポイントとのバックエンド統合が買おう

ユースケースに最適な API タイプを選択する

REST API	HTTP API	WebSocket API
単一価格での API の構築、管理、公開に必要なすべての機能が含まれているセット	ネイティブ OIDC および OAuth 2 認可を備えた最新の API を構築	クライアントとサービスが相互に個別にメッセージを送信できる双方向通信
証明書を使用するバックエンド認証、AWS WAF、リソースポリシーを使用する API を構築	Lambda またはHTTPエンドポイント用のプロキシ API を構築	クライアントが明示的リクエストを送信しなくても、サービスがクライアントにデータをプッシュできるため、クライアントとサービスはより有意義なやり取りが可能に
エッジ最適化またはプライベート API タイプが必要なワークロード	レイテンシーの影響を受けやすいワークロード用の API	リアルタイム通信用の API

WebSocket API の設計

WebSocket API の料金に関する考慮事項

API が使用された分の料金のみが請求
※詳細は参考資料。

API Gateway で WebSocket API を開発する

• 設定要素
  • WebSocket ルート
    • メッセージ内容とバックエンドサービスの紐づけ
      • JSONメッセージのルーティング
    • 事前定義済みルート
      • $connect
      • $disconnect
      • $default
      • カスタムルートも作成可能。
  • WebSocket API 統合
    • ルートのバックエンドエンドポイント・統合エンドポイントとの紐づけ
    • アクション
      • Lambda 関数
      • HTTP エンドポイント
      • AWS のサービス
    • オプション
      • 統合リクエスト
        • 片方向
      • 総合レスポンス
        • 双方向
    • WebSocket 選択式
      • リクエスト・レスポンスコンテキストの評価
      • ルートレスポンス選択式
        • バックエンドからクライアントへのレスポンスのモデリングに使用
      • API キー選択式
        • クライアントが有効な API キーを提供した場合にのみ特定のリクエストを続行すべきであるとサービスが決定した場合に、評価。
      • API マッピング選択式。
        • カスタムドメインを使用してリクエストが行われる場合にどの API ステージを選択するかを決定するために評価

WebSocket API への接続を維持

• 接続
  • クライアントアプリケーションがAPIに接続
  • $connect ルート呼び出し
• 接続の確立
  • JSONメッセージのルーティング
• 切断
  • $disconnect ルート呼び出し
  • ベストエフォート型

参考資料

REST API と HTTP API 間で選択する

Amazon API Gateway の料金

WebSocket 選択式の概要

REST API の設計

API Gateway REST API エンドポイントタイプ

• エンドポイントタイプ
  • リージョン別
    • APIと同じリージョン呼び出し時のレイテンシー低減
    • CloudFrontは利用されないで直接同じリージョン宛。
  • エッジ最適化
    • どこからでもレイテンシー低減
    • CloudFrontの自動設定
    • CDN の支払いや管理をする必要がない
  • プライベート
    • VPCに向ける
    • セキュリティ重視
    • API Gateway でプライベート API を使用する際には、AWS PrivateLink の料金が適用
• 後から変更する際のサポート状況
  • エッジ最適化からリージョン別またはプライベートへ
  • リージョン別からエッジ最適化またはプライベートへ
  • プライベートからリージョン別へ
    • プライベート API エンドポイントをエッジ最適化 API エンドポイントに変更は不可

API Gateway のオプションのキャッシュ

• API キャッシュを有効にして、エンドポイントのレスポンスをキャッシュできる。
• REST API でのみ利用できるオプション
• API Gateway キャッシュを使用すべき理由
  • TTLまでレスポンスをキャッシュ
    • リクエストを送らずにキャッシュを利用
• APIステージごとのキャッシュ設定
  • 特定の API デプロイへの名前付きリファレンス
  • 選択肢（オプション？）
    • キャッシュを 0.5～237 GB の範囲でプロビジョニング
    • TTL を秒単位で設定
      • TTL=0で無効
    • キャッシュデータの暗号化を有効化
    • GET メソッドのみキャッシュ
      • 理由がない限り、他の種類の呼び出しをキャッシュしないこと首位小
    • メソッドごとに設定
• API Gatewayキャッシュの管理
  • データキャッシュの料金は、キャッシュされる API コール数に関係なく、選択したキャッシュサイズに応じて 1 時間単位で請求
  • キャッシュサイズの選択に注意
  • 検証方法
    • CloudWatch メトリクス
      • CacheHitCount
      • CacheMissCount
    • タイムスタンプを作成し、API レスポンスに含めること

REST API の料金に関する考慮事項

※ WebSocket API と同様

API Gateway を使用した API の構築とデプロイ

API コールの仕組み

• ベース API 呼び出し URL はパターンに従う
  • URLの構造
    • ベースURL＝呼び出しURL
      • 画像参照
  • ホスト名のカスタマイズ
    • カスタムドメインを使用するのが敵席
    • AWS Certificate Manager (ACM) により、独自の証明書をインポート、SSL証明書生成が可能。

API Gateway を使用して API を構築するためのステップ

APIコンソールから呼び出しURLとAPIの内訳のマッピングが可能。

参考資料

プロキシリソースとのプロキシ統合を設定する
API Gateway で Lambda プロキシ統合を設定する

API Gateway 統合タイプ

• Lambda関数
  • リクエストが Lambda にプロキシされる
  • リクエストの詳細がイベントパラメータ内の関数ハンドラーで使用できるようになる
  • ユーザーに代わってバックエンドを呼び出すために必要なアクセス許可を持つ IAM ロールを設定必要
• HTTPエンドポイント
  • バックエンドの HTTP エンドポイントを公開することが可能
  • プロキシが設定されていない場合
    • 統合リクエストと統合レスポンスの両方を設定
    • メソッドリクエスト/メソッドレスポンスと統合リクエスト/統合レスポンス間に必要なデータマッピングを設定する必要がある
  • プロキシオプションを使用する場合
    • 統合リクエストまたは統合レスポンスは設定しない
    • API Gateway は、クライアントから受信したリクエストを HTTP エンドポイントに渡し、HTTP エンドポイントから送信されたレスポンスをクライアントに渡す。
• AWSのサービス
  • API が AWS のサービスのアクションを公開できる統合タイプ
    • 例えば、メッセージを Amazon Simple Queue Service (Amazon SQS) キューに直接ドロップ
• モック
  • API Gateway はリクエストをバックエンドに送信せずに、レスポンスを返す。
  • ヘルスチェックエンドポイントで API をテストするのに良い方法。
  • API コールに対するハードコードされたレスポンスが必要な場合は、モック統合を使用
• VPCリンク
  • NLBに接続して、プライベート VPC 内のものを取得。
    • 例えば、パブリックでない EC2 インスタンス上のエンドポイントの場合、API Gateway は VPC リンクを使わないとアクセスできないので、バックエンドに Network Load Balancer が必要。

API メソッドのテスト

• API Gateway コンソールでのメソッドのテストは、API Gateway コンソール外でのメソッドの呼び出しと同じ。
• 変更は元に戻せません。
  • 例えば、API Gateway コンソールを使用して API リソースを削除するメソッドを呼び出し、その呼び出しが成功すると、API リソースは削除されます。
• メソッド呼び出しの結果一覧。
  • リクエスト
    • メソッド用に呼び出されたリソースのパス。
  • ステータス
    • レスポンスの HTTP ステータスコード。
  • レイテンシー
    • 発信者からリクエストを受信してからレスポンスを返すまでの時間
  • レスポンス本文
    • HTTP レスポンスの本文
  • レスポンスヘッダー
    • HTTP レスポンスのヘッダー

レスポンスログ

• テスト結果には、シミュレートされた CloudWatch Logs が含まれる。
• テスト時には CloudWatch に実際にデータが書き込まれるわけではない
• 出力
  • メソッドリクエストから統合リクエストまでの状態の変化
  • 統合レスポンスからメソッドレスポンスまでの状態の変化
• マッピングエラーによってリクエストが失敗した場合のトラブルシューティングに有効

API ステージ

• ステージとは
  • API のスナップショットであり、デプロイされた API バージョンの一意の識別子を表します。
  • バージョン管理に利用可能
• ステージのオプション
  • キャッシュ
  • スロットリング
  • 使用量プラン
• API を差別化するオプション
  • 環境または顧客ごとに異なるステージを使用する。
  • ステージ変数を使用してデプロイの柔軟性を高める。
  • Canary デプロイメントでステージを使用して新しいバージョンをテストする。
• ステージ変数でバージョン管理を簡素化
  • コンソールのステージ設定で変数を定義する際に、$stageVariables.[変数名] という表記を使用して、変数を参照できます。
  • ステージに依存する以下のような項目を実行時に挿入することもできます。
    • URL
    • Lambda 関数
    • 必要なあらゆる変数
  • エンドポイントおよびバックエンドを呼び出すといったアクションの実行に適した方法
    • 例えば、環境によって異なる URL か異なる Lambda 関数エイリアスを持つさまざまなエンドポイントがある場合、ステージ変数を使用してそれらの変数を挿入できる。

構築とデプロイのベストプラクティス

• API Gateway ステージと Lambda エイリアスを併用
  • Lambda では、バージョニングを有効にして、エイリアスを使用して参照。
  • API Gateway では、環境にステージを使用
  • API Gateway ステージ変数が Lambda エイリアスステージ変数を示すようにする
• Canary デプロイメントの使用
• AWS SAM によるデプロイの簡素化
  • AWS SAMテンプレートの使用
  • 複雑なAPIにSwagger・OpneAPIを使用

参考資料

AWS SAM テンプレートの構造分析

API アクセスの管理

管理オプション

• API にアクセスするエンティティの認可
• よりきめ細かな制御
• スロットリングを介したアクセス量の制御

認可と認証の比較

	認証	認可	署名 V4	Cognito ユーザープール	サードパーティーの認証	複数ヘッダーのサポート	追加コスト
AWS IAM	✔️	✔️	✔️	ー	ー	ー	なし
Lambda オーソライザートークン	✔️	✔️	ー	✔️	✔️	ー	オーソライザーの呼び出しごとの料金
Lambda オーソライザーリクエスト	✔️	✔️	ー	✔️	✔️	✔️	オーソライザーの呼び出しごとの料金
Amazon Cognito	✔️	✔️	ー	✔️	ー	ー	月間アクティブユーザー数に基づいた料金

• API Gateway エンドポイントへの API コールを認可するには、主に 3 つの方法があります。
  • IAM および署名バージョン 4 (Sig v4) を使用して、API にアクセスするエンティティを認証および認可する。
  • Lambda オーソライザーを使用する。OAuth や SAML などの Bearer トークン認証戦略をサポートするために使用できる。
  • Amazon Cognito とユーザープールを使用する。
• AWS IAM
  • 内部サービスを利用している場合
  • 顧客数が制限されている場合
  • IAM ロールを使用して他の AWS のサービスとインタラクションするアプリケーション
• Lambda オーソライザー
  • 組織として OAuth 戦略を使用している場合
  • 必要なカスタム認可を実行するために記述できる Lambda 関数
    • Lambda オーソライザートークン
      • API Gateway はソーストークンを JSON 入力として Lambda 関数に渡す
      • このトークンの値に基づいて、Lambda 関数はリクエストの可否を判断する
  • Lambda オーソライザーリクエスト
    • リクエストを認可する前にリクエスト自体の情報を多く必要とする場合
• Amazon Cognito
  • Amazon Cognito と Cognito ユーザープールを使用して API へのアクセスを制御

スロットリングと使用量プラン

• API Gateway で、API エンドポイントを介して処理される API コールの量を管理することも可能
  • スロットリング制限とクォータ制限を設定
• API キーを作成して顧客に配布可能
• 使用量プラン
  • API キースロットリング (1 秒あたりおよびバーストあたり)
  • API キークォータ (日次、週次、月次)
  • API キー使用量 (日次使用量レコード別)
• トークンバケットアルゴリズム
  • バースト: バケットの最大サイズ
  • レート: バケットに追加されたトークン (リクエスト) の数
  • アカウントごとやリージョンごとに、リクエスト送信の定常レートとバーストに対して制限が設定
    • デフォルトで、定常リクエストレートが毎秒 10,000 リクエストに制限
    • AWS アカウント内のすべての API で、バーストは 5,000 リクエストに制限
    • 使用量プランを使用して、より詳細なレベルで制限を管理
• スロットリング設定の階層
  • 適用順序
    • 使用量プランで API ステージに設定したクライアントあたり、メソッドあたりのスロットリング制限
    • 使用量プランで設定したクライアントあたりのスロットリング制限
    • API ステージ設定で設定した、メソッドあたりのデフォルト制限およびメソッドあたりの個別の制限
    • アカウントレベルの制限

IAM アクセス許可

• IAM Policy を使用して実装できる許可制御のタイプ
  • 誰が API を呼び出せるのか
    • デプロイされた API を呼び出すか、API キャッシュを更新するには、発信者に execute-api アクセス許可が必要
  • 誰が API を管理できるのか
    • API Gateway で API を作成、デプロイ、管理するには、API デベロッパーに apigateway アクセス許可が必要

参考資料

Amazon API Gateway アイデンティティベースのポリシーの例

リソースポリシー

• リソースポリシーを使用して API Gateway に直接ポリシーを適用することもできます。
  • 指定したアカウント、IP アドレス範囲、VPC、VPC エンドポイントのユーザーによるアクセスを制限するために API にアタッチする JSON ポリシードキュメント
  • IAM Policy と連携させてアクセスを制限
    • 別の AWS アカウントにアクセスを許可
    • 特定の IP アドレス範囲のセットから API へのアクセスを制限
    • リソースポリシーによって、特定の VPC または VPC エンドポイントへのアクセスを許可することも可能。

参考資料

API Gateway リソースポリシーを使用して API へのアクセスを制御する

リソースポリシーと認証メソッド

• API Gateway リソースポリシーのみ
  • 発信者のインバウンド条件に明示的な許可が必要。
  • ない場合、発信者を拒否
• Lambda オーソライザーとリソースポリシー
  • ポリシーに明示的拒否がある場合、発信者は直ちにアクセスを拒否
  • それ以外の場合は、Lambda オーソライザーが呼び出され、リソースポリシーで評価されるポリシードキュメントを返す
• IAM 認証とリソースポリシー
  • ユーザーが IAM で正常に認証されると、IAM ユーザーにアタッチされたポリシーとリソースポリシーが一括で評価される
    • 発信者と API 所有者が別々のアカウントである場合
      • IAM ユーザーポリシーとリソースポリシーはどちらも、発信者が続行することを明示的に許可する
    • 発信者と API 所有者が同じアカウントである場合
      • ユーザーポリシーかリソースポリシーのいずれかが、発信者が続行することを明示的に許可する必要がある
• Cognito 認証とリソースポリシー
  • API Gateway が Cognito から発信者を認証する場合、リソースポリシーは個別に評価される
  • 明示的な許可がある場合、発信者は続行する
  • それ以外の場合、拒否するか、または許可も拒否もしないと、拒否される

参考資料

API Gateway リソースポリシーが認証ワークフローに与える影響

モニタリングとトラブルシューティング

API Gateway の CloudWatch メトリクス

• デフォルトメトリクス
  • Count: ある期間内の API リクエストの合計数
  • Latency: API Gateway がクライアントからリクエストを受信してから、クライアントにレスポンスを返すまでの時間。統合のレイテンシーなどの API Gateway のオーバーヘッドが含まれる
  • IntegrationLatency: API Gateway がバックエンドにリクエストを中継してから、バックエンドからレスポンスを受け取るまでの時間
  • 4xxError: 指定期間内にキャプチャされたクライアント側のエラー
  • 5xxError: 指定期間内にキャプチャされたサーバー側のエラー
  • CacheHitCount: 特定の期間に API キャッシュから提供されたリクエストの数
  • CacheMissCount: API キャッシュが有効になっている特定の期間内で、バックエンドから提供されたリクエストの数
• モニタリングできる情報
  • API が呼び出される頻度
  • API への呼び出し回数
  • API レスポンスのレイテンシー
  • エラーの有無。エラーがある場合は、400 エラーなのか 500 エラーなのか
  • キャッシュヒットの有無、またはキャッシュの有効期間中にバックエンド呼び出しの必要が生じた回数

API Gateway のオーバーヘッドの計算

• オーバーヘッドを計算するために使用される主要な CloudWatch メトリクス

  • レスポンス往復全体に要する時間の詳細が表示されます。
    • 顧客が API を呼び出してから API が結果をレスポンスするまでの時間
    • API Gateway を経由した API リクエストの往復全体の時間
  • 統合レイテンシーは、API Gateway がバックエンドに対して呼び出しを実行してから、レスポンスを受信するまでにかかった時間。

• API Gateway の CloudWatch Logs

  • 実行ログ記録
    • リクエスト実行時点からのすべての詳細
    • 機密データのログ記録を行う場合
      • 本番 API に対して [Log full requests/responses data] を有効にしないことをお勧め

• アクセスログ記憶

  • API を呼び出したユーザーに関する詳細情報が提供される
  • IP アドレス、使用メソッド、ユーザープロトコル、API を呼び出すエージェント

• トラブルシューティングサンプル

  • ログの確認
    • CloudWatch のメトリクスを確認
    • 実行ログを開く
    • ログ内でエラーを把握
    • 可能性のあるスロットリング設定を確認
  • 設定確認
    • 使用量プラン: API キースロットリング
    • ステージレベルでのメソッドスロットリング
    • ステージレベルのデフォルト
    • アカウントの制限

X-Ray と CloudTrail を使用したモニタリング

• AWS X-Ray

  • API とそのバックエンドサービスのレイテンシーを分析し、エラーをデバッグする。
  • 特定のリクエストに着目したサンプリングルールを設定する。

• AWS CloudTrail

  • IP アドレス、リクエスタ、リクエストの時刻が含まれる
  • イベント履歴を確認できる
  • Amazon Simple Storage Service (Amazon S3) バケットにイベントを送信する追跡を作成。

• トラブルシューティングサンプル

  • アクセスログによるエラーの確認
    • CloudWatch でアクセスログを開く
    • 期間中のログイベントの選択
    • エラーの確認
    • X-Ray を使用したエラーの確認
    • トレースの選択
    • トレースで報告されたエラーの確認
  • 設定確認
    • 認可設定
    • リソースポリシー

データマッピングとリクエストの検証

マッピングテンプレートによるデータ変換

API Gatewayとバックエンド間でペイロードの変換が必要

変換で使用する重要な変数

変数	ユースケース
$input	body、json、params、path
$stageVariables	任意のステージ変数名
$util	escapeJavaScript()、parseJson()、urlEncode/Decode()、base64Encode/Decode()

参考資料

API Gateway マッピングテンプレートとアクセスのログ記録の変数リファレンス

ゲートウェイのレスポンスを利用してエラーを処理

PI Gateway では API デベロッパーがカスタマイズして異なる形式でレスポンスを返すことが許可。

• HTTP ステータスコードの変更
• 本文の内容の修正
• ヘッダーの追加
• 特定のレスポンス
• デフォルト
  • 4xx
  • 5xx

リクエスト検証を API Gateway にオフロード

• URL、クエリ文字列、受信リクエストのヘッダーに必須のリクエストパラメータが含まれており、空白でない。
• 該当するリクエストペイロードが、メソッドの設定済み JSON リクエストモデルに従っている。

API Gateway でリクエスト検証を有効にする

まとめ・その他。

最後はAPI Gatewayのサービス詳細についてでした。
これで学習プランの全コース完了してデジタルバッジ発行されるぞ！
って思ったらAWS認定のアカウントページや、Credlyなど確認しても反映されておらず調査したところ、学習プランの中に確認テストが含まれてないことを以下参考にて気が付きました。

そもそもコースが微妙に間違っていることに気が付きました…

• Serverless Learning Plan (Japanese)
  • 各コースは日本語化されている
  • 確認テストは含まれていない
• Serverless Learning Plan - Earn a Learning Badge
  • 各コースは英語
    • このコース内上部の言語のリンクを選択すると、Serverless Learning Plan (Japanese)に飛ばされてしまうため注意
    • 言語以外の各コースの内容は同じ
  • 確認テストは含まれている

というわけで、確認テストに合格できれば、デジタルバッジ取得となります。
詳細は取得後のまとめ記事に書こうと思います。