カスタムモジュールおよびマッピングの作成

組み込みの DataWeave 関数モジュール (​dw::Core​ や ​dw::Crypto​ など) を使用する以外にも、カスタムモジュールおよびマッピングファイルを作成して使用することもできます。 例は、データ抽出および変換の一般的なアプローチを示しています。 開始する前に、Mule 4 アプリケーションでは DataWeave のバージョン 2.x が使用されることに注意してください。Mule 3 アプリケーションでの DataWeave については、​DataWeave バージョン 1.2 のドキュメント​を参照してください。 他の Mule バージョンの場合は、DataWeave の目次のバージョンセレクターを使用できます。

DataWeave 言語 (​.dwl​) ファイルでモジュールおよびマッピングファイルを作成し、Mule コンポーネントの DataWeave スクリプトで Mule アプリケーションにインポートします。モジュールとマッピングファイルのどちらも、同じ機能を何度も再利用する必要がある場合に役立ちます。

  • カスタムモジュールでは、関数、変数、型、名前空間を定義できます。これらのモジュールを DataWeave スクリプトにインポートして機能を使用できます。

  • カスタムマッピングファイルは、インポートして別の DataWeave スクリプトで使用したり、Mule コンポーネントで参照したりできる完全な DataWeave スクリプトが含まれるモジュールの種類です。

多くの Mule Connector およびコンポーネントの項目では、DataWeave 式やスクリプトを使用できます。

カスタムモジュールではなく、組み込みの DataWeave 関数モジュールをインポートして使用する場合、​「DataWeave 関数リファレンス」​を参照してください。

DataWeave マッピングファイルを作成して使用する

DataWeave 変換を ​.dwl​ マッピングファイル (マッピングモジュール) に保存し、そのファイルを別の DataWeave スクリプトにインポートできます。マッピングファイルは、Transform Message コンポーネントで実行したり、別のマッピングにインポートして ​main​ 関数で実行したりできます。

例: DataWeave マッピングファイル
Figure 1. 例: Studio プロジェクトの DataWeave マッピングファイル
  1. Studio プロジェクトで、マッピングモジュールのサブフォルダーとファイルをセットアップします。

    • src/main/resources​ にサブフォルダーを作成するには、[New (新規)] → [Folder (フォルダー)] → [your_project] → ​src/main/resources​ に移動して、​modules​ という名前のフォルダーを追加します。

    • そのフォルダーのモジュールの新しいファイルを作成するには、[New (新規)] → [File (ファイル)] → [your_project] → ​src/main/resources/modules​ に移動し、​MyMapping.dwl​ のような DWL (DataWeave 言語) ファイルを追加します。

      src/main/resources​ 内にモジュールを保存すると、そのプロジェクトの Mule アプリケーション内のどの DataWeave スクリプトでもそのモジュールにアクセスして使用できるようになります。

  2. 次のように、マッピングファイルで関数を作成します。

    例: マッピングファイルのコンテンツ
    %dw 2.0
    import dw::core::Strings
    fun capitalizeKey(value:String) = Strings::capitalize(value) ++ "Key"
    ---
    payload mapObject ((value, key) ->
        {
          (capitalizeKey(key as String)) : value
        }
      )
  3. DWL 関数モジュールファイルを保存します。

DataWeave スクリプトでのマッピングファイルの使用

マッピングファイルを使用するには、DataWeave スクリプトにインポートし、マッピングファイルで ​main​ 関数を使用してスクリプトの本文にアクセスする必要があります。

このスクリプトが含まれる ​MyMapping.dwl​ ファイルが ​/src/main/resources/modules​ に作成されていることが前提となっています。

MyMapping.dwl​ ファイル (上記) の本文の式を DataWeave マッピングファイルにインポートして使用するには、次の作業が必要になります。

  • ヘッダーで ​import​ ディレクティブを指定します。

  • MyMapping::main​ 関数を呼び出します。この関数では、マッピングファイルと同じ構造の入力を想定しています。たとえば、​MyMapping.dwl​ の本文では、​{"key" : "value"}​ の形式のオブジェクトを想定しています。

例: DataWeave スクリプトにマッピングをインポートして使用する
%dw 2.0
import modules::MyMapping
output application/json
---
MyMapping::main(payload: { "user" : "bar" })

次に、結果を示します。

出力
{
  "UserKey": "bar"
}

capitalizeKey​ 関数は非公開でも ​main​ 関数コールで使用されます。また、DataWeave マッピングファイルで ​dw::core::Strings​ モジュールをインポートして再利用することもできます。

カスタムモジュールの作成および使用

カスタム DataWeave モジュールを作成する手順は、カスタムマッピングファイルを作成する手順とほぼ同じです。​.dwl​ ファイルのコンテンツのみが異なります。一般的な DataWeave スクリプトまたはマッピングファイルとは異なり、カスタム DataWeave モジュールでは、ヘッダーセクションと本文セクションの間に ​output​ ディレクティブ、本文の式、区切り文字 (​---​) を含めることができません。マッピングに関する指針については、「​DataWeave マッピングファイルを作成して使用する​」を参照してください。

例: DataWeave カスタム関数モジュール
Figure 2. 例: Studio プロジェクトのカスタムモジュール

カスタムモジュールファイルには、次のように ​var​、​fun​、​type​、​ns​ 宣言のみを含めることができます。

例: カスタム DataWeave モジュール
%dw 2.0
var name = "MyData"
fun myFunc(myInput: String) = myInput ++ "_"
type User = {
    name: String,
    lastname: String
}
ns mynamespace http://acme.com/bar

カスタムモジュールを別の DataWeave スクリプトにインポートすると、モジュールで定義された関数、変数、型、名前空間を DataWeave 本文で使用できるようになります。次の例では、DataWeave スクリプトで以下の作業を行います。

  • ヘッダーの ​import​ ディレクティブでモジュール ​MyModule​ をインポートする。この場合、インポートされたモジュールは Studio プロジェクトパス ​src/main/resources/modules/MyModule.dwl​ に保存されます。

  • MyModule::myFunc("dataweave")​ を使用して ​MyModule​ の関数をコールする。

例: カスタム DataWeave モジュールをインポートして使用する
%dw 2.0
import modules::MyModule
output application/json
---
MyModule::myFunc("dataweave") ++ "name"

いくつかの方法でモジュールまたは要素をインポートできます。

  • モジュールをインポートする (例: import modules::MyModule​)。この場合、要素 (ここでは関数) をコールするときに ​MyModule::myFunc​ のようにモジュールの名前を含める必要があります。

  • モジュールのすべての要素をインポートする (例: import * from modules::MyModule​)。この場合、要素をコールするときにモジュールの名前を含める必要はありません。たとえば、​myFunc("dataweave") ++ "name"​ は動作します。

  • モジュールの特定の要素をインポートする (例: import myFunc from modules::MyModule​)。この場合、要素をコールするときにモジュールの名前を含める必要はありません。たとえば、​myFunc("dataweave") ++ "name"​ は動作します。たとえば、​import myFunc someOtherFunction from modules::MyModule​ (モジュールで ​myFunc​ と ​someOtherFunction​ の両方が定義されていることが前提) のようにモジュールの複数の要素をインポートできます。

出力
"dataweave_name"

インポートされる要素のローカル別名の割り当て

名前のクラッシュを避けるために、モジュールを DataWeave スクリプトにインポートするときに ​as​ を使用してカスタムモジュールまたはその要素の別名を割り当てることができます。

MyModule.dwl​ ファイルで次のようなカスタムモジュールを定義していることが前提となっています。

例: カスタムモジュール
%dw 2.0
fun myFunc(name:String) = name ++ "_"
var myVar = "Test"

カスタムモジュールを DataWeave スクリプトにインポートするときに、次のようにカスタムモジュールの要素の別名を作成できます。

例: インポートされる要素に別名を適用する
%dw 2.0
import myFunc as appendDash, myVar as weaveName from modules::MyModule
var myVar = "Mapping"
output application/json
---
appendDash("dataweave") ++ weaveName ++ "_" ++ myVar

このスクリプトでは ​"dataweave_Test_Mapping"​ を返します。

次のようにインポートされるモジュールの別名を作成できます。

例: インポートされるモジュールに別名を適用する
%dw 2.0
import modules::MyModule as WeaveMod
output application/json
---
WeaveMod::myFunc("dataweave")

DWL ファイルの参照

DWL ファイルは、Mule Connector およびコンポーネントで直接使用できます。

詳細は、​「dwl ファイル」​を参照してください。

カスタム DataWeave モジュールのドキュメントの記述

DataWeave では、関数、型、アノテーション、およびこれらが含まれるモジュールのドキュメント化に AsciiDoc テキスト形式の使用をサポートしています。

DataWeave 関数のドキュメント化

DataWeave では、関数コードをドキュメント化するための複数セクションのテンプレートを定義しています。テンプレートでは、次の目的のセクションが提供されます。

  • 関数の説明。

  • AsciiDoc テーブル形式でのパラメーターの説明。

  • 入力、DataWeave スクリプト、生成される出力のセクションが含まれるコード例。

関数の説明の下でパラメーターと例のセクションを定義するために、テンプレートでは AsciiDoc の見出しの文法を使用しています。

  • === Parameters

  • === Example

    • ==== Source

    • ==== Input

    • ==== Output

次の関数テンプレートは、関数のドキュメント化に関する指針となります。テンプレートで示されているように、一部のセクションは省略可能です。

/**
* %Replace with your function description%
*
*
* %Add additional information to your function description% (optional section)
*
* === Parameters (optional section)
*
* [%header, cols="1,1,3"]
* |===
* | Name | Type | Description
* | %`The parameter name`% | %`The parameter type`% | %The parameter description%  (one row per param)
* |===
*
* === Example (optional section)
*
* %The example description% (optional)
*
* ==== Source (optional section)
*
* [source,%The language%,linenums] (optional)
* ----
* YOUR CODE
* ----
*
* ==== Input (optional section)
*
* The input description (optional)
*
* [source,%The language%,linenums] (optional)
* ----
* YOUR CODE
* ----
*
* ==== Output (optional section)
*
* %The output description% (optional)
*
* [source,%The language%,linenums] (optional)
* ----
* YOUR CODE
* ----
*/

説明セクション

このセクションでは、関数の説明を提供します。このセクションはコメントの上部で開始され、最初のセクションの見出しの前の行までになります。セクションヘッダーがない場合、説明は関数のコメントの最後までになります。

説明は次のパートで構成されます。

  • 簡単な説明: 最初のパラグラフで、関数の主な説明となります。

  • 詳細な説明: 関数に関する追加情報。この省略可能な説明は、簡単な説明の下で 2 つの改行を挟んで開始されます。

パラメーターと例のセクションを含む説明が含まれている​​を参照してください。

各パートは自動生成ドキュメントで便利です。

パラメーターセクション

省略可能な ​=== Parameters​ セクションで、関数のパラメーターについて説明します。

テンプレートでは、AsciiDoc テーブル形式を使用してテーブル行で各パラメーターをドキュメント化しています。

[%header, cols="1,1,3"]
|===
| 名前 | 型 | 説明
| yourParameter1 | パラメーターの型 | ここに説明を記述します。
| yourParameter2 | パラメーターの型 | ここに説明を記述します。
|===

例セクション

0 個以上の ​=== Example​ セクションを使用して、関数の仕組みを説明するために必要な例を提供できます。

このセクションには、次の省略可能なサブセクションが含まれます。

  • DataWeave スクリプトへの入力用の ​==== Input​。

  • DataWeave スクリプト用の ​==== Source​。

  • スクリプトによって生成される出力用の ​==== Output​。

すべてのサブセクションは、省略可能な説明と省略可能なコードセクションが含まれる同じテンプレートに従います。

セクションの説明

[source,%The language%,linenums]
----
YOUR CODE
----

次の例では、 log​ 関数のドキュメントを示しています。

/**
* Without changing the value of the input, ​`log`​ returns the input as a system
* log.So this makes it very simple to debug your code, because any expression or subexpression can be wrapped
* with ​*log*​ and the result will be printed out without modifying the result of the expression.
* The output is going to be printed in application/dw format.
* (1)
*
* The prefix parameter is optional and allows to easily find the log output.
*
*
* この関数を使用して、DataWeave スクリプトのデバッグを容易にします。A Mule app
* outputs the results through the ​`DefaultLoggingService`, which you can see
* in the Studio console.
*
* === Parameters
*
* [%header, cols="1,13"]
* |===
* | 名前 | 型 | 説明
* | `prefix` | ​`String` | 通常はログを説明する文字列 (省略可能)。
* | `value` | ​`T` | ログに記録する値。
* |===
*
* === Example
*
* 次の例では、指定されたメッセージをログに記録します。Note that the ​`DefaultLoggingService`​
* in a Mule app that is running in Studio returns the message
* `WARNING - "Houston, we have a problem,"`​ adding the dash ​`-`​ between the
* prefix and value.The Logger component's ​`LoggerMessageProcessor`​ returns
* the input string ​`"Houston, we have a problem."`, without the ​`WARNING`​ prefix.
*
* ==== Source
*
* [source,DataWeave,linenums]
* ----
* %dw 2.0
* output application/json
* ---
* log("WARNING", "Houston, we have a problem")
* ----
*
* ==== Output
*
* `Console Output`​
*
* [source,XML,linenums]
* ----
* "WARNING - Houston, we have a problem"
* ----
*
* `Expression Output`​
*
* [source,XML,linenums]
* ----
* "Houston, we have a problem"
* ----
*
* === Example
*
* This example shows how to log the result of expression ​`myUser.user`​ without modifying the
* original expression ​`myUser.user.friend.name`​.
*
* ==== Source
*
* [source,DataWeave,linenums]
* ----
* %dw 2.0
* output application/json
*
* var myUser = ​{user: {friend: {name: "Shoki"}, id: 1, name: "Tomo"}, accountId: "leansh" }
* ---
* log("User", myUser.user).friend.name
* ----
*
* ==== Output
*
* `Console output`​
*
* [source,console,linenums]
* ----
* User - {
*   friend: {
*     name: "Shoki"
*   },
*   id: 1,
*   name: "Tomo"
* }
* ----
*
* `Expression Output`​
*
* [source,DataWeave,linenums]
* ----
* "Shoki"
* ----
*/

DataWeave モジュールのドキュメント化

DataWeave モジュールの説明は、構造化されたテンプレートに従いません。

唯一の要件は、ドキュメントを DataWeave バージョンタグの上に配置することです。

次の例では、 dw::Core​ モジュールをドキュメント化しています。

/**
 * This module contains core DataWeave functions for data transformations.
 * It is automatically imported into any DataWeave script. For documentation
 * on DataWeave _1.0_ functions, see
 * https://docs.mulesoft.com/dataweave/1.2/dataweave-operators[DataWeave Operators].
 */
%dw 2.0

アノテーションと型のドキュメント化

アノテーションと型のドキュメント化は、構造化されたテンプレートに従いません。

唯一の要件は、アノテーションまたは型の定義の上に説明を記述することです。

次の例では、​@StreamCapable​ アノテーションをドキュメント化しています。

/**
* Annotation that marks a parameter as stream capable, which means that this
* field will consume an array of objects in a forward-only manner.
*/
@AnnotationTarget(targets = ["Parameter", "Variable"])
annotation StreamCapable()

次の例では、 dw::extension::DataFormat​ モジュールにある ​EncodingSettings​ 型をドキュメント化しています。

/**
 * Represents encoding settings.
 */
@Since(version = "2.2.0")
type EncodingSettings = {
    /**
    * Encoding that the writer uses for output. Defaults to "UTF-8".
    */
    encoding?: String {defaultValue: "UTF-8"}
}