1.2. 3scale API の使用状況を把握するために APIcast がマッピングルールをどのように適用するか

API に対するリクエストに基づいて、マッピングルールにより API の使用状況を把握するメトリクスまたはメソッドを定義、指定します。マッピングルールの例を以下に示します。

Mapping Rules

このルールは、/ で始まるすべての GET リクエストがメトリクス hits のカウントを 1 つ増やす、という意味です。このルールは API に対するすべてのリクエストにマッチします。これは有効なマッピングルールですが、一般的すぎるので、より具体的なルールが追加された時に、2 倍にカウントされることになります。

より具体的なルールの例として、Echo API マッピングルールを以下に示します。

Hello World Mapping Rules

マッピングルールは、API プロダクトレベルおよび API バックエンドレベルで機能します。

  • プロダクトレベルでのマッピングルール

    • このマッピングルールは、バックエンドレベルのマッピングルールに優先します。つまり、プロダクトレベルのマッピングルールが先に評価されます。
    • どのバックエンドがリダイレクトされたトラフィックを受信するかにかかわらず、このマッピングルールは常に評価されます。

  • バックエンドレベルでのマッピングルール

    • バックエンドにマッピングルールを追加すると、それらのマッピングルールはそのバックエンドと結び付くすべてのプロダクトに追加されます。
    • このマッピングルールは、プロダクトレベルで定義されたマッピングルールの後に評価されます。
    • このマッピングルールは、マッピングルールが設定されたバックエンドにトラフィックがリダイレクトされた場合にのみ評価されます。
    • プロダクトに結び付けられるバックエンドのパスが、バックエンドの各マッピングルールの前に自動的に追加されます。

プロダクトレベルおよびバックエンドレベルのマッピングルールの例

1 つのバックエンドが設定されたプロダクトのマッピングルールの例を以下に示します。

  • Echo API バックエンド:

    • プライベートエンドポイント: https://echo-api.3scale.net

    • 以下のパターンの 2 つのマッピングルールが含まれる 

      /hello
/bye

  • Cool API プロダクト:

    • 公開エンドポイント: https://cool.api
    • ルーティングパス /echo により Echo API バックエンドを使用する

  • Cool API プロダクトには、自動的に以下のパターンのマッピングルールが含まれます。 

    /echo/hello
/echo/bye

ここで、同じ Echo API バックエンドを使用する Tools For Devs というプロダクトを追加することを考えてみます。

  • Tools For Devs プロダクト:

    • 公開エンドポイント: https://dev-tools.api
    • ルーティングパス /tellmeback により Echo API バックエンドを使用する

  • Tools For Devs プロダクトには、自動的に以下のパターンのマッピングルールが含まれます。 

    /tellmeback/hello
/tellmeback/bye

  • パターン /ping のマッピングルールを Echo API バックエンドに追加すると、Cool API プロダクトおよび Tools For Devs プロダクトの両方に変更が加えられます。

    • Cool API には、/echo/ping というパターンのマッピングルールが含まれます。
    • Tools For Devs には、/tellmeback/ping というパターンのマッピングルールが含まれます。

マッピングルールの照合

3scale では、前方一致に基づきマッピングルールを適用します。表記法は OpenAPI および ActiveDocs の仕様に準じます。

  • マッピングルールは、スラッシュ (/) で始める必要があります。

  • URL の文字列 (例: /hello) を使用してパスの照合を行います。

    • マッピングルールを保存すると、設定した URL 文字列にリクエストが送付され、それぞれのマッピングルールで定義したメトリクスまたはメソッドが呼び出されます。
  • マッピングルールでは、/{word}?value={value} のように、クエリー文字列またはボディーにパラメーターを含めることができます。

  • APIcast は以下のようにパラメーターを取得します。

    • GET メソッド: クエリー文字列から。
    • POST、DELETE、または PUT メソッド: ボディーから。
  • マッピングルールには、/{word} のように名前付きワイルドカードを含めることができます。このルールは、プレースホルダー {word} で定義する任意の文字にマッチします。たとえば、/morning のようなリクエストがマッピングルールにマッチします。ワイルドカードは、スラッシュとスラッシュの間またはスラッシュとピリオドの間に使用することができます。パラメーターにもワイルドカードを含めることができます。
  • デフォルトでは、指定したソート順に従ってすべてのマッピングルールが上から評価されます。ルール /v1 を追加した場合には、パスが /v1 で始まるリクエストにマッチします (例: /v1/word または /v1/sentence)。
  • パターンの最後にドル記号 ($) を追加して、完全一致を指定することができます。たとえば、/v1/word は、/v1/word のリクエストにだけマッチし、/v1/word/hello のリクエストにはマッチしません。完全一致を指定する場合には、すべてにマッチするデフォルトのマッピングルール (/) を必ず無効にする必要があります。
  • 複数のマッピングルールがリクエストのパスにマッチする場合がありますが、マッチするルールがなければ、リクエストは無視され HTTP 404 ステータスコードが返されます。

マッピングルールのワークフロー

マッピングルールに関するワークフローを以下に示します。

  • いつでも新たなマッピングルールを定義することができます。「Defining mapping rules」を参照してください。
  • 誤って変更されないように、次回のリロード時にマッピングルールはグレーアウト表示されます。
  • 既存のマッピングルールを編集するには、右側にある鉛筆アイコンをクリックして、まずそのルールを有効にする必要があります。
  • ルールを削除するには、ゴミ箱アイコンをクリックします。
  • Integration > Configuration で変更をプロモートすると、すべての変更および削除が保存されます。

他のマッピングルールの停止

1 つまたは複数のマッピングルールを処理した後、他のマッピングルールの処理を停止するには、新規マッピングルールの作成時に Last? を選択します。たとえば、API Integration Settings で以下のマッピングルールを定義し、それぞれのルールに異なるメトリクスが関連付けられていると仮定します。 

(get) /path/to/example/search
(get) /path/to/example/{id}

(get) /path/to/example/search の呼び出しを行う場合、ルールがマッチした後は、APIcast は残りのマッピングルールの処理を停止し、そのメトリクスのカウントを増やすのを停止します。