APIルーティング

APIGWは、API単位のルーティングリソースを管理します。すべてのルーティングリソースは、アクションパイプラインを保有し、リクエストとレスポンスのメッセージに様々な加工を行うことができます。また、カスタムスクリプトを埋め込んでマイクロワークフローを駆動させることでステートレスなマッシュアップを実現することもできます。

以下はアクションパイプラインの機能配置図です。

経路選択アルゴリズム

API Gatewayは、リクエストを受信したときにルーティング戦略を計画します。リクエストヘッダと起動パラメータは、次のルーティング戦略を決定します。

Strategy	Condition	description
Delegate	起動パラメータ--force_delegation_mode=True	上位のAPIGatewayに転送します。
Direct	X-Xaas-Direct-Routingが指定されている	X-Xaas-Direct-Routingで指定されたURLに転送します。v25.1LTSでサポートを停止しました。
Static	X-Xaas-Static-Routingが指定されている	ルートエントリのターゲットエンドポイントをX-Xaas-Static-Routingで指定されたエンドポイントに変換します。
Tunneling	X-Xaas-Tunnelingが指定されている	カプセル化されたリクエスト本文からヘッダ、パラメータ、本文をデコードして新しいHTTPリクエストを作成し、ルートエントリのターゲットエンドポイントに転送します。
Standard	経路制御拡張ヘッダが含まれていない	ルートエントリのターゲットエンドポイントに転送します。
Hierarchical	ルーティング未定義で且つ--hierarchical_routing_mode=True	上位のAPIGatewayに転送します。

アクションパイプライン

APIルーティングはリクエスト、レスポンスに対する様々なアクションを適用できるアクションパイプラインを持ちます。アクションパイプラインで利用できる各機能ブロックを以下に解説しています。

Out of service

API閉塞を制御する機能です。閉塞状態でリクエストを受信した場合に返却する応答はカスタマイズできます。デフォルトでは503 Service Unavailableが返却されます。

In service time

APIが稼働する時間を制限できる機能です。設定された開始時刻と終了時刻の間のアクセスのみを許可し、アクセスが許可されていない時間帯は、503 Service Unavailableを応答します。応答コードや本文は、Out of service機能にデフォルトのOUS応答を設定することでカスタマイズすることもできます。

Proxy authorization

リクエスト認可を行う機能です。BASIC認証、Digest認証、Keystone認証、およびQmonus独自認証をサポートしています。

Pop header

指定されたキーに合致するリクエストヘッダを除去する機能です。

Push header

指定されたヘッダをリクエストヘッダに追加する機能です。

Queuing

リクエストをキューイングして非同期化する機能です。

accept_responseを指定しない場合、次のデフォルトの応答が返されます。

type: object
required:
- taskid
- status
- content
properties:
  taskid:
    type: string
    description: The identifier of the queued task.
  status:
    type: string
    description: Task processing status
  content:
    type: object
    properties:
      registration_time:
        description: Entry time to the task queue
        type: string
      max_residence_time:
        description: Maximum residence time
        type: integer
      expire_time:
        description: Expiration time
        type: string
      request:
        type: object
        properties:
          url:
            type: string
          headers:
            type: object
          method:
            type: string
          body:
            type: string
        description: Queued HTTP request content

参考: キューイングと消費の基本シーケンス図

Target authentication

ターゲットへの認証を代行する機能です。BASIC認証、Digest認証、Keystone認証、OAuth認証、AWS-HMAC-V4認証、およびQmonus独自認証をサポートします。

Stub（非推奨）

APIモック応答を作成できる機能です。将来のリリースで削除される予定です。後述するforbidden_processでよりきめ細かいモック作成が可能です。

Body template（非推奨）

テンプレートエンジンを使用して本文をレンダリング結果に書き換える機能です。Scenarioサービスのtemplateプラグインを使用することもできます。本機能はforbidden_processまたはBody mapperで代替できるため、将来削除予定です。

templateに直接記述したテンプレートでは、埋め込む文字列の値をJSONの文字列としてエスケープします（v26.1LTS以降）。出力はJSONを前提としているため、XMLなどJSON以外を出力する場合は値に|eを付けてください。値をJSONとして埋め込む場合は、引用符で囲まずに|tojsonを使用してください（例: {"name": {{ params.name|tojson }}}）。

Forbidden process

リクエストとレスポンスを開発者のカスタムスクリプトにフックし、自由にカスタマイズできる機能です。詳細は、APIGWにおけるプログラミングを参照してください。

Body key filter

1ライナーのカスタムスクリプトまたはホワイトリスト、ブラックリストに従って、本文内のキーをフィルタリングできる機能です。

Body mapper

Parametermapperサービスを適用して本体を整形できる機能です。

Convert body style

本文のキースタイルを変換する機能です。snake caseからlower camel caseへの変換または、その逆変換をサポートします。

Body validation schema

jsonschemaによる本文のバリデーション検査を提供する機能です。v26.1LTS以降、リクエスト本文をJSONとして解釈した値を検証します(v25.2LTS以前は本文をそのまま検証していました)。JSONとして解釈できない場合やスキーマに一致しない場合は、400 Bad Requestを応答します。本文が空の場合はnullとして検証します。

Lambda proxy（非推奨）

リクエストをlambdaイベントに変換して発行し、処理結果で応答する機能です。本機能はforbidden_processで代替できるため、将来削除予定です。

Lambda hook（非推奨）

リクエスト/レスポンス時にlambdaイベントを発生させる機能です。本機能はforbidden_processで代替できるため、将来削除予定です。

Error body off

ターゲットからの応答がエラーの場合に、本体を空にする機能です。ターゲットに接続できない場合（599）も本体を空にします。ステータスコードは変わりません。

APIの認証スコープについて

APIルーティングにはscope属性があり、secure、 local、publicの3種類から指定できます。secureモードの場合は、Qmonus認証認可が有効化されます。起動パラメータ--local_scope_auth_modeがTrueの場合、localモードにはQmonus認証認可が必要になります。 Falseおよびpublicモードの場合、Qmonus認証認可は無効化されます。

スコープ	Qmonus認証認可
secure	enable
local	enable if options.local_scope_auth_mode==True else disable
public	disable