Fabricのアイテムをワークスペース間(例えば開発からテスト、本番まで)にデプロイすると、アイテム間の依存関係が壊れることがあります。 一部のアイテムは依存関係への参照を オブジェクトID (ワークスペース固有のGUID)として保存し、他のアイテムは 論理ID ( .platform ファイルに保存されたクロスワークスペースポータブル識別子)を使用します。
定義に論理IDを使用するアイテムは、ターゲットワークスペース内の対応するアイテムに正しくバインドされます。 オブジェクトIDを使用するアイテムは元のワークスペースを指し続け、デプロイメントが壊れます。
この記事では、Git統合を使った際に論理IDを通じて依存関係バインディングをサポートするFabricアイテムタイプと、サポートしないアイテムタイプをマッピングしています。 論理IDやソース管理におけるアイテムの表現方法について詳しく知りたい方は、「Fabricの論理ID」をご覧ください。
主な概念
-
論理ID:
.platformファイル内で自動生成されるクロスワークスペース識別子。 同じ論理IDを持つアイテムは、ワークスペース間で同じアイテムとして扱われます。 - オブジェクトID:特定のインスタンスを識別するワークスペース固有のGUID。 オブジェクトIDは、手動の介入やパラメータ化なしにはクロスワークスペース展開に耐えられません。
- 依存関係バインディング(Git):Gitのブランチを新しいワークスペースに同期すると、Fabricは論理IDを使って依存関係を参照を解決し、ターゲットワークスペース内の正しいアイテムを自動的に指し示します。
- 名前またはURIで:一部の項目はIDではなくディスプレイ名やURIで依存関係を参照します。 これらの参照は、ワークスペース間の命名規則によって正しく解決される場合もあればそうでない場合もあります。
依存関係のバインディングの仕組み
ワークスペース内では、アイテムはオブジェクトIDを使って依存関係を参照します。 FabricがアイテムをGitにエクスポートすると、これらのオブジェクトIDの一部を.platformファイルの論理IDに置き換えます。 Gitブランチを別のワークスペースに同期すると、Fabricはそれらの論理IDをターゲットワークスペース内の正しいオブジェクトIDに解決します。 これが依存関係の拘束が機能する理由です。
しかし、すべての依存関係参照がエクスポート時に論理IDに置き換えられるわけではありません。 オブジェクトIDをGit表現で保持するアイテムは同期後も元のワークスペースを指し示し、手動またはパラメータ化で更新する必要があります。
Important
依存関係バインディングは、同じワークスペース内のFabricアイテム間の参照にのみ適用されます。 もしアイテムが別のワークスペースのFabricアイテムを参照する場合、その参照はオブジェクトIDを使用し、自動的にバインドされません。 Connections(データソース接続、ゲートウェイ)への参照も自動バインドされません。 環境固有の値セットを持つ 変数ライブラリ を使って、環境間の接続参照を管理します。
依存関係バインディングの互換性
以下の表は、ワークスペース間でデプロイした際に各Fabricアイテムタイプの依存関係が正しくバインドされるかどうかを示しています。 現在、この記事は Git統合 の動作について扱っています。 バインディングは各アイテムが依存関係参照をどのように定義に格納するかによって決まるため、同じ動作はデプロイパイプラインやインポート(バルク)APIなど、定義を再利用する他の展開メカニズムにも当てはまります。
これらのテーブルは、依存関係がソースアイテムと同じ ワークスペース 内の別のアイテムであると仮定しています。 異なるワークスペース内のアイテムへの参照は自動バインドされません。 テーブルに示されている値に関係なく、ソースオブジェクトIDにピン留めされたままです。
Gitの Auto-bind 欄は以下の通りです:
- はい:Gitのアイテム定義は依存関係参照を論理IDとして保存しています。 ブランチを新しいワークスペースに同期すると、参照は自動的にそのワークスペース内の対応するアイテムにバインドされます。
- いいえ:Gitのアイテム定義は依存関係参照をオブジェクトID(ワークスペース固有のGUID)として保存します。 同期後も参照は元のワークスペースを指し続けます。クロスワークスペース展開のために手動で更新またはパラメータ化する必要があります。
- 部分的:アイテムは名前やURIで依存関係を解決します。ワークスペース間で名前が一貫していれば機能するかもしれません。
Notebooks
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| Lakehouse | Yes | ノートブックの設定で「Lakehouse Auto-Binding in Git」を有効にする必要があります。 有効化されると、オブジェクトIDは論理IDに置き換えられます notebook-settings.json。 この設定は既定ではオフになっています。 詳細は GitのLakehouse自動バインディングをご覧ください。 |
| Environment | Yes | |
| ミラー化されたデータベース | No |
注
NotebookからLakehouseへのバインディングはデフォルトでは有効になっていません。 各ノートブックの設定で「Lakehouse Auto-Binding in Git」設定をオンにする必要があります。 詳細については、「 ノートブックのソース管理とデプロイ」を参照してください。
Reports
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| セマンティックモデル(Power BIレポートより) | Partial | レポートはモデルをbyPathの相近definition.pbir参照を通じて参照しており、明示的な論理IDではありません。 モデルがターゲットワークスペース内の同じ相対位置にデプロイされると正しく解決されますが、論理IDを通じたバインドはされません。 詳細については、Power BIデスクトップのプロジェクトレポートフォルダをご覧ください。 |
| セマンティックモデル(ページ付きレポートより) | No | レポートの接続文字列は、デプロイ時に書き換えないワークスペース固有のIDでセマンティックモデルを参照するため、ソースモデルを指し続けます。 クロスワークスペース展開のためにこのリファレンスを更新する必要があります。 (Report Builderで作成されたモデル名で参照されるレポートは、代わりに表示名(部分的)で解決されることがあります。) |
パイプライン
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| パイプライン | Yes | |
| Notebook | Yes | |
| データフロー Gen2 | Yes | |
| SQL Database | Yes | |
| Spark ジョブ定義 | No | SparkJobDefinitionアクティビティは論理IDではなくオブジェクトIDでSparkジョブ定義を参照するため、デプロイ後もソースアイテムを指し続けます。 クロスワークスペース展開のためにこの値をパラメータ化する必要があります。 |
| Lakehouse | Yes | |
| セマンティック モデル | No | PBISemanticModelRefreshアクティビティは論理IDではなく、アイテムIDでセマンティックモデルを参照します。 クロスワークスペース展開のためにこの値をパラメータ化する必要があります。 |
| Warehouse | No | ウェアハウス artifactId 論理IDで解決しリバインドしますが、 linkedService はソースワークスペースのSQL endpointも保存しており、これは書き換えられません。 クロスワークスペース展開のために endpoint をパラメータ化してください。 |
セマンティック モデル
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| セマンティック モデル | Partial | 連結または複合モデル参照では、名前で指定された接続文字列を使用します。 |
| SQL 分析エンドポイント (lakehouse) | No | TMDL expressions.tmdlのDirect Lake 接続文字列には、ワークスペース固有のエンドポイントURLとデータベースのGUIDが含まれています。 クロスワークスペース展開のためにこれらのパラメータを置き換える必要があります。 |
| KQL データベース | No | TMDL式のクラスターURIを含む接続文字列はワークスペース固有の値を含む。 |
| SQL データベース | No | TMDL式の接続文字列はワークスペース固有の値を含む。 |
| Warehouse | No | ウェアハウスSQL分析エンドポイントへの接続は、ワークスペース固有のURLを使用します。 |
レイクハウス
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| レイクハウス(ショートカット) | Yes | レイクハウスや倉庫など他のFabricアイテムを指す内部OneLakeショートカットは論理IDとして保存され、ターゲットワークスペースアイテムに再割り当てされます。 Azure Data Lake Storage Gen2やAmazon S3のような外部ソースへのショートカットはFabricの外部を指し、接続参照を持ち、論理IDバインディングの対象外となります。 ショートカットターゲットの全リストについては、 OneLakeショートカットをご覧ください。 デプロイの動作については、 Lakehouse Git統合およびデプロイパイプラインを参照してください。 |
Dataflows(Gen2)
デフォルトでは、Dataflow Gen2はFabricアイテムへの絶対的な参照を作成します。クエリはソースワークスペースIDとアイテムのオブジェクトIDを保存し、デプロイ時に書き換えません。 source 参照では、代わりに 相対参照 を使用できます。Fabric コネクターで !(Current Workspace) ノードの下の項目を選択すると、クエリはその項目を名前で保存し（GUID は使用されません）、デプロイ時にターゲット ワークスペース内の一致する項目に解決されます。 出力 の宛先 は常に絶対参照を使い、再バインドはしません。 宛先や絶対的なソース参照については、クロスワークスペース展開用の値をパラメータ化してください。 詳細については、「Dataflow Gen2のFabricコネクタとの相対的な参照」および「CI/CDおよびGit統合のDataflow Gen2」をご覧ください。
出典:
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| Lakehouse | Partial | リバインドは相対的な参照として書かれた場合にのみ行われます(!(現在のワークスペース));デフォルトの絶対参照はリバインドされません。 |
| Warehouse | Partial | リバインドは相対的な参照として書かれた場合にのみ行われます(!(現在のワークスペース));デフォルトの絶対参照はリバインドされません。 |
目的地の参考:
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| Lakehouse | No | |
| Warehouse | No | |
| SQL Database | No |
Spark のジョブ定義
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| Environment | Yes | |
| Lakehouse | No |
defaultLakehouseArtifactIdはオブジェクトIDを使用します。 |
ジョブのコピー
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| Lakehouse | Yes | |
| Warehouse | No | ウェアハウス artifactId 論理IDで解決しリバインドしますが、 linkedService はソースワークスペースのSQL endPointも保存しており、これは書き換えられません。 クロスワークスペース展開のために endPoint をパラメータ化してください。 |
| SQL Database | Yes |
GraphQL API
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| SQL エンドポイント | Yes | |
| Warehouse | Yes | |
| SQL Database | Yes |
すべてのGraphQL APIデータソースについては、展開後に接続や認証情報の再構成が必要になるかもしれません。
イベントストリーム
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| Lakehouse | Yes | |
| Eventhouse | Yes | 同じワークスペース内のアイテムであれば、すべての宛先がCI/CDに完全にサポートされています。 EventhouseのDirect Inestionモードでは、デプロイ後に手動で接続を再設定する必要があるかもしれません。 詳細については、 Eventstream CI/CDをご覧ください。 |
| アクティベーター(反射) | Yes | 同じワークスペース内のアイテムであれば、すべての宛先がCI/CDに完全にサポートされています。 詳細については、 Eventstream CI/CDをご覧ください。 |
KQL アイテム
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| KQLデータベースからイベントハウスへ | Yes |
parentEventhouseItemIdのDatabaseProperties.jsonは論理IDであり、ターゲットイベントハウスにバインドします。 KQL データベースは、親イベントハウスの子リソースとしてデプロイされます。 |
| KQL queryset から KQL データベースへ | Partial | アイテムIDではなく、 clusterUri や databaseNameで解決します。 定義には databaseItemIdが含まれていますが、それは再バインドされないオブジェクトIDなので、解像度は環境間のURIに依存します。 |
| リアルタイム ダッシュボードから KQL データベースへ | Partial | クラスターURIを持つ dataSources 配列を使用しています。 KQLクエリセットと同じパターンです。 |
倉庫
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| 倉庫(クロスリファレンス) | No | 他のウェアハウスへの参照はオブジェクトIDを使用します。 |
| SQL エンドポイント | No | SQLエンドポイント参照はワークスペース固有の識別子を使用します。 |
変数ライブラリ
| 依存関係 | Gitでの自動バインド | メモ |
|---|---|---|
| Fabric アイテム(ItemReferenceタイプ) | No |
ItemReference変数型はworkspaceIdとitemIdを生のGUIDとして保存します。 これらの値は環境ごとの値セットで手動で更新またはオーバーライドする必要があります。 |
依存関係のないアイテム
以下の項目はクロスワークスペース依存バインディングの問題はありません:
- Environment
- SQL Database
- イベントハウス(コンテナアイテム;KQLデータベースでも参照されています)
- ミラードデータベース(外部ソース構成のみ)
まとめ
Fabric アイテムをワークスペース間でデプロイする際、参照が移植可能な論理 ID ではなくワークスペース固有のオブジェクト ID として保存されている場合、アイテム間の依存関係が壊れることがあります。 すべてのアイテムタイプが論理IDを介した依存関係バインディングをサポートしているわけではありません。 クロスワークスペース展開を設定する前に、この記事の互換性テーブルを確認し、どの依存関係が自動的にバインドされ、どれが手動のパラメータ化が必要かを特定してください。