AWS API Gateway(3)カスタムログの出力


API Gatewayは、詳細のアクセスログをCloudWatch Logsに吐き出すことができる。CloudWatch Logsへのログ書き込みを行うためには、書き込み権限の取得とログを書き込むロググループの指定が必要となる。

IAMロールの指定

IAM上でAPI GatewayからCloudWatch Logsへの書き込み許可を持つIAMロールを作成する。IAMでは、あらかじめAmazonAPIGatewayPushToCloudWatchLogsと呼ばれるポリシーが用意されているため、このポリシーがアタッチされたIAMロールを作成する。この作成したIAMロールをAPI Gatewayの設定画面上で指定することで、API GatewayはCloudWatch Logsへの書き込み権限を取得する。

ログの指定

次にAPI Gateway上の各APIのログ/トレース設定画面にて、カスタムアクセスのログ記録を有効化する。入力項目は、CloudWatchロググループのARNと、ログ形式の2種類。ログ形式は、JSONやCLFなどの中から選ぶと自動的に入力される。

AWS API Gateway(2)Kinesisへのデータ投入

API Gatewayから大量のデータを投入し、これらのデータを解析および蓄積する場合には、API GatewayからLambdaに直接データを渡すのではなく、大規模データストリームサービスのKinesisを介した方が、バックエンドのシステムが高負荷に晒されずに安定的に稼働させられる場合がある。

API Gatewayとバックエンドのエンドポイントとの接続は、API Gateway内の統合リクエスト機能を用いて行い、統合リクエストは下の5つの統合タイプを用意している。

  • Lambda関数
  • HTTP
  • Mock
  • AWSサービス
  • VPCリンク

Mockは、バックエンドと接続せずにレスポンスを返す統合タイプで、テストを行う際や、CROSのプリフライトリクエストの返答などに用いる。

統合リクエスト

Kinesisと接続する場合は、POSTメソッドを作成し、上記のうちの「AWSサービス」を選択して以下のように各欄に必要事項を入力する。Kinesisへデータ投入する際には、Kinesis側で用意されているputRecordメソッドを使用する。

データ入力項目

項目 入力内容 備考
統合タイプ AWSサービス  
AWS リージョン 当該Kinesisのリージョン  
AWS サービス Kinesis  
AWS サブドメイン 空欄  
HTTP メソッド POST  
アクション PutRecord  
実行ロール KinesisへのputRecordをAPI Gatewayに許可するIAMロール arn:aws:iam::account-id:role/iam-role-name

IAMロールについては、KinesisへのputRecordをAPI Gatewayに許可する記述が必要で、IAM上で以下の内容を含んだIAMロールを作成する。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "kinesis:PutRecord",
                "kinesis:PutRecords"
            ],
            "Resource": "arn:aws:kinesis:*:*:stream/*"
        }
    ]
}

データマッピング

API GatewayからKinesisにデータを投入する場合は、クライアントから受信したデータをKinesisが規定するデータフォマットに変換する必要がある。これに対応するのがデータマッピング機能で、Velocity Template Languageを用いて記述することができる。

よく使われる関数および使用例を以下に挙げる。

記述 内容
#set($param = ”) 変数の定義
#if(評価式) #end if文
$context.requestTimeEpoch データの受信時刻
$input.path(‘$.param’) 入力データ内の指定タグの値
$input.path(‘$.param’).size 入力データ内の指定タグの数
$input.params().header.get(”) ヘッダ内の指定タグの値
$input.json(‘$.param’) 入力データ内の指定タグJSONデータ
$util.urlDecode($input.path(‘$’)) 入力データをURLデコード
$util.escapeJavaScript(data) 文字をエスケープ
$util.base64Encode(data) 文字をBASE64エンコード

また、これらを使用してデータマッピングを記述すると以下となる。

#set($allParams = $input.params())
{
  "params" : {
    #foreach($type in $allParams.keySet())
    #set($params = $allParams.get($type))
    "$type" : {
      #foreach($paramName in $params.keySet())
      "$paramName" : "$util.escapeJavaScript($params.get($paramName))"
      #if($foreach.hasNext),#end
      #end
    }
    #if($foreach.hasNext),#end
    #end
  }
}

AWS API Gateway(1)API Gatewayの概要

API Gatewayとは

API Gatewayは、完全マネージドのAPI作成サービス。受信したAPIコールと送出したデータ量に対して課金される。スロットリングによるトラフィック管理ができるため、DDoSやトラフィックの激増にも対応することが可能であり、リミットを超えたリクエストにはHTTPステータス 429が返却される。また、レスポンスはキャッシュ可能であり、レイテンシやトラフィック等を低減することができる。

API Gatewayは、IAMやCognitoを用いたアクセス認証署名付きAPIコールなどを使用することができるために柔軟にセキュリティ管理ができる。また、CloudWatchやCloudWatch Logsを用いた監視が可能で効率的なデバッグとモニタリングを実現している。

![API Gateway]https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/BackplaneArch.png

エンドポイント

API Gatewayは、特定のリージョンにデプロイされる。エンドポイントは以下の3種類がサポートされている。エンドポイントは、HTTPSのみサポートされている。

種類 内容
エッジ最適化 CloudFrontネットワークにデプロイ
リージョン リージョンにデプロイ。EC2 インスタンスまたは API と同じリージョン内のサービスから送られる場合に使用すると良い。
プライベート VPCからのみアクセス可能

リソースとメソッド

APIは階層構造となっており、リソースやメソッドをネストすることも可能。指定可能なメソッドは以下の通り。

種類 実行内容
POST 子リリースの作成
PUT 既存リソースの更新
DELETE リソースの削除
PATCH リソースの更新
HEAD テストシナリオに使用
OPTIONS 通信オプションに関する情報を取得する度に使用できる

CROSを有効にするためには、OPTIONSメソッドのプリフライトリクエストに対してAPIが応答することが必要であり、このリクエストに対して、HTTPステータス 200Access-Control-Allow-Method, Access-Control-Allow-Headers, Access-Control-Max-Ageヘッダを含んだレスポンスを返す。これらの挙動には、統合リクエスト/レスポンスのMockタイプを使用する。

リクエストに対して、 URLクエリ文字列パラメータHTTPヘッダHTTPボディを検証し、必須の項目が含まれているかやキャッシュを行うかなどを指定することができる。HTTPボディがapplication/json形式である場合は、JSON Schemaを用いてJSON形式を指定することもできる。

統合リクエスト/レスポンスとマッピングテンプレート

API Gatewayとバックエンドとを接続する内部インタフェース。マッピングテンプレートを用いることで、フロントエンド(API Gateway)とバックエンドのデータ形式を変換することができる。

  • Lambda関数の呼び出し
  • 他のAWSサービスの呼び出し
  • HTTPウェブサイトのアクセス

の3つのバックエンドへのアクセスに対応している。Lambdaプロキシ統合を用いることで、API GatewayとLambdaがより協力に結合され、リクエストヘッダやパス変数などがLambdaに渡される。また、HTTPプロキシとして使用することも可能である。

デプロイ

APIを利用可能とするためには、APIのリソースおよびメソッドのスナップショットであるAPIのデプロイを実施する必要がある。APIをバージョン管理できるために、新しいバージョンを簡単にテストしリリースすることが可能である。

1アカウント1リージョンあたりのAPIの上限は、10000RPSである。これ以上のアクセス負荷にも耐えうる値とする場合は上限緩和申請が必要となる。

エラーコード

API Gateway の代表的なレスポンスコードは以下の通り。

エラーコード レスポンスタイプ 内容
400 BAD_REQUEST_PARAMETERS リクエストパラメータの不整合
400 BAD_REQUEST_BODY リクエストボディの不整合
401 UNAUTHORIZED 認証の失敗
403 EXPIRED_TOKEN トークンの期限切れ
403 ACCESS_DENIED 認証の失敗
403 INVALID_API_KEY APIキーの不整合
403 INVALID_SIGNATURE 署名の不整合
403 MISSING_AUTHENTICATION_TOKEN トークンが見つからない
403 WAF_FILTERED WAFによるブロック
404 RESOURCE_NOT_FOUND リクエスト先が存在しない
413 REQUEST_TOO_LARGE リクエストが大きすぎる
415 UNSUPPORTED_MEDIA_TYPE メディアタイプの相違
429 QUOTA_EXCEEDED クオータの超過
429 THROTTLED スロットルの発生
500 API_CONFIGURATION_ERROR API 設定が無効
500 AUTHORIZER_CONFIGURATION_ERROR オーソライザーへの接続が失敗
500 AUTHORIZER_FAILURE オーソライザーの認証が失敗
504 INTEGRATION_FAILURE 統合に失敗
504 INTEGRATION_TIMEOUT 統合のタイムアウト