カスタムポリシー開発リファレンス

カスタムポリシーを構築する場合、Mule 4 のアーキテクチャと XML スキーマ言語が多用されているため、Mule 3 エンジンよりも Mule 4 エンジンの方が強力です。

Maven を使用して、Mule 4 ポリシーを構築およびデプロイします。ポリシーは、2 つのファイルで構成されます。

ポリシー実装が含まれるデプロイ可能な JAR ファイル。
ポリシーパラメーターとメタデータが定義される YAML 設定ファイル。

Maven でポリシーをパッケージ化するには、次のファイルで開発プロジェクトが構成されている必要があります。

XML テンプレート

Mule の XML スキーマ言語を使用するポリシーの実装が含まれます。
YAML ファイル

ポリシーの設定可能なパラメーターを定義します。Anypoint API Manager は、このファイルを使用して UI を表示し、ポリシーの入力を表示します。
テンプレートの pom.xml ファイル

ポリシー連動関係を定義します。パッケージ化種別は、mule-policy にする必要があります。pom.xml ファイルでは、Maven プロジェクト開発ライフサイクルの管理に役立つ他の Maven プラグインを定義できます。
リソース

ポリシーが連動する省略可能なファイル (証明書や設定プロパティファイルなど)。
mule-artifact.json 記述子

ポリシーでは、パッケージやリソース (Java クラスなど) をエクスポートできません。

基本的な XML 構造

以下は、ポリシー設定の基本構造の例です。

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:http-policy="http://www.mulesoft.org/schema/mule/http-policy">

  <http-policy:proxy name="policy-template">  (1)
     <http-policy:source>  (2)
          …  (3)
         <http-policy:execute-next/> (4)
          …  (5)
     </http-policy:source>
  </http-policy:proxy>
</mule>

1	ポリシーの定義は、名前引数が含まれる `http-policy:proxy` 要素で始まります。 `http-policy:proxy` 要素には、`http-policy:source` または `http-policy:operation` 要素が含まれている必要があります。この例では、`http-policy:source` が使用されています。
2	`http-policy:source` ブロックには、ポリシーで設定されている処理対象の Mule フローに対して実行される実際の命令が含まれます。`http-policy:source` ブロックでは、フローの開始時の HTTP リスナーイベントの発生前に命令を挿入したり、フローの完了後に命令を挿入したりできます。
3	`execute-next` 要素の前に定義された Mule イベント操作は、HTTP リスナーでフローが開始される前に実行されます。
4	`http-policy:execute-next` 要素は、Mule イベント処理を続行するために必要です。`http-policy:execute-next` 要素では、他のポリシーまたはアプリケーションフローをトリガーできます。ポリシーでは、`http-policy:execute-next` を実行しないことで、Mule イベント処理チェーンを停止できます。
5	`http-policy:execute-next` 要素の後に定義された Mule イベント操作は、フローの完了後に実行されます。これらの Mule イベントプロセッサーは、フローから返された Mule イベントを処理できます。

実行順序の理解

Mule アプリケーションに 2 つのポリシー A と B が含まれるケースを考えます。

ポリシー A の順序は 1 で、B の順序は 2 です。

ポリシー A は、次の設定で定義されています。

  <http-policy:proxy name="policy-A">
     <http-policy:source>
          <A1 />
         <http-policy:execute-next/>
          <A2 />
     </http-policy:source>
  </http-policy:proxy>

ポリシー B の設定は次のようになっています。

  <http-policy:proxy name="policy-B">
     <http-policy:source>
          <B1 />
         <http-policy:execute-next/>
          <B2 />
     </http-policy:source>
  </http-policy:proxy>

フローは次のように定義されています。

  <flow name="flow">
     <http:listener />
     <F1/>
  </flow>

HTTP 要求が Mule アプリケーションのエンドポイントに到達すると、下図の順序で実行されます。

<A1> → <B1> → <F1> → <B2> → <A2>

順序の小さいポリシーが最初に実行されます。フローは、常にポリシー操作の途中で実行されます。

このモデルでは、http-policy:execute-next 要素の有無によって Mule イベント処理チェーンを制御できます。

たとえば、http-policy:execute-next 要素を choice 要素内に配置すれば、choice の条件に応じて次の Mule イベントの実行を続行または停止できます。

以下の例では、受信リクエストヘッダーの名前が myHeader で、その値が someValue の場合にのみフローが実行されます。受信要求が制約を満たさない場合、メッセージが記録されます。

  <http-policy:proxy name="policy">
     <http-policy:source>
        <choice>
           <when expression="#[attributes.headers['myHeader'] == 'someValue']" >
              <http-policy:execute-next/>
           </when>
           <otherwise>
              <logger message="Avoid Flow execution" />
           </otherwise>
        </choice>
      </http-policy:source>
  </http-policy:proxy>

拡張機能の使用

ポリシーは、Mule アプリケーションのように Mule 拡張機能またはプラグインを使用して Mule コア機能を拡張できます。

たとえば、フローの HTTP リスナーから HTTP 応答にヘッダーを追加するには、ポリシーが必要になります。
まず、HTTP 要求オブジェクトを変更できる Maven 連動関係を追加します。

mule-http-policy-transform-extension Mule プラグインは、HTTP 要求を変更できます。

   <dependencies>
       <dependency>
           <groupId>com.mulesoft.anypoint</groupId>
           <artifactId>mule-http-policy-transform-extension</artifactId>
           <version>1.0.0</version>
           <classifier>mule-plugin</classifier>
       </dependency>
   </dependencies>

これらの例は、Mule 拡張機能 v1.0.0 を使用して開発されています。別のバージョンの拡張機能を使用すると、例は期待どおりに動作しない可能性があります。Mule 拡張機能バージョンを更新する場合は、「HTTP ポリシートランスフォーム拡張機能」を参照してください。

次に、XML http-transform 名前空間を追加して、上記の連動関係の操作を公開する必要があります。

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:http-policy="http://www.mulesoft.org/schema/mule/http-policy"
     xmlns:http-transform="http://www.mulesoft.org/schema/mule/http-policy-transform"
     xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
              http://www.mulesoft.org/schema/mule/http-policy http://www.mulesoft.org/schema/mule/http-policy/current/mule-http-policy.xsd
              http://www.mulesoft.org/schema/mule/http-policy-transform http://www.mulesoft.org/schema/mule/http-policy-transform/current/mule-http-policy-transform.xsd">

   <http-policy:proxy name="policy">
       <http-policy:source>
           <http-policy:execute-next/>

           <http-transform:add-headers outputType="response">
               <http-transform:headers>#[{'policyHeader': 'policyHeaderValue'}]</http-transform:headers>
           </http-transform:add-headers>
       </http-policy:source>
   </http-policy:proxy>
</mule>

ポリシーでカスタムコードを使用する必要がある場合、ポリシーで次のいずれかの作業を実行します。

Java または XML SDK 拡張機能でプログラミングされたカスタム Mule プラグインをインポートする
<scripting:execute> 要素を使用して、カスタムスクリプトを追加する

SDK 拡張機能を使用する方法をお勧めします。

カスタムポリシーでは、リソースやパッケージ (Java クラスなど) をエクスポートするコネクタは使用できません。たとえば、カスタムポリシーでは Java Connector や Spring Connector は使用できません。

アウトバウンドポリシー

ポリシーは、フロー内のアウトバウンド HTTP 要求に適用できます。この機能により、ポリシーを使用して、フローで定義された HTTP リクエスターを介して追加のヘッダーやその他の情報をアウトバウンド HTTP トラフィックに挿入できます。

以下は、ソースブロックと操作ブロックが含まれるポリシーの例です。

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:http-policy="http://www.mulesoft.org/schema/mule/http-policy">

  <http-policy:proxy name="policy-template">  (1)
      <http-policy:source>
     …
      <http-policy:execute-next/>
     …
      </http-policy:operation> (2)
  </http-policy:proxy>
</mule>

1	1 つの `http-policy:proxy` 要素は、両方の種別のポリシーブロックで使用されます。ソースブロックと操作ブロックは共存できます。両方のブロックが存在する場合、各ブロックで変数を共有して、ポリシー実行全体で状態を保持できます。
2	このポリシーブロックには、フローの HTTP リクエスターから HTTP 応答が返された後に実行されるコードが含まれます。フローに HTTP リクエスター要素が含まれていない場合、このブロックは実行されません。

通常、ポリシーで http-policy:operation ブロックを使用すると、Mule 実行が HTTP リクエスターに到達する前と HTTP リクエスターが応答を返した後にコードを挿入できます。操作ブロックには、フローの HTTP 要求の前後の操作を制御する http-policy:execute-next 要素を含めることができます。

実行順序の例

2 つのポリシー A と B があります。

ポリシー A の順序は 1 で、B の順序は 2 です。

ポリシー A は、次の設定で定義されています。

  <http-policy:proxy name="policy-A">
     <http-policy:source>
        <A1 />
        <http-policy:execute-next/>
        <A2 />
     </http-policy:source>

     <http-policy:operation>
        <A3 />
        <http-policy:execute-next/>
        <A4 />
     </http-policy:operation>
  </http-policy:proxy>

ポリシー B の設定は次のようになっています。

  <http-policy:proxy name="policy-B">
     <http-policy:source>
        <B1 />
        <http-policy:execute-next/>
        <B2 />
     </http-policy:source>

     <http-policy:operation>
        <B3 />
        <http-policy:execute-next/>
        <B4 />
     </http-policy:operation>
  </http-policy:proxy>

フローは次のように定義されています。

  <flow name="flow">
      <http:listener />
      <F1/>
      <http:request />
      <F2/>
  </flow>

Mule Runtime が HTTP 要求を受信するときの実行順序は次の図のようになります。

<A1> → <B1> → <F1> → <A3> → <B3> → <http:requester> → <B4> → <A4> → <F2> → <B2> → <A2>

操作ポリシーは、http:request 操作の周囲にのみ挿入されます。

エラー処理

Mule 4 ポリシーは、以下でスローされたエラーを処理できます。

ポリシー
Mule アプリケーション内のフロー
他のポリシー

エラー処理は、Mule 4 の try および error-handler 要素を使用して実現できます。

error-handler でエラーがキャッチされると、エラーが Mule イベント処理チェーンに伝播されるか、処理されて通常の Mule イベント処理が引き続き実行されます。

たとえば、次のポリシーとフローを考えます。

  <http-policy:proxy name="policy">
     <http-policy:source>
        <try>
           <P1 />
           <http-policy:execute-next/>
           <P2 />
           <error-handler>
              <on-error-continue>
                 <PEH />
              </on-error-continue>
           </error-handler>
        </try>
      </http-policy:source>
  </http-policy:proxy>

  <flow name="flow">
     <http:listener />
     <F1 />
     <F2 />
     <error-handler>
        <on-error-continue>
           <FEH />
        </on-error-continue>
     </error-handler>
  </flow>

シナリオ 1

<F1> でエラーが発生したと想定します。実行順序は下図のようになります。

<P1> → <F1> → <FEH> → <P2>

<F2> は実行されず、処理はフローの error-handler に続きます。
エラーを伝播しないようにフローの error-handler が設定されているため、<FEH> はポリシーに戻り、ポリシーの error-handler の代わりに <P2> が実行されます。

シナリオ 2

<P1> でエラーが発生したと想定します。実行順序は下図のようになります。

<P1> → <PEH>

上記の例では、フローは実行されません。

シナリオ 3

フローのエラーハンドラーがエラーを伝播するようになったと想定します。

  <error-handler>
     <on-error-propagate>
        <FEH />
     </on-error-propagate>
  </error-handler>

<F1> でエラーが発生したと想定します。実行順序は下図のようになります。

<P1> → <F1> → <FEH> → <PEH>

エラーがポリシーに伝播され、ポリシーのエラーハンドラーが引き続きエラーを処理します。

つまり、エラーハンドラーはポリシー内でフローを条件付きで実行する代替方法を提供します。

クラスローディング分離

ポリシー間

ポリシーには、Mule 4 アプリケーションと同じクラスローディング分離アーキテクチャがあるため、特定のポリシーで定義されたリソースまたはライブラリは他のポリシーに表示されません。

ポリシーとアプリケーション間

ポリシーと Mule 4 アプリケーション間のクラスローディングは、完全に分離されません。このシナリオは、アプリケーションとドメイン間のクラスローディング分離と似ています。

アプリケーションに表示されるプラグイン、ライブラリ、リソースは、そのアプリケーションに適用されるポリシーにも表示されます。

ただし、ポリシーに表示されるプラグイン、ライブラリ、リソースは、適用されるアプリケーションに表示されません。

連動関係の解決

同じ連動関係の異なるバージョンがポリシーとアプリケーションで使用される場合、アプリケーションの連動関係のバージョンがポリシーで使用されます。

クラスローディング分離についての詳細は、「クラスローディング分離」のトピックを参照してください。

変数とイベントスコープ

ポリシーでは、任意の数の変数を定義できます。ポリシースコープ内の変数は、ポリシーブロック間で共有できます。たとえば、http-policy:source ブロックで定義された変数 maxCount を後続の http-policy:operation ブロックで使用することができます。

ただし、ポリシーで定義された変数を他のポリシーやアプリケーションで使用することはできません。
また、アプリケーションで定義された変数をポリシーで使用することもできません。

ソースポリシーの Mule メッセージの伝播

ポリシーで Mule メッセージを変更できますが、Mule メッセージが変更された場所 (http-policy:execute-next 要素に対する相対的な場所) によっては変更が伝播されない可能性があります。

ソースポリシーの場合、http-policy:execute-next 要素の後で行われた Mule メッセージへの変更は、Mule イベント処理チェーンの残りの部分全体に引き続き伝播されます。

以下のポリシーとフローは、この概念を示しています。

<http-policy:proxy name="policy">
  <http-policy:source>
     <http-policy:execute-next/>
     <set-payload value="Policy Message" />
   </http-policy:source>
</http-policy:proxy>

<flow name="flow">
  <http:listener />
  <set-payload value="Flow Message" />
</flow>

クライアントに返される最終応答は、本文として「Policy Message (ポリシーメッセージ)」が含まれる HTTP 応答になります。

たとえば、execute-next 要素の前で行われた変更は、デフォルトで次のポリシーまたはアプリケーションに伝播されません。

以下のポリシーとフローを考えます。

<http-policy:proxy name="policy">
  <http-policy:source>
     <set-payload value="Policy Message" />
     <http-policy:execute-next/>
  </http-policy:source>
</http-policy:proxy>

<flow name="flow">
  <http:listener />
  <logger message=#[payload] />
</flow>

クライアントに返される最終応答は、空の本文が含まれる HTTP 応答になります。さらに、フローのロガーは空のペイロードを記録します。

Mule メッセージの伝播

http-policy:source タグ内で、属性 propagateMessageTransformations を true に設定して伝播を有効にします。

<http-policy:proxy name="policy">
  <http-policy:source propagateMessageTransformations="true">
     <set-payload value="Policy Message" />
     <http-policy:execute-next/>
  </http-policy:source>
</http-policy:proxy>

<flow name="flow">
  <http:listener />
  <logger message=#[payload] />
</flow>

クライアントに返される最終応答は、本文として「Policy Message (ポリシーメッセージ)」が含まれる HTTP 応答になります。フロー内のロガーは「Policy Message (ポリシーメッセージ)」を記録します。

この設計により、アプリケーションに影響する可能性のある意図しない変更が回避されます。

操作ポリシーの Mule メッセージの伝播

Mule メッセージの伝播は、ソースポリシーと似ていますが、方向が逆です。操作ポリシーの場合、execute-next 要素の前に行われた変更は常に伝播されます。execute-next 要素の後に行われた変更は、デフォルトで伝播されません。

伝播は、操作ポリシー定義の同じ属性 propagateMessageTransformations を使用して有効にできます。

<http-policy:proxy name="scope-payload">
   <http-policy:operation propagateMessageTransformations="true">
       …
       <http-policy:execute-next/>
       …
   </http-policy:operation>
</http-policy:proxy>

つまり、変数を使用してポリシーの情報を他のポリシーまたは Mule アプリケーションに共有することはできません。

ただし、Mule メッセージを使用してポリシーの情報を他のポリシーまたは Mule アプリケーションに共有することはできます。 Mule メッセージが設定されるポリシーブロック内の場所によっては、属性 propagateMessageTransformations を true に設定して Mule メッセージの伝播を有効にすることが必要になる場合もあります。

認証 (セキュリティコンテキスト)

ユーザー認証は、セキュリティコンテキストオブジェクト内の認証オブジェクトを介して公開できます。

ポリシーで設定した認証オブジェクトは、他のポリシーやアプリケーションで使用できます。
認証オブジェクトは、DataWeave を使用してアクセスできます。

#[authentication.principal]
#[authentication.password]
#[authentication.properties.someProperty]

認証オブジェクトを設定する方法は、SDK Mule 拡張機能を使用した連動関係のみです。
認証オブジェクトを設定する方法については、「認証ハンドラー」の記事を参照してください。

Mule 4 で提供されるポリシーでは、この抽出方法を使用してクライアント情報を伝播します。

YAML 設定ファイル

Mule 4 ポリシーでは、YAML ファイルを使用してメタデータとユーザーパラメーターを保存します。この柔軟な設計により、異なるユーザーパラメーターと設定が必要な複数の API でポリシーが機能します。

たとえば、レート制限ポリシーでは、ユーザーパラメーターに基づいて異なる設定を行うことができます。ユーザーは、ある API では最大 100 件/分の要求を許可し、別の API では最大 5000 件/分の要求を許可するということができます。

ユーザーパラメーターを許可するには、ポリシー開発者は YAML 設定ファイルでユーザー入力を定義します。こうすることで、API Manager でファイルが使用されて、ユーザー入力を求める UI が表示されます。

クライアント ID 適用の YAML ファイルの例

id: openam-access-token-enforcement  (1)
name: OpenAM access token enforcement  (2)
supportedPoliciesVersions: '>=v4'  (3)
description: Enforces access tokens by OpenAM.  (4)
category: Security  (5)
violationCategory: authentication  (6)
type: system  (7)
resourceLevelSupported: true  (8)
standalone: true  (9)
identityManagement:  (10)
type: OpenAM
- OAuth 2.0 protected
configuration:  (11)
- propertyName: scopes
  name: Scopes
  description: A space-separated list of supported scopes
  type: string
  optional: true
  sensitive: false
  allowMultiple: false
- propertyName: exposeHeaders
  name: Expose Headers
  description: In a proxy scenario, defines if headers should be exposed in the request to the backend. The headers that may
      be sent are the user properties returned by the federation server when validating the access token with a 'X-AGW-' prefix.
  type: boolean
  optional: true
  defaultValue: true
  allowMultiple: false

1	ポリシーの組織内の一意の ID。必須
2	API Manager の UI にポリシー名を表示するために使用されるわかりやすい名前。必須
3	非推奨のプロパティ。現時点では、値は「>=v1」に設定する必要があります。必須
4	ポリシーで実行する内容の説明。API Manager の UI でも使用されます。必須
5	ポリシーが属するカテゴリ。API Manager の UI でポリシーのグループ化や絞り込みを行うために使用されます。任意の String (文字列) 値が有効です。必須
6	さまざまなポリシー違反種別に関するメトリクスを表示するために Edge によって使用される値。必須
7	非推奨のプロパティ。値は「system」に設定する必要があります。必須
8	ポリシーの適用時にリソースレベルのポイントカットを有効にする必要があるかどうか。必須
9	非推奨のプロパティ。値は「true」に設定する必要があります。必須
10	API の組織に設定される ID 管理に関する情報がポリシーで必要かどうか。省略可能
11	ポリシーパラメーターが定義される場所。ここにリストされる各パラメーターは、想定されるユーザー入力として API Manager の UI に表示されます。値の配列が想定されます。必須

以下は、上記のポリシーのパラメーターを定義する構文です。

  propertyName: scopes (1)
  name: Scopes (2)
  description: A space-separated list of supported scopes (3)
  type: string (4)
  defaultValue: some String (5)
  optional: true (6)
  sensitive: false (7)
  allowMultiple: false (8)

1	パラメーターの内部名。ポリシー内の一意である必要があります。
2	パラメーターのわかりやすい名前。API Manager の UI に表示するために使用されます。
3	パラメーターの説明。これも、API Manager の UI に表示するために使用されます。
4	パラメーターの種別。
5	パラメーターのデフォルト値。
6	ユーザーがこの値を入力することが必須であるかどうか。
7	API Manager の UI で入力するときにこのプロパティをマスクする必要があるかどうか。
8	このパラメーターで複数の値を許可する必要があるかどうか。

パラメーターの型

パラメーターの種別に応じて、UI には次のようなさまざまな入力種別が表示されます。

テキストボックス
ラジオボタン
チェックボックス

一部の表示要素では、追加の設定が必要になります。次に、追加の設定が必要な要素のリストを示します。

String (文字列): 任意の文字列が想定されます。
Expression (式): #[ で始まり ] で終わる DataWeave 式が想定されます。
Boolean (ブール): true または false。
Int (整数): 数値が想定されます。この種別では、追加のプロパティが必要です。
```
  minimumValue: -1 (1)
  maximumValue: 2147483647 (2)
```
1 パラメーターで許可される最小値。

2 パラメーターで許可される最大値。
Radio (ラジオ): オプションのグループの 1 つの値。この種別では、追加のプロパティが必要です。
```
options: (1)
- name: HTTP Basic Authentication Header
  value: httpBasicAuthenticationHeader
- name: Custom Expression
  value: customExpression
```
1 ユーザーが選択するオプションのリスト。各オプションには、UI に表示するための名前があり、ポリシーでは内部値が使用されます。
Keyvalues: キー - 値ペアのコレクション。

HandleBars

ポリシーでは、Handlebars (ポリシーの設定可能なパラメーターを解決して、条件式などのセマンティックロジックを実装するテンプレートエンジン) がサポートされています。これは、ポリシーでユーザー入力を使用する場合の推奨方法です。

YAML 設定ファイルで定義された各ポリシーパラメーターは、最終ポリシー設定を解決するための HandleBars 変数として使用できます。

Handlebars は、Mule ポリシーの以前のバージョンで使用されていた Mustache の拡張機能です。

HandleBars 変数の型は、YAML で定義されたパラメーターの型に応じて変わります。

String (文字列)、Expression (式)、Radio (ラジオ)、Int (整数)、Boolean (ブール) は、HandleBars のプリミティブ型です。

プリミティブ型は、ポリシーテンプレートから波括弧 ({{{myproperty}}}) を使用して参照できます。

Keyvalues は、HandleBars の複合型です。複合型には内部プロパティがあり、次のように参照できます。

{{{keyvalue.key}}}
{{{keyvalue.value}}}

一部のプロパティは、YAML 設定ファイルで定義されていなくてもポリシーで使用できます。

policyId: ポリシーの記録や名前付けに役立つポリシーの ID。
isWsdlEndpoint: ポリシーが適用される API が WSDL API かどうかを示します。

API が適用される組織で ID 管理が定義されると、次のプロパティも使用できます。

identityManagementTokenUrl: ID 管理のイントロスペクションエンドポイント。 identityManagementClientId: イントロスペクションエンドポイントの認証用のクライアント ID。 identityManagementClientSecret: イントロスペクションエンドポイントの認証用のクライアントシークレット。

ポイントカット

以前のバージョンでは、カスタムポリシーを設定するのにポイントカット要素が必要でした。ポイントカットを使用して、ポリシーで操作する API を指定していました。
Mule 4 では、ポイントカット要素を設定する必要はありません。カスタムポリシーで操作する API に関する情報は、ポリシーの適用時に API Manager によって提供されます。

ポリシーがオンラインで適用されない場合の設定ガイドラインについては、オフラインポリシーを参照してください。