> ## Documentation Index > Fetch the complete documentation index at: https://docs.arc.cdata.com/llms.txt > Use this file to discover all available pages before exploring further. # マッピングの設定 > 注釈付きのUI 要素、ノードの種類、Foreach ループ、AI アシストマッピング、ベストプラクティスなど、CData Arc でマッピングを設定する方法。 export const companyName = "CData"; export const siteNameShort = "Arc"; 以下の完成した[XML Map](../connectors/xml-map/xml-map) マッピングページ画像には、画面上の各要素を説明するための注釈が付いています（[EDI ドキュメントマッピング](../tpmc/edi-mapping)も同様です）。各番号は以下の説明に対応しています。 1. ドキュメントまたはコネクタの名前。 2. コネクタの種類。 3. マッピングのテストステータス。値は**テスト成功**、**テスト済み（エラー）**、または**未テスト**。 4. XML ストリーミングのON / OFF 切り替え（デフォルトはON）。ON にすると、マッピングエンジンはループ完了後に、マッピング内の最上位`Foreach` の現在の反復のドキュメントオブジェクトモデル（DOM）を削除します。これにより、大規模なXML ドキュメントのパフォーマンスが大幅に向上します。マッピングエンジンがマッピングを解決できない場合、XML ストリーミングは自動的にOFF になります。 5. マッピングの通常表示とコンパクト表示の切り替え（大きなテンプレートファイルではコンパクト表示が便利です）。 6. XML 属性の表示 / 非表示の切り替え。 7. マッピングをリフレッシュ。 8. [AI アシストマッピング](#ai-アシストマッピング)ツールを起動。 9. **マッピングをテスト**ページを開く。テスト結果が3 に表示されます。（詳しくは、[マッピングのテスト](#マッピングのテスト)を参照してください。） 10. マッピングを保存。 11. 選択されたソーステンプレートファイル。 12. マッピングの方向。 13. 選択された宛先テンプレートファイル。 14. ソース側と宛先側の検索バー。 15. ソースXML の構造。 16. 親ノードの名前。 17. リーフノードの名前。 18. 宛先ドキュメントの構造。 19. 完了したマッピング。 ## ソースと宛先の理解 マッピングを定義するには、左側のペインからノードをクリックして、右側の対応するオブジェクトにドラッグします。ノードが選択されると、その接続線は青色になり、その他の線はすべて黒色になります。 ソースまたは宛先ツリーで要素をドラッグ＆ドロップすると、次の画像に示すように、ドロップノードの青い線の一方または両方が濃く / アクティブになります。両方がアクティブな場合、ドラッグされているノードはドロップノードの*兄弟*として作成されます。右の線のみがアクティブな場合、ドラッグされているノードはドロップノードの*子*として作成されます。次の画像では、N103 ノードがN104 の下からN102 ノードの直接の兄弟になるように移動されているため、青い線が両方とも強調表示されています。 マッピングを削除するには、マッピングの一端にマウスを合わせて**マッピングを削除**をクリックします。マッピングの定義が完了したら、**保存**をクリックします。 ## ノードのマッピング 親ノードとリーフノードは、XML データの階層構造を定義します。親ノードは関連する要素をグループ化し、リーフノードはマッピングされる実際のデータ値を表します。 * **親**：リーフ要素を含むが値を持たないXML マッピングツリー内のノード。親ノードは、[TPMC](../tpmc/tpmc) の[テーブルノード](../tpmc/edi-mapping#テーブルノード)に似ています。 * **リーフ**：値を含むが子要素を持たないノード。リーフノードは、TPMC の[カラムノード](../tpmc/edi-mapping#列ノード)に似ています。 次のセクションでは、親ノードとリーフノードのオプションについて詳しく説明します。 ### 親ノード #### XML 親要素 前述したように、マッピングエディタのツリーには2種類のノードがあります： * *親*ノードは、子を持ちますが値を持ちません。 * *リーフ*ノードは、値を持ちますが子を持ちません。 ソースの親ノードは、宛先の親ノードにのみドラッグできます。 ソースの親を宛先の親にドラッグすると、ソースノードと宛先ノードの間に`Foreach` 関係が確立されます。これは、ソース要素が出現するたびに、宛先要素のすべての子を含む対応する宛先要素が生成されることを意味します。 Foreach 関係が確立されると、下の画像に示すように、宛先にXPath が表示されます。入力XML 内のこのパスにある要素は、出力ノードとその子の新しいインスタンスを生成します。つまり、Foreach 関係は、マッピングエンジンにソース内の特定のXPath をループし、見つかった要素ごとにマッピングされた宛先構造を生成するように指示します。宛先ツリービュー内のXPath は、マッピングエンジンがループするXPath です。 #### 仮想ループ 仮想ループは、出力XML に直接表示されない、宛先構造に追加できる特別なノードです。出力内の他の（非仮想）ノードの外観や値に影響するロジックを実装する機会を提供します。 親ノードが出力XML に表示されない点を除いて、親ノード間のForeach マッピングと同じように機能します。これにより、ソース内の繰り返し要素を、宛先の非階層構造にフラット化できます。具体例を使って説明しましょう。 次の入力XML を考えてみます： ```xml theme={null} 212.5 9.2 5.1 ``` これは、すべての *DataReading* データを含むフラットな構造にマッピングする必要があります： ```xml theme={null} 212.5 9.2 5.1 ``` これは、ソース内の各 *DataReading* 要素に対応する宛先内のループノードとのForeach 関係を確立することで実現できます： Foreach 関係が *DataReading* と *OutputData* の間に確立された場合、 *OutputData* 要素が結果内で繰り返されます。ループノードはこの階層の繰り返しを回避し、値を単一の *OutputData* 要素にフラット化します。 上記の例に示されているループノードを追加するには、以下の手順に従います： 1. *TemperatureReading* ノードを右クリックするか省略記号をクリックし、**ノードを追加 > ループを追加**を選択します。ループにわかりやすい名前を付け、チェックマークをクリックして保存します。 2. ソースの *DataReading* ノードをループにドラッグしてForeach 関係を作成します。 3. ソースの *Temperature* ノードを宛先の *TemperatureReading* ノードにマッピングします。 #### 仮想条件 仮想条件は、共有条件に基づいて出力要素をグループ化します。条件ノードのすべての子は、条件がtrue の場合は出力に表示され、条件がfalse の場合は表示されません。 これは、個々のノードに同じ条件を個別に追加することと機能的に同じです。多くの異なるノードに影響する条件の場合、一般的には、単一の条件ノードを作成して関連するすべての出力ノードをその条件ノードの子にする方が便利です。 条件仮想ノードを作成するには、次の手順に従います： 1. 宛先ノードを右クリックするか省略記号をクリックし、**ノードを追加 > 条件を追加**を選択します。 2. 新しい条件の横にあるファンネルアイコンをクリックして、条件ルールを作成します。詳しくは、[条件エディタの使用](./mapping-condition-editor)を参照してください。 ### リーフノード #### XML リーフ要素 ソースリーフを宛先リーフにドラッグすると、宛先要素にソース要素の値を入力するようマッピングエンジンに指示します。宛先ノードにドラッグ＆ドロップすると、以下の画像に示すように、値が読み取られるXPath が宛先ツリービューに表示されます。 宛先ツリービューに表示されるXPath は、*絶対*または*相対*のいずれかです。絶対XPath はスラッシュ（/）で始まり、ドキュメントのルートから始まるソース内の完全なXPath を記述します。相対XPath はスラッシュで始まらず、親ノードに設定されたForeach ループを基準とします。 相対XPath は、複数のForeach ループに対して相対的であることができます（要素がそれぞれForeach 関係がマッピングされた複数の親を持つ限り）。任意の相対XPath の絶対XPath を見つけるには、ドキュメントの最上位から現在のノードに到達するまで、各親要素のForeach XPath を連結します。 #### XML 属性 要素値に加えてXML 属性を操作するには、マッピングページの上部にある**アトリビュートを表示**設定がON になっていることを確認します（属性）。有効にすると、エディタには、その属性が属する要素の子として検出されたすべての属性が表示されます。 すべてのXML 属性名には`@` プレフィックスが付けられます（`@` 記号はXML 要素名では有効な文字ではありません）。この文字は表示のみを目的としており、属性の読み取りまたは書き込み時には削除されます。 ##### ソースからXML 属性を読み取る **アトリビュートを表示**トグルを有効にすると、XML ソース内のすべての属性がマッピングエディタにノードとして表示されます。これらの値は、他のノードと同様に宛先にドラッグ＆ドロップできます。次の画像に示すように、ノードにはXML 要素ではなくXML 属性であることを示す`@` プレフィックスが表示されます。 ##### 宛先にXML 属性を書き込む XML 属性を含む宛先テンプレートでは、属性ノードは所属する要素の子として表示され、他の値と同様にマッピングできます。 宛先ノードに新しい属性を追加するには、ノードを右クリックするか省略記号をクリックして、**ノードを追加 > アトリビュートを追加**を選択します。 属性名は常に`@` プレフィックスで始まります（この文字は出力XML には含まれません）。 #### ヘッダー ヘッダーノードを使用すると、マッピングの出力メッセージに値をヘッダーとしてマッピングできます。これらのヘッダーノードは出力XML には含まれません。代わりに、出力メッセージのメタデータメッセージヘッダーとして追加されます。これらのヘッダーはフロー全体を通じてメッセージに保持され、必要に応じて下流のコネクタで値を参照できます。これにより、アプリケーション内のデータの流れを簡単に追跡できます。ヘッダーノードは、ノード値エディタの**メッセージヘッダー**タブに自動的に追加されます。ヘッダーノードを追加するには、既存のノードを右クリックするか、省略記号をクリックして、**追加 > ヘッダーを追加**を選択します。 ヘッダーノードは[追跡されたヘッダー](../getting-started/administration/activity#追跡されたヘッダー)には追加されません。ノードの省略記号をクリックして**トラッキングを追加**を選択することで、非ヘッダーの宛先ノードを追跡ヘッダーに追加できます。詳しくは、[メッセージヘッダー](./mapping-node-value-editor#メッセージヘッダー)を参照してください。 #### コードスクリプト コードスクリプト仮想ノードを使用すると、出力値を返す必要のないカスタム{siteNameShort}Script を記述できます。多くの場合、これらのノードは[変数](./mapping-node-value-editor#変数)または特別な`_map` アイテムを使用して、マッピングの後の段階で参照する必要があるものの、現在のコンテキストでは出力する必要がない値を格納します。 例えば、[Map Item](../connectors/xml-map/xml-map-advanced#map-item) セクションで説明するシナリオは、仮想コードスクリプトノードの良い候補です。明細項目のコストの合計は、計算される`Foreach` ループの *外* で出力として返す必要があります。そのため、Foreach ループ *内* の仮想コードスクリプトノードで値を計算し、出力しないようにできます。その後、この値はループ *外* の非仮想ノードで出力として参照できます。 コードスクリプト仮想ノードを作成するには、以下の手順に従います： 1. 宛先ノードを右クリックするか、省略記号をクリックして、**ノードを追加 > コードスクリプトを追加**を選択します。 2. **スクリプト名**を入力します。 3. スクリプトを入力します。エディタは入力中に式を検証するため、構文に問題がある場合は**無効なスクリプト**のメッセージが表示されます。終了したら、**スクリプトを追加**をクリックします。 #### 変数ノード マッピングのある時点で変数を設定し、その変数をマッピングの後半で再度参照することは有用です。詳細と例については、[変数](./mapping-node-value-editor#変数)を参照してください。 ### ノードオプション 個々のノードを操作するには、ノードにカーソルを合わせて右クリックするか、省略記号をクリックして追加のオプションから選択します。オプションは、操作するノードの種類によって異なります。このセクションでは、親ノード、リーフノード、またはドキュメントノードを操作する際に使用できるオプションについて説明します。これらのノードの種類に関する詳細は、[テーブルノード](../tpmc/edi-mapping#テーブルノード) および[カラムノード](../tpmc/edi-mapping#列ノード) を参照してください。 * **ノード名を変更**では、ノード名を変更できます。 * **XPath を編集**では、ノードのXPath を編集できます（すでに`Foreach` としてマッピングされている要素のみ）。 * **ノードを削除**では、ドキュメントからノードを削除できます。 * **ノードを追加** * **兄弟を追加**は、選択したノードと同じレベルにノードを追加します。 * **アトリビュートを追加**は、選択したノードにアトリビュートを追加します。 * **子を追加**は、選択したノードの子としてノードを追加します。 * **ヘッダーを追加**は、値をマッピングできるヘッダーノードを作成します。マッピングされた値は出力ファイルに含まれませんが、マッピング出力メッセージのヘッダーとして追加されます。 * **ループを追加**は、選択したノードの上にループノードを作成し、そのノードはループノード内にネストされます。詳しくは、[ループのマッピング](#ループのマッピング)を参照してください。 * **条件を追加**は、[条件エディタ](./mapping-condition-editor)を開きます。ここで条件を追加して、条件がtrue の場合にのみデータが宛先にアップサートされるように設定できます。 * **コードスクリプトを追加**は、ターゲット要素の兄弟として新しいスクリプトノードを作成します。**スクリプトを追加**ウィンドウを使用して、スクリプトに名前を付け、カスタム{siteNameShort}Script を入力します。 * **変数を追加**は、選択したノードの下に変数ノードを作成します。詳しくは、[変数](./mapping-node-value-editor#変数)を参照してください。 * **ノードを切り取り**は、選択したノードを現在の場所から切り取ります。 * **ノードをコピー**は、選択したノードをコピーします。 * **子として貼り付け**は、切り取ったまたはコピーしたノードを、選択したノードの子として貼り付けます。 * **トラッキングを追加**は、マッピングに[追跡されたヘッダー](../getting-started/administration/activity#追跡されたヘッダー)を追加します。ノードでトラッキングが有効になっている場合はコンパスアイコンが表示されます。 **ノードを編集**を使用して**ノード値を編集**ページを開くこともできます。[ノード値エディタの使用](./mapping-node-value-editor)を参照してください。 ## AI アシストマッピング インスタンスで[AI 設定](../getting-started/administration/settings/ai-settings)をセットアップし、ソースと宛先のテンプレートファイルをアップロードまたは設定したら、サポートされている大規模言語モデル（LLM）のいずれかを使用してマッピング構築を支援できます。この機能は、インテリジェントなマッピング提案を提供してマッピング設定の課題に対処し、正確なデータ変換の作成を大幅に容易にします。 使用するLLM は構造化出力をサポートしている必要があります。{companyName} は、次のモデルが信頼性の高い構造化出力を提供することを確認しています： * Claude: Opus 4.6 * Gemini: gemini-3-pro * Grok: grok-4-fast-non-reasoning * Ollama Cloud: glm-4.6 * OpenAI: gpt-5.4 AI でマッピング全体を生成するには、ページ上部のAI アシストマッピング アイコンをクリックします。構造化出力をサポートしていないモデルを使用しようとすると、アイコンは無効になります。 または、ノードレベルでAI にマッピングを生成させることもできます。ソース側または宛先側の親ノードを右クリックするか省略記号を使用し、**AI アシストマッピング**を選択して、次のオプションのいずれかを選択します： * ノードをマッピング * 子ノードをマッピング * ノードと子ノード AI がマッピングを生成した後、必要に応じてそれらを調整できます。 この機能を[XML Map](../connectors/xml-map/xml-map) コネクタで使用する場合、アプリケーションがマッピング作成に使用するユーザープロンプトとシステムプロンプトをカスタマイズできます。詳しくは、[XML Map の高度な設定](../connectors/xml-map/xml-map-configuration#advanced-settings)を参照してください。 ## ループのマッピング 親ノードのマッピングを作成すると、ソースノードと宛先ノードの間に`Foreach` 関係が確立されます。これは、ソース要素が出現するたびに、宛先要素のすべてのリーフノードを含む対応する宛先要素が生成されることを意味します。リーフノードのマッピングを作成すると、宛先要素にソース要素の値を入力するようマッピングエンジンに指示します。 親ノード（Foreach ループ）をリーフノードよりも先にマッピングします。ループ関係を確立するには、ソースと宛先のXML 構造を理解する必要があります。ソース内の繰り返し要素が宛先でも繰り返し要素になる場合は、それらの要素をForeach 関係でマッピングする必要があります。 Foreach ループ内では、リーフ要素のXPath はマッピングされたForeach XPath を基準とします。 非常に簡単な例として、ネストされたXML 構造をフラットなXML 構造に変換する次のソースXML と宛先XML を考えてみましょう： ```xml theme={null}
``` ```xml theme={null} ``` ソース内の *customer* 要素が繰り返されるたびに、宛先に *customerInfo* 要素が作成されるため、これらの親要素を一緒にマッピングしてForeach 関係を形成する必要があります。これにより、各リーフ要素のマッピングはシンプルになります： リーフ要素のXPath は、親要素のXPath（Foreach 関係を定義するXPath）を基準としていることに注意してください。 ### 複数ループのマッピング マッピングでは、多くの場合、同じドキュメント内に複数のForeach ループ関係が必要になります。ループのマッピングの原則は変わりません。宛先で繰り返し要素を生成するソース内の繰り返し親要素は、ループとしてマッピングする必要があります。外側のループを内側のループよりも先にマッピングします（つまり、構造の上部から下に向かって作業を進めます）。すべてのループ関係は、リーフ要素がマッピングされる前にマッピングされる必要があります。 一般的な例として、受信した発注書レポートを宛先データベースにマッピングする場合を考えます。このようなマッピングには、繰り返される可能性のある2つの異なる要素構造が含まれているため、それぞれにForeach 関係が必要です：(1) 1つのレポートに複数の個別注文が含まれている場合があり、(2) 1つの個別注文に複数の明細項目が含まれている場合があります。 ### インプット例 ソーステンプレートの構造は次のようになります： ```xml theme={null} John Doe 12/21/22 Hammer 1500 1 Standard claw hammer Nail 10 20 Ten penny nails 1700 4 ``` この例では、簡潔にするため *WebOrder* 要素は1つだけですが、同じ *OrderReport* に複数の *WebOrder* セクションが含まれている場合も、マッピングで処理する必要があります。 ### アウトプット例 このマッピングの出力は、データベース挿入のXML モデルと一致する必要があります。データベースの挿入のXML モデルは、データベースコネクタ（例：MySQL、SQLite、CData コネクタ）によって自動的に作成されます。[データベースコネクタからのテンプレートファイル](../connectors/xml-map/xml-map-template-files#template-files-from-database-connectors) セクションでは、これらのXML モデルをXML Map コネクタのテンプレートファイルとして使用する方法について説明します。 適切なデータベース設計では、データを2つの別々のテーブル（注文用と明細項目用）に挿入することが推奨されます。このアプローチに適した入力マッピングを生成すると、次のようなテンプレート構造が得られます： ```xml theme={null} ``` この例では、 *Order* 要素はOrders テーブルへの挿入を表し、 *OrderLine* 要素はLine Items テーブルへの挿入を表します。テンプレートは各テーブルを表す要素を1つだけ生成されますが、マッピング中に確立されるForeach 関係により、適切な数の挿入が作成されます。 *Order* の他の子（ *FirstName* 、 *LastName* 、 *Date* ）はOrders テーブルのカラムを表し、 *OrderLine* の子（ *SKU* 、 *Price* など）はLine Items テーブルのカラムを表します。 ### ループ関係の確立 ソースの *WebOrder* 要素はOrders テーブルへの新しい挿入となるため、宛先の *Order* 要素にドラッグします。同様に、ソースの *Line* 要素はLine Items テーブルへの新しい挿入となるため、宛先の *OrderLine* 要素にドラッグします。 これら2つのForeach 関係を確立すると、マッピングエディタは次のようになります： ループ関係が確立され、宛先の不要な要素が削除されたら、リーフ要素をマッピングして宛先の値を埋めることができます： ## 不要な親ノード Foreach 関係を確立する際は、マッピングされた要素のインスタンスがソースファイルと宛先ファイルに1つだけ存在すれば十分です。つまり、Foreach 関係は、出力要素の数を対応する入力要素の数と一致するように調整します。 この点を明確にするため、[ループのマッピング](#ループのマッピング)の例で、ソースファイル（入力XML のテンプレート）に複数の *customer* 要素グループが存在する場合を考えてみます。*customer* （ソース）と *customerInfo* （宛先）の間に単一のForeach 関係を設定すると、 *customerInfo* 要素グループの数が、どの入力ファイルの *customer* 要素グループの数とも一致することが保証されます。このForeach 関係を確立するために必要な *customer* 要素は1つだけなので、他のすべての *customer* 要素はマッピングには無関係であり、無視または削除できます。 同様に、上の例の宛先ファイルに複数の *customerInfo* 要素がある場合は、1つを除いてすべて削除する必要があります。*customer* と *customerInfo* 間のForeach 関係により、XML 出力に適切な数の *customerInfo* 要素グループが表示されます。 ## マッピングのテスト **マッピングをテスト**ボタンを使用して、マッピングが期待どおりに機能することを確認します。テストでは、以下に示すように、ソースファイルの値が宛先要素に入力されます： テストが失敗した場合、**宛先**ペインに失敗の理由が表示されます。 ## マッピングのベストプラクティス Foreach ループは、宛先ファイル内の繰り返し要素をマッピングするための強力なツールです。ただし、適切な機能を確保し、パフォーマンスの問題を回避するために、以下のベストプラクティスに従うことが重要です： * 大きなXML ファイルを使用する場合、ファイル全体をForeach ループとしてマッピングしないでください。このマッピング方式では、ファイル全体をメモリに読み込むようマッピングエンジンに指示するため、処理時間が長くなる可能性があります。 * 代わりに、ソースドキュメント全体の構造を念頭に置き、繰り返しがあることがわかっている要素（上記[ループ関係の確立](#ループ関係の確立)で説明）に対してのみForeach 関係を作成することがベストプラクティスです。このプラクティスにより、Foreach 関係に関連するパフォーマンスへの影響を最小限に抑えることができます。