MuleSoft 入門(9)カスタムポリシーの開発

December 19, 2019 Minoru Nakanishi

こんにちは、アピリオ中西です。MuleSoft 入門ブログですが、今回は実践的な内容ということで「カスタムポリシー」の開発手順についてご紹介します。かなり複雑な内容なので入門編と言えるか怪しいですが、分かりやすくご紹介します。

前回は、MuleSoft 標準の提供ポリシーと SLA 層の利用による API アクセスの管理についてお話しました。標準のポリシーの組み合わせで幅広い要件はカバーできますが、場合によっては既存機能の拡張や新機能の定義が必要になります。

カスタムポリシーの実装を必要とするのは、社内ネットワークの認証、特定の API / リソースへのアクセスなど、複雑な要件をポリシーで満たす必要がある場合や、特定の定型的な処理(例えばログ出力)をポリシーとして実現したい場合が考えられます。ただし、ポリシーは API 実装と切り離して設定でき、複数の API に容易に適用できる点が強みであるため、再利用の必要性のない機能であれば API 実装に組み込んでしまう方がいい場合もあります。

開発手順の概要

Mule 4 におけるカスタムポリシーの開発手順は、大きく分けて以下の5ステップです。

(1) プロジェクトのセットアップ

(2) ポリシーの開発

(3) ポリシーのローカル環境での動作検証

(4) ポリシーアセットのデプロイ

(5) API Manager にてポリシーを API に適用

 

(1)プロジェクトのセットアップ

まず、カスタムポリシー開発の最初のステップはプロジェクトのセットアップです。基本的には Mule 公式ドキュメント(カスタムポリシーの開発の開始)に沿って進めれば大きくつまずくポイントはないと思います。任意のディレクトリにて、以下のような構成の雛形が生成されれば開発を開始できます。

<<ポリシーの名称>>/
├── <<ポリシーの名称>>.yaml
├── mule-artifact.json
├── pom.xml
└── src
   └── main
       └── mule
           └── template.xml

(2)カスタムポリシーの開発

実装時に最低限手を加える必要のあるファイルは <<ポリシーの名称>>.yaml, template.xml, pom.xml の3種類です。

<<ポリシーの名称>>.yaml 

API Manager から、ポリシーを適用する際に表示される設定ダイアログに表示される設定項目を定義するファイルです。リンクを参考に、設定ファイルを作成します。
 
なお、最低限動作する構成は以下です。
id: <<ポリシーの名称>>
name: <<ポリシーの名称>>
description: sample custom policy
category: Custom
violationCategory: system
type: custom
resourceLevelSupported: true
encryptionSupported: false
standalone: true
requiredCharacteristics: []
providedCharacteristics: []
configuration: []

一番下に定義してある configuration は、ポリシーの適用時にダイアログ上に表示される設定項目です。クライアント ID 適用の標準ポリシーの場合を例として挙げると、ポリシーの適用前に 「client_id/secret 情報の取得場所を表す "Client ID Expression" と ”Client Secret Expression" が設定項目になっています。

[Client ID Enforcement Policy の設定ダイアログ]

 

例えば、「ラジオボタンで選択させる設定項目」と「文字列の設定項目」の2つを定義する場合は以下のように記述します。

configuration: 
  - propertyName: radioSample  # プロパティの名称を記載します。
    name: Radio Property Sample  # 設定ダイアログに表示される、設定項目の名称。
    description: please select 1 or 2  # 設定ダイアログに表示される、設定項目の説明。
    type: radio  # 設定項目の型定義。ラジオボタンの場合は、key-value形式でoptionsを追加する。
    options: 
     - name: selection 1 
       value: 1 
     - name: selection 2
       value: 2
    defaultValue: 1  # デフォルト値の設定。
    optional: false  # ユーザーの入力が必須か否かの設定。
    sensitive: false  # 入力内容をマスクする必要があるか否かの設定。
    allowMultiple: false # 複数選択を許可するか否かの設定。
  - propertyName: stringSample 
    name: String Property Sample
    description: please input your name 
    type: string 
    defaultValue: Appirio Taro
    optional: false 
    sensitive: false 
    allowMultiple: false

なお、 configuration で定義された値はポリシー実装時に変数として利用できます。上記例のラジオボタンのユーザー入力値を取得したい場合は、{{{radioSample}}} という形式で実装ファイルに記述します。

template.xml

カスタムポリシーの実装ファイルで、通常の Mule アプリケーションのように Logger や Set-payload などを利用してフローを定義します。デフォルトでは次のような構成でテンプレートが生成されています。

<?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">
  <http-policy:source>
   (A)
   <http-policy:execute-next/>
   (B)
  </http-policy:source>
 </http-policy:proxy>
</mule>
(A)がフロー実行前に動作するロジック、(B)がフロー実行後に動作するロジックを定義する箇所です。
<logger level="INFO" message="#[payload]" />

例えば、以下のような Logger を (A) (B) 両方に定義したとすると、実行時には(A)は Request payload、(B)は Response payload がランタイムログに出力されます。

細かな実装時のリファレンスは Mule 公式ドキュメント(カスタムポリシー開発リファレンス)をご参照ください。

2019年12月時点では、Anypoint Studio 7.4 はカスタムポリシー実装をサポートしていないので、xml を直接編集して実装する必要があります。そのため、xml の名前空間の定義忘れや typo によるエラーに注意しましょう。個人的には、通常の Mule アプリケーションで類似フローを作成し、MUnit で動作検証をした上でコピーするのが現状の最善の実装手順だと思います。

(3)ポリシーのローカル環境での動作検証

先述のように xml を直接編集して実装したポリシーをデプロイし、API Manager で適用して初めて挙動を確認するのでは、開発効率が良いとは言えません。

そこで、開発したポリシーをローカルでテストするため「オフラインポリシー」という仕組みを利用します。オフラインポリシーは、API Manager 経由ではなく Mule ランタイムに直接適用する方法で、今回は Anypoint Studio にデフォルトで同梱されている Mule ランタイムプラグインを対象とします(スタンドアロンの Mule ランタイムを利用している場合でもほぼ同じ手順です)。

ポリシーをローカルで動作検証する場合は、API を呼び出すことのできる Mule アプリケーションを用意しておく必要があります。Request Payload をランタイムログに出力するだけの、シンプルな API で構いません。

 

ローカル環境でのカスタムポリシーの動作検証手順は次のようになります。

(1)カスタムポリシーをビルドして jar を作成する

カスタムポリシーの pom.xml が配置されているディレクトリで、下記コマンドを実行します。

mvn clean install

(2)%MULE_HOME% のパスを確認する

Mule アプリケーションをローカル実行した際に、コンソールログに表示されるパスです。Anypoint Studio を利用してMule アプリケーションを開発している場合は、同梱されている Mule Runtime のプラグインのパスが表示されると思います。

(2)%MULE_HOME% > policies > offline-policy 以下に、<<ポリシーの名称>>.json を作成

(3)作成した json に、下記の内容を記述する

{
 "template" : {
   "groupId" : "com.mulesoft.anypoint",
    "assetId" : "<<ポリシーの名称>>",
    "version" : "1.0.0-SNAPSHOT"
  },
  "api":[
    {
      "id":"00000"
    }
   ],
   "order":1,
   "configuration": {
      "payload": "payload",
      "logging_req":true
    }
}
api 属性に複数定義できる id には、ポリシー適用対象の Mule アプリケーションに定義した Autodiscovery 設定と同じ値を定義します("0000"はダミーのID、サーバーへのデプロイ時にAPI Managerで定義したAPIインスタンスのIDに変更する)。

(4)%MULE_HOME% > policies > policy 以下に、手順(1)で作成した jar を配置する

(5)テスト用の Muleアプリケーションを準備し、実行する

この時、アプリケーション実行の設定画面で次の起動時 JVM パラメータを設定する必要があります。

-Danypoint.platform.gatekeeper=disabled

アプリケーション起動後に任意の API をコールすることで、ポリシーの挙動を確認することができます。

※本記事執筆時(2019年12月)の私の環境は Anypoint Studio 7.4 かつ Mule ランタイム 4.2.1 です。バージョンによって挙動が変わる場合があるのでご注意ください。

(4) ポリシーアセットのデプロイ

Anypoint Platform の Exchange にアクセスするために、.m2 > server.xml にExchange へのAdmin 権限を持つAnypoint Platform ユーザー情報を追加します。

<server>
 <id>exchange-server</id>
 <username>対象Mule組織のAnypoint Platformユーザ名</username>
 <password>上記ユーザーのパスワード</password>
</server>

以下のコマンドで Exchange へのデプロイを行います。

mvn deploy

デプロイに成功すると、Anypoint Platform の Exchange にポリシーアセットが表示されます。

(5) API Manager にてポリシーをAPIに適用

環境へのデプロイが完了すると [Anypoint Platform] - [API Manager] - [任意のAPIインスタンス] - [Policies] から、標準のポリシーと同様にカスタムポリシーを適用することができるようになります。

 

いかがでしたでしょうか。カスタムポリシーの作成ができるようになると、固有の複雑な認証の仕組みをポリシーで一括対応するなどの応用の幅がかなり広がるので、覚えておく価値はあると思います。ただ、やはり開発が面倒なので、ポリシー専用のエディタ機能が提供される日を心待ちにしています。

次回は、Mule API のバージョン管理の方針についてご紹介します。

 

[MuleSoft 入門シリーズ]

MuleSoft 入門(1)MuleSoft による API-led なアプリケーションネットワーク

MuleSoft 入門(2)ようこそ Anypoint Platform へ

MuleSoft 入門(3)Anypoint Studio による API の実装

MuleSoft 入門(4)DataWeave によるデータ変換

MuleSoft 入門(5)Flow Designer で Mule アプリケーションを開発

MuleSoft 入門(6)MUnit による単体テスト

MuleSoft 入門(7)API 開発におけるテストの考え方

MuleSoft 入門(8)ポリシーと SLA

MuleSoft 入門(9)カスタムポリシーの開発

MuleSoft 入門(10)Mule API のバージョン管理

MuleSoft 入門(11)ランタイムログの自動アーカイブ

著者について

2018年にアピリオに入社し、Salesforce を中心としたクラウドの世界に足を踏み入れました。2019年には MuleSoft のプロジェクトに携わり、API 主導の開発に強い興味と関心を持っています。IT 技術の変遷が激しい今だからこそ、勉強に励んで自分の価値を高めようと絶賛奮闘中です。

Minoru Nakanishi のコンテンツをもっと見る
戻る
MuleSoft 入門(8)ポリシーと SLA
MuleSoft 入門(8)ポリシーと SLA

これまで API の実装開発とテストの手法に関して紹介してきましたが、 API は実装したらすぐに運用開始できるというものではありません。今回は、API のアクセス制限の要である API Manager の機能の中...

次へ
MuleSoft 入門(10)Mule API のバージョン管理
MuleSoft 入門(10)Mule API のバージョン管理

Mule による API 開発では 3 つのバージョン(アセットのバージョン」、「API のバージョン」、「API リソースのバージョン」)を管理する必要があります。今回はこの Mule API のバージョン管理に...

アピリオまでお気軽にお問合せください

ご質問はこちら