第1章 APIcast の運用
本セクションでは、高度な APIcast 設定を使用する際に考慮すべき概念について説明します。
1.1. マッピングルール
マッピングルールにより、API に対するリクエストに応じて報告するメトリクスまたはメソッドを定義します。マッピングルールの例を以下に示します。
このルールは、/ で始まるすべての GET リクエストがメトリクス hits のカウントを 1 つ増やす、という意味です。このルールは API に対するすべてのリクエストにマッチします。ただし、このルールは一般的すぎるので、通常は変更されます。
より具体的な Echo API ルールの例を以下に示します。
1.1.1. マッピングルールの照合
マッピングルールは前方一致で照合され、複雑な設定が可能です (表記法は OpenAPI および ActiveDocs の仕様に準じます)。
-
マッピングルールは、スラッシュ (
/) で始める必要があります。 -
文字列 (例:
/hello) を使用してパスの照合を行うことができます。 マッピングルールでは、クエリー文字列またはボディーにパラメーターを含めることができます (例:
/{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 ステータスコードが返されます。
1.1.2. マッピングルールのワークフロー
マッピングルールに関するワークフローを以下に示します。
- 新たなマッピングルールを定義することができます (マッピングルールの追加 を参照)。
- 誤って変更されないように、次回のリロード時にマッピングルールはグレーアウト表示されます。
- 既存のマッピングルールを編集するには、右側にある鉛筆アイコンをクリックして、まずそのルールを有効にする必要があります。
- ルールを削除するには、ゴミ箱アイコンをクリックします。
- Update & Test Staging Configuration をクリックすると、すべての変更および削除が保存されます。
マッピングルールの追加
新たなマッピングルールを追加するには、以下の手順を実施します。
- Add Mapping Rule をクリックします。
以下の設定を指定します。
-
Verb: HTTP リクエストの動詞 (
GET、POST、DELETE、またはPUT)。 -
Pattern: 照合するパターン (例:
/hello)。 -
+: メトリクスのカウントを増やす数 (例:
1)。 -
Metric (or method): メトリクスまたはメソッドの名前 (例:
gethello)。
-
Verb: HTTP リクエストの動詞 (
- Update & Test Staging Configuration をクリックして変更を適用します。
他のマッピングルールの停止
他のマッピングルールの処理を停止するには、Last? を選択します。たとえば、API Integration Settings で以下のマッピングルールを定義し、それぞれのルールに異なるメトリクスが関連付けられている場合には、
(get) /path/to/example/search
(get) /path/to/example/{id}
(get) /path/to/example/search の呼び出しを行う場合、APIcast は残りのマッピングルールを処理してルールがマッチした際にそのメトリクスのカウントを増やすのを停止します。
マッピングルールの並べ替え
マッピングルールを並べ替えるには、各マッピングルールの Last? 設定の横にある緑色の矢印を使用して、ルールをドラッグアンドドロップします。Update & test in Staging Environment をクリックすると、指定した並べ替えがデータベースに保存されプロキシー設定に維持されます。
その他の設定オプションは、高度な APIcast 設定 を参照してください。
