1. ホームページ
  2. DataWeave
  3. 言語ガイド

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

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

組み込みの 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
    }
  )
    dataweave

  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" })
dataweave

次に、結果を示します。

出力
{
  "UserKey": "bar"
}
json

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 本文で使用できるようになります。次の例では、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"
dataweave

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

  • モジュールをインポートする (例: 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"
json

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

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

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

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

カスタムモジュールを 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

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

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

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

DWL ファイルの参照

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

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

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

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

DataWeave 関数のドキュメント化

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

  • 関数の説明。

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

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

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

  • === Parameters

  • === Example

    • ==== Source

    • ==== Input

    • ==== Output

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

説明セクション

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

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

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

  • 詳細な説明: 関数に関する追加情報。この省略可能な説明は、簡単な説明の下で 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​ 関数のドキュメントを示しています。

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
dataweave

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

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

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

次の例では、​@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()
dataweave

次の例では、 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"}
}
dataweave

関連情報