Visual Studio Code を使って Azure Logic Apps でデータを変換するマップを作成する
適用対象: Azure Logic Apps (Standard)
Azure Logic Apps ワークフローで異なる XML または JSON 形式のメッセージを交換するには、特にソースおよびターゲットのスキーマ構造の間にギャップがある場合に、データをある形式から別の形式に変換する必要があります。 データ変換は、これらのギャップを埋めるのに役立ちます。 このタスクでは、ソースおよびターゲット スキーマのデータ要素間の変換を定義するマップを作成する必要があります。
マップを視覚的に作成および編集するには、Standard ロジック アプリ プロジェクトのコンテキスト内で Azure Logic Apps (Standard) 拡張機能と共に Visual Studio Code を使用できます。 Data Mapper ツールでは、ドラッグ アンド ドロップ ジェスチャを使用した XSLT マッピングと変換の統合エクスペリエンス、式を作成するための事前構築済みの関数ライブラリ、ワークフローで作成して使用するマップを手動でテストする方法が提供されます。
マップを作成したら、ロジック アプリ プロジェクトのワークフローまたは Azure portal 内のワークフローから、そのマップを直接呼び出すことができます。 このタスクでは、Data Mapper XSLT を使用した変換という名前の Data Mapper 操作アクションをワークフローで使用することができます。
この攻略ガイドでは、空のデータ マップの作成、ソースおよびターゲット スキーマの選択、マッピングを開始するスキーマ要素の選択、さまざまなマッピングの作成、マップの保存とテストを行い、ロジック アプリ プロジェクトのワークフローからマップを呼び出す方法を示します。
制限事項と既知の問題
Data Mapper は、現在、Windows オペレーティング システムで実行されている Visual Studio Code でのみ機能します。
Data Mapper は現在、Azure portal ではなく Visual Studio Code 内でのみ使用でき、従量課金ロジック アプリ プロジェクトではなく Standard ロジック アプリ プロジェクト内からのみ使用できます。
Data Mapper は、現在、コンマ区切り値 (.csv) ファイルをサポートしていません。
Data Mapper の [コード ビュー] ウィンドウは現在、読み取り専用です。
マップ レイアウトと項目の位置は現在、自動で読み取り専用です。
Data Mapper ツールで作成されたマップを呼び出すには、Data Mapper XSLT を使用した変換という名前の Data Mapper 操作アクションのみを使用できます。 他のツールによって作成されたマップの場合は、XML 変換という名前の XML 操作アクションを使用します。
Data Mapper ツールを使って作成したマップを Azure portal で使うには、Standard ロジック アプリのリソースにそれを直接追加する必要があります。
前提条件
Standard ロジック アプリ ワークフローを作成する Visual Studio Code と Azure Logic Apps (Standard) 拡張機能。
Note
以前は個別に存在していた Data Mapper 拡張機能は、Azure Logic Apps (Standard) 拡張機能と統合されました。 競合を回避するため、Azure Logic Apps (Standard) 拡張機能をインストールまたは更新すると、Data Mapper 拡張機能の既存のバージョンはすべて削除されます。 拡張機能のインストールまたは更新後、Visual Studio Code を再起動してください。
変換するデータ型を記述するソースとターゲットのスキーマ ファイル。 これらのファイルには、次のいずれかの形式を使用できます。
- .xsd ファイル拡張子を持つ XML スキーマ定義ファイル
- .json ファイル拡張子を持つ JavaScript Object Notation ファイル
少なくともトリガーを持つステートフルまたはステートレス ワークフローを含む Standard ロジック アプリ プロジェクト。 プロジェクトがない場合は、Visual Studio Code で次の手順に従います。
Azure アカウントに接続します (またしていない場合)。
ローカル フォルダー、ローカル Standard ロジック アプリ プロジェクト、ステートフルまたはステートレス ワークフローを作成します。 ワークフローの作成時に、[現在のウィンドウで開く] を選択します。
マップをテストし、変換が期待どおりに動作することを確認する場合は、サンプルの入力データ。
Run XSLT 関数を使うには、XSLT スニペットが、ファイル名拡張子 .xml または .xslt のいずれかのファイルに存在する必要があります。 XSLT スニペットは、ローカル プロジェクト フォルダー構造の InlineXslt フォルダー (Artifacts>DataMapper>Extensions>InlineXslt) に配置する必要があります。 このフォルダー構造が存在しない場合は、不足しているフォルダーを作成します。
データ マップを作成する
Visual Studio Code の左側のメニューで、Azure アイコンを選択します。
[Azure] ウィンドウの [Data Mapper] セクションで、[新しいデータ マップの作成] を選択します。
データ マップの名前を指定します。
次の手順に従って、ソースおよびターゲット スキーマを指定します。
マップ画面で、[ソース スキーマの追加] を選択します。
開いた [構成] ウィンドウで、[新規追加]>[参照] を選択します。
ソース スキーマ ファイルを見つけて選択し、[追加] を選択します。
ソース スキーマが [開く] ウィンドウに表示されない場合は、ファイルの種類の一覧から [XSD ファイル (*.xsd)] を [すべてのファイル (*.*)] に変更します。
マップ画面に、ソース スキーマのデータ型が表示されるようになりました。 このガイドの例では、
マップ画面で、[ターゲット スキーマの追加] を選択します。
開いた [構成] ウィンドウで、[新規追加]>[参照] を選択します。
ターゲット スキーマ ファイルを見つけて選択し、[追加] を選択します。
ターゲット スキーマが [開く] ウィンドウに表示されない場合は、ファイルの種類の一覧から [XSD ファイル (*.xsd)] を [すべてのファイル (*.*)] に変更します。
マップ画面に、ターゲット スキーマのデータ型が表示されるようになりました。
または、ソースおよびターゲットのスキーマ ファイルをローカルで Artifacts/Schemas フォルダー内のロジック アプリ プロジェクトに追加して、Visual Studio Code に表示されるようにすることもできます。 この場合は、[構成] ウィンドウの Data Mapper ツールでソースおよびターゲット スキーマを指定できます。そのためには、[新規追加] ではなく [既存のものを選択] を選択します。
完了すると、マップは次の例のようになります。
次の表では、スキーマに表示される可能性のあるデータ型について説明します。
| Symbol | 型 | 詳細情報 |
|---|---|---|
 |
Array | 項目または繰り返し項目ノードを含む |
 |
バイナリ | |
 |
Bool | True または False のみ |
 |
Complex | オブジェクト JSON 型に似た子プロパティを持つ XML オブジェクト |
 |
DateTime | |
 |
Decimal (10 進数型) | |
 |
整数型 | 整数のみ |
 |
Null | データ型ではないが、エラーまたは無効な型が存在する場合に表示される |
 |
数値 | JSON 整数または 10 進数 |
 |
オブジェクト | 複合 XML 型に似た子プロパティを持つ JSON オブジェクト |
 |
String |
マップ内を移動する
マップ内を移動するには、次のオプションがあります。
パンするには、マップ画面の周囲にポインターをドラッグします。 または、マウスまたはトラックボールを移動しながら、マウス ホイールを長押しします。
マップで 1 レベル下に移動すると、マップの左下隅にナビゲーション バーが表示され、次のオプションから選択できます。
オプション 代替ジェスチャ 縮小します マップ画面で、Shift キーを押しながらダブルクリックします。
または
マウス ホイールで下にスクロールします。拡大します マップ画面で、ダブルクリックします。
または
マウス ホイールで上にスクロールします。ウィンドウのサイズに合わせて拡大 なし ミニマップの表示 (非表示) なし マップで 1 レベル上に移動するには、マップの上部にある階層リンク パスで、前のレベルを選択します。
マップするターゲットおよびソース要素を選択する
マップ画面の右側から始めて、ターゲット スキーマ領域で、マップするターゲット要素を選択します。 必要な要素が親要素の子である場合は、最初に親を検索して展開します。
次に、左側のソース スキーマ領域から [要素の選択] を選択します。
表示される [ソース スキーマ] ウィンドウで、マップに表示する 1 つ以上のソース要素を選択します。
親と直接の子を含めるには、親のショートカット メニューを開き、[子の追加] を選択します。
親とその親のすべての子 (サブ親を含む) を含めるには、最上位の親のショートカット メニューを開き、[子の追加 (再帰)] を選択します。
完了したら、[ソース スキーマ] ウィンドウを閉じることができます。 ソース要素は後でいつでも追加できます。 マップの左上隅で、[ソース スキーマの表示] (
) を選択します。
要素間の直接マッピングを作成する
ソースおよびターゲット スキーマで同じ型の要素間で簡単に変換するには、次の手順に従います。
マッピングを作成するときのコードの動作を確認するには、マップの右上隅にある [コードの表示] を選択します。
まだマップするターゲット要素とその後にソース要素を選択していない場合は、マップ上でこれを行います。
円とプラス記号 (+) の両方が表示されるように、ソース要素の上にポインターを移動します。
ターゲット要素に線をドラッグして、表示される円に線が接続されるようにします。
これで、両方の要素間に直接マッピングが作成されました。
[コード ビュー] ウィンドウには、作成したマッピング リレーションシップが反映されます。
Note
データ型が一致しない要素間のマッピングを作成すると、ターゲット要素に次のような警告が表示されます。
要素間の複雑なマッピングを作成する
結合する要素や異なるデータ型を持つ要素など、ソースおよびターゲット スキーマ内の要素間のより複雑な変換を行うには、1 つ以上の関数を使用してその変換のタスクを実行できます。
次の表に、使用可能な関数グループと、使用できる関数の "例" を示します。
| グループ | 関数の例 |
|---|---|
| コレクション | Average、Count、Direct Access、Distinct 値、Filter、Index、Join、Maximum、Minimum、Reverse、Sort、Subsequence、Sum |
| 変換 | To date、To integer、To number、To string |
| 日付と時刻 | 日の加算 |
| 論理比較 | 等しい、Exists、より大きい、以上、If、If else、Is nil、Is null、Is number、Is string、より小さい、以下、論理 AND、論理 NOT、論理 OR、等しくない |
| 数値演算 | 絶対、Add、アークタンジェント、Ceiling、コサイン、除算、指数、指数 (底 10)、Floor、整数除算、対数、対数 (底 10)、モジュール、乗算、累乗、四捨五入、サイン、平方根、減算、正接 |
| String | Code points to string、Concat、Contains、Ends with、Length、Lowercase、Name、正規表現一致、正規表現置換、置換、Starts with、String to code-points、Substring、Substring after、Substring before、Trim、Trim left、Trim right、Uppercase |
| ユーティリティ | Copy、Error、Execute XPath、Format 日時、Format 数値、Run XSLT |
マップ上では、関数のラベルは次の例のようになり、関数グループに基づいて色分けされています。 関数名の左側に、関数の記号が表示されます。 関数名の右側には、関数の出力のデータ型の記号が表示されます。
マッピング リレーションシップのない関数を追加する
このセクションの例では、ソース要素の型を String 型から DateTime 型に変換します。これはターゲット要素の型と一致します。 この例では、1 つの入力を受け取る To date 関数を使用します。
マッピングを作成するときのコードの動作を確認するには、マップの右上隅にある [コードの表示] を選択します。
まだマップするターゲット要素とその後にソース要素を選択していない場合は、マップ上でこれを行います。
マップの左上隅で、[関数の表示] (
) を選択します。
開いた関数の一覧から、使用する関数を見つけて選択し、マップに関数を追加します。 関数がマップに表示されない場合は、マップ画面で縮小してみてください。
この例では、To date 関数を選択します。 また、同じ方法でカスタム関数を検索して選ぶこともできます。 詳細については、「カスタム関数を作成する」を参照してください。
Note
マップに関数を追加するときにマッピング行が存在しないか選択されていない場合、関数はマップ上に表示されますが、要素やその他の関数からは切断されています。次に例を示します。
関数の詳細と接続ポイントを表示するには、関数シェイプを展開します。 関数シェイプを展開するには、シェイプ内を選択します。
関数をソースおよびターゲット要素に接続します。
ソース要素と関数の左端の間に線をドラッグして描画します。 ソース要素からでも関数からでも開始できます。
関数の右端とターゲット要素の間に線をドラッグして描画します。 ターゲット要素からでも関数からでも開始できます。
関数の [プロパティ] タブで、使用する入力を確認または編集します。
配列などの一部のデータ型では、変換のスコープも使用できる場合があります。 このスコープは通常、配列などの直接の要素ですが、一部のシナリオでは、スコープが直接の要素を超えて存在する可能性があります。
[コード ビュー] ウィンドウには、作成したマッピング リレーションシップが反映されます。
たとえば、配列項目を反復処理するには、「配列間にループを作成する」を参照してください。 要素の値が条件を満たすときにタスクを実行するには、要素間に条件を追加するに関する記事を参照してください。
既存のマッピング リレーションシップに関数を追加する
ソースおよびターゲット要素の間にマッピング リレーションシップが既に存在する場合は、次の手順に従って関数を追加できます。
マップで、作成したマッピングの行を選択します。
選んだ行にポインターを移動し、表示される [関数の挿入] のプラス記号 (+) を選びます。次に例を示します。
開いた関数の一覧から、使用する関数を見つけて選択します。
関数はマップに表示され、ソースおよびターゲット要素の間で自動的に接続されます。
複数の入力を含む関数を追加する
このセクションの例では、複数のソース要素型を連結して、結果をターゲット要素型にマップできるようにします。 この例では、複数の入力を受け取る Concat 関数を使用します。
マッピングを作成するときのコードの動作を確認するには、マップの右上隅にある [コードの表示] を選択します。
まだマップするターゲット要素とその後にソース要素を選択していない場合は、マップ上でこれを行います。
マップの左上隅で、[関数の表示] (
) を選択します。
開いた関数の一覧から、使用する関数を見つけて選択し、マップに関数を追加します。 関数がマップに表示されない場合は、マップ画面で縮小してみてください。
この例では、Concat 関数を選択します。
Note
マップに関数を追加するときにマッピング行が存在しないか選択されていない場合、関数はマップ上に表示されますが、要素やその他の関数からは切断されています。 関数に構成が必要な場合は、関数の右上隅に赤い点が表示されます。次に例を示します。
関数の詳細と接続ポイントを表示するには、関数シェイプを展開します。 関数シェイプを展開するには、シェイプ内を選択します。
関数情報ウィンドウの [プロパティ] タブの [入力] で、入力として使用するソース データ要素を選択します。
この例では、関数入力として FirstName および LastName のソース要素を選択します。これによって、マップ上にそれぞれの接続が自動的に追加されます。
マッピングを完了するには、関数の右端とターゲット要素の間に線をドラッグして描画します。 ターゲット要素からでも関数からでも開始できます。
[コード ビュー] ウィンドウには、作成したマッピング リレーションシップが反映されます。
配列間にループを作成する
ソースおよびターゲット スキーマに配列が含まれている場合は、それらの配列内の項目を反復処理するループ マッピング リレーションシップを作成できます。 このセクションの例では、Employee ソース配列と Person ターゲット配列をループします。
マッピングを作成するときのコードの動作を確認するには、マップの右上隅にある [コードの表示] を選択します。
マップ上のターゲット スキーマ領域で、マップするターゲット配列要素とターゲット配列項目要素を選択します。
マップ上のターゲット スキーマ領域で、ターゲット配列要素と配列項目を展開します。
ソース スキーマ領域で、ソース配列要素と配列項目要素をマップに追加します。
ソースおよびターゲット要素の間に直接マッピングを作成します。
一致する配列項目のペア間にマッピング リレーションシップを最初に作成すると、マッピング リレーションシップが親配列レベルで自動的に作成されます。
[コード ビュー] ウィンドウには、作成したマッピング リレーションシップが反映されます。
他の配列要素のマッピングに進みます。
要素間で実行する条件とタスクを設定する
条件を評価し、条件が満たされたときにタスクを実行するマッピング リレーションシップを追加するには、If 関数、Greater などの比較関数、Multiply などを実行するタスクなどの複数の関数を使用できます。
このセクションの例では、次の関数を使用して、購入数量が 20 品目を超えた場合に適用する割引を計算します。
- Greater: 品目数が 20 を超えるかどうかを確認します。
- If: Greater 関数で true が返されるかどうかを確認します。
- Multiply: 品目の価格に 10% と品目数を乗算して割引を計算します。
マッピングを作成するときのコードの動作を確認するには、マップの右上隅にある [コードの表示] を選択します。
まだマップするターゲット要素とその後にソース要素を選択していない場合は、マップ上でこれを行います。
この例では、次の要素を選択します。
マップの左上隅で、[関数の表示] (
) を選択します。Greater、If、Multiply 関数をマップに追加します
関数の詳細と接続ポイントを表示するには、関数シェイプをすべて展開します。
ソース要素、関数、ターゲット要素を次のように接続します。
- ソース スキーマの ItemPrice 要素からターゲット スキーマの ItemPrice 要素
- ソース スキーマの ItemQuantity 要素から Greater 関数の Value フィールド
- Greater 関数の出力から If 関数の Condition フィールド
- ソース スキーマの ItemPrice 要素から Multiply 関数の Multiplicand 0* フィールド
- Multiply 関数の出力から If 関数の Value フィールド
- If 関数の出力からターゲット スキーマの ItemDiscount 要素
Note
If 関数では、関数名の右側に "ANY" という単語が表示され、出力値を何にでも割り当てることができることを示します。
次の関数の [プロパティ] タブで、次の値を指定します。
機能 入力パラメーターと値 より大きい - 値 #1: ItemQuantity という名前のソース要素
- 値 #2: 20Multiply - Multiplicand #1: ItemPrice という名前のソース要素
- Multiplicand #2: .10If - 条件: is-greater-than(ItemQuantity,20)
- 値: multiply(ItemPrice, .10)完成した例を次のマップに示します。
[コード ビュー] ウィンドウには、作成したマッピング リレーションシップが反映されます。
マップを保存する
完了したら、マップ ツール バーで [保存] を選択します。
Visual Studio Code では、マップは次の成果物として保存されます。
- Artifacts>MapDefinitions プロジェクト フォルダー内の <your-map-name>.yml ファイル
- Artifacts>Maps プロジェクト フォルダー内の <your-map-name>.xslt ファイル
任意のタイミングで XSLT ファイルを生成する
<your-map-name>.xslt ファイルを任意のタイミングで生成するには、マップ ツール バーで [XSLT の生成] を選びます。
マップをテストする
変換が期待どおりに動作することを確認するには、サンプル入力データが必要です。
マップをテストする前に、必ず最新の <your-map-name>.xslt ファイルを生成します。
マップ ツール バーで、[テスト] を選択します。
[マップのテスト] ペインの [入力] ウィンドウで、サンプル入力データを貼り付け、[テスト] を選択します。
テスト ウィンドウが [出力] タブに切り替わると、テストの状態コードと応答本文が表示されます。
プロジェクト内のワークフローからマップを呼び出す
Visual Studio Code の左側のメニューで、[エクスプローラー] (ファイル アイコン) を選択して、ロジック アプリのプロジェクト構造を表示します。
ワークフロー名を持つフォルダーを展開します。 workflow.json ファイルのショートカット メニューから、[デザイナーを開く] を選択します。
ワークフロー デザイナーで、この一般的な手順に従って、Data Mapper XSLT を使用した変換という名前の Data Mapper 操作組み込みアクションを追加します。
デザイナーで、[Data Mapper XSLT を使用した変換] アクションを選びます。
表示されるアクション情報ペインで、[コンテンツ] の値を指定し、[ソースのマップ] を [ロジック アプリ] に設定したままにします。 [マップ名] 一覧から、使用するマップ ファイル (.xslt) を選択します。
Azure portal で同じ [Data Mapper XSLT を使用した変換] アクションを使うには、マップを Standard ロジック アプリ リソースに追加する必要があります。
カスタム関数を作成する
Data Mapper ツールで使用できる独自の関数を作成するには、次の手順に従います。
関数の目的を説明するわかりやすい名前を持つ XML (.xml) ファイルを作成します。
関連する関数が複数ある場合は、1 つのファイルをこれらの関数に使用できます。 任意のファイル名を使用できますが、意味のあるファイル名またはカテゴリを使うことで、関数の識別、検索、検出が容易になります。
XML ファイルでは、関数定義に次のスキーマを使う必要があります。
<?xml version="1.0" encoding="utf-8"?> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="customfunctions"> <xs:complexType> <xs:sequence> <xs:element maxOccurs="unbounded" name="function"> <xs:complexType> <xs:sequence> <xs:element maxOccurs="unbounded" name="param"> <xs:complexType> <xs:attribute name="name" type="xs:string" use="required" /> <xs:attribute name="as" type="xs:string" use="required" /> </xs:complexType> </xs:element> <xs:any minOccurs="0" /> </xs:sequence> <xs:attribute name="name" type="xs:string" use="required" /> <xs:attribute name="as" type="xs:string" use="required" /> <xs:attribute name="description" type="xs:string" use="required" /> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>"function" という名前の各 XML 要素は、さらにいくつかの属性を持つ XSLT3.0 スタイルの関数を実装します。 Data Mapper 関数の一覧には、関数名、説明、パラメーター名、パラメーターの種類が含まれます。
次の例は、SampleFunctions.xml ファイルの実装を示しています。
<?xml version="1.0" encoding="utf-8" ?> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <customfunctions> <function name="age" as="xs:float" description="Returns the current age."> <param name="inputDate" as="xs:date"/> <value-of select="round(days-from-duration(current-date() - xs:date($inputDate)) div 365.25, 1)"/> </function> <function name="custom-if-then-else" as="xs:string" description="Evaluates the condition and returns corresponding value."> <param name="condition" as="xs:boolean"/> <param name="thenResult" as="xs:anyAtomicType"/> <param name="elseResult" as="xs:anyAtomicType"/> <choose> <when test="$condition"> <value-of select="$thenResult"></value-of> </when> <otherwise> <value-of select="$elseResult"></value-of> </otherwise> </choose> </function> </customfunctions>ローカル コンピューターで、Standard ロジック アプリ プロジェクトのフォルダーを開きます。
Artifacts フォルダーを開き、次のフォルダー構造を作成します (存在しない場合): DataMapper>Extensions>Functions。
Functions フォルダーに関数の XML ファイルを保存します。
Data Mapper ツールの関数一覧でカスタム関数を見つけるには、関数を検索するか、カスタム関数コレクションを展開します。
次のステップ
- Azure Logic Apps での B2B 操作を使用したデータ変換については、「Azure Logic Apps でワークフローに変換用のマップを追加する」を参照してください