fabric-cli

Fabric CLI

使用 fab 以编程方式管理 Fabric 和 Power BI 服务的指南

• 通过 uv tool install ms-fabric-cli 安装（通过 winget install uv 或 brew install uv 获取 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 的功能经常变化

将通用的 fab 使用经验（错误、用户偏好）记录在 .claude/rules/fabric-cli.md 中， 以便后续会话可以参考；特定于项目或任务的发现不应记录在那里。

重要通用规则

• 首次使用时，运行 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 小时数的四分之一、会重复发生、无法估算，或容量已出现节流，则必须取得用户明确批准；用户提及某项功能并不代表同意承担其费用。请参阅容量成本和capacity-cost.md
• 如果某条命令因权限不足而受阻，停止操作并向用户确认；切勿尝试绕过限制
• 导出前创建输出目录：fab export 不会创建中间目录；请先对输出路径运行 mkdir -p，否则命令会失败并显示 [InvalidPath]

容量成本：操作前先估算

突发处理会掩盖成本：操作虽然很快完成，但其 CU 会在接下来的 5 到 64 分钟（交互式）或 24 小时（后台）内进行平滑计费。在较小的 F SKU 上，单次操作消耗的容量可能超过一天的额度；随后产生的结转用量会导致其上的所有工作区持续受到节流，直到空闲容量将其抵消。在 F2 上，这可能需要数周。

• 先检查容量：运行 fab ls .capacities -l 查看 SKU 和状态；在 Monitoring hub 容量页面查看利用率、节流和结转用量。任何结转用量都意味着没有可用余量
• 估算操作的 CU 小时数和 EUR 费用，以及占 SKU 每日预算的比例（F 每天有 24 * n 个 CU 小时；F2 为 48）
• 了解固定费用：Plan（预览版）按用户收取 30 天会话费用（Planner 为 847、Stakeholder 为 168、Viewer 为 37 CU 小时）；通过 REST 创建和编辑计划曾按 Stakeholder 会话计费（168 CU-h），且会话无法结束或退款
• 暂停容量（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. 查询数据（始终优先使用封装脚本，而不是直接使用 fab api／duckdb／sqlcmd；这些脚本会为你解析 ID、主机和身份验证）：
   • 语义模型（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 时才会提供该 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
    • 设置服务主体以供自动化使用，而非使用个人身份：service-principals.md——通过 az CLI 创建、工作区角色与租户设置组的双重要求，以及如何以该身份对 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)"；命令替换会将机密直接传入子进程参数列表，不会写入标准输出、文件或命名的 Shell 变量
    • 完整的 fab 与 az 决策矩阵：fab-vs-az-cli.md

核心概念

有关 Power BI 或 Fabric 相关概念的信息，必须搜索或获取 Microsoft Learn 文档（网址为 https://learn.microsoft.com），或使用 pbi-search CLI，并使用 AskUserQuestion 工具向用户提问；切勿猜测或自行假设。

工作区

• 工作区是用于容纳项目的容器，例如笔记本（以及其他 ETL 项目）、湖仓（以及其他数据项目）、SemanticModels、报表（以及其他使用类项目）和 OrgApps。
• 工作区可以分配给不同的对象：
  • 部署管道，用于生命周期管理（开发、测试、生产等）
  • 域，用于治理和租户结构管理
  • 容量，用于许可和资源管理（仅限 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 数据 Agent
• .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 根据数据源提供三种查询路径；请始终优先使用封装脚本——它们会为你解析 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/ 中的原始文件：传入 --sql，并使用你自己的 delta_scan() / read_csv / read_json_auto 调用
  • 也可以改为搭建 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、description、敏感度配置）：
  • 原生更新：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
  • 语义模型源重新绑定（例如，更换 lakehouse）：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
  • 规划上下文、创建 / 获取 / 设置 Surface、大型存储格式、Spark 池、OneLake 默认值、Git：workspaces.md
• 复制、分叉、下载：
  • 在租户内复制工作区：fab cp -r "dev.Workspace" "prod.Workspace"
  • 先试运行源目录树：fab ls "dev.Workspace"
  • 完整的本地快照（项目 + Lakehouse 文件）：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 确认访问权限；如果报错，请停止，不要重试。

大多数管理任务可通过以下两个入口完成：

• 治理审计（租户设置、委派覆盖、Entra SG 范围限定）：
  • 使用 fabric-admin 插件中的 audit-tenant-settings 技能。它负责整理后的元数据基线、审计和变更检测脚本、委派覆盖项枚举，以及 Entra SG 调查工作流。
  • 当问题涉及租户状态与组成员身份、覆盖范围或相对于基线的偏差时，请调用此技能。
• 原始管理 API（跨工作区搜索、活动事件、项目访问权限、项目搜索）：
  • 模式见 admin.md
  • 速率限制：每分钟 25 个写入请求；遇到 429 错误时遵守 Retry-After
  • 执行任何破坏性管理操作前，打印确切命令并等待用户确认

执行管理操作前请查看参考资料：

• admin.md
• permissions.md，用于工作区 / 项目 ACL 暴露审计

定义与部署（项目定义、部署管道、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 会返回 202 Accepted，并带有 Retry-After: 20 标头。fab import、nb create 和 nb cell edit 在状态轮询之间大约会等待这么久，因此服务器约 1 秒就能完成的笔记本操作，这些命令却需要 25-60 秒。fab 和 nb 都没有提供调整此间隔的参数。 对于笔记本定义变更，强烈建议使用 scripts/deploy_notebook.py， 它每隔约 0.3 秒轮询一次 LRO（可通过 --poll-interval 调整），创建约需 1-2 秒，或原位更新约需 1 秒。它会自动检测应创建还是更新。必须为其他项目类型自行实现时，原则相同：以约 0.3 秒的间隔轮询 updateDefinition / 创建操作，而不是使用标称的 20 秒间隔。

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
• 完整工作区快照（项目 + Lakehouse 文件）：
  • 用于备份、离线分析、跨租户分支：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 插件中）；Fabric 治理工作流，涵盖租户设置、委派的覆盖设置（容量 / 域 / 工作区）以及这些设置所引用的 Entra 安全组。只读；包含整理好的元数据基线，以及审计和变更检测脚本。

注意事项

• fab ls 用于列出工作区和项目，并浏览数据项目（.Lakehouse、.Warehouse）；对其他项目执行时会失败，因此请使用 fab get 读取其定义
• 为 fab get、fab import 和 fab export 传入 -f，以跳过覆盖和敏感度提示
• 仅在没有命令可执行相应操作时才使用 fab api
• 定义更改看起来很慢，实际并非如此： fab import / nb create / nb cell edit 推送笔记本定义需要 25-60s，唯一原因是它们按服务器的 Retry-After: 20 轮询 LRO。实际操作约需 1s。定义更改请使用 scripts/deploy_notebook.py（以约 0.3s 的间隔快速轮询）；轮询间隔是影响最大的因素

参考资料

参考资料索引（了解哪些参考资料彼此相关；请沿着它们之间的链接浏览，而不只是查看此列表）：

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 查询；输出格式为表格、csv 或 json
• query_lakehouse_duckdb.py；通过 DuckDB 对 OneLake 中的 lakehouse 或 warehouse Delta 表执行查询（重用 az login）；输出格式为表格、csv 或 json
• query_sql_endpoint.py；通过 sqlcmd 查询 lakehouse SQL endpoint、warehouse 或 SQL database（通过 ActiveDirectoryAzCli 重用 az login）；输出格式为表格、csv 或 json
• create_direct_lake_model.py；根据 lakehouse 表创建 Direct Lake 语义模型
• download_workspace.py；下载包含所有项目定义和 lakehouse 文件的完整工作区
• run_notebook_checked.py；运行 notebook 并检查其退出值；即使作业状态为 Completed，如果 notebook 自身的 {ok:false} 判定未通过，也会以非零状态退出（通过 notebook 作业实例 beta endpoint 读取退出值）
• deploy_notebook.py；通过紧密轮询 LRO 创建或更新 notebook 定义，速度更快（约 1-2s），而非采用 CLI 约 20s 的 Retry-After 周期；自动检测创建或更新，--poll-interval 是影响性能的参数。任何 notebook 定义变更都强烈建议优先使用此工具，而不是 fab import / nb
• task_flow.py；通过 Fabric UI 使用的内部元数据 endpoint，根据 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 最佳实践