Power BI API：面向开发者与数据专业人士的全面指南

Power BI REST API 是扩展 Microsoft Power BI 能力的关键组件。

它使开发者和组织能够以编程方式访问报表、仪表板、数据集和工作区，而不仅仅是提供固定的图形界面（GUI）。

在现代 BI 解决方案中，自动化、集成和嵌入是业务流程的核心，而这种能力至关重要。

在本指南中，我将介绍 Power BI REST API，提供简单的分步使用指南，展示一些使用示例，并分享它所提供的一些高级功能。

Power BI API 生态系统

Power BI API 生态系统旨在在企业范围内扩展，向开发者提供强大的能力。

它让组织可以将 Power BI 视为一个服务层，能够无缝集成到工作流和应用程序中。

以下是生态系统的基本组件：

1. REST API：生态系统的基础，公开数据集、报表、仪表板、工作区和用户的端点。
2. SDK：Microsoft 提供 .NET、Python 和 JavaScript 的 SDK，分别契合常见开发工作流：
3. CLI：用于管理工作区、推送数据集和部署内容的命令行界面。
4. PowerShell：管理员偏爱的工具，可编写脚本并自动化常规任务，如用户供应或审计日志记录。

目的与能力

该 API 为以下用例提供 Power BI 资产的端到端管理：

• 自动化： 触发数据集刷新、在环境之间移动报表、无需手动操作即可更新权限。
• 治理： 提取元数据以满足合规要求，跟踪使用模式并执行策略。
• 集成： 将 Power BI 与其他企业系统（CRM、ERP、HR、ETL 工具）连接，提供实时报表。
• 嵌入： 在 Web 或移动应用中交付安全、交互式的仪表板和报表。

这些能力将 Power BI 的功能延伸至 GUI 之外，使组织能够大规模运作。

RESTful 架构

该 API 遵循 REST 原则，对开发者而言易于上手。

以下是架构的一些组成部分：

• HTTP 方法： GET 用于检索、POST 用于创建、PUT/PATCH 用于更新、DELETE 用于删除。
• JSON 负载： 易于解析并与现代应用集成。
• 互操作性： 可与 Python requests、Node.js axios 或 .NET HttpClient 等库无缝协作。

该 API 还支持以编程方式进行内容管理。

这意味着您可以执行以下功能：

• 创建新的数据集及其架构。
• 导出报表以进行版本控制和迁移。
• 将报表和仪表板克隆到新环境。
• 将报表重新绑定到不同的数据集，简化部署流水线。

Power BI API 的身份验证与安全

身份验证是安全通信的基础。Power BI API 依赖 Azure Active Directory 来对应用和用户进行身份验证。

1. 身份验证流程

启用访问需要：

1. 注册应用： 在 Azure AD 中创建应用注册。
2. 收集凭据： 获取租户 ID、客户端 ID 和客户端机密。
3. 选择访问模型： 使用委托访问（用户上下文）或服务主体（仅应用）。

对于自动化，推荐使用服务主体，因为它不与个人用户绑定。

2. OAuth 2.0 流程

Power BI 支持标准的 OAuth 2.0 流程：

• 客户端凭据流程： 适用于服务器到服务器的应用，无需用户交互。
• 授权码流程： 需要用户登录，用于交互式应用。Azure AD 签发的令牌包含定义用户或应用权限的声明。

3. 持票人令牌方式

将令牌附加到请求中：

Authorization: Bearer {access_token}技术支持

令牌会在短时间后过期（通常为一小时），因此应用必须以编程方式刷新它们。

Power BI API 核心操作

Power BI API 按类别划分，涵盖 Power BI 内容与用户管理的各个方面。

以下是其核心操作与功能：

1. 端点类别
2. 数据集管理
3. 报表与仪表板管理
4. 工作区与嵌入管理
5. 用户与权限管理

如何使用 Power BI REST API：分步过程

Power BI REST API 可用于自动化任务（如刷新数据集）、管理用户与工作区，或在应用中嵌入报表。

使用步骤如下：

步骤 1：为 Power BI 注册应用

在您的代码能够与 Power BI 通信之前，必须在 Azure Active Directory（Azure AD）中注册一个应用。

1. 前往 Azure 门户。
2. 导航至 Microsoft Entra ID → 应用注册 → 新注册。
3. 输入：
• 名称：PowerBI-API-Test
• 支持的帐户类型： 单租户（用于测试已足够）。
• 重定向 URI： https://oauth.pstmn.io/v1/callback（这是 Postman 的重定向 URL）。
4. 注册后，复制 应用程序（客户端）ID 和 目录（租户）ID。
5. 在 证书和机密 下，创建一个 客户端机密 并复制保存。

步骤 2：授权用户或服务主体

接下来的授权步骤通常有两种方式：

• 委托（用户）流程： 用户登录并授予权限。
• 服务主体（仅应用）流程： 管理员同意权限，应用可独立运行。

在本示例中，我们将使用委托流程的方法。

1. 在 API 权限 → 添加权限 → Power BI Service → 委托权限 中，添加：
• Dashboard.Read.All
• Report.Read.All
• Dataset.Read.All
2. 如有提示，单击 授予管理员同意。

步骤 3：获取 API 访问令牌

每次 API 调用都需要一个 OAuth 令牌。没有它，API 将无法识别您的身份或权限。

我们将使用 Postman 获取 API 令牌。

1. 打开 Postman → New → Request。
2. 在 Authorization 选项卡中选择：
• Type： OAuth 2.0
• Grant Type： Authorization Code
• Callback URL： https://oauth.pstmn.io/v1/callback
• Auth URL: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize
• Access Token URL: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token
• Client ID： 您的应用程序（客户端）ID
• Client Secret： 您的机密
• Scope:  openid profile offline_access https://analysis.windows.net/powerbi/api/Dashboard.Read.All https://analysis.windows.net/powerbi/api/Report.Read.All https://analysis.windows.net/powerbi/api/Dataset.Read.All
3. 单击 Get New Access Token。
4. 使用您的 Microsoft 帐户登录。
5. 成功后，Postman 会显示一个 访问令牌。单击 Use Token。

您也可以使用以下基于 requests 库的 Python 脚本，从 Microsoft Azure 获取访问令牌。

import requests

payload = {
    'grant_type': 'client_credentials',
    'client_id': CLIENT_ID,
    'client_secret': CLIENT_SECRET,
    'scope': 'https://analysis.windows.net/powerbi/api/.default'
}

response = requests.post(TOKEN_URL, data=payload)
access_token = response.json()["access_token"]技术支持

该令牌的有效期较短；在生产环境中应自动刷新。

步骤 4：发起 API 调用

一旦获取了访问令牌（来自步骤 3），您就可以开始与 Power BI REST API 通信。

可以将该令牌视为您的“入场券”。没有它，每个请求都会被拒绝。

所有 Power BI REST API 调用均以以下 URL 开始：

https://api.powerbi.com/v1.0/myorg

以下是该字符串各部分的含义：

• v1.0 → API 版本。
• myorg → 指您的租户。

您将追加诸如 /groups、/reports、/datasets 等资源路径。

每个请求都必须在 Authorization 头中包含您的访问令牌：

Authorization: Bearer <access_token>技术支持

对于 POST 请求，还需添加：

Content-Type: application/json技术支持

如果忘记这些头部，您将收到 401 Unauthorized 错误。

首先，让我们尝试列出所有工作区（groups）。

headers = {
    "Authorization": f"Bearer {access_token}"
}

groups_url = "https://api.powerbi.com/v1.0/myorg/groups"
groups_response = requests.get(groups_url , headers=headers)技术支持

上述 GET 请求会显示您的用户可访问的所有工作区。

示例响应：

{
  "value": [
    {
      "id": "1234-abcd-5678-efgh",
      "name": "Marketing Analytics"
    },
    {
      "id": "7890-ijkl-1234-mnop",
      "name": "Sales Reporting"
    }
  ]
}技术支持

处理身份验证与常见问题

如果遇到任何错误，以下是一些可能的问题及其含义。

• 401 Unauthorized：令牌过期或缺失。
• 403 Forbidden：权限不足。
• Invalid Scope：确保所请求的 scope 与 API 端点匹配。使用 Postman 或 PowerShell cmdlet 进行调试有助于定位权限问题。

Power BI REST API 示例

下面来看一些 Power BI API 的实际示例。

示例 1：获取数据集

此调用检索某个工作区内的所有数据集。

headers = {
    "Authorization": f"Bearer {access_token}"
}
# Example: List datasets in the default workspace
datasets_url = "https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/datasets"
datasets_response = requests.get(datasets_url, headers=headers)
for dataset in datasets_response.json()['value']:
    print(dataset['id'], dataset['name'])技术支持

示例响应：

{
  "value": [
    {
      "id": "1234abcd-5678-efgh-9101-ijklmnop",
      "name": "SalesDataset",
      "configuredBy": "[email protected]",
      "addRowsAPIEnabled": false,
      "isRefreshable": true
    },
    {
      "id": "9876wxyz-5432-ponm-1112-abcd1234",
      "name": "MarketingDataset",
      "configuredBy": "[email protected]",
      "addRowsAPIEnabled": true,
      "isRefreshable": false
    }
  ]
}技术支持

示例 2：刷新数据集

您可以自动化数据集刷新，而不必仅依赖 Power BI 服务中的计划刷新。此示例会触发数据集刷新，常用于 ETL 流水线。

headers = {
    "Authorization": f"Bearer {access_token}"
}
datasets_refreshes_url = "https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/datasets/{datasetId}/refreshes"
refresh_response = requests.post(datasets_refreshes_url , headers=headers)

print("Refresh Status:", refresh_response .status_code)技术支持

响应：

• 如果成功，您将收到：HTTP 202 Accepted 消息。这表示刷新已进入队列。

示例 3：列出报表与仪表板

在下一个示例中，我们来看一个获取工作区中报表的脚本，对清单编制或迁移脚本很有用。

列出报表

以下脚本用于列出报表：

headers = {
    "Authorization": f"Bearer {access_token}"
}
reports_url = "https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/reports"
reports = requests.get(reports_url , headers=headers).json()['value']

for report in reports:
    print(report['id'], report['name'])技术支持

响应：

{
  "value": [
    {
      "id": "a1b2c3d4",
      "name": "Executive Sales Report",
      "embedUrl": "https://app.powerbi.com/reportEmbed?reportId=a1b2c3d4",
      "datasetId": "1234abcd-5678-efgh-9101-ijklmnop"
    }
  ]
}技术支持

列出仪表板

我们也可以列出 Power BI 工作区中已有的仪表板名称。

以下脚本用于列出仪表板：

headers = {
    "Authorization": f"Bearer {access_token}"
}
dashboards_url = "https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/dashboards"
dashboards = requests.get(dashboards_url  , headers=headers).json()['value']

for dashboard in dashboards :
    print(dashboard ['id'], dashboard ['name'])技术支持

响应：

{
  "value": [
    {
      "id": "z9y8x7w6",
      "displayName": "Sales Performance Dashboard",
      "embedUrl": "https://app.powerbi.com/dashboardEmbed?dashboardId=z9y8x7w6"
    }
  ]
}技术支持

Power BI API 的嵌入与集成 

嵌入 Power BI 可将分析扩展到外部应用和门户，而不仅限于在 Power BI 服务中共享。对于希望为面向客户的应用创建仪表板的组织来说，这是一个不错的选择。

来源：Microsoft Power BI

1. 嵌入架构

嵌入 Power BI 内容包括使用 Power BI REST API 和 JavaScript SDK 在自定义应用中渲染报表、仪表板或可视对象。

其典型架构包括：

• 应用前端：使用 Power BI JavaScript 库在 Web 或移动端承载嵌入的报表。
• 应用后端：安全服务，负责与 Azure AD 进行身份验证，生成嵌入令牌并传递给前端。
• Power BI 服务：托管数据集、报表和模型的核心平台，提供分析能力。

2. 嵌入场景

嵌入 Power BI 内容主要有两种场景，分别具有不同的许可和安全模型：

• 面向您的组织：同一租户内的已认证用户。
• 面向您的客户：通过嵌入令牌认证的外部用户，依托 Power BI Embedded 容量。

下面的图片展示了嵌入如何工作。

来源：Microsoft

3. 技术实现

要实现 Power BI 嵌入，您需要后端身份验证与前端渲染相配合。

一般步骤如下：

• 步骤 1：在 Azure AD 中注册应用并配置相应的 API 权限
• 步骤 2：调用 Power BI REST API 生成嵌入令牌，以授予限时访问
• 步骤 3：使用 Power BI JavaScript SDK 将报表加载到 iframe 容器中。
• 步骤 4：通过仅在服务端生成令牌、强制 HTTPS 通信、使用短期令牌和令牌刷新机制来确保工作流安全。

Power BI API 性能优化

高效使用 Power BI API 对于确保可扩展性、可靠性和响应性至关重要。

由于所有 API 都受限流与节流规则约束，您需要在保持高性能的同时设计可处理这些限制的应用。

以下是我认为有用的一些措施：

1. 限速约束与节流

Power BI 会实施 API 限速 以维护服务稳定性并在租户间公平分配资源。每个租户都有请求配额，超出限制将触发 429 Too Many Requests 错误。

2. 优化策略

多种技术可最小化 API 调用、最大化吞吐量并降低对 Power BI 服务的负载：

• 批处理： 在一次请求中发送多个操作。
• 缓存： 避免重复 API 调用。
• 异步调用： 在后台处理刷新或长任务。

3. 监控与日志

对 API 使用情况的可见性是管理配额和排查性能问题的关键。

来源：Microsoft Azure Monitor

以下是一些 API 监控方法：

• 跟踪所有 API 调用的时间戳与结果。
• 使用 Azure Monitor 进行系统级监控。

Power BI API 安全注意事项

安全与治理是任何计划实施 Power BI 及其 API 生态系统的企业的基础支柱。

以下是一些措施：

1. 凭据管理

• 使用安全存储机制：将凭据存储在安全位置，如 Azure Key Vault、AWS Secrets Manager 或 HashiCorp Vault。
• 定期轮换机密：实施自动策略，轮换客户端机密、证书和令牌，尽量降低凭据泄露风险。
• 监控与告警：跟踪异常的身份验证失败或重复令牌请求，以检测潜在入侵。

使用 Azure Key Vault 管理机密。

• 频繁轮换机密。
• 切勿在源代码中硬编码凭据。

2. 访问控制

访问控制确保只有授权用户可以查看或操作数据集、报表和仪表板。

1. 行级安全（RLS）：
• 通过应用 DAX 筛选器在数据行级别限制访问。
• 示例：区域经理仅能查看其所辖区域的销售数据。
• 可在 Power BI Desktop 中测试 RLS 角色，并在服务中强制执行。
2. 对象级安全（OLS）：
• 限制对数据集中特定表或列的访问。
• 适用场景：隐藏薪资信息、敏感客户标识或机密财务指标。

3. 数据保护

为确保数据得到良好保护，您可以采取以下数据保护策略：

• 静态加密
• 传输中加密
• 审计日志
• 数据分级

4. 数据隐私与合规

企业往往在多个地区运营，使合规成为关键因素。

您应考虑的方面包括：

• 与 GDPR、HIPAA 或行业特定法规保持一致。
• 使用区域端点以保持合规。

Power BI API 开发工具与 SDK 生态

1. .NET SDK

Power BI .NET SDK 提供与 Microsoft 技术栈无缝集成的强类型接口。对于已使用 Azure、C# 或 ASP.NET 应用的企业开发者尤其合适。

用例：自动发布报表、在企业门户中嵌入仪表板以及管理工作区资产。

优势：类型安全、健壮的错误处理以及对 Azure Active Directory 身份验证流程的原生支持。

2. Python SDK

面向 Python 的 SDK（及 REST 客户端库）在偏好脚本环境的数据科学家和分析师中很受欢迎。

用例：自动刷新数据集、导出报表元数据，以及将 Power BI 工作流集成到更广泛的数据管道中。

优势：快速原型制作、丰富的数据库生态（pandas、Polars、NumPy），并易于与 Jupyter 笔记本集成。

3. JavaScript SDK

面向 JavaScript 的 SDK 是将 Power BI 内容直接嵌入 Web 应用所必需的。

用例：将报表嵌入客户门户、SaaS 产品或内部仪表板。开发者还可以在客户端代码中自定义用户交互，如筛选、导出和下钻。

优势：实时交互性、浏览器兼容性，并支持使用 React、Angular 或 Vue 等框架的单页应用（SPA）。

Power BI API 开发注意事项

1. 配置管理

在创建运行 API 调用的开发环境时，请注意以下事项：

• 将客户端 ID、客户端机密和租户 ID 等机密存储在环境变量或安全保管库（如 Azure Key Vault）中。
• 避免在源代码中硬编码敏感值。
• 在生产部署前验证权限。

2. 权限验证

在生产部署之前，确保 Azure AD 中的应用注册具有正确的 API 范围和委托或应用权限。

运行部署前脚本或检查，以确认令牌授予了预期的访问级别。

3. 版本控制与兼容性

SDK 往往会随着 Power BI API 一同演进。

您应跟踪版本更新以避免破坏性变更，特别是在使用预览功能时。在 requirements.txt（Python）或 package.json（JavaScript）中固定版本。

测试方法

要检查 API 调用是否顺畅运行，之后可以进行一些测试。

1. 使用 Postman 探索端点

进行端点测试时，可使用 Postman 交互式测试 REST API 端点。您可以导入 Power BI API 集合，通过 OAuth 2.0 进行身份验证，并在编码前尝试不同的请求/响应负载。

2. 自动化测试

为身份验证流程实现单元测试，并为端到端工作流实现集成测试。

以下是一些测试框架：

• Python：pytest + mock API
• .NET：MSTest、NUnit 或 xUnit
• JavaScript：Jest 或 Mocha 搭配 nock（用于 API 模拟）

故障排除与常见实现挑战

如果您在设置 Power BI API 时遇到困难，可参考以下错误与解决方案：

1. 常见错误

401 Unauthorized： 检查令牌有效性与 scope。

解决方法：确认访问令牌未过期，且按正确的 API 权限生成。

403 Forbidden： 权限缺失或被拒绝。

解决方法：确认调用方拥有正确的角色分配（如 Contributor、Power BI Admin，或具备所需权限的自定义角色）。

429 Too Many Requests： 触发节流；延迟后重试。

解决方法：在代码中实现指数退避或重试逻辑。监控 API 调用量并分散请求时段。

2. 连接器可见性与数据源问题

某些数据源需要本地或 VNet 数据网关。如果网关未安装、配置错误或离线，API 将无法刷新或访问数据集。

为避免这些问题，请确认网关为最新版本、正在运行，并在 Power BI 服务中正确映射到数据源。

如果数据源凭据过期或变更，数据集刷新或 API 调用也可能失败。

为防止这种情况，请定期在 Power BI 服务中更新凭据，或配置凭据轮换策略。您也可以使用托管标识或密钥保管库实现更安全、自动化的管理。

Power BI API 的高级功能

随着 Power BI 发展为核心分析平台，其高级功能与自动化能力对于在 企业范围内扩展分析方面至关重要。

接下来，让我们看看 Power BI 提供的一些高级功能。

1. 部署流水线

部署流水线为在开发、测试与生产环境间管理 Power BI 内容全生命周期提供了结构化方式。

它们有助于执行变更控制、降低风险并确保一致的部署实践。

借助这些流水线，开发者可以将数据集与报表发布到开发阶段。使用 REST API，内容随后可提升到测试与生产阶段。

2. 刷新与用户管理自动化

围绕刷新和用户权限的自动化是保持数据最新与访问合规的核心。

以下是一些自动化刷新的使用方式：

• 数据集刷新自动化：通过 Power BI REST API 或 PowerShell cmdlet，管理员可以以编程方式触发数据集刷新。
• 用户管理自动化：API 允许以编程方式添加、移除和更新工作区或数据集权限。例如，当新员工加入特定 Azure AD 组时，自动授予其报表访问权限。

3. 开发与发布自定义可视化

可以创建自定义可视化来扩展 Power BI 的能力，让组织构建定制化的数据体验。

简要步骤如下：

• 步骤 1：搭建开发环境
• 安装 Node.js 和 Power BI 可视化工具（pbiviz）。
• 运行 pbiviz new <visualName> 脚手架新项目。
• 步骤 2：开发可视化
• 使用 TypeScript、HTML 和 CSS 定义渲染逻辑。
• 绑定 Power BI 的数据模型 API，以读取字段、度量和筛选器。
• 在 Power BI Desktop 中使用开发者模式进行迭代测试，支持侧载可视化。
• 步骤 3：调试与优化
• 使用浏览器开发者工具调试渲染逻辑。
• 通过限制 DOM 操作并高效处理更新，优化大数据集下的性能。
• 步骤 4：打包可视化
• 使用 pbiviz package 构建打包，生成 .pbiviz 文件。
• 该文件可在内部分发，或上传至组织的 AppSource 租户。

结语

将 Power BI API 集成到商业智能工作流中，可以带来强大的自动化与可扩展性。它使您能够超越内置 GUI 的仪表板交付方式。

如果您希望进一步学习 Power BI，推荐我们的 Introduction to Power BI 课程和 Power BI 基础学习路径。更多阅读资源请参阅我们的 Power BI 仪表板教程或 在 Power BI 中部署与维护资产 教程。