Back to Details

fabric-cli-powerbi

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fabric CLI Power BI Operations

Fabric CLI Power BI 操作指南

Expert guidance for working with Power BI items (semantic models, reports, dashboards) using the 
fab
CLI.
提供使用
fab
CLI处理Power BI对象（语义模型、报表、仪表板）的专业指导。

When to Use This Skill

何时使用本技能

Activate automatically when tasks involve:
  • Semantic model (dataset) operations — get, export, refresh, update
  • Report management — export, clone, rebind to different model
  • Executing DAX queries against semantic models
  • Managing refresh schedules and troubleshooting failures
  • Gateway and data source configuration
  • TMDL (Tabular Model Definition Language) operations
当任务涉及以下场景时可自动启用：
  • 语义模型（数据集）操作：查询、导出、刷新、更新
  • 报表管理：导出、克隆、重新绑定到其他模型
  • 对语义模型执行DAX查询
  • 管理刷新计划与排查刷新故障
  • 网关与数据源配置
  • TMDL（表格模型定义语言）操作

Prerequisites

前置要求

  • Load 
    fabric-cli-core
    skill first for foundational CLI guidance
  • User must be authenticated: 
    fab auth status
  • Appropriate workspace permissions for target items
  • 首先加载
    fabric-cli-core
    技能获取基础CLI使用指导
  • 用户必须完成身份验证：
    fab auth status
  • 拥有目标对象对应的工作区权限

Automation Scripts

自动化脚本

Ready-to-use Python scripts for Power BI tasks. Run any script with 
--help
for full options.
ScriptPurposeUsage
refresh_model.py
Trigger and monitor semantic model refresh
python scripts/refresh_model.py <model> [--wait] [--timeout 300]
list_refresh_history.py
Show refresh history and failure details
python scripts/list_refresh_history.py <model> [--last N]
rebind_report.py
Rebind report to different semantic model
python scripts/rebind_report.py <report> --model <new-model>
Scripts are located in the 
scripts/
folder of this skill.
可直接使用的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 Item Types

1 - Power BI 对象类型

Entity SuffixTypeDescription
.SemanticModel
Semantic ModelPower BI dataset (tabular model)
.Report
ReportPower BI report (visualizations)
.Dashboard
DashboardPower BI dashboard (pinned tiles)
.Dataflow
DataflowPower Query dataflow
.PaginatedReport
Paginated ReportRDL-based paginated report
实体后缀类型描述
.SemanticModel
语义模型Power BI数据集（表格模型）
.Report
报表Power BI报表（可视化内容）
.Dashboard
仪表板Power BI仪表板（固定磁贴）
.Dataflow
数据流Power Query数据流
.PaginatedReport
分页报表基于RDL的分页报表

Path Examples

路径示例

undefined
undefined

Semantic model

语义模型

Production.Workspace/Sales.SemanticModel
Production.Workspace/Sales.SemanticModel

Report connected to model

关联到模型的报表

Production.Workspace/SalesReport.Report
Production.Workspace/SalesReport.Report

Dashboard

仪表板

Production.Workspace/ExecutiveDash.Dashboard
undefined
Production.Workspace/ExecutiveDash.Dashboard
undefined

2 - Semantic Model Operations

2 - 语义模型操作

Get Model Information

获取模型信息

bash
undefined
bash
undefined

Check if model exists

检查模型是否存在

fab exists "ws.Workspace/Model.SemanticModel"
fab exists "ws.Workspace/Model.SemanticModel"

Get model properties

获取模型属性

fab get "ws.Workspace/Model.SemanticModel"
fab get "ws.Workspace/Model.SemanticModel"

Get model ID (needed for Power BI API calls)

获取模型ID（Power BI API调用时需要）

fab get "ws.Workspace/Model.SemanticModel" -q "id"
fab get "ws.Workspace/Model.SemanticModel" -q "id"

Get full definition (TMDL)

获取完整定义（TMDL格式）

fab get "ws.Workspace/Model.SemanticModel" -q "definition"
undefined
fab get "ws.Workspace/Model.SemanticModel" -q "definition"
undefined

Export Model

导出模型

bash
undefined
bash
undefined

Export to local directory (PBIP format with TMDL)

导出到本地目录（PBIP格式，包含TMDL）

fab export "ws.Workspace/Model.SemanticModel" -o ./exports -f

Creates folder structure:
Model.SemanticModel/ ├── .platform ├── definition.pbism └── definition/ ├── model.tmdl ├── tables/ │ ├── Sales.tmdl │ └── Date.tmdl └── relationships.tmdl
undefined
fab export "ws.Workspace/Model.SemanticModel" -o ./exports -f

生成的目录结构如下：
Model.SemanticModel/ ├── .platform ├── definition.pbism └── definition/ ├── model.tmdl ├── tables/ │ ├── Sales.tmdl │ └── Date.tmdl └── relationships.tmdl
undefined

Import/Update Model

导入/更新模型

bash
undefined
bash
undefined

Import from PBIP folder

从PBIP文件夹导入

fab import "ws.Workspace/Model.SemanticModel" -i ./exports/Model.SemanticModel -f
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
undefined
fab cp "Dev.Workspace/Model.SemanticModel" "Prod.Workspace/Model.SemanticModel" -f
undefined

3 - Refresh Operations

3 - 刷新操作

Trigger Refresh

触发刷新

bash
undefined
bash
undefined

Get IDs

获取ID

WS_ID=$(fab get "ws.Workspace" -q "id" | tr -d '"') MODEL_ID=$(fab get "ws.Workspace/Model.SemanticModel" -q "id" | tr -d '"')
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"}'
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"
undefined
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?$top=1"
undefined

Enhanced Refresh (Partition-Level)

增强型刷新（分区级别）

bash
undefined
bash
undefined

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"} ] }'
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 }'
undefined
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{ "type": "Full", "retryCount": 3 }'
undefined

Refresh Schedule

刷新计划

bash
undefined
bash
undefined

Get current schedule

获取当前刷新计划

fab api -A powerbi "datasets/$MODEL_ID/refreshSchedule"
fab api -A powerbi "datasets/$MODEL_ID/refreshSchedule"

Set daily refresh at 6 AM UTC

设置UTC时间每天早6点刷新

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

Troubleshoot Refresh Failures

刷新故障排查

bash
undefined
bash
undefined

Get refresh history

获取刷新历史

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes"
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes"

Common failure patterns:

常见失败原因：

- "credentials" → Update data source credentials

- "credentials" → 更新数据源凭证

- "gateway" → Check gateway status

- "gateway" → 检查网关状态

- "timeout" → Use enhanced refresh with smaller batches

- "timeout" → 使用增强型刷新，缩小批次大小

- "memory" → Optimize model or use incremental refresh

- "memory" → 优化模型或使用增量刷新

undefined
undefined

4 - DAX Query Execution

4 - DAX查询执行

Execute DAX queries against semantic models:
bash
MODEL_ID=$(fab get "ws.Workspace/Model.SemanticModel" -q "id" | tr -d '"')
对语义模型执行DAX查询：
bash
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])"}] }'
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]))" }] }'
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{ "queries": [{ "query": "EVALUATE SUMMARIZECOLUMNS(Date[Year], "Total", SUM(Sales[Amount]))" }] }'

TOPN query

TOPN查询

fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{ "queries": [{ "query": "EVALUATE TOPN(10, Product, [Total Sales], DESC)" }] }'
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"}] }] }'
undefined
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{ "queries": [{ "query": "EVALUATE FILTER(Sales, Sales[Year] = @Year)", "parameters": [{"name": "@Year", "value": "2024"}] }] }'
undefined

5 - Report Operations

5 - 报表操作

Get Report Info

获取报表信息

bash
undefined
bash
undefined

Check exists

检查报表是否存在

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

Get properties

获取报表属性

fab get "ws.Workspace/Report.Report"
fab get "ws.Workspace/Report.Report"

Get connected model

获取关联的模型

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

Export Report

导出报表

bash
undefined
bash
undefined

Export to PBIP format

导出为PBIP格式

fab export "ws.Workspace/Report.Report" -o ./exports -f
undefined
fab export "ws.Workspace/Report.Report" -o ./exports -f
undefined

Clone Report

克隆报表

bash
undefined
bash
undefined

Copy within workspace

在同一工作区内复制

fab cp "ws.Workspace/Report.Report" "ws.Workspace/ReportCopy.Report" -f
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
undefined
fab cp "Dev.Workspace/Report.Report" "Prod.Workspace/Report.Report" -f
undefined

Rebind Report to Different Model

报表重新绑定到其他模型

bash
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\"
}"
bash
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\"
}"

Export Report to File (PDF/PPTX)

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

bash
undefined
bash
undefined

Export to PDF

导出为PDF

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

Poll for completion, then download

轮询任务完成后即可下载

undefined
undefined

6 - Gateway Operations

6 - 网关操作

List Gateways

列出网关

bash
undefined
bash
undefined

Tenant-level gateways (hidden entity)

租户级网关（隐藏实体）

fab ls .gateways
fab ls .gateways

Get gateway details

获取网关详情

fab get ".gateways/MyGateway.Gateway"
undefined
fab get ".gateways/MyGateway.Gateway"
undefined

Data Source Management

数据源管理

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

List data sources on gateway

列出网关上的数据源

fab api -A powerbi "gateways/$GATEWAY_ID/datasources"
fab api -A powerbi "gateways/$GATEWAY_ID/datasources"

Get data source status

获取数据源状态

fab api -A powerbi "gateways/$GATEWAY_ID/datasources/$DATASOURCE_ID"
undefined
fab api -A powerbi "gateways/$GATEWAY_ID/datasources/$DATASOURCE_ID"
undefined

Update Data Source Credentials

更新数据源凭证

bash
undefined
bash
undefined

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" } }'
undefined
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" } }'
undefined

7 - Take Over Ownership

7 - 接管所有权

When a semantic model owner leaves the organization:
bash
WS_ID=$(fab get "ws.Workspace" -q "id" | tr -d '"')
MODEL_ID=$(fab get "ws.Workspace/Model.SemanticModel" -q "id" | tr -d '"')
当语义模型所有者离开组织时使用：
bash
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
undefined
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/Default.TakeOver" -X post
undefined

8 - Common Patterns

8 - 常用场景

Dev to Production Deployment

开发到生产环境部署

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

1. Export from dev

1. 从开发环境导出

fab export "$DEV_WS/Sales.SemanticModel" -o ./deploy -f fab export "$DEV_WS/SalesReport.Report" -o ./deploy -f
fab export "$DEV_WS/Sales.SemanticModel" -o ./deploy -f fab export "$DEV_WS/SalesReport.Report" -o ./deploy -f

2. Import to prod

2. 导入到生产环境

fab import "$PROD_WS/Sales.SemanticModel" -i ./deploy/Sales.SemanticModel -f fab import "$PROD_WS/SalesReport.Report" -i ./deploy/SalesReport.Report -f
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

3. 触发刷新

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"}'
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

4. 验证

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

Backup Semantic Model

语义模型备份

bash
undefined
bash
undefined

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)"
undefined
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)"
undefined

Incremental Refresh Setup

增量刷新配置

For large models, use incremental refresh:
  1. Configure in Power BI Desktop with RangeStart/RangeEnd parameters
  2. Publish to workspace
  3. First refresh creates partitions:
bash
undefined
大型模型推荐使用增量刷新：
  1. 在Power BI Desktop中配置RangeStart/RangeEnd参数
  2. 发布到工作区
  3. 首次刷新会生成分区：
bash
undefined

Monitor partition creation

监控分区创建进度

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?$top=5"
undefined
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?$top=5"
undefined

9 - Safety Guidelines

9 - 安全指南

  • Always verify workspace context before refresh operations
  • Test in dev first — never refresh production without testing
  • Monitor refresh duration — set appropriate timeouts
  • Backup before major changes — export definition before updates
  • Use enhanced refresh for large models to avoid timeouts
  • 执行刷新操作前务必确认工作区上下文
  • 先在开发环境测试，未测试不要直接操作生产环境刷新
  • 监控刷新耗时，设置合理的超时时间
  • 重大变更前先备份，更新前先导出模型定义
  • 大型模型使用增强型刷新避免超时

10 - References

10 - 参考文档

For detailed patterns, see:
  • references/semantic-models.md — Full TMDL operations
  • references/reports.md — Report management
  • references/refresh.md — Refresh troubleshooting
  • references/dax-queries.md — Advanced DAX patterns
  • references/gateways.md — Gateway configuration
更多详细场景请查看：
  • references/semantic-models.md — 完整TMDL操作指南
  • references/reports.md — 报表管理指南
  • references/refresh.md — 刷新故障排查
  • references/dax-queries.md — 高级DAX使用模式
  • references/gateways.md — 网关配置指南