fabric-cli

Fabric CLI

Fabric と Power BI サービスをプログラムで管理するための fab の使用ガイド

• uv tool install ms-fabric-cli でインストールします（uv は winget install uv または brew install uv で入手できます）
• Fabric CLI はクラウド環境での作業に使用するもので、ローカルファイルには使用しません。Power BI Pro、PPU、または Fabric で動作します。Fabric CLI の使用に Fabric SKU は必要ありません
• fab を最新の状態に保ちます。インストール済みのバージョンを最新の ms-fabric-cli リリースと照合し、ユーザーが特定のバージョンを固定していない限り、uv tool upgrade ms-fabric-cli でアップグレードします。動作をハードコードするのではなく、fab --help と fab <command> --help でコマンドとフラグを確認してください。CLI の仕様は定期的に変更されます

重要

Fabric CLI の使用中にエラー、ユーザーの設定、または得られた知見に遭遇した場合は、今後の改善のため、必ずユーザーメモリのルール（.claude/rules/fabric-cli.md など）に記録してください。 これは一般的な知見のみを対象とし、アイテム固有またはタスク固有の知見は対象外です。

このスキルを使用する場面

• ユーザーが「Fabric」または「Power BI」と言及した場合に使用します
• Power BI のワークスペース、デプロイ、テナント、公開、ダウンロード、アクセス許可、またはデータについてユーザーから依頼された場合に使用します

重要な一般ルール

• 重要：fab を初めて使用するときは、最新バージョンであることを確認します（ユーザーがバージョンを固定していない限り、uv tool upgrade ms-fabric-cli でアップグレードします）。また、fab auth status を実行します。ユーザーが認証されていない場合は、fab auth login を実行するよう依頼します
• コマンドを初めて使用するときは、必ず fab --help と fab <command> --help を使用して構文を確認します
• fab の使用を開始する前に、スキルの /references/ を検索し、関連するコマンド、例、スクリプト、またはワークフローを説明する参照ファイルを探す必要があります
• 初めて使用する前に、Fabric 管理者アクセス、秘密度ラベルまたは DLP ポリシー、API の制限、Fabric／Power BI API の使用に関する希望があるかどうかをユーザーに確認します。これらの情報をメモリファイルに追加するようユーザーに伝えます
• ワークスペース名またはアイテム名が不明確な場合は、先にユーザーに確認してから、続行する前に fab ls または fab exists で検証します
• ユーザーから明示的な指示がない限り、アイテム、ワークスペース、または定義の削除や移動、プロパティの変更を避けます
• 重要：容量ユニットを消費する操作（アイテムの作成、ノートブックやパイプラインの実行、更新、大規模なクエリ、Copilot、Plan、Ontology、Graph などのプレビューアイテム、スケジュールされた処理など）を行う前に、CU 時間と容量への影響を見積もります。料金が定額またはセッションごとである場合、容量の日次 CU 時間の 4 分の 1 を超える場合、繰り返し実行される場合、見積もりができない場合、または容量がすでにスロットリングされている場合は、ユーザーから明示的な承認を得てください。ユーザーが機能名を指定したことは、その費用への同意を意味しません。容量コスト と capacity-cost.md を参照してください
• コマンドがアクセス許可によってブロックされ、そのコマンドを実行しようとした場合は、そこで停止してユーザーに確認を求めます。決して制限を回避しようとしてはいけません
• エクスポートの前に出力ディレクトリを作成します。fab export は中間ディレクトリを作成しないため、先に mkdir -p で出力パスを作成しないと、コマンドは [InvalidPath] で失敗します

容量コスト：実行前に見積もる

バーストによりコストが見えにくくなります。操作はすぐに完了しますが、CU はその後 5～64 分間（対話型）または 24 時間（バックグラウンド）にわたって平準化されます。小規模な F SKU では、1 回の操作で 1 日分を超える容量を使うことがあり、その繰り越し分をアイドル容量で返済するまで、すべてのワークスペースがスロットリングされます。F2 では数週間かかることがあります。

• まず容量を確認します。SKU と状態は fab ls .capacities -l で、使用率、スロットリング、繰り越し分は Monitoring ハブの容量ページで確認します。繰り越し分があれば、余力はありません。
• 操作に必要な CU 時間と EUR、および SKU の 1 日あたりの予算に占める割合を見積もります（F は 1 日あたり 24 * n CU 時間、F2 は 48 CU 時間です）。
• 定額料金を把握します。Plan（プレビュー）では、ユーザーごとに 30 日間のセッション料金が発生します（Planner は 847、Stakeholder は 168、Viewer は 37 CU 時間）。REST によるプランの作成と編集は Stakeholder セッション（168 CU 時間）として課金され、セッションを終了したり返金を受けたりすることはできません。
• 一時停止（fab stop）すると、繰り越し分全額が一度に課金され、スロットリングが解除されます。スケールアップすると、総コストはほぼ同じまま、繰り越し分をより速く解消できます。
• しきい値、計算式、既知の料金、および操作のコストを確認する方法については、capacity-cost.md を参照してください。

対話なしで使用する場合は -f（強制）を指定する

fab CLI では確認が求められるため、機密ラベルが有効になっている場合を除き、必ず -f を追加して確認を防止する必要があります。機密ラベルが有効な場合は、ユーザーに確認してください。次のコマンドで実行します。

• fab get -q "definition"：機密ラベルの確認
• fab export：機密ラベルの確認
• fab import：上書きの確認
• fab cp / fab cp -r：上書きと機密ラベルの確認
• fab rm：削除の確認
• fab assign / fab unassign：容量／ドメインの割り当て確認
• fab mv：名前の変更／移動の確認

クイックスタートガイド

基本的な例を含む共通の操作一覧を読み、理解する必要があります。 0. コマンド、構文、認証状態を確認します：fab --help と fab auth status

1. ユーザーがワークスペース名とアイテム名を指定した場合は、アイテムが存在するか確認します：fab exists "spaceparts-dev.Workspace/spaceparts-otc-full.SemanticModel"
2. ユーザーがアクセスできるすべてのワークスペースから、名前でアイテムを検索します：fab find 'sales' -P type=Report -l（名前、説明、ワークスペースを部分一致で検索します。-P type= で絞り込み、-l で ID を表示します。-q '<jmespath>' でクライアント側のフィルタリング／プロジェクションを行います）。最終訪問日時／最終更新日時／所有者／ストレージモード／容量 SKU が必要なガバナンスワークフローでは、scripts/search_across_workspaces.py を使用してください。差分については、workspaces.md を参照してください。
3. ワークスペースを検索します：fab ls
4. アイテムを検索します：fab ls "Workspace Name.Workspace"
5. そのアイテムで使用できるコマンドを確認します：
   • fab desc で itemTypes を取得します
   • コマンドを確認するには fab desc .<ItemType> を実行します。例：fab desc .SemanticModel
6. そのアイテムには何が含まれているか、何のためのものか、何なのかを確認します：
   • TMDL の定義全体：fab get "spaceparts-dev.Workspace/spaceparts-otc-full.SemanticModel" -q "definition" -f
   • 特定のメジャー／テーブル／列を検索：fab get "ws.Workspace/Model.SemanticModel" -q "definition" -f | rga -i "Sales Amount"
   • AI の指示／AI スキーマを取得：python3 scripts/get_semantic_model_ai_metadata.py "ws.Workspace/Model.SemanticModel" --instructions-out instructions.md --schema-out schema.json
7. ファイル、テーブル、またはテーブルスキーマを取得します：
   • レイクハウスのファイルを一覧表示：fab ls "ws.Workspace/LH.Lakehouse/Files"
   • レイクハウスのテーブルを一覧表示：fab ls "ws.Workspace/LH.Lakehouse/Tables"
   • テーブルスキーマ：fab table schema "ws.Workspace/LH.Lakehouse/Tables/gold/orders"
8. データをクエリします（ID、ホスト、認証を解決してくれるため、生の fab api／duckdb／sqlcmd よりも、常にラッパースクリプトを優先してください）：
   • セマンティックモデル（DAX）：python3 scripts/execute_dax.py "ws.Workspace/Model.SemanticModel" -q "EVALUATE TOPN(10, 'Orders')"
   • レイクハウス SQL エンドポイント、ウェアハウス、または SQL データベース（T-SQL）：python3 scripts/query_sql_endpoint.py "ws.Workspace/LH.Lakehouse" -q "SELECT TOP 10 * FROM dbo.orders"。fabric-sql MCP は、ユーザーが登録している場合にのみ存在します。querying-data.md を参照してください
   • OneLake 上のレイクハウスまたはウェアハウスの Delta（DuckDB）：python3 scripts/query_lakehouse_duckdb.py "ws.Workspace/LH.Lakehouse" -q "SELECT * FROM tbl LIMIT 10" -t gold.orders
9. アイテムまたはワークスペースのプロパティを設定します：fab set "ws.Workspace/Item.Notebook" -q displayName -i "New Name" または fab set "ws.Workspace" -q description -i "Production environment"
10. 権限を確認または管理します：
    • アイテム ACL：fab acl ls "ws.Workspace/Model.SemanticModel" を実行し、続けて fab acl set "ws.Workspace/Model.SemanticModel" -I [email protected] -R Read を実行します
    • ワークスペースのロール：fab acl ls "ws.Workspace" を実行し、続けて fab acl set "ws.Workspace" -I [email protected] -R Member を実行します
    • 人間の ID の代わりに、自動化用のサービスプリンシパルを設定する方法：service-principals.md — az CLI による作成、ワークスペースロールとテナント設定グループの両方が必要なこと、およびその ID で fab を認証する方法
11. アイテムを Fabric にデプロイします：fab import "ws.Workspace/New.Notebook" -i ./local-path/Nb.Notebook -f
12. Fabric からアイテムをダウンロードします：fab export "ws.Workspace/Nb.Notebook" -o ./backup -f（必ず最初に mkdir -p ./backup を実行してください）
13. ワークスペース間でアイテムをコピーまたは移動します：fab cp "dev.Workspace/Item.Notebook" "prod.Workspace" -f または fab mv "ws.Workspace/Old.Notebook" "ws.Workspace/New.Notebook" -f
14. ブラウザーから Fabric のアイテムを開きます：fab open "spaceparts-dev.SpaceParts/Amazing Report.Report"
15. Fabric または Power BI の API を使用します：fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes" -X post -i '{"type":"Full"}' または fab api "workspaces/<ws-id>/items"
16. Fabric CLI では不十分な場合に、Azure CLI を使用します（上級者向け）：
    • SQL に対応する任意のアイテムで T-SQL を実行する場合は、scripts/query_sql_endpoint.py を使用してください（ActiveDirectoryAzCli を介して az login を再利用します。querying-data.md に詳しい手順があります）
    • Key Vault のシークレットを一度も読み取ったり、エコーしたり、保存したりせずに利用先へ渡す場合：az login --service-principal -u <appId> -t <tenantId> --password "$(az keyvault secret show --vault-name <vault> --name <secret> --query value -o tsv)"。コマンド置換により、シークレットは子プロセスの引数リストへ直接渡され、標準出力、ファイル、名前付きシェル変数には一切書き込まれません
    • fab と az の完全な判断マトリックス：fab-vs-az-cli.md

重要な概念

Power BI または Fabric に関連する概念については、microsoft-learn MCP サーバー（代替手段として pbi-search CLI）を使用して検索または取得し、AskUserQuestion ツールでユーザーに質問してください。推測したり、思い込みで判断したりしてはいけません。

ワークスペース

• ワークスペースは、ノートブック（およびその他の ETL アイテム）、レイクハウス（およびその他のデータアイテム）、SemanticModel、レポート（およびその他の利用アイテム）、OrgApps などのアイテムを格納するコンテナーです。
• ワークスペースは、次のものに割り当てることができます。
  • ライフサイクル管理のためのデプロイ パイプライン（Dev、Test、Prod など）
  • ガバナンスとテナント構造のためのドメイン
  • ライセンスとリソースのための容量（Fabric または Premium の容量のみ。PPU と Pro は異なる仕組みです）
  • Git 統合によるソース管理のための Git リポジトリ

主なパターン

Fabric CLI を使用する際は、以下の各領域に特に注意してください。

パス形式

Fabric では、型の拡張子を使用したファイルシステム風のパスを使います。

"WorkspaceName.Workspace/ItemName.ItemType"

スペースや句読点を含むパスは、引用符で囲む必要があります。

"Workspace Name.Workspace/Semantic Model Name.SemanticModel"

レイクハウスの場合、パスはファイルやテーブルまで拡張されます。

WorkspaceName.Workspace/LakehouseName.Lakehouse/Files/FileName.extension または /WorkspaceName.Workspace/LakehouseName.Lakehouse/Tables/TableName

Fabric の容量には fab ls .capacities を使用する必要があります。

例：

• "Production Workspace.Workspace/Sales Report.Report"
• Data.Workspace/MainLH.Lakehouse/Files/data.csv
• Data.Workspace/MainLH.Lakehouse/Tables/dbo/customers

一般的なアイテムの種類

• .Workspace - ワークスペース
• .SemanticModel - Power BI データセット
• .Report - Power BI レポート
• .Notebook - Fabric ノートブック
• .DataPipeline - データ パイプライン
• .Lakehouse / .Warehouse/ .SQLDatabase - データ アーティファクト
• .SparkJobDefinition - Spark ジョブ
• .AISkill - Fabric Data Agents
• .MirroredDatabase / .MirroredWarehouse - ミラー化されたデータベース
• .Environment - Spark 環境
• .UserDataFunction - ユーザー データ関数

完全な一覧：上記に記載されていないアイテムの種類についてユーザーから質問された場合は、fab desc または fab desc .<ItemType> を使用して構文と種類を確認してください。

JMESPath クエリ

-q で JSON 応答をフィルター処理および変換します。

# Get single field
-q "id"
-q "displayName"

# Get nested field
-q "properties.sqlEndpointProperties"
-q "definition.parts[0]"

# Filter arrays
-q "value[?type=='Lakehouse']"
-q "value[?contains(name, 'prod')]"

# Get first element
-q "value[0]"
-q "definition.parts[?path=='model.tmdl'] | [0]"

fab api の使用

fab には API 用のエスケープハッチがあり、主要なコマンドが用意されていない API も使用できます。

変数の抽出パターン

fab api を使用するには、アイテム ID が必要です。次のように抽出します。

WS_ID=$(fab get "ws.Workspace" -q "id" | tr -d '"')
MODEL_ID=$(fab get "ws.Workspace/Model.SemanticModel" -q "id" | tr -d '"')

# Then use in API calls
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{"type":"Full"}'

管理者 API（管理者ロールが必要）

ユーザーが管理者アクセス権を持っていない場合は、管理者コマンドや API を使用しないでください。以下に例を示します。

# Find semantic models by name (cross-workspace)
fab api "admin/items" -P "type=SemanticModel" -q "itemEntities[?contains(name, 'Sales')]"

# Find all notebooks
fab api "admin/items" -P "type=Notebook" -q "itemEntities[].{name:name,workspace:workspaceId}"

# Find all lakehouses
fab api "admin/items" -P "type=Lakehouse"

# Common types: SemanticModel, Report, Notebook, Lakehouse, Warehouse, DataPipeline, Ontology

管理者 API の完全なリファレンス（ワークスペースをまたぐ検出、テナント設定の読み取り／更新、容量／ドメイン／ワークスペースのオーバーライド、アクティビティ イベント）については、admin.md を参照してください。

エラー処理とデバッグ

# Show response headers
fab api workspaces --show_headers

# Verbose output
fab get "Production.Workspace/Item" -v

# Save responses for debugging
fab api workspaces -o /tmp/workspaces.json

一般的なワークフロー

Fabric でよく使われるワークフローは次のとおりです。

ワークスペース、アイテム、メタデータの検索または確認

コマンド	目的	例
fab ls	ワークスペース／アイテムを一覧表示します	fab ls "Sales.Workspace" -l
fab exists	パスが存在するか確認します	fab exists "Sales.Workspace/Model.SemanticModel"
fab get	アイテムの詳細を取得します	fab get "Sales.Workspace" -q "id"
fab desc	種類ごとに対応するコマンドを確認します	fab desc .SemanticModel

フラグ：

• -l（詳細な一覧表示）
• -a（隠しアイテムを表示）
• -q（JMESPath フィルター）
• -v（詳細な出力）
• -o（レスポンスをファイルに保存）

Fabric の探索は、段階的に詳細を絞り込むパターンに従います。

• 閲覧：
  • ワークスペースを一覧表示します：fab ls
  • ワークスペース内のアイテムを一覧表示します：fab ls "ws.Workspace" -l
  • パスが存在することを確認します：fab exists "ws.Workspace/Item"
  • アイテムの種類で対応しているコマンドを確認します：fab desc .<ItemType>
• 調査：
  • アイテムの詳細を取得します：fab get "ws.Workspace/Item"
  • 単一のフィールドを取得します：fab get "ws.Workspace" -q "id"
• ワークスペース横断検索：
  • 名前、説明、ワークスペースを対象に通常の検索を行います：fab find '<text>' -P type=<Type> -l
  • fab find に含まれないガバナンスフィールド（最終アクセス、最終更新、所有者、ストレージモード、容量 SKU、Copilot 対応状況）：scripts/search_across_workspaces.py。差分についてはworkspaces.mdを参照してください。
  • 指定したモデルの下流レポート：scripts/get-downstream-reports.py
  • テナント全体の管理 API：admin.md

探索を始める前に、以下のリファレンスを確認してください。

• workspaces.md
• folders.md
• admin.md
• reference.md

データのクエリ

コマンド	目的	例
fab get -q "definition"	モデルのスキーマを取得	fab get "ws.Workspace/Model.SemanticModel" -q "definition" -f
fab api -A powerbi	DAX を実行	fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/executeQueries" -X post -i '{"queries":[{"query":"EVALUATE..."}]}'
fab ls	ファイル／テーブルを参照	fab ls "ws.Workspace/LH.Lakehouse/Files"
fab table schema	Lakehouse テーブルのスキーマ	fab table schema "ws.Workspace/LH.Lakehouse/Tables/sales"
fab cp	OneLake ファイルをアップロード／ダウンロード	fab cp ./local.csv "ws.Workspace/LH.Lakehouse/Files/"
duckdb + delta_scan	Delta テーブルをクエリ（DuckDB が必要）	duckdb -c "... delta_scan('abfss://<ws-id>@onelake.../<lh-id>/Tables/schema/table')"
duckdb + read_csv/json	生ファイルをクエリ（DuckDB が必要）	duckdb -c "... read_csv('abfss://.../Files/data.csv')"

フラグ：

• -A fabric|powerbi|storage|azure（API のオーディエンス）
• -X get|post|put|delete|patch（HTTP メソッド）
• -i（JSON 本文またはファイル）
• -f（定義の取得時に機密性の確認プロンプトをスキップ）。

Fabric では、データソースに応じて 3 つのクエリ方法が用意されています。ID、ホスト、認証を自動で解決するラッパースクリプトを常に優先してください。

• セマンティックモデル（DAX）：
  • まずモデルのフィールドを確認します：fab get "ws.Workspace/Model.SemanticModel" -q "definition"
  • クエリを実行します：scripts/execute_dax.py
• OneLake 経由の Delta を使った Lakehouse／Warehouse（DuckDB）：
  • 単一のテーブルをクエリします：scripts/query_lakehouse_duckdb.py（tbl をプレースホルダーとして使い、-t schema.table を渡します）
  • 複数テーブルの結合や Files/ 内の生ファイルをクエリする場合は、独自の delta_scan()／read_csv／read_json_auto 呼び出しを指定して --sql を渡します
  • 代わりに Direct Lake モデルを作成することもできます：scripts/create_direct_lake_model.py
• Lakehouse SQL エンドポイント、Warehouse、または SQL Database（T-SQL）：
  • scripts/query_sql_endpoint.py を使います（sqlcmd。アイテムの種類に応じてホストを自動検出し、ActiveDirectoryAzCli を使って az login の認証を再利用します）
  • このプラグインには fabric-sql MCP が含まれていません。ユーザー自身が登録した場合に限り使用してください
  • INFORMATION_SCHEMA、sys.* のメタデータ、CTE、またはウィンドウ関数が必要な場合は、DuckDB よりもこちらを優先してください
  • クエリ経路の優先順位の詳細：querying-data.md

クエリを作成する前に、以下のリファレンスを確認してください。

• querying-data.md
• semantic-models.md
• lakehouses.md
• warehouses.md
• sql-databases.md

メタデータまたはアクセス権の変更（説明、タグ、推奨、プロパティ、バインド、権限）

コマンド	目的	例
fab set	プロパティを更新	fab set "ws.Workspace/Item" -q displayName -i "New Name"
fab mv	アイテムの名前を変更／移動	fab mv "ws/Old.Notebook" "ws/New.Notebook" -f
fab acl ls	権限を一覧表示	fab acl ls "ws.Workspace"
fab acl set	権限を付与	fab acl set "ws.Workspace" -I <objectId> -R Member
fab acl rm	権限を取り消し	fab acl rm "ws.Workspace" -I <upn>
fab label set	機密ラベルを設定	fab label set "ws/Nb.Notebook" --name Confidential

フラグ：

• -q <field> + -i <value>（単一のプロパティを設定）
• -I（fab acl のオブジェクト ID または UPN）
• -R Admin|Member|Contributor|Viewer（fab acl set のロール）
• -f（確認をスキップします。機密ラベルが関係する場合は、先にユーザーに確認してください）

メタデータとアクセス権の変更は、いくつかのグループに分けられます。

• プロパティ（displayName、説明、機密設定）：
  • ネイティブの更新：fab set "<path>" -q <field> -i "<value>"
  • 元に戻せるよう、まず現在の状態を保存します：fab get -v -o /tmp/before.json
• 推奨、認定、タグ（専用の fab コマンドはありません）：
  • アイテム固有のエンドポイントを使って fab api 経由でパッチを適用します
  • タグのワークフロー：tags.md
  • 推奨のパターン：reference.md
• フォルダーの配置：
  • ワークスペースのサブフォルダー間でアイテムを移動します：folders.md
• アクセス制御と機密ラベル：
  • 付与／取り消し：fab acl set、fab acl rm
  • 機密ラベルを設定：fab label set
  • まずプリンシパルを確認します：az ad user show
  • ユーザーの明示的な確認なしに、権限やラベルを変更してはいけません
• バインド：
  • 薄い .Report を別の .SemanticModel に再バインドします：reports.md
  • セマンティックモデルのソース再バインド（例：レイクハウスの切り替え）：semantic-models.md

メタデータを変更する前に、以下のリファレンスを確認してください。

• reference.md
• tags.md
• folders.md
• reports.md
• semantic-models.md

ワークスペースの操作

コマンド	目的	例
fab mkdir	ワークスペース／アイテムを作成する	fab mkdir "New.Workspace" -P capacityname=MyCapacity
fab assign	キャパシティ／ドメインを割り当てる	fab assign .capacities/cap.Capacity -W ws.Workspace -f
fab unassign	キャパシティ／ドメインの割り当てを解除する	fab unassign .capacities/cap.Capacity -W ws.Workspace
fab start / fab stop	キャパシティを再開／一時停止する	fab start .capacities/cap.Capacity
fab cp -r	ワークスペースを複製する	fab cp "dev.Workspace" "prod.Workspace" -r -f
fab rm	論理削除する（復元を参照）	fab rm "ws/Item.Type" -f

フラグ：

• -P key=value（fab mkdir の作成パラメーター）
• -W（fab assign／fab unassign の対象ワークスペース）
• -r（再帰的にコピー／移動する）
• -bpc（fab cp でパスの衝突時に処理をブロックする）
• -f（確認を省略する）

ワークスペーススコープの操作はいくつかのグループに分けられます。

• 作成とプロビジョニング：
  • ワークスペースを作成する：fab mkdir "<Name>.Workspace" -P capacityname=<cap>
  • キャパシティまたはドメインを割り当てる：fab assign .capacities/<cap>.Capacity -W <ws>.Workspace
  • プランニングコンテキスト、サーフェスの作成／取得／設定、大容量ストレージ形式、Spark プール、OneLake のデフォルト設定、Git：workspaces.md
• コピー、複製、ダウンロード：
  • テナント内でワークスペースを複製する：fab cp -r "dev.Workspace" "prod.Workspace"
  • まずソースツリーをドライランする：fab ls "dev.Workspace"
  • ローカルに完全なスナップショットを作成する（アイテム＋レイクハウスファイル）：scripts/download_workspace.py
• 権限：
  • 確認／付与／取り消し：fab acl ls | set | rm
  • テナント全体のガバナンス監査：fabric-admin プラグインの audit-tenant-settings スキルを使用する
• 接続とゲートウェイ（ワークスペースにバインドされていますが、ワークスペースの外部にあります）：
  • 資格情報の種類（WorkspaceIdentity、SPN、Basic）、OAuth2 の制限：connections.md
  • データソースのバインド、資格情報のローテーション：gateways.md
• ワークスペース内のフォルダー：
  • レイアウト、ネスト、規約：folders.md

ワークスペースを変更する前に、以下のリファレンスを確認してください。

• workspaces.md
• folders.md
• connections.md
• gateways.md

ジョブの実行またはスケジュール設定（ノートブック、ノートブックのセル、パイプライン、セマンティックモデルの更新）

コマンド	目的	例
fab job run	同期的に実行	fab job run "ws/ETL.Notebook" -P date:string=2025-01-01
fab job start	非同期で実行	fab job start "ws/ETL.Notebook"
fab job run-list	実行履歴を一覧表示	fab job run-list "ws/Nb.Notebook"
fab job run-status	ステータスを確認	fab job run-status "ws/Nb.Notebook" --id <job-id>
fab job run-cancel	ジョブをキャンセル	fab job run-cancel "ws/Nb.Notebook" --id <job-id> -w
scripts/run_notebook_checked.py	ノートブックを実行し、終了値を検証（ステータスが Completed でもETLが成功したとは限りません）	python3 scripts/run_notebook_checked.py "ws/ETL.Notebook"
fab api -A powerbi .../refreshes	セマンティックモデルの更新を開始	fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes" -X post -i '{"type":"Full"}'

フラグ：

• -P key:type=value（パラメーター。型は string|int|bool）
• --id（ジョブ実行ID）
• -w（キャンセル時に待機）
• --timeout（同期実行の全体タイムアウト）
• --polling_interval（ステータス確認の間隔）

ジョブは項目の種類によって異なるエンドポイントに対応します：

• ノートブックとパイプライン：
  • 同期的に実行：fab job run "ws/ETL.Notebook" -P date:string=2025-01-01
  • 非同期で実行：fab job start "ws/ETL.Notebook"
  • ステータスを確認：fab job run-status "ws/Nb.Notebook" --id <job-id>
  • 履歴を一覧表示：fab job run-list "ws/Nb.Notebook"
  • 実際の結果を検証：ジョブの Completed は、プロセスが終了したことだけを意味します。ノートブックは例外を独自に捕捉し、Completed と表示されたまま失敗ペイロードを終了値として返すことがあります。終了値を読み取るか、scripts/run_notebook_checked.py を使用してください。詳細は notebooks.md を参照してください。
  • Python／PySpark カーネル、Livy セッション、セル単位のCRUD：notebooks.md
• セマンティックモデルの更新（fab job では公開されていません）：
  • 開始：fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes" -X post -i '{"type":"Full"}'
  • 新たに開始する前に現在の実行を確認（すでに実行中の場合は409）：fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes?\$top=1"
  • 拡張更新、増分ポリシー、パーティションの指定：semantic-models.md
• データフローの更新：
  • Gen1とGen2ではエンドポイントが異なります：dataflows.md
• スケジュール設定：
  • スケジューラーAPIを使用した項目ごとのスケジュール：notebooks.md、reference.md

ジョブを実行する前に、以下のリファレンスを確認してください：

• notebooks.md
• semantic-models.md
• dataflows.md
• reference.md

Fabric 管理者向け操作（監査、管理）

コマンド	目的	例
fab api "admin/items"	ワークスペース横断のアイテム検索	fab api "admin/items" -P "type=SemanticModel" -q "itemEntities[?contains(name,'Sales')]"
fab api "admin/workspaces"	ワークスペースの一覧	fab api "admin/workspaces"
fab api "admin/tenantsettings"	テナント設定	fab api "admin/tenantsettings"
fab api "admin/capacities"	キャパシティの一覧	fab api "admin/capacities"
fab api -X post .../update	テナント設定の更新	fab api -X post "admin/tenantsettings/<name>/update" -i body.json

フラグ：

• -P key=value（クエリパラメーター。例：type=SemanticModel）
• -q（JMESPath フィルター）
• -X post + -i（書き込み操作）
• --show_headers（429 エラー時の Retry-After を確認）

管理者スコープの作業には、Fabric / Power BI の管理者ロールが必要です。まず fab api "admin/capacities" 2>&1 | head -5 でアクセスを確認してください。エラーが発生した場合は、再試行せずに中止してください。

ほとんどの管理者向けタスクには、次の 2 つの入口があります。

• ガバナンス監査（テナント設定、委任されたオーバーライド、Entra SG のスコープ設定）：
  • fabric-admin プラグインの audit-tenant-settings スキルを使用してください。このスキルは、厳選されたメタデータのベースライン、監査および変更検出スクリプト、委任されたオーバーライドの列挙、Entra SG の調査ワークフローを管理します。
  • テナントの状態と、グループメンバーシップ、オーバーライドのスコープ、またはベースラインとの乖離が関わる質問では、必ずこのスキルを呼び出してください。
• 未加工の管理者 API（ワークスペース横断検索、アクティビティイベント、アーティファクトアクセス、アイテム検索）：
  • admin.md のパターン
  • レート制限：書き込みリクエストは毎分 25 件。429 エラー時は Retry-After に従ってください。
  • 破壊的な管理者操作を行う前に、実行する正確なコマンドを表示し、ユーザーの確認を待ってください。

管理者向けの作業を行う前に、次のリファレンスを確認してください。

• admin.md
• ワークスペース／アイテムの ACL 露出監査については、permissions.md

定義とデプロイ（アイテム定義、デプロイパイプライン、Git 統合、CI/CD）

コマンド	目的	例
fab get -q "definition"	生の定義を読み取る	fab get "ws/Model.SemanticModel" -q "definition" -f
fab export	アイテムをローカルにエクスポートする	fab export "ws/Nb.Notebook" -o ./backup -f
fab import	ローカルからアイテムをインポートする	fab import "ws/Nb.Notebook" -i ./backup/Nb.Notebook -f
fab cp	ワークスペース間でコピーする	fab cp "dev/Item" "prod.Workspace" -f
fab api "deploymentPipelines"	デプロイパイプライン API	fab api "deploymentPipelines" -q "value[]"

フラグ：

• -o（fab export の出力パス）
• -i（fab import の入力パスまたは JSON 本文）
• --format（エクスポート／インポートする定義の形式）
• -f（上書き確認と機密性に関する確認をスキップ）

重要

定義を変更する際、パフォーマンスに最も大きく影響するのはポーリング間隔です。 アイテム定義の作成または更新は、長時間実行操作（LRO）です。API は Retry-After: 20 ヘッダーとともに 202 Accepted を返します。fab import、nb create、nb cell edit はステータスをポーリングする間隔が その程度あるため、サーバー側では約 1 秒で完了するノートブックの処理に 25〜60 秒かかります。 fab にも nb にも、この間隔を変更する設定はありません。ノートブック定義を変更する場合は、 LRO を約 0.3 秒ごとにポーリングし（--poll-interval で調整可能）、約 1〜2 秒で作成、または 約 1 秒でインプレース更新する scripts/deploy_notebook.py を強く推奨します。 作成と更新は自動判定されます。他のアイテムの種類で独自の処理を実装する必要がある場合も、同じルールが適用されます。 updateDefinition／作成のポーリングは、示されている 20 秒ではなく、約 0.3 秒間隔にしてください。

python3 scripts/deploy_notebook.py "ws.Workspace/ETL.Notebook" -i ./ETL.Notebook   # インプレースで作成または更新

すべての Fabric アイテムには、シリアル化可能な定義があります。範囲に応じて、環境間で定義を移動してください。

• 単一アイテム：
  • ローカルで往復する：fab export の後に fab import を実行します（必ず事前に出力ディレクトリへ mkdir -p を実行してください。fab export は中間ディレクトリを作成せず、[InvalidPath] で失敗します）
  • 同一テナント内のショートカット。ローカルを経由しません：fab cp "dev/Item" "prod.Workspace"
• PBIP としてのセマンティックモデル（TMDL + 空のレポート）：
  • fab export でモデルをエクスポートし、pbir new report でレポートを作成してから、 pbir report merge-to-thick で結合します。import-download-deploy.md を参照してください
• ワークスペース全体のスナップショット（アイテム + レイクハウスのファイル）：
  • バックアップ、オフライン分析、テナントをまたぐフォークには、scripts/download_workspace.py を使用します
• Dev、Test、Prod 間の昇格：
  • Fabric デプロイパイプライン API（すべてのアイテムの種類に対応）
  • Power BI パイプライン API（Power BI アイテムのみ対応。ただし、allowPurgeData、allowTakeOver など、より細かなデプロイフラグを利用可能）
  • 使い分け、選択的デプロイ、LRO のポーリングについては、deployment-pipelines.md を参照してください
• Git 統合（ワークスペースをリポジトリに接続する、ブランチを作成する、コミットする、Git から更新する）：
  • workspaces.md のワークスペースの Git セクション

デプロイする前に、関連ドキュメントを確認してください。

• import-download-deploy.md ；エクスポート／インポート／コピー／移動、PBIP の往復、移行パターン、再バインド時の注意点
• deployment-pipelines.md
• semantic-models.md
• reports.md
• paginated-reports.md
• notebooks.md
• workspaces.md

関連スキル

• audit-tenant-settings（fabric-admin プラグイン内）；テナント設定、委任されたオーバーライド（容量／ドメイン／ワークスペース）、およびそれらの設定が参照する Entra セキュリティグループを対象とする Fabric ガバナンスのワークフローです。読み取り専用です。厳選されたメタデータのベースラインと、監査および変更検出のスクリプトが含まれています。

注意事項

• 重要： データ項目（.Lakehouse、.Warehouse など）以外の項目に対して fab ls を使おうとしないでください。fab ls はワークスペースと項目の検索に使い、定義を確認するには fab get を使います
• 上記のとおり、fab get、fab import、fab export などを使うときは必ず -f フラグを指定してください
• コマンドが存在しない場合に限り、fab api にフォールバックしてください
• 定義の変更に時間がかかるように見えますが、実際はそうではありません。 fab import／nb create／nb cell edit でノートブック定義の反映に25～60秒かかるのは、サーバーの Retry-After: 20 に従ってLROをポーリングするためだけです。処理自体は約1秒です。定義を変更する場合は、ポーリング間隔を約0.3秒に短縮する scripts/deploy_notebook.py を使ってください。ポーリング間隔は最も効果の大きい調整項目です

参考資料

参考資料マップ（関連する参考資料のまとまりを示しています。この一覧だけでなく、資料間のリンクもたどってください）：

etl / notebooks
  notebooks.md ── run jobs, exit value, scheduling
    ├─ querying-data.md ── nb exec / Livy, DuckDB/sqlcmd, SQL-endpoint sync
    └─ lakehouses.md ── attach, table ops, OneLake shortcuts, SQL-endpoint id
  (cross-plugin) executing-spark, using-duckdb  ── etl plugin: ephemeral Spark, local Delta

data items
  lakehouses.md · warehouses.md · sql-databases.md · semantic-models.md
    └─ all feed querying-data.md (route priority) and notebooks.md (load then read)

governance / deploy
  admin.md · permissions.md · tags.md · folders.md
  import-download-deploy.md ─ deployment-pipelines.md ─ workspaces.md (git status)
  (cross-plugin) audit-tenant-settings ── fabric-admin plugin

スキルの参考資料：

• インポート、ダウンロード、デプロイ - 項目のエクスポート／インポート／コピー／移動、PBIPの往復、開発環境から本番環境への移行パターン
• データのクエリ - DAXでセマンティックモデルをクエリし、DuckDBを使ってSQLでレイクハウスやウェアハウスをクエリする
• レイクハウス - エンドポイント、ファイル／テーブル操作、OneLakeパス
• ウェアハウス - 作成、参照、DuckDB経由のクエリ、データの読み込み
• SQLデータベース - 作成、参照、DuckDB経由のクエリ、自動ミラーリング
• セマンティックモデル - TMDL、DAX、更新、ストレージモード
• レポート - エクスポート、インポート、ビジュアル、フィールド
• ページ分割されたレポート - RDLのアップロード、ファイルへのエクスポート、データソース、パラメーター
• ノートブック - Python／PySparkカーネル、メタデータ、セルのCRUD、Livyの実行、スケジュール設定
• ワークスペース - 作成、管理、アクセス許可
• アクセス許可 - 共有と配布、ワークスペースのロール、項目のアクセス許可、アプリ、埋め込み、B2B、デプロイメントパイプラインのアクセス許可、ライセンスと容量SKU
• デプロイメントパイプライン - CI/CD、ステージのデプロイ、選択的なデプロイ、LROのポーリング
• データフロー - Gen1とGen2、更新、公開、管理
• ダッシュボード - タイル、複製（ダッシュボードはレポートではありません）
• 組織アプリ - 配布されたコンテンツパッケージの読み取り専用API
• スコアカード - 目標、チェックイン、ステータスルール（プレビューAPI）
• ゲートウェイ - データソース、資格情報、データセットのバインド
• フォルダー - API経由で項目をフォルダーに整理。ワークスペースを構成するためのベストプラクティスも含みます
• タグ - fab api を使った項目やワークスペースへのテナント／ドメインタグの作成、適用、監査（ネイティブの fab tag コマンドはありません）
• 容量コスト - 操作の前にCU時間と容量への影響を見積もる：SKUの予算、平滑化、スロットリングの段階、繰り越しと消費、課金の一時停止、既知の定額料金（Plan、Ontology、Copilot）
• fabとaz CLIの比較 - 使い分け、容量、ネットワーク、Key Vault、監視、CMK、CI/CD
• 管理者API - ワークスペース横断検索、テナント操作、ガバナンス
• APIリファレンス - 容量、ドメイン、その他のAPIパターン
• 接続 - 接続のプログラムによる作成、更新、一覧表示。資格情報の種類（WorkspaceIdentity、SPN、Basic）、OAuth2の制限事項
• サービスプリンシパル - az CLIでのSPの作成、ワークスペースへのアクセス権の付与、テナント設定のゲートの解除、サービスプリンシパルとしての fab の認証（実際のログインと環境トークンによるテスト）、ローテーションと削除
• 全コマンドリファレンス - すべてのコマンドの詳細

スクリプト（実行可能なスクリプト）：

• search_across_workspaces.py；fab find を補完する、ワークスペース横断のガバナンス検索（最終訪問、最終更新、所有者、ストレージモード、容量 SKU、Copilot の準備状況）。どちらを選ぶべきかについては、workspaces.md を参照してください。
• get-downstream-reports.py；アクセス可能なワークスペース全体から、指定したセマンティックモデルに接続されているすべてのレポートを検索します（管理者権限は不要です）。
• execute_dax.py；セマンティックモデルに対して DAX クエリを実行します。出力形式は table、csv、json です。
• query_lakehouse_duckdb.py；OneLake に対して DuckDB 経由でレイクハウスまたはウェアハウスの Delta テーブルをクエリします（az login を再利用します）。出力形式は table、csv、json です。
• query_sql_endpoint.py；sqlcmd 経由でレイクハウスの SQL エンドポイント、ウェアハウス、または SQL データベースをクエリします（ActiveDirectoryAzCli 経由で az login を再利用します）。出力形式は table、csv、json です。
• create_direct_lake_model.py；レイクハウスのテーブルから Direct Lake セマンティックモデルを作成します。
• download_workspace.py；すべてのアイテム定義とレイクハウスファイルを含むワークスペース全体をダウンロードします。
• run_notebook_checked.py；ノートブックを実行し、終了値を確認します。ジョブのステータスが Completed でも、ノートブック自身の {ok:false} 判定が失敗した場合は、ゼロ以外の値で終了します（ノートブックのジョブインスタンスのベータエンドポイントから終了値を読み取ります）。
• deploy_notebook.py；CLI の約 20 秒間隔の Retry-After に従う代わりに、LRO を短い間隔でポーリングしてノートブック定義をすばやく（約 1〜2 秒で）作成または更新します。作成か更新かを自動検出します。パフォーマンスを調整するには --poll-interval を使用します。ノートブック定義を変更する場合は、fab import や nb よりもこちらを強く推奨します。
• task_flow.py；Fabric UI が使用する内部メタデータエンドポイント経由で、JSON 仕様（タスク、<displayName>.<Type> 形式のアイテム、エッジ）からワークスペースのタスクフローを作成、更新、エクスポート、または削除します。タスクフロー用のパブリック API や fab コマンドはありません。

詳しい使い方、引数、例については、scripts/README.md を参照してください。新しいヘルパーを作成する前に、必ず scripts/ フォルダーを検索してください。タスクに使えるスクリプトがすでにある場合があります。

外部リファレンス（可能であれば Markdown をリクエストしてください）：

• fab CLI：GitHub ソース | ドキュメント
• Microsoft：Fabric CLI の Learn ドキュメント
• API：Fabric API | Power BI API
• DAX：dax.guide — dax.guide/<function>/ を使用します。例：dax.guide/addcolumns/
• Power Query：powerquery.guide — powerquery.guide/function/<function> を使用します。
• Power Query のベストプラクティス