semantic-model-authoring

テレメトリ — 必須。 すべての api.fabric.microsoft.com 呼び出しには、 x-ms-fabric-skill: semantic-model-authoring（az rest の場合：--headers "x-ms-fabric-skill=semantic-model-authoring"）を含める必要があります。 fabric_lro や再試行を含む、すべての LRO ポーリングにも必要です。スニペットでは省略されていますが、必ず追加してください。

重要な注意事項

1. ワークスペース名から詳細（ID を含む）を確認するには、すべてのワークスペースを一覧表示してから、JMESPath でフィルタリングします。
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を確認するには、そのワークスペース内の該当する種類のアイテムをすべて一覧表示してから、JMESPath でフィルタリングします。
3. 各操作で使用するツールを選ぶ際は、必ずツール選択の優先順位を考慮してください。MCP が利用可能で、対象のモデルに接続されている場合は、TMDL の編集や az rest を既定で使用しないでください。

Power BI セマンティックモデルの作成 — CLI スキル

ワークフローセレクター

ユーザーの意図に応じて、以下の判断ツリーから適切なワークフローを選択します。

ユーザーの目的	ワークフロー
セマンティックモデルをゼロから作成する	新しいセマンティックモデルの作成
モデルのメタデータ（テーブル、列、メジャー、リレーションシップ）を調査または確認する	セマンティックモデルのメタデータを確認する
セマンティックモデルのオブジェクト（メジャー、テーブル、列、リレーションシップなど）を追加・編集する	既存のモデルを変更する
DAX コードを記述またはリファクタリングする	既存のモデルを変更する
フィールドパラメーターを作成・編集する	フィールドパラメーターを作成する
DAX クエリまたはメジャーのパフォーマンスを改善する	DAX パフォーマンスを最適化する
セマンティックモデルをベストプラクティスに照らして分析する	ベストプラクティスを分析する
AI での利用（Copilot／Data Agents）に向けてセマンティックモデルを準備する	セマンティックモデルの AI 対応
モデルを Fabric ワークスペースにデプロイする	Fabric にデプロイする
セマンティックモデルを更新する	セマンティックモデルを更新する
データソース、パラメーター、またはアクセス許可を設定する	Fabric でセマンティックモデルを管理する
セマンティックモデルを Fabric 接続にバインドする（またはバインドを解除する）	セマンティックモデルを接続にバインドする
セマンティックモデル定義を PBIP としてエクスポート／取得する	PBIP にエクスポートする

目次

ワークフローのステップで参照が必要になったときに、必要に応じて読み込んでください。一度にすべて読み込まないでください。

トピック	参照	読み込むタイミング
モデリングのベストプラクティス	modeling-guidelines.md	モデルを作成または編集する前
命名規則	naming-conventions.md	テーブル、列、メジャーに名前を付ける、または名前を変更するとき
Direct Lake モデリング	direct-lake-guidelines.md	モデルを OneLake に接続するとき
TMDL の編集	tmdl-guidelines.md	TMDL ファイルを生成または編集する前
PBIP プロジェクト	pbip.md	PBIP フォルダーで作業するとき
DAX 言語	dax-guidelines.md	DAX コードを記述またはレビューするとき
フィールド パラメーター	field-parameters.md	フィールド パラメーター テーブル（メトリック セレクター、動的ビュー）を作成または編集するとき
メタデータの検出（DAX INFO 関数）	metadata-discovery.md	DAX INFO 関数を使ってモデルのメタデータを検出するとき（ワークフロー：セマンティック モデルのメタデータを検出するを参照）
DAX パフォーマンスの判断ガイド	dax-perf-decision-guide.md	DAX を最適化するときは、まずここを参照してください
DAX パフォーマンス パターン カタログ	dax-perf-patterns.md	判断ガイドで候補となるパターンが特定された後、必要に応じて読み込みます
セマンティック モデルの AI 対応	semantic-model-ai-readiness.md	Copilot または Data Agents 向けにモデルを準備するとき
セマンティック モデル REST API	semantic-model-rest-api.md	TMDL の CRUD、更新、パラメーター、アクセス許可、プロパティの取得に az rest を使用するとき
接続のバインド	connection-binding.md	セマンティック モデルを Fabric データ接続（ゲートウェイ、クラウド、VNet、自動、なし）にバインドまたはバインド解除するとき
ワークスペース／アイテムの検索	COMMON-CLI.md	ワークスペース ID／アイテム ID を解決するとき
Fabric コントロール プレーン API	COMMON-CLI.md	az rest のパターン、LRO、ページネーションを使用するとき
認証	COMMON-CLI.md	az login で認証するとき
認証とトークンの取得	COMMON-CORE.md § Authentication & Token Acquisition	audience が間違っていると 401 が発生します。認証に関する問題がある場合は、必ず先に読んでください
コア コントロール プレーン REST API	COMMON-CORE.md § Core Control-Plane REST APIs	ページネーション、LRO のポーリング、レート制限のパターンを含みます
定義エンベロープ	ITEM-DEFINITIONS-CORE.md	TMDL 定義ペイロードを作成するとき
例	Examples	エンドツーエンドの手順を参照できます。

---

ツール選択の優先順位

優先順位（高い順）：

1. Tier 1 — powerbi-modeling-mcp MCP が登録されている -> 任意のソース（Power BI Desktop、Fabric ワークスペース、ローカルの PBIP フォルダー）からモデルを作成または編集する場合は、オーサリングに MCP を使用します。MCP はセマンティックモデルを編集するための最も信頼性が高く、機能が充実した方法です。ライブモデルに即座に反映され、TMDL の不整合が発生するリスクもありません。

   重要： 動的検索ツール（例：tool_search_tool_regex）が利用可能な場合は、パターン powerbi-modeling-mcp に一致する利用可能な MCP サーバーを検索してください。

   読み取り／確認と書き込みの両方が対象です。

   • 変更を確認または検証するには、対応する MCP 操作（List / Get）を使用します。
   • アンチパターン： MCP が接続されているときに、TMDL ファイル（*.tmdl）を開く、view する、glob する、またはその他の方法で読み取ること。MCP に読み込まれたモデルが信頼できる情報源であり、ディスク上の TMDL は古くなっています。唯一の例外は、ユーザーが TMDL ファイルを使った作業を明示的に依頼した場合です。

2. Tier 2 — MCP が登録されておらず、PBIP フォルダーまたは Fabric ワークスペースがある -> TMDL ファイルを直接編集します。tmdl-guidelines.md と pbip.md を読み込んでください。ソースが Fabric ワークスペースの場合は、az rest を使用して TMDL を往復させます（semantic-model-rest-api.md を読み込みます）：getDefinition -> TMDL をローカルで編集 -> updateDefinition。

フォールバック — 上記のいずれも利用できない場合（例：PBIP も MCP もない Power BI Desktop） -> 停止します。この構成では、エージェントはモデルをオーサリングできません。powerbi-modeling-mcp MCP サーバーをインストールして登録するか（a）、PBIX を PBIP プロジェクトとして保存してからワークフローを再開するよう（b）、ユーザーに案内してください。

以下のすべてのワークフローは、使用するツールに依存しません。 ワークフローの手順では、目的（接続、作成、編集、保存、デプロイ、更新）を説明しています。各手順の実行に使用するツールは、ここで決定します。現在の環境で利用可能な最優先のツールを必ず選択し、より優先度の高い選択肢が機能する場合はツールを混在させないでください。一部のワークフローではこの既定の優先順位が上書きされるため、Tier 1 を既定として選ぶ前に、ワークフロー独自のツール選択ルールを必ず確認してください。

セマンティックモデルへの接続

セマンティックモデルは 3 か所に配置できます。ツール選択の優先順位に従って接続方法を決定してください。

• Power BI Desktop：実行中の Power BI Desktop インスタンスを特定し、そのローカルモデルに接続します。
• Fabric ワークスペース：まず、ワークスペースとアイテムの検索のパターンに従って、ワークスペースとセマンティックモデルを見つけます。ワークスペースを一覧表示して名前からワークスペース ID を特定し、次にそのワークスペース内で種類が SemanticModel のアイテムを一覧表示して、名前からモデル ID を特定します。その後、モデルに接続する（ライブ）か、ローカル編集用に TMDL 定義をエクスポートします。
• PBIP プロジェクト：[Name].SemanticModel/definition フォルダーに接続します。PBIP フォルダー構造を理解するために pbip.md を読み込みます。TMDL コードを含む [Name].SemanticModel/definition フォルダーのみを読み込んでください。

セマンティックモデルへの変更の保存

変更の永続化方法は、モデルの保存場所と使用するツール階層（ツール選択の優先順位に従います）によって異なります。

ライブ接続（階層 1 - Desktop または Fabric ワークスペースに対する MCP）：

• 操作がライブモデルに対して実行されるたびに、変更が直ちに適用されます。明示的な保存手順は不要です。
• PBIP プロジェクト（MCP 経由のライブ接続）：セッションの終了時に、モデルを [Name].SemanticModel/definition フォルダーにシリアル化して戻します。PBIP フォルダーがまだ存在しない場合は、まずPBIP へのエクスポートに従って完全な構造を作成します。

ローカル TMDL の編集（階層 2 - ファイルの直接編集または az rest のラウンドトリップ）：

• PBIP プロジェクト：編集中に変更が TMDL ファイルへ書き込まれています。追加の保存手順は不要です。
• Fabric ワークスペース：サービスからエクスポートしたローカル TMDL ファイルに変更が加えられています。モデルを再デプロイし（updateDefinition のフローについては semantic-model-rest-api.md を読み込んでください）、変更をワークスペースに反映します。

---

ワークフロー：新しいセマンティックモデルの作成

適用される場合： ユーザーが新しいセマンティックモデルをゼロから作成するよう依頼した場合です。

手順：

1. 要件を収集する - モデルの目的、データソースの接続情報とスキーマ、主要なビジネスエンティティおよびファクトについて、ユーザーと共通認識を得られるまでヒアリングします。データソースの情報がない場合は、停止して ask_user を使用してください。推測したり、情報を捏造したりしないでください。

2. ストレージモードを決定する - データソースが Fabric OneLake の場合は Direct Lake、それ以外の場合はデフォルトで Import を使用します。DirectQuery はユーザーが明示的に求めた場合にのみ使用します。

3. スター スキーマを設計する - ファクトテーブルとディメンションテーブル、およびリレーションシップキーを特定します。

   • ファクトテーブルに日付フィールドが含まれる場合は、個別の日付ディメンションテーブルを作成し、リレーションシップでファクトテーブルとリンクします。明示的な依頼がない場合は、DAX 計算テーブルではなく PowerQuery/M パーティションを使用します。

4. 該当するガイドラインを読み込む - 必須：オブジェクトを構築する前に（以下の階層 1 の MCP パスを含め）、modeling-guidelines.md を読み込んでください。 Direct Lake の場合は、direct-lake-guidelines.md も読み込みます。記憶だけに頼って構築しないでください。

5. 構築する - ツール選択の優先順位に従います。モデリング MCP が利用できる場合は、モデル全体の構築に優先して使用します。利用できない場合は、TMDL コード編集パスを使用します。 空のデータベース（互換性レベル 1702 以上）を作成し、各テーブルについて既存のモデルを変更するの実行順序（パーティション -> 列 -> リレーションシップ -> メジャー）に従います。ストレージモードごとの詳細：

   • Import / DirectQuery - データソース用の M パラメーター（Server、Database、...）を作成し、パーティションの M コードで参照します。列の dataType と sourceColumn のマッピングが適切であることを確認します。
   • Direct Lake - AzureStorage.DataLake コネクターを使用して、Direct Lake 接続用の共有名前付き式を作成します。directLake モードの EntityPartitionSource を使用し、レイクハウスのテーブル列にマッピングします。

   モデル全体を一度に構築してから、一度だけデプロイします。 デプロイ前に、すべてのテーブル、列、リレーションシップ、メジャーを追加します。モデルの一部だけをデプロイしてから編集・再デプロイすることは避けてください。MCP パスでは、最初から最後までモデルをセッション内に保ちます。

6. デプロイまたは保存する - Fabric ワークスペースが利用可能な場合はFabric にデプロイ、それ以外の場合はPBIP にエクスポートします。セマンティックモデルへの変更の保存を参照してください。構築に使用したのと同じパスでデプロイします。

7. 検証する - 検証チェックリストを実行します。

---

ワークフロー：セマンティックモデルのメタデータを検出する

適用される場面： ユーザーがモデルの構造（テーブル、列、メジャー、リレーションシップ、階層、パーティション、ロール、またはストレージの内部構造）の調査、一覧表示、検出を求めている場合に適用されます。また、編集前にモデルのインベントリを作成するため、他のワークフロー（変更、ベストプラクティスの分析、AI 対応状況）でも内部的に使用されます。

検出方法を選択します（優先度の高い順）。

1. powerbi-modeling-mcp による TOM の検査（List / Get） - powerbi-modeling-mcp が登録され、対象モデルに Write アクセスで接続されている場合のデフォルトです。構造化されたオブジェクトモデルを直接返し、保留中の編集と同期されるため、作成中の使用に適しています。

2. DAX INFO.VIEW 関数 - モデルの INFO.VIEW.* メタデータ行セットをクエリします。必須：INFO 関数を使った DAX の作成または実行の前に、必ず metadata-discovery.md を読み込んでください。記憶を頼りに INFO クエリを作成しないでください。リファレンスを読み込み、記載されたパターンを使用してください。次のいずれかに該当する場合は、この方法を優先してください。

   • モデルに対する Write 権限がない場合。powerbi-modeling-mcp の List / Get 操作には Write 権限が必要です。Build アクセスがある場合は、dax_query_operations ツールを使って INFO.VIEW 関数を実行します。
   • powerbi-modeling-mcp が登録されていない、または利用できない場合。Tier 2 を使用します。モデル定義（getDefinition）をエクスポートし、.tmdl ファイルを調べてスキーマメタデータを確認します。

まず範囲を絞ります。スコープ推定と INFO.VIEW.* クエリを最初に実行し、次にタスクに関連するオブジェクトのみを投影／フィルターします（metadata-discovery.md を参照）。

---

ワークフロー：既存のモデルを変更する

適用される場面： ユーザーがメジャー、テーブル、列、リレーションシップの追加／編集／削除、DAX コードの作成、UDF を使ったリファクタリング、または TMDL の直接編集を求めている場合に適用されます。

手順：

1. 接続して検出する - セマンティックモデルへの接続とセマンティックモデルのメタデータを検出するに従います。テーブル、リレーションシップ、既存のメジャーを一覧表示し、ストレージモードを特定します（適用するガイドラインはストレージモードによって異なります）。
2. 該当するガイドラインを読み込む - modeling-guidelines.mdは常に読み込みます。Direct Lake の場合はdirect-lake-guidelines.mdを、TMDL を直接編集する場合はtmdl-guidelines.mdを、DAX を変更する場合（UDF のリファクタリングを含む）はdax-guidelines.mdを読み込みます。
3. 変更を計画する - 追加、変更、削除する内容を正確に特定します。名前の競合や重複がないか確認します。
4. 正しい順序で実行します。
   • テーブルの追加 - パーティション -> 列 -> リレーションシップ -> メジャー。
   • リレーションシップの追加 - 両側にキー列が存在し、データ型が一致していることを確認します。
   • メジャーの追加 - 参照先の列／テーブルが存在することを確認します。
5. 保存して検証する - セマンティックモデルへの変更の保存と検証チェックリストに従います。

---

ワークフロー：フィールドパラメーターの作成

適用される場合： ユーザーがフィールドパラメーターの作成、編集、並べ替え、名前変更、または削除を依頼した場合です。これはモデル側で完結する計算テーブルです。一致するレポートスライサーとビジュアルは別途レポートでの作業となるため、ここでは対象外です。

開始前にfield-parameters.mdを読み込み、そこに定義されたワークフローに従ってください。

手順：

1. 接続して検出する - セマンティックモデルへの接続に従います。重複を作成する前に、既存のフィールドパラメーター（ParameterMetadata "kind": 2を持つ列）があるかどうかを検出します。
2. field-parameters.mdの該当するサブワークフローに進みます：
   • 新しいパラメーターを作成する -> ワークフロー：フィールドパラメーターの作成（Tier 1 のtable_operations CreateFieldParameter）。
   • 既存のパラメーターを編集する（フィールドの追加／削除／並べ替え／ラベル変更） -> ワークフロー：フィールドパラメーターの編集（partition_operationsによるパーティションの書き換え。UpdateFieldParameter操作はありません）。
   • 名前変更または削除する -> ワークフロー：フィールドパラメーターの名前変更または削除。
3. 保存して検証する - セマンティックモデルへの変更の保存および検証チェックリストに従います。Desktop がこのテーブルをフィールドパラメーターとして認識できるよう、3 つの列とParameterMetadata "kind": 2が保持されていることを確認します。

---

ワークフロー：DAX のパフォーマンス最適化

適用される場合： ユーザーが DAX クエリのパフォーマンス改善、低速なメジャーの診断、または計算の最適化を依頼した場合です。

必須要件： トレース対応クライアントが必要です（MCP を推奨））

まずdax-perf-decision-guide.mdを読み込み、そこで定義されたフレームワークに従ってください。候補となる最適化パターンを適用する場合にのみdax-perf-patterns.mdを読み込みます。このフレームワークには以下が含まれます：

1. 最適化の取り組みを分類するための階層モデル
2. ボトルネックを特定するためのトレース診断
3. テストと検証を行う最適化手法の候補をまとめたパターンカタログ

---

ワークフロー：ベストプラクティスの分析

適用される場合： ユーザーがベストプラクティスに照らしたセマンティックモデルのレビュー、監査、または分析を依頼した場合です。

手順：

1. 接続して一覧を作成する - セマンティックモデルへの接続およびセマンティックモデルのメタデータの検出に従います。すべてのテーブル、列、リレーションシップ、メジャー、およびストレージモードを記録します。
2. 該当するガイドラインを読み込む - modeling-guidelines.mdは常に読み込みます。Direct Lake の場合はdirect-lake-guidelines.md、命名を評価する場合はnaming-conventions.md、DAX を評価する場合はdax-guidelines.mdも読み込みます。
3. 評価する - 読み込んだガイドラインに照らしてモデルを比較します（スター スキーマ、命名、リレーションシップのカーディナリティとクロスフィルター、formatStringを設定した明示的なメジャー、列のデータ型とsourceColumn、非表示の FK 列、計算列とメジャーの使い分け、Direct Lake の制約など）。
4. 重要度（重大、推奨、任意）ごとに分類して調査結果を提示します。各項目について、違反しているルールと提案する修正を示します。ユーザーの承認を待ちます。
5. 承認された修正を既存のモデルの変更に従って適用します。
6. 保存して検証する - セマンティックモデルへの変更の保存および検証チェックリストに従います。

---

ワークフロー：セマンティックモデルの AI 対応

適用されるケース： ユーザーが、セマンティックモデルを Microsoft Fabric Copilot、Power BI Data Agent、または会話型 BI エクスペリエンスで利用できるようにすることを求めている場合です。「Copilot 対応」「AI 対応」「AI 向けに準備」「Copilot 向けにモデルを準備」などが該当します。

作業を始める前に、semantic-model-ai-readiness.md を読み込んでください。

手順：

1. 範囲を確認し、背景情報を収集する - ask_user を使って、利用形態（レポートのみ／会話型 BI／両方）と「適用するタイミング」セクションに記載されたモデルの安定性を確認します。業務上の背景情報（業務プロセス、主要な指標、よくある自然言語での質問、用語）を収集します。情報を作り上げないでください。
2. 接続してインベントリを作成する - セマンティックモデルへの接続に従います。モデルの内容とソースの場所（PBIP／Fabric ワークスペース／Desktop のみ）を記録します。
3. 評価して振り分ける - Readiness Checklistを順に確認します。各ギャップについて、Supported Editing Routesに従って修正方法（エージェントが編集可能な TOM メタデータ、またはユーザーが Power BI の「Prep data for AI」UI で設定する AI 固有の成果物）を分類します。
4. 調査結果を提示する - 重要度ごとにまとめ、各項目に対応方法（エージェントで対応可能／ユーザーによる対応が必要）を付記します。承認を待ちます。
5. 承認された変更を適用する - TOM メタデータの修正は既存モデルの変更に従って適用します。AI の指示、AI Data Schema、Verified Answers については、Power BI の「Prep data for AI」UI で設定するようユーザーに案内します。ユーザーが同意した場合に限り、Readiness のリファレンスに従って提案を行います。Desktop のみで扱う PBIX の場合は、ユーザーに操作を案内します。
6. 保存して検証し、実環境でのテストを勧める - セマンティックモデルへの変更の保存と検証チェックリストに従います。Copilot または Data Agent で代表的な自然言語プロンプトをテストし、改善を繰り返すようユーザーに勧めます。

---

ワークフロー：PBIP へのエクスポート

適用されるケース： ユーザーがセマンティックモデルを PBIP プロジェクトフォルダーにエクスポートまたは保存することを求めている場合、またはデプロイ先となる Fabric ワークスペースがない場合（たとえば、メモリ上でモデルを作成した後）です。

重要な事実： モデルをエクスポートして作成されるのは、TMDL 定義ファイルのみです。周囲の PBIP フォルダー構造（Report フォルダー、definition.pbism、definition.pbir、.pbip エントリポイント）は作成されません。Power BI Desktop で開けるように、エクスポート前にエージェントがこれらを作成する必要があります。

作業を始める前に、pbip.md を読み込み、そこで定義されている PBIP フォルダー構造に従ってください。

手順：

1. 保存先を決定する - ask_user を使って、保存先フォルダーのパスとセマンティックモデル名を取得します。フォルダーのみが指定された場合は、モデルのデータベース名をセマンティックモデルフォルダー名として使用します。
2. PBIP 構造を作成する - pbip.mdに従い、<Name>.SemanticModel/（definition/ と definition.pbism を含む）、<Name>.Report/（definition/ と byPath 参照を使用する definition.pbir を含む）、および <Name>.pbip が存在することを確認します。不足しているものがあれば作成します。
3. TMDL を <Name>.SemanticModel/definition/ にエクスポートする - ツール選択の優先順位に従います。
   • Tier 1（MCP） - ライブモデルに対して MCP のエクスポート／保存操作を使用します。
   • Tier 2（MCP なしの Fabric ワークスペース） - getDefinition を呼び出し（semantic-model-rest-api.mdを読み込みます）、返された各パーツを書き込みます。
   • ローカルの TMDL ファイルがすでにディスク上にある場合 - definition/ フォルダーにコピーまたは移動します。
4. 検証する - definition/ フォルダーに最低限 model.tmdl とテーブルの .tmdl ファイルがあることを確認します。definition.pbism、<Name>.Report/definition.pbir（../<Name>.SemanticModel への正しい byPath を含む）、および <Name>.pbip が存在し、相互に正しく参照していることを確認します。

---

ワークフロー：Fabric へのデプロイ

適用される場合： ユーザーが Fabric ワークスペースへのセマンティックモデルのデプロイまたは公開を依頼した場合です。

厳守事項 — このワークフローは、既定の ツール選択の優先順位 よりも優先されます。 MCP が利用可能だからといって、既定で MCP を使用しないでください。デプロイ方法は、接続されているツールではなく、モデルのソースによって決まります。ソースがディスク上の PBIP／TMDL ファイルの場合、MCP セッションがアクティブでも、必ず Fabric REST API を使用してください。

判断ツリー（上から順に確認し、最初に一致したものを 1 つだけ選択します）：

1. デプロイが必要な PBIP／TMDL ファイルがディスク上にありますか？ -> はい — Fabric REST API を使用します。 az rest を呼び出して、（新しいモデルの場合は）createItemWithDefinition、または（既存のモデルの場合は）updateDefinition を使用します。semantic-model-rest-api.md を読み込んでください。
   • 理由：TMDL ファイルを Fabric API 経由で直接デプロイするほうが信頼性が高く、速いうえ、モデルを MCP に読み込んでから再びプッシュする無駄を避けられます。
   • MCP で先に PBIP を開いてから MCP 経由でデプロイしないでください。 これは、このワークフローにおける明確なアンチパターンです。
2. PBIP／TMDL ファイルを使わずに、モデルがすでにライブ MCP セッションに読み込まれていますか（例：メモリ上で構築したばかり、または現在 MCP 経由で編集中）？ -> MCP ツールを使い、対象のワークスペースとセマンティックモデル名を指定してデプロイします。
3. PBIP として保存されていないモデルが Power BI Desktop でライブ状態ですか？ -> MCP が Desktop に接続されている場合は、MCP Deploy を使用します。MCP を利用できない場合は、まず PBIP として保存するようユーザーに案内してから、このワークフローを手順 1 から再開します。

ワークスペースのアイテムを種類 SemanticModel で一覧表示し、デプロイが成功したことを確認します。

デプロイは必ず 1 回だけ実行してください。デプロイは冪等ではありません。 デプロイを再試行すると、同じ名前のモデルがもう 1 つ作成され、その後デプロイは There are multiple datasets named '<name>' というエラーで失敗します。このエラーが発生した場合は、むやみに再試行しないでください。ワークスペースのセマンティックモデルを一覧表示し、同じ名前の重複項目をすべて削除してから、クリーンな状態から 1 回だけデプロイしてください。既存の可能性があるモデルをデプロイする場合は、1 回だけデプロイする前に、同じ名前の既存モデルを削除してください。

---

ワークフロー：セマンティックモデルの更新

適用される場合： ユーザーがセマンティックモデル内のデータ更新を依頼した場合です。

更新できるのは、Desktop または Fabric Service のライブモデルを使用している場合に限られます。ローカルの TMDL ファイルを使用している場合は、まずモデルをデプロイしてください。

ツール選択の優先順位に従って更新を開始します。

• Power BI Desktop：Tier 1（MCP）のみ — MCP Refresh 操作を使用します。
• Fabric Service：Tier 1（MCP Refresh 操作）を使用するか、Power BI Enhanced Refresh API にフォールバックします（semantic-model-rest-api.md を読み込んでください）。

認証情報エラーで更新に失敗した場合は、直ちに中止し、Power BI Service でデータソース接続を手動で設定するようユーザーに案内してください。認証情報エラーに対し、プログラムで再試行したり回避したりしないでください。

---

ワークフロー：Fabric でのセマンティックモデルの管理

適用される場合： ユーザーが Fabric Service のセマンティックモデルについて、データソースの構成、パラメーターの更新、またはアクセス許可の管理を依頼した場合です。

厳守事項 — このワークフローは、既定の ツール選択の優先順位 よりも優先されます。 既定で MCP（Tier 1）を使用せず、az rest と REST API の使用を優先してください。

データソースとパラメーター

Power BI REST API 経由でデータソースとパラメーターを取得／更新します。semantic-model-rest-api.md を読み込んでください。

アクセス許可

Power BI REST API 経由でデータセットのユーザー権限を一覧表示／付与／更新します。semantic-model-rest-api.md を読み込んでください。

接続のバインド

connection-binding.md を読み込み、その手順に従ってください。このリファレンスでは、前提条件、bindConnection エンドポイント、検出 → 照合 → バインド → 検証の手順、すべての connectivityType の値、バインド解除のパターン、トラブルシューティングについて説明しています。

主なルール（詳細はリファレンスを参照してください）：

• Fabric の Bind Semantic Model Connection REST API を使用してください（従来の Power BI BindToGateway に代わる API です）。
• データソース参照ごとにバインドリクエストを 1 件送信してください。この API は一括バインドをサポートしていません。
• List Item Connections でモデルのデータソース参照を検出し、connectionDetails を List Connections の内容と照合して、対象の id を見つけてください。一致するものがない場合は、先に接続を作成してください。
• アイテムの接続を再度一覧表示し、更新を実行して検証してください。

---

検証チェックリスト

モデルの作成または変更後に実行してください。

常に実行（PBIP、Desktop、Fabric Service で利用できます）：

1. PBIP の構造を確認する - モデルのソースが PBIP フォルダーの場合は、フォルダー構造とファイルが正しいことを確認してください（pbip.md を参照）。
2. モデリングガイドラインに照らして確認する - 変更内容をすべて modeling-guidelines.md（Direct Lake モデルでは direct-lake-guidelines.md も参照）に照らして再確認してください。

Analysis Services データベースに接続している場合のみ（Power BI Desktop または Fabric Service）：

3. 新しいメジャーをテストする - 新しいメジャーごとに、簡単な DAX クエリを実行して期待どおりの結果が返ることを検証してください（例：EVALUATE { [Measure Name] }）。ローカルの TMDL/PBIP ファイルのみを扱う場合は、この手順を省略してください。
4. テーブルの更新をテストする - 新しいテーブルを作成した場合は、更新を実行して、パーティション、データソース式、列のマッピングが正しいことを確認してください。更新に失敗する場合、通常は sourceColumn 名の不一致、無効な M 式、または Direct Lake エンティティ参照の誤りが原因です。ローカルの TMDL/PBIP ファイルのみを扱う場合は、この手順を省略してください。

いずれかのチェックに失敗した場合は、問題を修正して検証を再実行してください。

---

必須／推奨／回避

必須

• 作業を始める前にデータソースのスキーマを把握する - モデルの設計や変更の前に、ソースのテーブル、列、データ型を分析してください。
• モデリングガイドラインに従う - モデルを作成または編集する前に modeling-guidelines.md を読み込み、スター スキーマ設計、命名規則、列とメジャーのルールを適用してください。
• ツール選択の優先順位に従う - 現在の環境で利用可能な最も優先度の高いツール階層を必ず選択してください。より優先度の高い選択肢が利用できる場合は、階層を混在させないでください。

推奨

• スノーフレーク スキーマやフラット テーブルよりスター スキーマを優先する - 単一列のリレーションシップキーを持つ非正規化ディメンションを使用してください。
• 既存のモデルパターンとの一貫性を保つ - 既存のモデルを編集する場合、新しい規則を持ち込むのではなく、そのモデルの命名規則と構造に合わせてください。
• TMSL より TMDL 形式を優先する - テキストベースで差分を確認しやすく、Fabric で推奨されます。
• 変更後に検証する - ワークフロー：セマンティックモデルのメタデータを検出するを使用して、オブジェクトが反映されたことを確認してください。

回避

• ワークスペース／アイテム ID のハードコード - API を使って動的に解決してください。
• MCP 接続中に TMDL ファイルを読み取る - Tier 1 MCP セッションが有効な状態で *.tmdl に対して view／glob を実行するのはアンチパターンです（ツール選択の優先順位を参照）。
• MCP が登録されている状態で TMDL ファイルを手作業で作成する - model.tmdl、database.tmdl、relationships.tmdl、tables/*.tmdl のひな形を作成するために create／edit／ファイル書き込みツールを使用するのは、新規モデルの場合も含め、Tier 1 のアンチパターンです。MCP ツールを使って構築し、エクスポートしてください。

禁止

• RLS／OLS ロールのメンバーシップを管理する - セキュリティロールへのユーザーまたはグループの追加・削除を目的とする REST 呼び出し、az rest URL、MCP 操作、TMDL 変更を提案しないでください。この依頼は対象範囲外として断り、Power BI ポータルを案内してください。

例

対象範囲に関する注記 — 例では、ID の解決と Fabric メタデータの検出に az rest を使用しています（COMMON-CLI.md § ワークスペースとアイテムの検索を参照）。セマンティックモデル定義の作成は、ツール選択の優先順位に従って行います。利用可能な場合は Tier 1 の MCP powerbi-modeling-mcp を使用し、それ以外の場合は Tier 2 として getDefinition / updateDefinition を介して TMDL を編集します。

例 1：既存のセマンティックモデルを変更する

プロンプト：「ワークスペース Marketing のセマンティックモデル Sales にある、集計可能なすべての列の基本メジャーを作成してください。」

エージェントの応答 - ワークフロー：既存のモデルを変更するに従います。

1. az rest でID を検出します。
2. セマンティックモデルへの接続とツール選択の優先順位に従って、モデルに接続します。powerbi-modeling-mcp が登録されている場合は、MCP を Fabric ワークスペースのモデルに直接接続します（Tier 1）。それ以外の場合は、Tier 2（getDefinition → TMDL をローカルで編集）にフォールバックします。
3. 調査と計画 - 使用中のツール階層を介してテーブルと列を一覧表示し、集計可能な列（数値型、外部キーではない、非表示の代理 ID ではない）を特定します。modeling-guidelines.mdとnaming-conventions.mdに従って、列ごとにSUM / AVERAGE / MIN / MAXのいずれを使用するかを決定します。DAX を記述する前に、dax-guidelines.mdを読み込みます。
4. ワークフロー：既存のモデルを変更するに従って、メジャーを追加します。
   • Tier 1（MCP）：各新規メジャーについて、expression、formatString、対象テーブルを指定して、ツールの作成操作を呼び出します。TMDL を手動で作成しないでください。
   • Tier 2（MCP なし）：テーブルの.tmdlファイルを直接編集し、updateDefinition REST API を介して往復処理します。
5. セマンティックモデルの変更を保存するに従って、保存して検証します。

---

例 2：Fabric Lakehouse から新しいセマンティックモデルを作成する

プロンプト：「同じワークスペースのデータソースとしてSalesLakehouseを使用し、ワークスペース Marketing に新しい Power BI セマンティックモデルを作成してください。」

エージェントの応答 - ワークフロー：新しいセマンティックモデルを作成するに従います。

1. az rest でワークスペースと Lakehouse の ID を検出します。
2. Lakehouse のスキーマを検出します - Lakehouse OneLake API または Lakehouse の SQL エンドポイントを介してテーブルと列を一覧表示します。テーブル名、列名、データ型を記録します。これらがセマンティックモデルのテーブル、列の定義、パーティションのメタデータに反映されます。
3. ツール選択の優先順位に従ってツール階層を選択します。モデル全体の構築には Tier 1（powerbi-modeling-mcp）を優先します。MCP が登録されていない場合に限り、Tier 2（PBIP/TMDL の雛形を作成してからデプロイ）を使用します。
4. ワークフロー：新しいセマンティックモデルを作成するに従ってモデルを構築します - データソースは OneLake であるため、ストレージモードはDirect Lakeです（direct-lake-guidelines.mdとmodeling-guidelines.mdを読み込みます）。Lakehouse のテーブルからスター スキーマを設計し、次に以下を行います。
   • 空のデータベースを作成します。
   • Lakehouse 接続用の名前付き式を 1 つ作成します。
   • 各テーブルについて、EntityPartitionSource（モードdirectLake）を追加し、列を Lakehouse の列にマッピングしてから、リレーションシップとメジャーを追加します。
5. ワークフロー：Fabric にデプロイするに従ってデプロイします。
6. 検証チェックリストに従って検証します - モデルがワークスペースに表示されることを確認し、初回の更新を実行して Direct Lake の列マッピングが正しく解決されることを検証します。

---

例 3：セマンティックモデルを Fabric 接続にバインドする

プロンプト：「ワークスペース Marketing のセマンティックモデル Sales を sql-prod 接続にバインドしてください。」

エージェントの応答 - ワークフロー：Fabric でセマンティックモデルを管理 § 接続のバインド に従います。MCP は使用しません - このワークフローは ツール選択の優先順位 を上書きし、REST のみを使用します。

1. az rest を使用して、ワークスペースとモデルの ID を特定します。

2. サーバー名を照合して、Fabric で対象の接続を特定します。

   SERVER="sql-prod"
   CONN_ID=$(az rest --method get --resource "https://api.fabric.microsoft.com" \
     --url "https://api.fabric.microsoft.com/v1/connections" \
     --query "value[?connectionDetails.path | contains(@, '$SERVER')] | [0].id" -o tsv)
   

   一致する接続がない場合は、停止し、connection-binding.md に従って、まず接続を作成するようユーザーに案内します。

3. ワークフロー：Fabric でセマンティックモデルを管理 § 接続のバインド に従ってバインドを実行します。connection-binding.md を読み込み、特定 -> 照合 -> バインド -> 検証の流れに従います。

   • モデルのデータソース参照を一覧表示します（List Item Connections）。
   • connectionDetails が $CONN_ID と一致する各参照について、Fabric の bindConnection エンドポイントを呼び出します（データソース参照ごとに 1 リクエスト。まとめてバインドすることはできません）。

4. 検証 - 項目の接続を再度一覧表示してバインドを確認し、ワークフロー：セマンティックモデルを更新 に従って更新を開始するようユーザーに促します。資格情報のエラーが発生した場合は停止し、Service ポータルを案内します（トラブルシューティングを参照）。

---

トラブルシューティング

症状	対処方法
MCP 接続エラー	TMDL の編集に切り替えます（ツール選択の優先順位を参照）。切り替えについてユーザーに伝えます。
TMDL の検証エラー	エラーの詳細を確認し、構文を修正して再検証します。tmdl-guidelines.md を読み込みます。
403 Forbidden / identity None	ユーザーには Contributor 以上のロールが必要です。直ちに停止してください。再試行しないでください。
401 Unauthorized	--resource のオーディエンスを一度だけ正しく設定します（semantic-model-rest-api.md を参照）。オーディエンスが正しい状態でも解決しない場合は、権限が不足しています。停止してユーザーに伝えてください。再試行を繰り返さないでください。
202 Accepted だが結果がない	LRO を完了するまでポーリングします。
updateDefinition 後にパーツが不足	変更したパーツと変更していないパーツを含む、すべてのパーツを含める必要があります。
更新時の資格情報エラー	Service ポータルで設定するようユーザーに案内します。再試行しないでください。
メジャーの DAX エラー	列名／テーブル名の参照を確認します（大文字と小文字を区別します）。参照先のオブジェクトが存在することを確認します。
デプロイの失敗	ワークスペースの権限、モデルの互換性レベル、Direct Lake の式のソース参照を確認します。
データソースが見つからない	M パラメーターまたは名前付き式が正しく定義されていることを確認します。