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

December 19, 2019 Minoru Nakanishi

こんにちは、アピリオ中西です。第3回は Anypoint Studio による API の実装手順について説明しました。その中で、MIME Type を切り替えることで出力形式を変更するという簡単な実装を例に DataWeave というデータ変換言語について触れました。今回はその DataWeave について焦点を当て、解説しようと思います。

DataWeave の概要

DataWeave は、Mule アプリケーションを介して受け取ったデータ( payload, attributes, variables など)にアクセスし、変換するための独自の MuleSoft 式言語(Expression Language)です。本記事は Mule 4で利用される DataWeave 2.0 に基づいた記載となります。DataWeave は1.0から2.0へのバージョンアップでかなり大きく言語仕様が変更されているので、注意してください。DataWeave は 以下の2つに大きく大別できます。 

・xml に直接記載するインライン DataWeave スクリプト

・Transform Message コンポーネント上に記載するスタンドアロンの DataWeave スクリプト

前者のインラインDataWeave スクリプトは、データをその場で変換し、さまざまなプロパティの値を動的に設定することができます。スクリプトは #[ ] コードブロックで囲みます。例えば、DataWeave スクリプトを使用して Choice ルータの条件を設定したり、Set Payload または Set Variable コンポーネントの値を設定したりできます。

第3回で、以下のようなシンプルな Mule フローを紹介しました。この例では入力値や外部リクエストのレスポンスの変換を行いますが、その変換処理に主に利用されるのが DataWeave です。インラインのスクリプトは様々なコンポーネントで利用できますが、payload などの Mule イベントを変換する場合は、多くの場合は Transform Message コンポーネントにスタンドアロンの DataWeave スクリプトを記述します。

[ Mule フローの例]

なお、Transform Message コンポーネントではインライン形式でスクリプトを記述することも、別ファイル( ***.dwl )で定義してスクリプトを保管することもできます。DataWeave スクリプト自体の単体テストを行う場合は、MUnit からスクリプトを呼び出せるように別ファイルでの定義を推奨します。DataWeave スクリプトの単体テストに関しては、MuleSoft 入門(6)MUnitによる単体テストの記事をご参照ください。

DataWeave スクリプトの構造

DataWeave スクリプトとファイルは2つのセクションに分割されます。

ヘッダー:本文のスクリプトに適用するディレクティブを定義します。

本文:出力構造を生成するスクリプトが含まれます。

ヘッダーを含めた場合、ヘッダーは本文の上に表示され3 つのダッシュ "---" で構成される区切り文字で分離されます。

%dw 2.0 
output application/json     // ここまでヘッダー
---                         // 区切り文字
message.payload             // 本文

[ヘッダーを含む DataWeave スクリプトの例]

DataWeave スクリプトのヘッダーセクション

ヘッダーセクションでは、以下のキーワードが定義できます。

キーワード
詳細
%dw

DataWeave のバージョンを示し、省略可能。 デフォルトでは2.0が指定される。

(例) %dw 2.0

output

スクリプトから出力される MIME タイプを指定。

有効な値は 公式ドキュメント:DataWeave でサポートされる形式 を参照。

(例) output application/json

import

DataWeave 関数モジュールをインポートする。

リファレンス詳細は 公式ガイド:DataWeave リファレンス を参照。

(例) import dw::core::Strings

var

DataWeave スクリプトの本文全体で参照できる変数を定義する。 定数や式も定義可能。

詳細は 公式ガイド:DataWeave 変数 を参照。

(例1) var msg = ”Hello”

(例2) var toUpper = (str) -> upper(str)

type

式で使用できるカスタム型を指定する。

(例) type Currency = String { format: "\$#,###.00"}

ns

名前空間のインポートに利用する。

(例) ns ns0 http://www.abc.com

fun

スクリプト本文から参照できるカスタム関数を定義する。

(例) fun toUser = (user) -> {firstName: user.name, lastName: user.lastName}

ヘッダーセクションは省略が可能ですが、メンテナンス性を考慮し DataWeave バージョンおよび出力形式の記載を推奨します。

DataWeave スクリプトの本文セクション

DataWeave 本文には、出力構造を生成する式を記述します。変数に定義されたフィールドにセレクタを利用してアクセスしたり、関数や型定義を利用して変換したりすることで、変換後の出力構造を定義します。

例えば、次に示す(A)の構造の payload を(B)の構造に変換する場合を考えます。

// (A) 変換前の payload

{
  "bookTitle": "MuleSoftトレーニング",
  "autherFirstName": "アピリオ",
  "autherLastName" : "太郎",
  "price": 1000
}
// (B) 変換後の payload

{
  "title": "MuleSoftトレーニング",
  "auther": "アピリオ太郎",
  "price": "1,000.00"
}

この場合の DataWeave 変換スクリプトは次のようになります。

%dw 2.0
output application/json
---
{
  "title": payload.bookTitle, //セレクタでフィールドにアクセスし、新たに定義したjson定義にマップ
  "auther": payload.autherFirstName ++ payload.autherLastName, // ++ 関数による文字列の連結
  "price": payload.price as String {format: "#,###.00"} // Stringの型定義と、フォーマット指定
}

※コメントは Java に類似した記法で、単一行と複数行の使い分けができます。(// および /** */)

DataWeave における型定義

DataWeave は、配列、ブール、オブジェクト、日付、日時を含め、さまざまな型のデータで動作します。 dw::Core モジュール内の型 ( Core 型) は、Core モジュールをインポートしなくても使用できます。他のモジュールについては、モジュールをインポートしてその関数と型を使用できるようにする必要があります。以下に、Core 型の

モジュール
詳細

Array

配列には、サポートされるすべての型の要素を保持できます。

(例1) [ "sample1", "sample2"]

(例2)[{"name": "アピリオ太郎", "age": 30},{"name": "アピリオ次郎", "age": 25}]

Boolean

Boolean は、キーワード true および false によって定義されます。

CData

XML では、String を継承・拡張したCDataという名称のカスタム型を定義します。値は<![CDATA[***]]>というセクションに定義され、XML で利用可能な文字をすべて記述することができます。

日時

DataWeave の日付は ISO-8601 標準に従い、リテラルは "|" 文字の間で定義されます。

(例1)var date = |2019-12-01|

Date / DateTime / LocalDateTime / LocalTime / Period / Time / TimeZone の7種類の日付型をサポートします。書式設定文字 (日付形式 yyyy-MM-dd の y、M、d など) は、概ね Java8 の "java.time.format" パッケージに基づいてサポートされています。

Enum

Enum 型は、"java.lang" パッケージの Enum Java クラスに基づきます。DataWeave で利用する場合は、Java のクラスを指定する "class" プロパティを定義する必要があります。

Iterator

Iterator 型は、配列を反復処理する "java.util" パッケージの Iterator Java クラスに基づきます。Iterator にはコレクションとコレクションの反復処理および絞り込みを行うメソッドが含まれます。

Number

浮動小数点数値および整数値の両方をサポートする1つの数値型のみがあります。MuleSoft のエンジンが精度を損なわない最も効率の良い方法でデータを常に保存し、あらゆる操作においても精度を保ちます。

Object

任意のオブジェクトを "Key:value" ペアのコレクションとして表します。オブジェクトは中括弧 {} で囲んで表示しますが、1つの "Key:value" ペアしか含まれないオブジェクトの場合は中括弧は省略可能です。

Regex

正規表現は、/ (スラッシュ)の間に定義され、文字列、オブジェクト、配列などに対してアクションを実行する特定の操作にて、引数として使用します。

String

シングル / ダブルクォーテーションにて定義します。( "" もしくは '')

MuleSoft は Java で開発されたオープンソースのアプリケーション統合/連携用のフレームワークなので、Java の知見があれば型や言語仕様の理解の助けになるかもしれません。

今回は DataWeave の構造と記法に関してご紹介しました。後半では具体的な DataWeave の変換例を交えて、より実践的な内容をご紹介していこうと思います。

 

[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 入門(4)DataWeave によるデータ変換(2/2)
MuleSoft 入門(4)DataWeave によるデータ変換(2/2)

今回は、より実践的な DataWeave の変換例を紹介しようと思います。変数や関数の利用、典型的な変換パターンを例を交えて説明します。

次へ
MuleSoft 入門(3)Anypoint Studio による API の実装(2/2)
MuleSoft 入門(3)Anypoint Studio による API の実装(2/2)

第3回目では、Mule API 開発の基本的な流れと Eclipse ベースの開発ツールである Anypoint Studio について説明します。前半では Mule API の開発作業全体の流れと Anypoin...

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

ご質問はこちら