Amazon API Gateway＠AWS リソース

はじめに

本サイトにつきまして、以下をご認識のほど宜しくお願いいたします。

• https://hiroki-it.github.io/tech-notebook/

01. Amazon API Gateway とは

異なるクライアントからのリクエストを受信して差分を吸収し、適切な API に振り分けられる。

内部的には CloudFront を使用しているらしい。

• https://dev.classmethod.jp/articles/edge-computing-by-api-gateway/
• https://dev.classmethod.jp/articles/cache-api-gateway-by-cloudfront/

02. セットアップ

コンソール画面の場合

Amazon API Gateway は、メソッドリクエスト、統合リクエスト、統合レスポンス、メソッドレスポンスから構成される。

設定項目	説明	補足
リソース	エンドポイント、HTTP メソッド、ルーティング先などを設定する。	作成した AWS リソースのパスが、Amazon API Gateway のエンドポイントになる。
ステージ	Amazon API Gateway をデプロイする環境を定義する。
オーソライザー	AWS Lambda または Cognito によるオーソライザーを使用して、認可プロセスを定義する。
ゲートウェイのレスポンス
モデル	リクエスト／レスポンスのスキーマを設定する。これらのバリデーションのために使用できる。	OpenAPI 仕様におけるスキーマについては、以下のリンクを参考にせよ。 https://hiroki-it.github.io/tech-notebook/software/software_application_messaging_api_restful.html
リソースポリシー	ポリシーを使用して、Amazon API Gateway にセキュリティを定義づける。
ドキュメント
ダッシュボード
API の設定
使用サイズプラン	有料サービスとして API を公開し、料金体系に応じてリクエストサイズを制限するために使用する。API キーにリクエスト量のレートを設定する。	有料サービスとして使用しない API の場合は、レートを設定する必要はない。
API キー	API キー認証を設定する。	・その他の認証の方法として、以下がある。 https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-to-api.html
クライアント証明書	サーバー証明書を Amazon API Gateway に割り当てる。	API が、Amazon API Gateway からルーティングされたリクエストであることを識別できるようになる。
Amazon CloudWatch Logs の設定	Amazon API Gateway が Amazon CloudWatch Logs にリクエストを送信できるよう、ロールを設定する。	1 個の AWS アカウントにつき、1 個のロールを設定すればよい。

リソース

▼ リソース

順番	処理	説明	補足
1	メソッドリクエスト	クライアントから受信したデータのうち、実際にルーティングするデータをフィルタリングする。
2	統合リクエスト	メソッドリクエストからルーティングされた各データを、マッピングテンプレートの JSON に紐付ける。
3	統合レスポンス		統合リクエストでプロキシ統合を使用する場合、統合レスポンスを使用できなくなる。
4	メソッドレスポンス	レスポンスが成功した場合、クライアントに送信するステータスコードを設定する。

▼ メソッドリクエスト

設定項目	説明	補足
認可	定義した AWS Lambda または Cognito によるオーソライザーを有効化するか否かを設定する。
リクエストの検証	『URL クエリ文字列パラメーター』『HTTP リクエストヘッダー』『リクエスト本文』のバリデーションを有効化するか否かを設定する。
API キーの必要性	リクエストヘッダーにおける API キーのバリデーションを実行する。リクエストのヘッダーに『x-api-key』を含み、これに API キーが割り当てられていることを強制する。	ヘッダー名は大文字でも小文字でも問題ないが、小文字が推奨。 https://hiroki-it.github.io/tech-notebook/software/software_application_messaging_api_restful.html
URL クエリ文字列パラメーター	リクエストされた URL のクエリパラメーターのバリデーションを実行する。
HTTP リクエストヘッダー	リクエストヘッダーのバリデーションを実行する。
リクエスト本文	リクエストボディのバリデーションを実行する。
SDK 設定

▼ 統合リクエスト

設定項目	説明	補足
統合タイプ	リクエストのルーティング先を設定する。
URL パスパラメーター	メソッドリクエストからルーティングされたデータを、Amazon API Gateway からルーティングするリクエストのパスパラメーターに紐付ける。代わりに、紐付けずに新しいデータをルーティングしてもよい。
URL クエリ文字列パラメーター	メソッドリクエストからルーティングされたデータを、Amazon API Gateway からルーティングするリクエストのクエリパラメーターに紐付ける。代わりに、紐付けずに新しいデータをルーティングしてもよい。
HTTP ヘッダー	メソッドリクエストからルーティングされたデータを、Amazon API Gateway からルーティングするリクエストのヘッダーに紐付ける。代わりに、紐付けずに新しいデータをルーティングしてもよい。	値はシングルクオートで囲う必要がある。
マッピングテンプレート	メソッドリクエストからルーティングされたデータを、Amazon API Gateway からルーティングするリクエストのメッセージボディに紐付ける。代わりに、紐付けずに新しいデータをルーティングしてもよい。

▼ ホワイトボックステスト

設定項目	設定例	補足
クエリ文字
ヘッダー	X-API-Token: test	波括弧、スペース、クオーテーションは不要。
リクエスト本文	{test:"test"}	改行タグやスペースが入り込まないようにする。

▼ OpenAPI 仕様のインポート

以下のリンクを参考にせよ。

• https://hiroki-it.github.io/tech-notebook/cloud_computing/cloud_computing_aws_resource_api_gateway_import.html

▼ CORS の突破

正しいリクエストが CORS を突破できるように、異なるオリジンによって表示されたページからのリクエストを許可する。

• https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html

プライベート統合

▼ プライベート統合とは

Amazon API Gateway と Amazon VPC リンクの間で、リクエスト／レスポンスの JSON 型データを自動的にマッピングする機能のこと。

また、Amazon VPC リンクを設定することで、Amazon VPC エンドポイントサービスを作成する。

設定項目	説明
統合タイプ	Amazon VPC リンクを選択する。
プロキシ統合の使用	Amazon VPC リンクとのプロキシ統合を有効化するか否かを設定する。
メソッド	HTTP メソッドを設定する。
Amazon VPC リンク	Amazon VPC リンク名を設定する。
エンドポイント URL	NLB の DNS 名をドメイン名として、フォワーディング先の URL を設定する。
デフォルトのタイムアウト時間の使用

• https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-private-integration.html

▼ メソッドリクエストと統合リクエストのマッピング

AWS Lambda プロキシ統合

▼ AWS Lambda プロキシ統合とは

Amazon API Gateway と AWS Lambda の間で、リクエスト／レスポンスの JSON 型データを自動的にマッピングする機能のこと。

プロキシ統合を使用すると、AWS Lambda に送信されたリクエストはハンドラ関数の event オブジェクトに代入される。

プロキシ統合を使用しない場合、AWS Lambda と Amazon API Gateway の間のマッピングを手動で実行する必要がある。

設定項目	説明
統合タイプ	AWS Lambda 関数を選択する。
AWS Lambda プロキシ統合の使用	AWS Lambda とのプロキシ統合を有効化するか否かを設定する。
AWS Lambda リージョン	実行した AWS Lambda 関数のリージョンを設定する。
AWS Lambda 関数	実行した AWS Lambda 関数の名前を設定する。
実行ロール	実行したい AWS Lambda 関数への認可スコープが紐付けられたロールの ARN を設定する。ただし、AWS Lambda 側に Amazon API Gateway への認可スコープを紐付けしてもよい。
資格情報のキャッシュ
デフォルトのタイムアウト時間の使用

• https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-integrations.html

▼ リクエスト時のマッピング

Amazon API Gateway 側でプロキシ統合を有効化すると、Amazon API Gateway を経由したクライアントからのリクエストは、ハンドラ関数の event オブジェクトの JSON 型データにマッピングされる。

{
  "resource": "Resource path",
  "path": "Path parameter",
  "httpMethod": "Incoming request's method name",
  "headers": {
      String
      containing
      incoming
      request
      headers,
    },
  "multiValueHeaders": {
      List
      of
      strings
      containing
      incoming
      request
      headers,
    },
  "queryStringParameters": {
      query
      string
      parameters,
    },
  "multiValueQueryStringParameters": {
      List
      of
      query
      string
      parameters,
    },
  "pathParameters": {
      path
      parameters,
    },
  "stageVariables": {
      Applicable
      stage
      variables,
    },
  "requestContext": {
      Request
      context
      including
      authorizer-returned
      key-value
      pairs,
    },
  "body": "A JSON string of the request payload.",
  "isBase64Encoded": "A boolean flag to indicate if the applicable request payload is Base64-encoded",
}

▼ レスポンス時のマッピング

Amazon API Gateway は、AWS Lambda からのレスポンスを、以下の JSON 型データにマッピングする。

これ以外の構造の JSON 型データを送信すると、Amazon API Gateway で『Internal Server Error』のエラーが起こる。

{
  "isBase64Encoded": "true",
  "statusCode": httpStatusCode,
  "headers": {"headerName": "headerValue", ...},
  "multiValueHeaders":
    {"headerName": ["headerValue", "headerValue2", ...], ...},
  "body": "Hello AWS Lambda",
}

Amazon API Gateway は上記の JSON 型データを受信した後、body のみ値をレスポンスのメッセージボディに持たせ、クライアントに送信する。

"Hello AWS Lambda"

ステージ

▼ 設定

設定項目	説明
キャッシュ設定	・https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html
デフォルトのメソッドスロットリング	リクエスト数 (個/秒) 制限を設定する。 https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html
AWS WAF	・https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-aws-waf.html
クライアント証明書	紐付ける AWS WAF を設定する。

▼ ステージ変数

デプロイされるステージ固有の環境変数を設定できる。

AWS Lambda 関数名、エンドポイント URL、パラメーターマッピング、マッピングテンプレートで値を出力できる。

以下のリンクを参考にせよ。

• https://docs.aws.amazon.com/apigateway/latest/developerguide/aws-api-gateway-stage-variables-reference.html

▼ SDK の作成

デプロイメント

▼ 通常のデプロイメント

Amazon API Gateway では、通常のデプロイメントの仕組みが隠蔽されている。

ダウンタイム無しで、新しいステージをデプロイできる。

• https://forums.aws.amazon.com/thread.jspa?threadID=238876

▼ カナリアリリース

カナリアリリースを使用して、新しいステージをデプロイする。

設定項目	説明
ステージのリクエストディストリビューション
Canary のデプロイ
Canary ステージ変数
キャッシュ

• https://docs.aws.amazon.com/apigateway/latest/developerguide/canary-release.html

ログの種類

▼ 実行ログ

Amazon CloudWatch Logs に Amazon API Gateway の実行ログを送信するか否かを設定できる。

リクエスト／レスポンスの構造もログへ出力するようにしたほうがよい。

• https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html

▼ カスタムアクセスログ

Amazon CloudWatch Logs に Amazon API Gateway のアクセスログを送信するか否かを設定できる。

アクセスログを構造化ログとして出力できる。

• https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html

分散トレースの収集

X-Ray を使用して、Amazon API Gateway を開始点とした分散トレースを収集する。

まず、Amazon API Gateway でトーレス ID を作成する。

その後、各 AWS リソースでスパンを取得し、スパンを紐付けることより、分散トレースを表現できる。

補足として X-Ray では、親スパンをセグメント、子スパンをサブセグメントと呼ぶ。

• https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-traces

API の設定

▼ エンドポイントタイプ

タイプ名	説明
リージョン	Amazon API Gateway のエンドポイントに対するリクエストを、リージョン内の物理サーバーで受け付ける。
プライベート	Amazon API Gateway のエンドポイントに対するリクエストを、Amazon VPC 内からのみ受け付ける。
エッジ最適化	Amazon API Gateway のエンドポイントに対するリクエストを、Amazon CloudFront のエッジサーバーで受け付ける。

• https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-endpoint-types.html

03. AWS Lambda オーソライザー

Amazon API Gateway の認証プロキシと中央集権的な認可プロバイダーとして機能する。

ID プロバイダーが別途必要である。

似たものとして AWS Cognito オーソライザーがある。

これを使用する場合は AWS Lambda オーソライザーを使用できない。

	AWS Cognito オーソライザー	AWS Lambda オーソライザー
認証	✅
認可	✅	✅

• https://dev.classmethod.jp/articles/aws-cdk-api-gateway-lambda-rest-auth0-lambda-authorizer/