Anypoint Code Builder での DataWeave 式と変換の使用

DataWeave は、データ変換と式の定義のための MuleSoft プログラミング言語です。DataWeave を使用して、コネクタ操作やその他のコンポーネントで、payload、attributes、vars などの Mule イベントデータを処理します。式項目、式ビルダー、または変換ビルダーを使用するか、設定 XML を編集して、Mule アプリケーションで DataWeave 式と変換を開発します。入力および出力サンプルデータまたはメタデータを提供することで、AI を使用して DataWeave 変換を生成します。

1) 式項目の fx ボタン、2) 式ビルダーボタン、3) 変換ビルダーボタンの 3 つの番号付きコールアウトが表示されている設定パネル

1	式項目: コンポーネント設定パネルに DataWeave 式またはスクリプトを入力します。
2	式ビルダー: Mule アプリケーション内で式を作成および管理します。
3	変換ビルダー: AI 支援の視覚的インターフェースで、Mule アプリケーションの DataWeave 変換を作成します。

Anypoint Code Builder での実装とインテグレーションにより、Mule Runtime Engine のインスタンスで実行される Mule アプリケーションが作成されます。

Anypoint Code Builder は、DataWeave 式と変換を Mule アプリケーション開発プロセスに統合し、次の機能をサポートします。

階層マッピング
オブジェクト間および配列間の変換
文字列、数値、ブールの連結
データ型の変換

Anypoint Code Builder では、次の変換マッピングユースケースがサポートされています。

Object から Object
Primitive から Primitive
Object から Primitive
Primitive から Object
Object から Array
Array から Object
Object から Object のデータ型の変換
シンプルな項目の連結
Array から Array (同レベル)

始める前に

DataWeave 式の関数、演算子、変数、セレクターを理解します。

詳細は、DataWeave Referenceを参照してください。
IDE が提供する関数の組み込みドキュメントを確認します。例については、DataWeave 関数のリストの表示およびドキュメントの取得を参照してください。
- 定義済みの Mule イベント変数 (payload、attributes、vars など)。
- DataWeave セレクター。Mule イベント内のペイロード内の項目、属性、または変数の値を取得します。
  
  その他のリソースについては、DataWeave Overviewを参照してください。
Anypoint Code Builder AI 機能を使用するには、次の権限があることを確認します。
- Anypoint Code Builder Developer (Anypoint Code Builder 開発者)
- Mule Developer Generative AI User (Mule 開発者生成 AI ユーザー)
[Access Management (アクセス管理)] で Einstein を有効にします。詳細は、「Enabling Einstein for Anypoint Platform (Anypoint Platform での Einstein の有効化)」を参照してください。
AI 支援変換で問題がある場合は、AI 支援変換のトラブルシューティングを参照してください。

式項目を開く

ほとんどのコネクタ操作およびコンポーネントで、DataWeave 式とスクリプトを受け入れる 1 つ以上の項目が提供されます。コンポーネントの設定パネルの [fx] ボタンは、項目が式を受け入れることを示します。XML では、これらの項目には #[] マークアップが含まれます。式項目は、DataWeave 関数と Mule イベントデータ (payload、attributes、vars など) を含め DataWeave 式を受け入れます。

コンポーネントの式項目 (fx) を開く手順は、次のとおりです。

実装またはインテグレーションプロジェクトのキャンバスから、式を受け入れるコンポーネントを開きます。
[fx] をクリックして、項目を文字列項目から式項目に変更します。

XML では fx 項目にマークアップ #[] も表示されるため、式の項目であることが示されます。
```
<set-variable variableName="variableName" value="#[]"
              doc:name="Set variable" doc:id="ndpiap" />
```
コンポーネントを設定するには、式ビルダーをクリックします。

[Data (データ)]、[Functions (関数)]、[Preview (プレビュー)] タブを使用すると、コンポーネントの式を容易に設定できます。外部ソースのデータで Mule アプリケーションを実行せずに、式の出力をプレビューします。

式ビルダーを開く

式ビルダーを使用すると、Mule アプリケーション内で式を作成および管理するプロセスが簡略化されます。ビルダーでは、DataWeave 式と変換を作成するための視覚的インターフェースが提供されます。

データ構造の確認

ペイロード、属性、Mule 変数を含め Mule イベントのデータ構造を確認するには、[Data (データ)] タブを使用します。サンプルデータが含まれるこのタブは、コンポーネントの fx 項目の式ビルダーに含まれます。次に例を示します。

[Data (データ)] タブ (自動生成データを含む)	[Data (データ)] タブ (拡張済み)
タブ"]	タブとモック属性"]

自動生成された文字列はモック値として表示され、[Preview (プレビュー)] タブなどにプレビューの出力を生成するために使用されます。例の属性メタデータキーはフローの HTTP Listener コンポーネントの設定から取得されます。

[Input/Output (入力/出力)] タブには、データ入力 (Input (入力)) コンポーネントとデータ出力 (Output (出力)) コンポーネントの構造が表示されます。次に例を示します。

"コンポーネントの [Input/Output (入出力) タブ"]

DataWeave 関数のリストの表示およびドキュメントの取得

コンポーネントの [Functions (関数)] タブ、fx 項目、または XML エディターのオートコンプリートメニューから使用可能な関数のリストを取得する手順は、次のとおりです。

fx 式項目を持つコンポーネントを開きます。

案内については、式項目を開くを参照してください。

使用可能な関数のリストを表示します。

空の fx 項目からコアモジュールの DataWeave 関数のリストを表示するには、空の fx 項目内で Ctrl+Space を押します。次に例を示します。

String モジュール、Array モジュール、Core モジュールなど、すべての DataWeave モジュールから関数を表示する手順は、次のとおりです。

fx 項目をクリックして、式ビルダーを開きます。

[Functions (関数)] タブをクリックします。

DataWeave 関数	関数リファレンス
関数にマウスポインターを置くと、短い説明が表示されます。タブに、検索機能を備えた Array、Core、Object、String モジュールを含む分類済み DataWeave 関数が表示されています"]	[Details (詳細)] をクリックすると、完全なドキュメントが表示されます。

DataWeave 関数

関数リファレンス

関数にマウスポインターを置くと、短い説明が表示されます。

"式ビルダーの [Functions (関数) タブに、検索機能を備えた Array、Core、Object、String モジュールを含む分類済み DataWeave 関数が表示されています"]

[Details (詳細)] をクリックすると、完全なドキュメントが表示されます。

関数の詳細ポップアップに、構文、パラメーター、使用例など、DataWeave 関数の完全なドキュメントが表示されています

DataWeave 式の出力のプレビュー

キャンバスまたは XML エディターで DataWeave 式の出力をプレビューします。プレビュー機能の動作は、fx (式) 項目のペイロード (payload) や Mule 変数 (vars.somevar など) の設定 XML から提供されたサンプルデータに基づきます。

独自のサンプルデータを提供するには、DataWeave 式のサンプルデータを提供するを参照してください。

UI での結果のプレビュー
XML エディターからの結果のプレビュー

UI での結果のプレビュー

自動生成されたサンプルデータをプレビューするか、独自のサンプルデータをプレビューします。出力は、コンポーネントの式項目の式ビルダーの [Preview (プレビュー)] タブでプレビューします。

自動生成されたサンプルデータのプレビュー	サンプルデータのプレビュー
自動生成されたサンプルデータからの出力結果タブ"]	ユーザーが作成したサンプルデータを使用した式からの出力結果タブ"]

自動生成されたサンプルデータのプレビュー

サンプルデータのプレビュー

自動生成されたサンプルデータからの出力結果

"自動生成されたサンプルデータを使用した DataWeave 式の出力が表示されている式ビルダーの [Preview (プレビュー) タブ"]

ユーザーが作成したサンプルデータを使用した式からの出力結果

"ユーザーが提供したサンプルデータを使用した DataWeave 式の評価結果が表示されている式ビルダーの [Preview (プレビュー) タブ"]

DataWeave セレクターと関数をサンプルデータに適用することができます。想定される構造とデータ型を持つサンプルデータを作成するには、DataWeave 式のサンプルデータを提供するを参照してください。

XML エディターからの結果のプレビュー

設定 XML から結果をプレビューするには、DataWeave コードにマウスポインターを置いて [Show Code Actions (コードアクションを表示)] アイコンをクリックし、[Run Preview (プレビューを実行)] をクリックします。

XML エディターの [Code Actions (コードアクション)] メニューで、DataWeave 式を実行するための [Run Preview (プレビューを実行)] オプションが強調表示されています

Anypoint Code Builder では、関数の結果を含む新しい [Preview Output (出力をプレビュー)] タブが開きます。

JSON 形式の出力で DataWeave 関数の実行結果が表示されている [Preview Output (出力をプレビュー)] タブ

変換ビルダーを開く

Einstein 生成 AI 支援の変換ビルダーを使用して、Mule アプリケーションで DataWeave 変換を作成します。DataWeave スクリプトを生成するために、入力および出力のサンプルメタデータまたはデータを提供します。

変換ビルダーで、ニーズに最適なオプションを選択します。

Map with AI (AI を使用したマップ)
Map and Transform with AI (AI を使用したマップと変換)

AI 支援変換に関する考慮事項

AI 支援変換を使用する場合は、次の考慮事項を評価します。

メタデータは、出力の形状を提供します。
サンプルデータは、計算、条件、その他の操作のための関数または式を生成するためのコンテキストを提供します。サンプルデータを含む Web Services Description Language (WSDL) ファイルを提供できます。サンプルデータでサポートされているデータ形式 (MIME タイプ) については、DataWeave 式のサンプルデータを提供するを参照してください。
AI では、変換スクリプトを作成するために有効なデータが必要です。必要に応じて、手動で記述します。
AI チャット履歴は、変換ビルダーでは使用できません。
サンプルデータや AI 入力では、実際の個人識別情報 (PII) を使用しないでください。架空のデータまたはマスクされたデータのみを含む入力および出力のサンプルデータを提供します。

AI を使用したマップ

変換ビルダーにアクセスするときに、項目間の自動マッピングを取得します。

[Map with AI (AI を使用したマップ)] にアクセスできない場合、次の作業を行う必要があります。

設定が AI 支援変換を使用するための前提条件を満たしていることを確認する。始める前にを参照してください。
提供された入力メタデータと出力メタデータが有効であることを確認する。
1. Mule プロジェクトを開きます。
2. fx 項目を持つコンポーネントを開きます。
3. 変換ビルダーを開きます。
  
  提供されたサンプルデータを考慮して、マッピングが自動的に開始されます。
  
  マッピングは XML ファイルに適用されます。
  
  [Preview (プレビュー)] タブに変換の出力が表示されます。
4. マッピングが完了したら、次の作業を行う必要があります。
  1. [Apply Mapping (マッピングを適用)] をクリックして、提案されたマッピングをプロジェクトに適用します。
  2. AI から新しい提案を取得するには、[Revise Mapping (マッピングを修正)] をクリックします。

Map and Transform with AI (AI を使用したマップと変換)

AI 支援 DataWeave 変換スクリプトを作成します。入力および出力サンプルデータ、入力および出力メタデータ、および AI をガイドするための省略可能な指示を提供します。

Mule プロジェクトを開きます。
fx 項目を持つコンポーネントを開きます。
変換ビルダーを開きます。

提供されたデータを考慮して、マッピングが自動的に開始されます。マッピングは XML ファイルに適用されます。
[Map and Transform with AI (AI を使用したマップと変換)] をクリックします。

必要に応じて、次の情報を提供するか変更します。

[Input sample (入力サンプル)] データ
[Output sample (出力サンプル)] データ

AI をガイドする省略可能な指示

入力および出力サンプルデータを変更する場合は、AI が意図した変換を理解できるように同じ情報を提供します。入力データは、ペイロード、属性、または変数から取得できます。

[Transform (変換)] をクリックします。

Einstein AI は、入力および出力サンプル、指示 (ある場合) を分析して、推奨変換を実行することを目的とした DataWeave スクリプトの提案を生成します。
該当する場合は [View Suggested Scripts (推奨スクリプトを表示)] をクリックしてスクリプトを挿入するか、推奨スクリプトをその形式のままでクリップボードにコピーします。

スクリプトを挿入すると、XML ファイルが更新され、[Revise (修正)] をクリックしてスクリプトを再生成できます。

AI 支援変換のトラブルシューティング

AI 支援変換で問題が発生した場合は、次の手順に従います。

Anypoint Platform にログインして再試行します。
Anypoint Platform 管理者に問い合わせて、組織で生成 AI が有効になっていることを確認します。
Anypoint Platform にログインしており、組織が Einstein 生成 AI にアクセスできる場合は、Einstein 生成 AI の使用条件に同意します。

データソースと対象を手動で追加する

変換スクリプトにデータソースと対象を手動で追加できます。

[Transformation Workspace (変換ワークスペース)] セクションで、ソース項目を入力ペイロードから対象項目にドラッグして、ソースデータを対象データにマップします。

マップされた項目には緑色のドットが表示され、マッピングが成功したことを示すために強調表示されます。[Script (スクリプト)] セクションが新しいマッピングで更新され、[Output Preview (出力プレビュー)] セクションに変換の出力が表示されます。

必要に応じて、複数のソース項目を対象項目にマップし、変換ビルダーでそれらを連結します。
メタデータを更新したりすべてのマッピングを削除したりするには、[More Actions (その他のアクション)] をクリックします。
項目マッピングから生成された入力サンプルを確認します。

生成されたサンプルを選択するか、独自のサンプルデータを提供できます。

DataWeave 式のサンプルデータを提供する

Anypoint Code Builder で DataWeave 式をローカルでテストおよびプレビューします。アプリケーションを実行せずに出力をプレビューするには、fx の項目で payload などの Mule 変数のサンプルデータを追加します。AI 支援変換の場合、サンプル入力および出力データを提供すると、AI が意図した変換を理解し、正しい DataWeave スクリプトを生成するのに役立ちます。

サンプルデータは次の形式で作成することができます。

JSON
XML
CSV
Java
Text (テキスト)
YAML
Avro
Excel
NDJSON
URL エンコード
Protobuf
Multipart

実際のデータでアプリケーションを実行したときにエラーが発生しないようにするには、式で期待されるデータの基本構造、形式、およびデータ型に一致するサンプルデータを提供します。
キャンバスからコンポーネントを再度開くと、サンプルデータは上書きされます。

Mule 変数のサンプルデータを作成する手順は、次のとおりです。

プロジェクトを開きます。
XML エディターで Mule イベント変数 (payload など) にマウスポインターを置きます。次に例を示します。
[Quick Fix (クイック修正)] をクリックして [Quick Fix (クイック修正)] メニューを開きます。
[Create sample data for payload (ペイロードのサンプルデータを作成)] など、[Create sample data for your-value (your-value のサンプルデータを作成)] を選択します。次に例を示します。
開いたメニューで、サンプルデータの形式 (JSON など) を選択します。

IDE にサンプルデータのタブが開きます。
選択した形式のコンテンツをサンプルデータファイルに追加します。たとえば、JSON の場合は次のようになります。

ファイル名は payload.json です。独自のサンプルデータと自動作成されたサンプルデータのファイルはプロジェクトディレクトリ src/test/resources に保存されます。

サンプルデータを追加する前に「重要」を参照してください。

XML エディター内の値にマウスポインターを置くと、サンプルデータの構造、データキー、データ型が表示されます。次に例を示します。
式ビルダーでサンプルデータをプレビューします。
1. キャンバスから、サンプルデータが含まれるコンポーネントをクリックして、その項目の式ビルダーを開きます。
2. サンプルデータが含まれるコンポーネントの fx をクリックして、その項目の式ビルダーを開きます。
3. [Preview (プレビュー)] をクリックして、サンプルデータを表示します。次に例を示します。
  
  値は変更できます。たとえば、DataWeave セレクターまたは関数を追加します。
  
  この例では id 値の配列が返されるようになりました。

DataWeave エラーへの対処

DataWeave コードに構文エラーやセマンティックエラーが含まれている場合、Anypoint Code Builder ではエラーが強調表示され、推奨の修正方法が提供されます。次のような問題があります。

DataWeave モジュールで欠落している Import ディレクティブを追加する
未定義関数エラーを修正する

DataWeave モジュールで欠落している Import ディレクティブを追加する

多くの DataWeave モジュールでは、式に明示的な import ディレクティブが必要です。このディレクティブを必要としないモジュールはコアモジュールのみです。

たとえば、この関数が属している String モジュールをインポートしていない場合、関数 camelize( "hello world") では、「Unable to resolve the reference of 'camelize' (「camelize」の参照を解決できません)」というエラーが発生します。

<set-payload value='#[ camelize( "hello world")]' doc:name="Set payload" doc:id="vyvcds" />

式ビルダーではエラーが識別されます。次に例を示します。

この問題を修正するには、クリックして import ディレクティブを自動で追加します。次に例を示します。

この修正の XML は次の例のようになります。

<set-payload value='#[%dw 2.0
import camelize from dw::core::Strings
---
 camelize( "hello world")]' doc:name="Set payload" doc:id="vyvcds" />

未定義関数エラーを修正する

Anypoint Code Builder では未定義の関数が自動的にフラグ付けされます。

たとえば、次のコードでは、DataWeave により toUpper がエラーとしてフラグ付けされています。

カーソルを関数の上に置くと、DataWeave によりエラーに関する情報が提供されます。

この問題を修正する手順は、次のとおりです。

エラーをクリックしてポップアップを表示します。
[Quick Fix (クイック修正)]、[Create Function (関数を作成)] の順にクリックします。

Anypoint Code Builder では ??? プレースホルダー付きの関数定義が自動的に追加されます。このプレースホルダーにユーザーは関数を定義できます。
```
fun toUpper(param0: String) = ???
```

upper 関数を使用して、指定された文字列を大文字で返すように関数を更新します。

<set-payload value="#[%dw 2.0
fun toUpper(param0: String) = upper(param0)
output application/json
---
toUpper('hello')]" doc:name="Set payload" doc:id="xiyfpa" />

DataWeave ライブラリをインポートする

Anypoint Code Builder を使用して、Exchange から Mule アプリケーションに DataWeave ライブラリをインポートします。

DataWeave ライブラリは、DataWeave モジュール、マッピングファイル、およびリソースファイル (JSON、XML、CSV ファイルなど) の再利用可能なパッケージです。

DataWeave ライブラリをインポートする方法は、Exchange から他のアセットをインポートする方法と同じです。

Anypoint Code Builder でインテグレーションプロジェクトを開きます。
コマンドパレットを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
「import」と入力し、次のコマンドを選択します。
```
MuleSoft: Import Asset from Exchange
```
[DataWeave Library (DataWeave ライブラリ)] を選択します。

ライブラリを検索するには、検索語を入力して Enter キーを押します。たとえば、「DataWeave」と入力します。
[Assets From Exchange (Exchange のアセット)] メニューから DataWeave ライブラリを選択します。
DataWeave ライブラリのバージョンを選択します。

ステータスバーに進行状況が表示されます。

完了したら、連動関係がプロジェクトに正常に追加されたことを示すメッセージが Anypoint Code Builder に表示されます。