カスタムモジュールおよびマッピングの作成
組み込みの 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 関数で実行したりできます。
-
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 スクリプトでもそのモジュールにアクセスして使用できるようになります。
-
-
次のように、マッピングファイルで関数を作成します。
例: マッピングファイルのコンテンツ%dw 2.0 import dw::core::Strings fun capitalizeKey(value:String) = Strings::capitalize(value) ++ "Key" --- payload mapObject ((value, key) -> { (capitalizeKey(key as String)) : value } ) -
DWL 関数モジュールファイルを保存します。
DataWeave スクリプトでのマッピングファイルの使用
マッピングファイルを使用するには、DataWeave スクリプトにインポートし、マッピングファイルで main 関数を使用してスクリプトの本文にアクセスする必要があります。
このスクリプトが含まれる MyMapping.dwl ファイルが /src/main/resources/modules に作成されていることが前提となっています。
MyMapping.dwl ファイル (上記) の本文の式を DataWeave マッピングファイルにインポートして使用するには、次の作業が必要になります。
-
ヘッダーで
import ディレクティブを指定します。 -
MyMapping::main 関数を呼び出します。この関数では、マッピングファイルと同じ構造の入力を想定しています。たとえば、MyMapping.dwl の本文では、{"key" : "value"} の形式のオブジェクトを想定しています。
%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 マッピングファイルを作成して使用するを参照してください。
カスタムモジュールファイルには、次のように var、fun、type、ns 宣言のみを含めることができます。
%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 の関数をコールする。
%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"] |=== | Name | Type | Description | 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"]
* |===
* | 名前 | Type | Description
* | `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"}
}