Data Factory のヒント

Microsoft Fabric Data Factory を使用する場合の運用知識です。

必須 / 推奨 / 回避

必ず実施すること

• API で作成したデータフローの初回リフレッシュ時に executeOption = "ApplyChangesIfNeeded" を使用する
• save_dataflow_definition 後に add_connection_to_dataflow で接続を再度追加する (保存により接続が削除される可能性あり)
• list_workspaces を使用して名前でフィルタリングする — find_workspace ツールは存在しない
• 追加後、execute_query で各接続を検証する
• マルチソースからシングルソースに戻す場合、既存のデータフローを復元する代わりに新しいデータフローを作成する — remove_connection ツールは存在しない

推奨事項

• M クエリ内で早期にフィルタリングして、クエリ フォールディングを有効にする (フィルタをソースにプッシュする)
• 高コストの操作 (ソート、集計) は最後に — ストリーミング操作 (フィルタ、選択) を最初に実行する
• customMashupDocument で execute_query を使用して M コードを保存前に繰り返し改善する
• 複雑な変換には標準エンジンを使用; シンプルな取り込みには Fast Copy のみを使用する

回避すること

• get_authoring_guidance — 非推奨、M を直接作成する
• クエリチェーンの早期のソート (すべてのデータを読み込んでから結果を返す必要がある)
• 開発中に行制限なしの SELECT * 相当の操作 — 「最初の行を保持」を使用してから削除する

症状のトラブルシューティング

症状	考えられる原因	参照先
DataflowNeverPublishedError	初回実行時のデフォルト SkipApplyChanges	destinations/dest-new-table.md
DestinationColumnNotFound	新しいテーブルの手動マッピング	destinations/dest-new-table.md
Lakehouse での認証情報エラー	接続が バインドされていない	datafactory-connections.md (バインディング)
Fast Copy が変換で失敗	Fast Copy でサポートされていない変換	datafactory-advanced.md (Fast Copy)
即座リフレッシュ失敗 (0～3秒)	プライバシー ファイアウォール、または未公開のドラフト	sources/multi-source.md
API 経由のマルチソース即座失敗	ダーティなデータフロー、または別の Lakehouse.Contents 呼び出し	sources/multi-source.md
IsNewTarget = false 失敗	API で作成されたデータフローの直接ナビゲーション	destinations/dest-new-table.md
復元後の古い接続	save_dataflow_definition が接続を削除しない	datafactory-connections.md (トラブルシューティング)

ナレッジファイル

ファイル	参照する場合
datafactory-core.md	MCP ツール、M の基礎、ローリング日付、What-If クエリ
datafactory-connections.md	接続の検出、作成、バインディング、ゲートウェイ、接続エラーのトラブルシューティング
datafactory-performance.md	クエリタイムアウト、チャンキング、クエリ フォールディング、コネクタの選択
datafactory-advanced.md	Fast Copy の制限事項、Action.Sequence、Modern Evaluator
datafactory-pipelines.md	パイプラインの作成、データフロー アクティビティ、チェーニング、スケジューリング

宛先ファイル (必要なものだけを参照)

ファイル	参照する場合
destinations/dest-new-table.md	MCP 経由で新しい出力テーブルを作成する (最も一般的なパス)
destinations/dest-existing-table.md	既存のテーブルに書き込む
destinations/dest-troubleshooting.md	リフレッシュ失敗、接続の問題、サイレント エラーの診断

ソースファイル

ファイル	参照する場合
sources/multi-source.md	Lakehouse と SharePoint/Web ソースを組み合わせる、AllowCombine
sources/sharepoint-excel.md	Web.Contents 経由で SharePoint から Excel ファイルを読み込む

M テンプレート (コピペ可能、説明文なし)

ファイル	参照する場合
templates/m-new-table-destination.m	新しいテーブルの完全な M セクション ドキュメントが必要
templates/m-existing-table-destination.m	既存テーブルの M セクション ドキュメントが必要
templates/m-multi-source-section.m	AllowCombine を使用したマルチソースの M セクション ドキュメントが必要
templates/m-sharepoint-excel-source.m	Web.Contents 経由の SharePoint Excel の M スニペットが必要
templates/pipeline-single-dataflow.json	単一のデータフロー アクティビティのパイプライン JSON が必要
templates/pipeline-chained-dataflows.json	チェーン された データフロー アクティビティのパイプライン JSON が必要