1. Homepage
  2. Mule ゲートウェイ
  3. Mule ゲートウェイポリシー
  4. リソースレベルのポリシー

  5. URI テンプレート正規表現の設定

URI テンプレート正規表現の設定

API によって公開されているリソースの一部にポリシーを適用する場合には、正規表現 (regex) を指定することで、複数のパスを含めることができます。正規表現の式は、ポリシーの ​URI template regex​ 項目で指定できます。

URI template regex​ を設定する場合は、アプリケーションを実装 (またはプロキシを使用) する Mule Runtime Engine (Mule) アプリケーションのベースパスを考慮する必要があります。その理由は、Mule 4 のリソースレベルポリシーは、API がデプロイされている場所に依存するためです。

この図は、ポリシーを適用するリソースサブセットを指定するメソッドのリストを示しています。

API エンドポイントと対応する GET および POST メソッドを示すリスト

この API 仕様は、次の Mule アプリケーションで実装されています。

<api-gateway:autodiscovery apiId="1" flowRef="proxy"/>

<http:listener-config name="httpConfig" basePath="api">
   <http:listener-connection host="localhost" port="80"/>
</http:listener-config>

<flow name="proxy">
   <http:listener config-ref="httpConfig" path="v1/*" />
   <logger />
</flow>

この例では、​http:listener-config​ は ​basePath​ 属性と、パス ​v1/​ の最後にある ​​ の前に追加パス v1 の両方を定義しています。これら 2 つのパスを連結した ​/api/v1​ が​ベースパス​として参照されます。

API ​resource-1​ の最初のリソースを呼び出すには、ベースパスをリソースパス ​resource-1: http://localhost:80/api/v1/resource-1​ と組み合わせて使用する必要があります。

以後、​resource-1​ をポリシーで保護するには、リソースレベルのポリシーを使用する必要があります。そのため、ポリシーを適用するときに指定する ​URI テンプレート正規表現​にはベースパスを含める必要があります。

URI テンプレート正規表現​の設定方法を下図に示します。

設定を特定の API メソッドおよびリソースに適用できるフォーム

API のアセットタイプが RAML または OAS である場合、​Preview Resource Matching​ オプションは実際のランタイム動作とは異なり、どのリソースとも一致したとは示しません。

また、正規表現を使用することで、ベースパス (例: .*/resource-1​) を明示的に指定する必要がなくなります。ただし、同じ名前のリソースが API 定義の別のレベルにも存在する場合は、正規表現によってそれらすべてと一致してしまうため問題が発生します。つまり、正規表現が ​/api/v1/resource-1​ と ​/api/v1/resources/resource-1​ の両方と一致するため、結果が曖昧になってしまいます。

ignoreBasePath を使用する状況

リソースレベルのポリシーを適用するときにリソースのフルパスにベースパスを含めることで、設計時の API とランタイムの API が強制的に結合されます。これは、リソースレベルポリシーを適用するときには、API のデプロイ先となるベースパスを知る必要があるためです。

この結合の問題を回避するため、Mule 4.3.0 には新しい設定が追加され、Mule ポリシーエンジンが受信した HTTP 要求をポリシーの ​URI テンプレート正規表現​と一致させるときに、API リソースのベースパスを無視できるようになりました。

この設定は、API を実装する Mule アプリケーションで公開されます。

<api-gateway:autodiscovery apiId="1" flowRef="flow_api" ignoreBasePath="true"/>

ignoreBasePath​ 属性を ​true​ に設定すると、API のデプロイ先となるベースパスは考慮されなくなります。

機能の前提条件

この機能を実装するには、Mule アプリケーションが次の条件を満足していることが必要です。

  • Mule 4.3.0 で動作している

  • HTTP 用 Anypoint Connector (HTTP Connector) 1.5.15 以降を使用している

下位互換性を実現するため、この機能は属性が ​true​ に明示的に設定されない限り無効化されています。Mule アプリケーションがバージョン 4.3.0 より古い Mule で動作していて、リソースレベルのポリシーが正しく設定されている場合は、何も変更を行わなくても Mule 4.3.0 以降に移行できます。

API Manager で使用できる API プロキシの最新バージョンは、ベースパスを無視するように事前に設定されています。旧バージョンの API プロキシを使用して実装されている既存のリソースレベルポリシーとの互換性を保証するため、この機能を搭載した以下のメジャーバージョンの API プロキシがリリースされています。

  • HTTP プロキシ 2.0.0

  • HTTP プロキシ 3.0.0

Mule バージョン 4.2.x および 4.1.x ではリソースレベルのポリシーが互換モードで機能するため、これらのプロキシバージョンをデプロイすることはお勧めしません。これらのプロキシバージョンをデプロイする場合、Mule 4.3.x に移行する前に URI テンプレート設定を更新する必要があります。

機能の制限

ベースパスの要件

API のルートパスは、API のベースパスを計算できるように正しく定義されている必要があります。Mule アプリケーションで設定されている HTTP リスナーのパス属性の末尾が ​*​ であることを確認してください。そうでない場合は、​ignoreBasePath​ が ​false​ に設定されている場合と同じようにリソースレベルポリシーの一致が行われます。

クエリパラメーターの除外

正規表現は要求の URI パスコンポーネントに対してのみ照合を行い、クエリパラメーターは考慮されません。たとえば、​/api/products.*123​ のような正規表現パターンは ​/api/products/123​ には一致しますが ​/api/products?id=123​ には一致しません。

関連情報