DataWeave スクリプト

DataWeave は Mule フローで使用する主データ変換言語です。開始する前に、Mule 4 アプリケーションでは DataWeave のバージョン 2.x が使用されることに注意してください。Mule 3 アプリケーションでの DataWeave については、DataWeave バージョン 1.2 のドキュメントを参照してください。他の Mule バージョンの場合は、DataWeave の目次のバージョンセレクターを使用できます。

Transform Message コンポーネントでスタンドアロンの DataWeave スクリプトを記述できます。また、インライン DataWeave 式を記述すると、データをその場で変換し、さまざまなプロパティの値 (イベントプロセッサーまたはグローバル設定要素の設定項目など) を動的に設定することもできます。インライン DataWeave 式は #[ ] コードブロックで囲みます。たとえば、DataWeave 式を使用して、Choice ルーターの条件を設定したり、Set Payload または Set Variable コンポーネントの値を設定したりできます。

次の例の DataWeave コードでは、DataWeave の now() 関数を使用して、タイムスタンプ変数を現在時刻に設定しています。

例: 簡単なインライン DataWeave スクリプト

<set-variable value="#[now()]" variableName="timestamp" doc:name="Set timestamp" />

DataWeave コードを外部ファイルに保存して他の DataWeave スクリプトに読み込んだり、Mule アプリケーションのすべてのコンポーネントで共有できる再利用可能な DataWeave 関数のモジュール (ライブラリ) に DataWeave コードをファクタリングしたりすることもできます。

DataWeave スクリプトの構造

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

ヘッダー: 本文の式に適用するディレクティブを定義します (省略可能)。
本文: 出力構造を生成する式が含まれます。

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

DataWeave ファイルの例を次に示します。このファイルでは、ヘッダーで出力ディレクティブを宣言し、その後の DataWeave 式で、子の 2 つのキー/値ペアを含むユーザーオブジェクトを作成します。

例: 簡単な DataWeave スクリプト

%dw 2.0
output application/xml
---
{
  user: {
    firstName: payload.user_firstname,
    lastName: payload.user_lastName
  }
}

DataWeave ヘッダー

この例は、ヘッダーディレクティブで使用できるキーワード (import、var など) を示しています。

DataWeave スクリプト

%dw 2.0
import * from dw::core::Arrays
var myVar=13.15
fun toUser(obj) = {
  firstName: obj.field1,
  lastName: obj.field2
}
type Currency = String { format: "##"}
ns ns0 http://www.abc.com
output application/xml
---
/*
 * Body here.
 * /

%dw: DataWeave バージョンは省略可能です。デフォルトは 2.0 で、これは DataWeave のすべての 2.x バージョンに対応します。

例: %dw 2.0
output: スクリプトから出力される MIME タイプを特定する、よく使用されるディレクティブ。

例: output application/xml

有効な値: サポートされるデータ形式。

デフォルト: 出力が指定されていない場合、デフォルトの出力は、スクリプトで使用されている入力 (ペイロード、変数など) を検査するアルゴリズムによって決まります。
1. 入力がない場合、デフォルトの output application/java になります。
2. すべての入力の MIME タイプが同じ場合、スクリプトの出力は同じ MIME タイプになります。たとえば、すべての入力が application/json の場合、output application/json が出力されます。
3. 各入力の MIME タイプが異なり、出力が指定されていない場合、スクリプトは例外をスローして、出力の MIME タイプを指定するようにユーザーに知らせます。
  
  指定できる出力のタイプは 1 つのみです。
import: DataWeave 関数モジュールをインポートします。「DataWeave 関数」を参照してください。
var: DataWeave スクリプトの本文全体で参照できる定数を定義するためのグローバル変数。
例
```
%dw 2.0
var conversionRate=13.15
output application/json
---
{
 price_dollars: payload.price,
 price_localCurrency: payload.price * conversionRate
}
```
詳細は、「DataWeave 変数」を参照してください。
type: 式で使用できるカスタム型を指定します。

完全な例は、「DataWeave を使用した型の強制」を参照してください。

ns: 名前空間。名前空間をインポートするために使用します。

例

%dw 2.0
output application/xml

ns ns0 http://www.abc.com
ns ns1 http://www.123.com
---
{
    ns0#myroot: {
         ns1#secondroot: "hello world"
    }
}

fun: スクリプトの本文内からコールできるカスタム関数を作成します。

例

%dw 2.0
output application/json
fun toUser(user) = {firstName: user.name, lastName: user.lastName}
---
{
  user: toUser(payload)
}

インライン DataWeave スクリプトにヘッダーを含める

インライン DataWeave スクリプトを記述する場合、DataWeave スクリプトのすべての行を 1 つの行にフラット化することで、ヘッダーディレクティブを含めることができます。小さな DataWeave スクリプトの場合、これにより、ヘッダーディレクティブをすばやく適用し (個別の Transform Message コンポーネントを追加して変数を設定する必要はありません)、次のイベントプロセッサーで変数を置き換えることができます。

たとえば、前述の Transform Message コンポーネントと同じ有効な XML 出力を作成する Mule 設定の XML を次に示します。

例: 簡単なインライン DataWeave スクリプト

<set-payload value="#[output application/xml --- { myroot: payload } ]" doc:name="Set Payload" />

DataWeave ドキュメントに多くの変換例が記載されています。

DataWeave 本文

DataWeave 本文には、出力構造を生成する式が含まれます。MuleSoft では、DataWeave モデルを使用してデータを操作するための正規の方法 (クエリ、変換、ビルドプロセス) が提供されています。

DataWeave スクリプト用の JSON 入力を提供する簡単な例を次に示します。

例: JSON 入力

{
    "message": "Hello world!"
}

この DataWeave スクリプトは、上の JSON 入力のペイロード全体を取得して application/xml 形式に変換します。

例: application/xml を出力するスクリプト

%dw 2.0
output application/xml
---
payload

次の例は、DataWeave スクリプトから生成された XML 出力を示しています。

例: XML 出力

<?xml version='1.0' encoding='UTF-8'?>
<message>Hello world!</message>

上のスクリプトは JSON 入力を XML 出力に正常に変換します。

エラー (スクリプティングエラーと書式設定エラー)

DataWeave スクリプトは、DataWeave コーディングエラーを原因とするエラーと書式設定エラーを原因とするエラーをスローする可能性があります。このため、データ形式を変換する場合、言語と形式の両方の制約に留意することが重要です。たとえば、XML には単一ルートノードが必要です。上の DataWeave スクリプトを使用して次の JSON 入力を XML に変換しようとすると、JSON 入力に単一ルートがないためエラー (Unexpected internal error) が発生します。

例: JSON 入力

{
    "size" : 1,
    "person": {
      "name": "Yoda"
    }
}

スクリプトを作成するには、入力を JSON に似た application/dw 形式に標準化することをお勧めします。実際に、エラーが発生した場合は、単に入力を application/dw に変換することができます。変換が成功した場合、エラーは書式設定エラーの可能性があります。変換が失敗した場合、エラーはコーディングエラーの可能性があります。

次の例では、出力形式を application/dw に変更します。

例: application/dw を出力する DataWeave スクリプト

%dw 2.0
output application/dw
---
payload

このスクリプトでは上記の JSON 入力例から application/dw 出力が正常に生成されることを確認できます。

例: application/dw 出力

{
  size: 1,
  person: {
    name: "Yoda"
  }
}

つまり、前述のエラー (Unexpected internal error) は、コーディングではなく形式に固有のエラーであることがわかります。上記の application/dw 出力では、XML 形式で必要な単一ルート要素が提供されていないことを確認できます。XML 出力用のスクリプトを修正するには、例えば次のように単一ルート要素をスクリプトに提供する必要があります。

例: application/xml を出力するスクリプト

%dw 2.0
output application/xml
---
{
    "myroot" : payload
}

出力が XML の要件を満たすようになったため、出力ディレクティブを application/xml に戻すと、結果として有効な XML 出力が生成されます。

例: 単一 XML ルートを含む XML 出力

<?xml version='1.0' encoding='UTF-8'?>
<myroot>
  <size>1</size>
  <person>
    <name>Yoda</name>
  </person>
</myroot>

DataWeave コメント

Java に似た構文を使用するコメントも DataWeave で受け入れられます。

%dw 2.0
output application/json
---
/* Multi-line
 * comment syntax */
payload
// Single-line comment syntax

Anypoint Studio で発生する可能性があるエラーを回避するには、DataWeave スクリプトの本文の最初の行がコメントである場合に、複数行のコメント構文 (/*comment here*/) を使用します。後続のスクリプトコメントには任意の構文 (//comment または /*comment*/) を使用できます

特殊文字のエスケープ

DataWeave では、バックスラッシュ (\) を使用して、入力文字列で使用している特殊文字をエスケープします。

詳細は、「特殊文字のエスケープ」を参照してください。

DataWeave スクリプトの入力文字列では特殊文字がエスケープされますが、出力では、出力形式の要件に従ってエスケープされます。この要件は、application/json、application/xml、application/csv などの形式によって異なる可能性があります。

この例では、二重引用符で囲まれた内部の二重引用符がエスケープされます。

DataWeave の例

%dw 2.0
output application/json
---
{
    "a": "something",
    "b": "dollar sign (\$)",
    "c": 'single quote (\')',
    "c": "double quote (\")",
    "e": `backtick (\`)`
}

JSON 出力でも、出力が有効な JSON になるように二重引用符がエスケープされますが、他の文字はエスケープされません。

JSON 出力

{
  "a": "something",
  "b": "dollar sign ($)",
  "c": "single quote (')",
  "c": "double quote (\")",
  "e": "backtick (`)"
}

次の例では、同じ文字がエスケープされますが、XML に出力されます。

DataWeave の例

%dw 2.0
output application/xml
---
{
  xmlExample:
  {
     "a": "something",
     "b": "dollar sign (\$)",
     "c": 'single quote (\')',
     "d": "double quote (\")",
     "e": `backtick (\`)`
   }
}

XML 出力は、(JSON 出力とは異なり) 二重引用符をエスケープしなくても有効です。

XML 出力

<?xml version='1.0' encoding='UTF-8'?>
<xmlExample>
  <a>something</a>
  <b>dollar sign ($)</b>
  <c>single quote (')</c>
  <d>double quote (")</d>
  <e>backtick (`)</e>
</xmlExample>

有効な識別子を宣言するためのルール

有効な識別子を宣言するには、その名前が次の要件を満たす必要があります。

大文字または小文字にかかわらずアルファベット文字 (a-z) で始まる必要があります。
名前の 2 文字目以降には、文字、数字、およびアンダースコア (_) の任意の組み合わせを含めることができます。
名前は DataWeave の予約済みのキーワード (完全なリストは、予約済みのキーワードを参照) に一致することはできません。

有効な識別子のいくつかの例を以下に示します。

myType
abc123
a1_3BC_22
Z___4
F

次の表で、無効な識別子の例と、無効になる理由を説明します。

Identifier (識別子) 問題

Identifier (識別子)	問題
`123456`	数字で始まることはできません。
`value$`	特殊文字を含めることはできません。
`_number`	アンダースコアで始まることはできません。
`type`	予約済みのキーワードは使用できません。

123456

数字で始まることはできません。

value$

特殊文字を含めることはできません。

_number

アンダースコアで始まることはできません。

type

予約済みのキーワードは使用できません。

予約済みのキーワード

有効な識別子は、予約済みの DataWeave キーワードに一致することはできません。

and
論理演算子として予約済み
as
型強制用に予約済み
async
予約済み
case
case ステートメント用に予約済み。たとえば、パターン一致を実行したり、update 演算子で使用したりします。
default
パラメーターのデフォルト値の割り当て用に予約済み
do
do ステートメント用に予約済み
else
if-else および else-if ステートメント用に予約済み

「DataWeave のフローコントロール」を参照してください。
enum
予約済み
false
ブール値として予約済み
for
予約済み
fun
DataWeave ヘッダーの関数定義用に予約済み
if
if-else および else-if ステートメント用に予約済み

「DataWeave のフローコントロール」を参照してください。
import
DataWeave ヘッダーの import ディレクティブ用に予約済み
input
予約済み
is
予約済み
ns
DataWeave ヘッダーの名前空間定義用に予約済み
null
値 null として予約済み

「Null (dw::Core 型)」を参照してください。
or
論理演算子として予約済み
output
DataWeave ヘッダーの output ディレクティブ用に予約済み
private
予約済み
throw
予約済み
true
ブール値として予約済み
type
DataWeave ヘッダーの型定義用に予約済み
unless
予約済み
using
後方互換性のために予約済み。do で置き換えられます。

「スコープ演算子とフローコントロール演算子」を参照してください。
var
DataWeave ヘッダーの変数定義用に予約済み
yield
予約済み

dwl ファイル

Transform や他のコンポーネント内で DataWeave スクリプトを指定するのに加えて、.dwl ファイル内でスクリプトを指定することもできます。Studio プロジェクトでは、スクリプトファイルは src/main/resources に保存されます。

Mule アプリケーションの XML では、${file::filename} 構文を使用して、dwl ファイル内のスクリプトを、式を期待している XML タグに送信することができます。たとえば、次の Choice ルーターの when expression="${file::someFile.dwl}" を参照してください。

<http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/test">
  <http:response >
    <http:body ><![CDATA[#[${file::transform.dwl}]]]></http:body>
  </http:response>
</http:listener>
<choice doc:name="Choice"  >
  <when expression="${file::someFile.dwl}" >
    <set-payload value="It's greater than 4!" doc:name="Set Payload"  />
  </when>
  <otherwise >
    <set-payload value="It's less than 4!" doc:name="Set Payload" />
  </otherwise>
</choice>

ガートナーが MuleSoft をリーダーとして評価

Salesforce のフルパワーを解放する API 活用術

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan

ガートナーが MuleSoft をリーダーとして評価

Salesforce のフルパワーを解放する API 活用術

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan

DataWeave スクリプト

DataWeave スクリプトの構造

DataWeave ヘッダー

インライン DataWeave スクリプトにヘッダーを含める

DataWeave 本文

エラー (スクリプティングエラーと書式設定エラー)

DataWeave コメント

特殊文字のエスケープ

有効な識別子を宣言するためのルール

予約済みのキーワード

dwl ファイル

関連情報