1. Homepage
  2. Mule Runtime (4.4)
  3. Mule 3 ユーザー向けの Mule 4 情報
  4. Mule 4 への移行
  5. API ゲートウェイの移行

  6. API ポリシーの移行

API ポリシーの移行

Mule 4 では、ポリシーが大幅に変更されています。詳しい説明は、 「Custom Policy General Reference (カスタムポリシーの一般リファレンス)」 (2017 年 11 月)​ に記載されています。

ポリシーの動作の定義

3.x では、特定のポリシー内のロジックが 2 つのブロックに分割されています。次のポリシーまたはフローの前に実行されるブロックと、その後に実行されるブロックです。

Mule 3 の例
<?xml version="1.0" encoding="UTF-8"?>
<policy online="false"
        xmlns="http://www.mulesoft.org/schema/mule/policy"
        xmlns:mule="http://www.mulesoft.org/schema/mule/core"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:api-platform-gw="http://www.mulesoft.org/schema/mule/api-platform-gw"
        xsi:schemaLocation="http://www.mulesoft.org/schema/mule/policy http://www.mulesoft.org/schema/mule/policy/current/mule-policy.xsd
              http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
              http://www.mulesoft.org/schema/mule/api-platform-gw http://www.mulesoft.org/schema/mule/api-platform-gw/current/mule-api-platform-gw.xsd">

    <before>
        <mule:set-payload value="(pre)"/>
    </before>

    <after>
        <mule:set-payload value="(post)"/>
    </after>

    <pointcut>
        <api-platform-gw:api-pointcut apiName="sampleApi" apiVersion="1.0.0"/>
    </pointcut>

</policy>

Mule 4 では、ポリシーが ​before​ と ​after​ ブロックに分けられなくなりました。 ポリシーは次のポリシーまたはフローに明示的にジャンプするフローとして機能するようになり、ポリシー内でこのジャンプを定義する必要があります。

Mule 4 では、次の設定で同じ動作を実行できます。

Mule 4 の例
<?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"
      xmlns="http://www.mulesoft.org/schema/mule/core"
      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-policy:proxy name="policy-deployment">
        <http-policy:source propagateMessageTransformations="true">

            <set-payload value="(pre)"/>

            <http-policy:execute-next/>

            <set-payload value="(post)"/>

        </http-policy:source>
    </http-policy:proxy>
</mule>

注意点:

  • ロジックは同じブロックに配置されます。フローの前に動作を挿入するには、単に ​execute-next​ 要素の前にロジックを配置します。フローの後に動作を挿入するには、その要素の後にロジックを配置します。

  • http-policy:source​ 要素の ​propagateMessageTransformations​ 属性: Mule 4 以降、フローを実行する前に Mule メッセージ (ペイロードまたは属性) を変更しても、デフォルトではフローに反映されません。反映されるようにするには、​propagateMessageTransformations​ を ​true​ に設定する必要があります。

  • pointcut​ 要素が、ポリシー設定ファイルで定義されなくなりました。現在は、ポリシーが API Manager から取得されたときに、API ゲートウェイがこの要素を解決します。

エンドポイントとアプリケーションの ​pointcut​ 要素を使用できなくなり、その代わりになるものもありません。

ポリシーテンプレートの Exchange へのアップロード

3.x では、ポリシーが定義されると XML ファイルが生成され、そのファイルを API Manager にアップロードする必要があります。

Mule 4 では、ポリシーの動作が定義されると、そのポリシーをポリシーテンプレート JAR にパッケージ化して Exchange にアップロードし、API Manager で使用可能にする必要があります。

  1. ポリシーテンプレート JAR を生成する Maven プロジェクトの作成方法は、記事​「Packaging a Custom Policy (カスタムポリシーのパッケージ化)」​に記載されています。

  2. JAR の Exchange へのアップロード方法は、記事​「Uploading a Custom Policy to Exchange (カスタムポリシーの Exchange へのアップロード)」​に記載されています。

以前と同様、ポリシーテンプレート JAR が Exchange にアップロードされると、JAR がアップロードされたのと同じ組織に属する API の API Manager に表示されます。

ポリシーの移行の実行

ポリシーの移行を実行するこの例では、GitHub オープンソースプロジェクトである Mule Migration Assistant (MMA) を使用します。この手順では、ツールの​ 前提条件​​を満たしている必要があります。MMA の完全なユーザードキュメントについては、 「Migration to Mule 4 (Mule 4 への移行)」(GitHub)​ を参照してください。

ポリシーを移行するための MMA コマンドは、Mule アプリケーションを移行するための一般的な コマンドラインオプション (GitHub)​​ とは 1 つの重要な点で異なります。

  • MMA の ​-projectBasePath​ では、ポリシー XML ファイルと YAML ファイルの両方が同じディレクトリ内にある必要があります。次の例では、ポリシーファイルが ​src/main/policy​ 内にあることが想定されています。

コマンドラインの呼び出し:
$ java -jar mule-migration-assistant-runner-0.5.1.jar \
 -projectBasePath /Users/me/AnypointStudio/workspace-studio/my-mule3-policy/src/main/policy \
 -muleVersion 4.1.5 \
 -destinationProjectBasePath /Users/me/my-dir/my-migrated-policy

MMA では、​-destinationProjectBasePath​ オプションを使用して移行したプロジェクトのディレクトリが作成されます。​my-migrated-policy​ は、コマンドを呼び出す前には​存在しない​必要があります。すでに存在するフォルダーを指定すると、移行は次のようなエラーで失敗します。 ​Exception: Destination folder already exists. (例外: 宛先フォルダーがすでに存在しています。)

移行が正常に実行されると、次のようなメッセージが表示されます。

成功した移行
Executing migration...
...
========================================================
MIGRATION SUCCESS
========================================================
Total time: 11.335 s
Migration report:
/Users/me/my-dir/my-migrated-policy/report/summary.html

移行が正常に完了すると、宛先フォルダーには次の内容が含まれます。

  • ポリシー POM ファイル。

  • ポリシー YAML ファイル。POM ファイル内にある ​artifactId​ 値に名前が変更されます。

  • Mule 移行レポート (GitHub)​ (​summary.html​) を含む ​report​ ディレクトリ。 このレポートで提供されるものと同じ情報は、ポリシー XML ファイルにコメントとして含まれています。

  • MMA コマンドで設定された ​-muleVersion​ 値と一致する ​minMuleVersion​ 値が設定された ​mule-artifact.json​ ファイル。

  • src​ ディレクトリ。移行したコンテンツが含まれます。

src​ ディレクトリには、​main​ および ​test​ ディレクトリが含まれます。​main​ 内では、​mule​ ディレクトリにポリシー XML ファイルが含まれ、​template.xml​ に名前が変更されます。​mule​ ディレクトリと同じレベルで、移行したポリシーに必要な DataWeave ファイルまたはその他のファイルを含む ​resources​ ディレクトリが作成される場合があります。 test​ ディレクトリには、テスト設定ファイルが含まれます。

移行に成功したら、​POM の移行​で説明されているように、POM ファイルを変更する必要があります。POM ファイルに適切な組織 ID が設定されたら、​mvn clean install​ を使用してコンパイルできます。コンパイルに成功した場合、​maven clean deploy​ を使用して移行したポリシーを Exchange にアップロードできます。カスタムポリシーのアップロードについての詳細は、​「Exchange へのカスタムポリシーのアップロード」​を参照してください。

POM の移行

POM ファイルの移行により、カスタムポリシーを Exchange にアップロードするために必要な要素が含まれるようにファイルが変更されます。

移行後:

<groupId/>​ および ​<exchange.url/>​ 要素の ​{orgId}​ 値は、Anypoint Platform にある組織 ID に置き換えられます。

組織 ID を取得する方法についての詳細は、​「Exchange へのカスタムポリシーのアップロード」​を参照してください。

デフォルトでは、Exchange URL は本番環境に設定されます。

<groupId>{orgId}</groupId>

<properties>
 <exchange.url>https://maven.anypoint.mulesoft.com/api/v1/organizations/{orgId}/maven</exchange.url>
</properties>

EU バージョンの URL の場合、移行後に URL を手動で設定する必要があります。

  • EU の URL テンプレート: https://maven.eu1.anypoint.mulesoft.com/api/v1/organizations/{orgId}/maven

MMA がポリシーの POM ファイルを見つけられない場合、新しい POM ファイルが作成されます。このファイルでは、ポリシーの ​artifactId​ はポリシー XML ファイルの親ディレクトリの名前になります。たとえば、​src/main/mytestpolicy/policy.xml​ 内のポリシーの場合、​artifactId​ は ​mytestpolicy​ です。

連動関係およびプラグインバージョン

連動関係およびプラグインバージョンは MMA によってデフォルトで設定されており、必要に応じて手動で変更できます。

未移行の要素

いくつかの要素は、Mule 3 から Mule 4 に移行されません。

要素 理由

policy:before-exception

Mule 4 では動作を再現できません。

policy:pointcut​

リソースと API のポイントカットは、Mule Runtime Engine によって自動的に解決されます。Mule 4 では、アプリケーションとエンドポイントのポイントカットに同等のものはありません。

policy:data​

この動作は、Mule Runtime Engine によって自動的に解決されます。

これらの各要素では、子要素も削除されます。

他の構造に移行される要素

delay-response​ 要素の子要素として複数の ​rate-limit​ 要素が見つかった場合、調整要素 ​fixed-time-frame-algorithm​ はレート制限形式に移行されます。

さらに、調整 SLA ポリシーはサポートされなくなったため、​delay-response​ 要素が ​sla-based-algorithm​ 要素の子として見つかった場合、ポリシーはレート制限 SLA 形式に移行されます。

一般的な移行の問題

移行中にポリシーファイルが見つからない場合、MMA は次のようなメッセージを出力します。

失敗した移行
Executing migration...
...
===============================================================================
MIGRATION FAILED
===============================================================================
Total time: 3.008 s
Exception: Cannot read mule project. Is it a Mule Studio project?
com.mulesoft.tools.migration.engine.exception.MigrationJobException: Cannot read mule project. Is it a Mule Studio project?
	at com.mulesoft.tools.migration.engine.project.MuleProjectFactory.getMuleProject(MuleProjectFactory.java:50)
	at com.mulesoft.tools.migration.engine.MigrationJob.generateSourceApplicationModel(MigrationJob.java:116)
	at com.mulesoft.tools.migration.engine.MigrationJob.execute(MigrationJob.java:80)
	at com.mulesoft.tools.migration.MigrationRunner.main(MigrationRunner.java:83)

===============================================================================

POM の移行の問題

MMA がポリシーの POM モデルを見つけられない場合、Mule 3 の既存の POM からモデルが生成されるか、Mule 3 POM がない場合はモデルが作成されます。MMA が既存の POM を使用している場合、不正な POM 定義が検出されると POM モデルの作成プロセスが失敗します。POM モデル障害に関する情報については、POM モデルの変更時の MMA ステップに関する前のエラーメッセージを確認する必要があります。

YAML の移行の問題

次の問題が発生する可能性があります。

事例 理由

YAML の編集エラー

詳細は、MMA のスタック追跡を使用してください。

複数の YAML が見つかった

MMA では、プロジェクトのベースパスに 1 つの YAML ファイルのみが必要です。これは、ポリシー YAML として解釈されます。 プロジェクトに複数の YAML が必要な場合は、追加の YAML ファイルを別のディレクトリに保存する必要があります。

YAML が見つからない

MMA では、移行の開始時にプロジェクトのベースパスに YAML ファイルが必要です。何も見つからない場合、移行プロセスの早い段階で別のエラーが発生していた可能性があります。

脅威保護の移行の問題

次の問題が発生する可能性があります。

事例 理由

ポリシーが XML 脅威保護種別か JSON 脅威保護種別かを判断できなかった

脅威保護ポリシーでは、移行する脅威保護の種別は要素 ​xml-policy​ と ​json-policy​ によって決まります。いずれか 1 つのみが存在する必要があります。いずれも存在しない場合、移行レポートにエラーメッセージが表示されます。

要素 ​structure​ が見つからなかった

脅威保護ポリシーでは、​xml-policy​ 要素に子要素の ​structure​ が必要です。

要素 ​values​ が見つからなかった

脅威保護ポリシーでは、​xml-policy​ 要素に子要素の ​values​が必要です。

クライアント ID 適用の移行の問題

次の問題が発生する可能性があります。

事例 理由

クライアント ID 適用の移行要素が無効

validate-client​ 要素の ​basicAuthEnabled​ 属性が存在しないか ​false​ の場合、MMA では ​validate-client​ 要素に ​clientSecret​ または ​clientId​ 属性が存在する必要があります。

Spring の制限

MMA によって Mule 3 ポリシーの ​spring:bean​ 要素が ​resources​ ディレクトリの ​template-beans.xml​ ファイルに移行される場合でも、​template-beans.xml​ を参照する ​spring-module:config​ 要素がカスタムポリシーに追加される場合でも、Spring Bean の手動移行を実行する必要があります。Mule 4 ではポリシーでの Bean の宣言はサポートされておらず、ポリシーのデプロイに失敗します。

既知の問題

MMA には、次の既知の問題があります。

  • 拡張子が ​.yml​ のポリシー YAML ファイルを使用するポリシーは検出されない。

  • ポリシー YAML ファイルの必須項目が自動入力されない。

  • mule:processor​ 要素が移行されない。

  • byte-array-to-string-transformer​ 要素が移行されない。

  • expression-component​ 要素が移行されない。

  • mulexml:object-to-xml-transformer​ 要素が移行されない。

  • 移行した要素 ​ee:transform​ にスキーマの場所の URI が追加されない。

  • アンダースコアで始まる DataWeave 式は引用符が付けられないため、ポリシーが失敗する。

関連情報

API ゲートウェイの移行

API ゲートウェイの移行: Autodiscovery

API ゲートウェイの移行: Mule Runtime の設定

コアコンポーネントの移行

レート制限および調整ポリシー

レート制限 SLA ベースポリシー

Exchange へのカスタムポリシーのアップロード