fabric-cli-powerbi

Fabric CLI Power BI 操作

使用 fab CLI 处理 Power BI 项（语义模型、报表、仪表板）的专家指南。

何时使用此技能

当任务涉及以下内容时自动启用：

• 语义模型（数据集）操作 — 获取、导出、刷新、更新
• 报表管理 — 导出、克隆、重新绑定到其他模型
• 对语义模型执行 DAX 查询
• 管理刷新计划并排查故障
• 网关和数据源配置
• TMDL（表格模型定义语言）操作

前提条件

• 先加载 fabric-cli-core 技能，了解 CLI 基础知识
• 用户必须已通过身份验证：fab auth status
• 对目标项拥有适当的工作区权限

自动化脚本

可直接用于 Power BI 任务的 Python 脚本。运行任意脚本时使用 --help 可查看完整选项。

脚本	用途	用法
refresh_model.py	触发并监控语义模型刷新	python scripts/refresh_model.py <model> [--wait] [--timeout 300]
list_refresh_history.py	显示刷新历史记录和失败详情	python scripts/list_refresh_history.py <model> [--last N]
rebind_report.py	将报表重新绑定到其他语义模型	python scripts/rebind_report.py <report> --model <new-model>

脚本位于此技能的 scripts/ 文件夹中。

1 - Power BI 项类型

实体后缀	类型	说明
.SemanticModel	语义模型	Power BI 数据集（表格模型）
.Report	报表	Power BI 报表（可视化内容）
.Dashboard	仪表板	Power BI 仪表板（固定磁贴）
.Dataflow	数据流	Power Query 数据流
.PaginatedReport	分页报表	基于 RDL 的分页报表

路径示例

# Semantic model
Production.Workspace/Sales.SemanticModel

# Report connected to model
Production.Workspace/SalesReport.Report

# Dashboard
Production.Workspace/ExecutiveDash.Dashboard

2 - 语义模型操作

获取模型信息

# Check if model exists
fab exists "ws.Workspace/Model.SemanticModel"

# Get model properties
fab get "ws.Workspace/Model.SemanticModel"

# Get model ID (needed for Power BI API calls)
fab get "ws.Workspace/Model.SemanticModel" -q "id"

# Get full definition (TMDL)
fab get "ws.Workspace/Model.SemanticModel" -q "definition"

导出模型

# Export to local directory (PBIP format with TMDL)
fab export "ws.Workspace/Model.SemanticModel" -o ./exports -f

创建文件夹结构：

Model.SemanticModel/
├── .platform
├── definition.pbism
└── definition/
    ├── model.tmdl
    ├── tables/
    │   ├── Sales.tmdl
    │   └── Date.tmdl
    └── relationships.tmdl

导入/更新模型

# Import from PBIP folder
fab import "ws.Workspace/Model.SemanticModel" -i ./exports/Model.SemanticModel -f

# Copy between workspaces
fab cp "Dev.Workspace/Model.SemanticModel" "Prod.Workspace/Model.SemanticModel" -f

3 - 刷新操作

触发刷新

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

# Trigger full refresh
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{"type":"Full"}'

# Check refresh status
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=1"

增强刷新（分区级别）

# Refresh specific tables
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{
  "type": "Full",
  "commitMode": "transactional",
  "objects": [
    {"table": "Sales"},
    {"table": "Inventory"}
  ]
}'

# Refresh with retry
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{
  "type": "Full",
  "retryCount": 3
}'

刷新计划

# Get current schedule
fab api -A powerbi "datasets/$MODEL_ID/refreshSchedule"

# Set daily refresh at 6 AM UTC
fab api -A powerbi "datasets/$MODEL_ID/refreshSchedule" -X patch -i '{
  "enabled": true,
  "days": ["Monday","Tuesday","Wednesday","Thursday","Friday"],
  "times": ["06:00"],
  "localTimeZoneId": "UTC"
}'

排查刷新失败问题

# Get refresh history
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes"

# Common failure patterns:
# - "credentials" → Update data source credentials
# - "gateway" → Check gateway status
# - "timeout" → Use enhanced refresh with smaller batches
# - "memory" → Optimize model or use incremental refresh

4 - 执行 DAX 查询

对语义模型执行 DAX 查询：

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

# Simple query
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{"query": "EVALUATE VALUES(Date[Year])"}]
}'

# Aggregation query
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{
    "query": "EVALUATE SUMMARIZECOLUMNS(Date[Year], \"Total\", SUM(Sales[Amount]))"
  }]
}'

# TOPN query
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{
    "query": "EVALUATE TOPN(10, Product, [Total Sales], DESC)"
  }]
}'

# Query with parameters
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{
    "query": "EVALUATE FILTER(Sales, Sales[Year] = @Year)",
    "parameters": [{"name": "@Year", "value": "2024"}]
  }]
}'

5 - 报表操作

获取报表信息

# Check exists
fab exists "ws.Workspace/Report.Report"

# Get properties
fab get "ws.Workspace/Report.Report"

# Get connected model
fab get "ws.Workspace/Report.Report" -q "definition.parts[?contains(path, 'definition.pbir')].payload | [0]"

导出报表

# Export to PBIP format
fab export "ws.Workspace/Report.Report" -o ./exports -f

克隆报表

# Copy within workspace
fab cp "ws.Workspace/Report.Report" "ws.Workspace/ReportCopy.Report" -f

# Copy to another workspace
fab cp "Dev.Workspace/Report.Report" "Prod.Workspace/Report.Report" -f

将报表重新绑定到其他模型

WS_ID=$(fab get "ws.Workspace" -q "id" | tr -d '"')
REPORT_ID=$(fab get "ws.Workspace/Report.Report" -q "id" | tr -d '"')
NEW_MODEL_ID=$(fab get "ws.Workspace/NewModel.SemanticModel" -q "id" | tr -d '"')

fab api -A powerbi "groups/$WS_ID/reports/$REPORT_ID/Rebind" -X post -i "{
  \"datasetId\": \"$NEW_MODEL_ID\"
}"

将报表导出为文件（PDF/PPTX）

# Export to PDF
fab api -A powerbi "groups/$WS_ID/reports/$REPORT_ID/ExportTo" -X post -i '{
  "format": "PDF"
}'

# Poll for completion, then download

6 - 网关操作

列出网关

# Tenant-level gateways (hidden entity)
fab ls .gateways

# Get gateway details
fab get ".gateways/MyGateway.Gateway"

数据源管理

GATEWAY_ID=$(fab get ".gateways/MyGateway.Gateway" -q "id" | tr -d '"')

# List data sources on gateway
fab api -A powerbi "gateways/$GATEWAY_ID/datasources"

# Get data source status
fab api -A powerbi "gateways/$GATEWAY_ID/datasources/$DATASOURCE_ID"

更新数据源凭据

# Update credentials (basic auth example)
fab api -A powerbi "gateways/$GATEWAY_ID/datasources/$DATASOURCE_ID" -X patch -i '{
  "credentialDetails": {
    "credentialType": "Basic",
    "credentials": "{\"credentialData\":[{\"name\":\"username\",\"value\":\"user\"},{\"name\":\"password\",\"value\":\"pass\"}]}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "Organizational"
  }
}'

7 - 接管所有权

当语义模型所有者离开组织时：

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

# Take over semantic model ownership
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/Default.TakeOver" -X post

8 - 常见模式

从开发环境部署到生产环境

#!/bin/bash
DEV_WS="Dev.Workspace"
PROD_WS="Prod.Workspace"

# 1. Export from dev
fab export "$DEV_WS/Sales.SemanticModel" -o ./deploy -f
fab export "$DEV_WS/SalesReport.Report" -o ./deploy -f

# 2. Import to prod
fab import "$PROD_WS/Sales.SemanticModel" -i ./deploy/Sales.SemanticModel -f
fab import "$PROD_WS/SalesReport.Report" -i ./deploy/SalesReport.Report -f

# 3. Trigger refresh
PROD_WS_ID=$(fab get "$PROD_WS" -q "id" | tr -d '"')
MODEL_ID=$(fab get "$PROD_WS/Sales.SemanticModel" -q "id" | tr -d '"')
fab api -A powerbi "groups/$PROD_WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{"type":"Full"}'

# 4. Verify
fab api -A powerbi "groups/$PROD_WS_ID/datasets/$MODEL_ID/refreshes?\$top=1" -q "value[0].status"

备份语义模型

# Export definition for version control
fab export "Prod.Workspace/Model.SemanticModel" -o ./backups/$(date +%Y%m%d) -f
git add ./backups/
git commit -m "Backup Model $(date +%Y-%m-%d)"

设置增量刷新

对于大型模型，请使用增量刷新：

1. 在 Power BI Desktop 中使用 RangeStart/RangeEnd 参数进行配置
2. 发布到工作区
3. 首次刷新会创建分区：

# Monitor partition creation
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=5"

9 - 安全指南

• 刷新操作前务必确认工作区上下文
• 先在开发环境中测试 — 未经测试，切勿刷新生产环境
• 监控刷新时长 — 设置适当的超时时间
• 重大更改前先备份 — 更新前导出定义
• 大型模型使用增强刷新，避免超时

10 - 参考资料

详细模式请参阅：

• references/semantic-models.md — 完整的 TMDL 操作
• references/reports.md — 报表管理
• references/refresh.md — 刷新故障排查
• references/dax-queries.md — 高级 DAX 模式
• references/gateways.md — 网关配置