mcpField
F
fabric-cli-core

fabric-cli-core

github.com/microsoftデータ・データベース178151 回インストール今日更新
リポジトリ

fabric-cli-core について

Fabric CLI（`fab`）を使って Microsoft Fabric を安全かつ一貫して操作するための、AI エージェント向けスキルです。エンティティのパス、認証、機密データの扱いに加え、事前確認、トラブルシューティング、コマンド検証の規則を示します。

主な機能

  1. 01Fabric のパスとエンティティ階層を説明
  2. 02対話モードとコマンドラインモードの選択を案内
  3. 03認証と機密データの取り扱いを規定
  4. 04隠しエンティティの確認方法を記載
  5. 05安全な実行と検証の手順を定義

活用シーン

  1. 01CLI 認証とワークスペース接続の確認
  2. 02ワークスペース内の Fabric アイテムの特定
  3. 03CLI 操作の安全な実行と検証
  4. 04Fabric コマンドエラーのトラブルシューティング

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/microsoft/fabric-cli --skill fabric-cli-core

インストール後、Claude Code で/fabric-cli-coreを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

README.md
references/
create-workspaces.md
fab-api.md
notebooks.md
querying-data.md
quickstart.md
reference.md
reports.md
semantic-models.md
workspaces.md
scripts/
health_check.py

詳細

Fabric CLI Core

このスキルは、AI エージェントが Fabric CLI（fab） を介して Microsoft Fabric を操作する際の、安全で一貫したデフォルト設定を定義します。

1 - Fabric CLI のメンタルモデル（パスとエンティティ）

自動化スクリプト

主要な CLI タスク向けのすぐに使える Python スクリプトです。各スクリプトに --help を付けて実行すると、すべてのオプションを確認できます。

スクリプト目的使用方法
health_check.pyCLI のインストール状況、認証状態、接続状況を確認するpython scripts/health_check.py [--workspace WS]

スクリプトは、このスキルの scripts/ フォルダーにあります。

パスとエンティティ
  • Fabric は、パスに一貫した ドット（.）形式のエンティティ接尾辞（例：.Workspace、.Folder、.SemanticModel）を使う、ファイルシステムのような階層構造として扱います。
  • 階層構造は次のとおりです。
    • テナント：すべてを格納する最上位のコンテナーです。
    • ワークスペース：フォルダー、アイテム、ワークスペースレベルの要素を格納する、個人用またはチーム用のワークスペースです。
    • フォルダー：ワークスペース内のアイテムを整理するためのコンテナーです（約 10 階層のネストに対応します）。
    • アイテム：ワークスペースまたはフォルダー内の個別のリソースです（例：Notebook、SemanticModel、Lakehouse）。
    • OneLakeItem：Lakehouse 内にある OneLake ストレージアイテムです（テーブル、ファイルなど）。
  • 次のようなパスを優先して生成します。
    • /Workspace1.Workspace/Notebook1.Notebook
    • /Workspace1.Workspace/FolderA.Folder/SemanticModel1.SemanticModel
    • /Workspace1.Workspace/FolderA.Folder/lh1.Lakehouse/Tables（OneLakeItem）
  • ユーザーが曖昧な識別子を指定した場合は、完全なパスを尋ねます（または、明示した前提に基づいて推測します）。

2 - モード（対話モードとコマンドラインモード）

  • ユーザーがどちらのモードを使っているかを明確にします。
    • 対話モードは REPL のように動作し、fab プレフィックスなしでコマンドを実行します。
    • コマンドラインモードは呼び出しごとに 1 つのコマンドを実行し、スクリプトや自動化に最適です。
  • 選択したモードはセッション間で保持されます。ユーザーが終了して再度ログインすると、CLI は最後に使用したモードで再開します。
  • 手順を提示する際は、ユーザーが対話モードを使用していると言わない限り、コマンドラインモードのコマンドを示します。

3 - 認証（公開しても安全なガイダンス）

  • 次の認証パターンを優先し、新たなフローを独自に作らないでください。
    1. 対話型ユーザー：fab auth login（対応環境ではブラウザー/WAM を使用します）。
    2. サービスプリンシパル（シークレット／証明書）：環境変数や安全な仕組みを使用し、ファイルへのシークレットの埋め込みは避けます。
    3. サービスプリンシパル（フェデレーション資格情報）：フェデレーショントークン環境変数（FAB_SPN_FEDERATED_TOKEN）を使用し、未加工のトークンを永続化しないでください。
    4. マネージド ID：Azure でホストされるワークロードでサポートされます。資格情報は不要です。
  • ユーザーにシークレットをチャットに貼り付けたり、再度表示したりするよう求めないでください。

4 - 機密データの取り扱い（厳守）

  • トークン、パスワード、クライアントシークレット、未加工のフェデレーショントークンをログに記録したり出力したりしないでください。
  • セキュリティに影響する可能性のあるユーザー入力をすべて検証します。
    • パス：ファイルパスと API パラメーターをサニタイズします。
    • GUID：使用前にリソース識別子を検証します。
    • JSON：JSON 入力の形式が正しいことを検証します。
  • ユーザーが機密文字列を共有した場合は、それらをローテーションまたは再生成し、安全なストレージに移すよう助言します。

5 - 非表示エンティティと検出

  • 非表示エンティティは、通常は表示されない特別なリソースで、ドットで始まる命名規則（UNIX の隠しファイルに類似）に従います。
  • テナントレベルの非表示エンティティ（ルートからアクセス）：
    • .capacities — fab ls .capacities / fab get .capacities/<name>.Capacity
    • .gateways — fab ls .gateways / fab get .gateways/<name>.Gateway
    • .connections — fab ls .connections / fab get .connections/<name>.Connection
    • .domains — fab ls .domains / fab get .domains/<name>.Domain
  • ワークスペースレベルの非表示エンティティ（ワークスペース内からアクセス）：
    • .managedidentities — fab ls ws1.Workspace/.managedidentities
    • .managedprivateendpoints — fab ls ws1.Workspace/.managedprivateendpoints
    • .externaldatashares — fab ls ws1.Workspace/.externaldatashares
    • .sparkpools — fab ls ws1.Workspace/.sparkpools
  • 非表示リソースを表示するには、ls -a / ls --all を推奨します。

6 - エラーとトラブルシューティングのガイダンス

  • 失敗について説明するときは、次の内容を含めてください。
    • コマンドが実行しようとしていた内容
    • 考えられる原因
    • 次に実行できる具体的な手順
  • CLI にエラーコード／メッセージが表示された場合は、そのまま保持し、重要な識別子を言い換えて失わないようにしてください。（Fabric CLI では、安定したエラーコード／メッセージが重視されます。）
  • API エラーのデバッグに役立つよう、取得できる場合はリクエスト ID を含めてください。

7 - エージェントの出力規約

  • 簡潔で実行可能な手順を基本とします。
  • コマンドを推奨するときは、次の内容を含めてください。
    • 前提条件（認証、正しいワークスペース／パス）
    • 期待される結果
    • 確認方法（例：後続の fab ls / fab get）

8 - 安全性のデフォルト設定

  • 削除、上書き、またはアクセス権／権限の変更を行うコマンドを提案する前に、確認してください。
  • ユーザーが明示的に承認した場合は、可能であれば明確なロールバックの注記を添えて進めてください。

9 - プラットフォームとトラブルシューティングのリファレンス

  • サポート対象プラットフォーム：Windows、Linux、macOS。
  • サポート対象シェル：zsh、bash、PowerShell、cmd（Windows コマンドプロンプト）。
  • Python バージョン：3.10、3.11、3.12、3.13、3.14。
  • CLI ファイルストレージ（トラブルシューティングに便利）：
    • 設定ファイルは ~/.config/fab/ に保存されます。
      • cache.bin — 暗号化された認証トークンキャッシュ
      • config.json — 機密情報を含まない CLI 設定
      • auth.json — 機密情報を含まない認証情報
      • context-<session_id> — コマンドラインモードのセッション用パスコンテキスト
    • デバッグログの出力先：
      • Windows：%AppData%/fabcli_debug.log
      • macOS：~/Library/Logs/fabcli_debug.log
      • Linux：~/.local/state/fabcli_debug.log

10 - 重要な運用ルール

  • 初回実行：コマンドを実行する前に、必ず fab auth status を実行して認証状態を確認してください。未認証の場合は、ユーザーに fab auth login の実行を依頼してください。
  • 実行前に確認：コマンドを初めて使用するときは、必ず fab --help と fab <command> --help を使って構文を確認してください。
  • まずはシンプルに：パイプやコマンドの連結を試す前に、まず基本の fab コマンドだけを実行してください。
  • 非対話モード：コーディングエージェントで作業する場合は、コマンドラインモードで fab を使用してください。対話モードは自動化では動作しません。
  • 強制フラグ：非対話で実行するためのフラグが利用できる場合は、コマンドの実行時に -f を使用してください（確認プロンプトを省略します）。
  • 実行前に確認：ワークスペース名または項目名が不明確な場合は、まずユーザーに確認してから、fab ls または fab exists で検証してください。
  • 権限エラー：コマンドが権限によってブロックされた場合は停止し、ユーザーに確認してください。決して回避しようとしないでください。

11 - 一般的なアイテムの種類

拡張子説明
.Workspaceワークスペースコンテナー
.Folderワークスペース内のフォルダー
.SemanticModelPower BI データセット／セマンティックモデル
.ReportPower BI レポート
.DashboardPower BI ダッシュボード
.NotebookFabric ノートブック
.Lakehouseレイクハウス
.Warehouseデータウェアハウス
.DataPipelineデータパイプライン
.SparkJobDefinitionSpark ジョブ定義
.Eventstreamリアルタイムイベントストリーム
.KQLDatabaseKQL データベース
.MLModelML モデル
.MLExperimentML 実験
.CapacityFabric キャパシティ（非表示）
.Gatewayデータゲートウェイ（非表示）
.Connection接続（非表示）

fab desc .<ItemType> を使用して、任意のアイテムの種類を確認できます。

12 - コマンドリファレンス

コマンドの構文と実用例の詳細については、以下を参照してください。

コメント

Markdown 対応