使用 Power BI REST API 的增强型刷新

项目
01/23/2025

可以使用任何支持 REST 调用的编程语言，通过 Power BI 刷新数据集 REST API 执行语义模型刷新操作。

对于大型和复杂的分区模型，刷新优化传统上是通过编程方法来调用的，这些方法包括使用 TOM（表格对象模型）、PowerShell cmdlet 或 TMSL（表格模型脚本语言）。但是，这些方法需要长时间运行的 HTTP 连接，这些连接可能不可靠。

Power BI 刷新数据集 REST API 可以异步执行模型刷新操作，因此不需要从客户端应用程序建立长时间运行的 HTTP 连接。与标准刷新操作相比，由 REST API 增强的刷新操作提供了更多自定义选项，并且以下功能对大型模型有帮助：

批处理提交
表和分区级刷新
应用增量刷新策略
GET 刷新详细信息
刷新取消
超时配置

注意

以前，增强型刷新称为“使用 REST API 的异步刷新”。但是，使用刷新数据集 REST API 的标准刷新由于其固有特性也会异步运行。
增强的 Power BI REST API 刷新操作不会自动刷新磁贴缓存。仅当用户访问报表时，磁贴缓存才会刷新。

基 URL

基本URL采用以下格式：

https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes

可以根据参数将资源和操作追加到基 URL。在下图中，多个“组”、“数据集”和“刷新”是集合。单个“组”、“数据集”和“刷新”是对象。

显示异步刷新流的图显示异步刷新流的关系图。。

要求

需要满足以下要求才能使用 REST API：

Power BI Premium、Premium per user 或 Power BI Embedded 中的语义模型。
有一个要在请求 URL 中使用的组 ID 和数据集 ID。
Dataset.ReadWrite.All 权限范围。

根据 Pro 和 Premium 模型的基于 API 的刷新的常规限制，刷新次数受到限制。

认证

所有调用都必须使用授权标头中的有效Microsoft Entra ID OAuth 2 令牌进行身份验证。令牌必须满足以下要求：

要么是用户令牌，要么是应用程序服务主体。
将受众正确设置为 https://api.powerbi.com。
由对模型具有足够权限的用户或应用程序使用。

注意

REST API 修改不会更改模型刷新当前定义的权限。

POST /refreshes

若要执行刷新，请使用 /refreshes 集合上的 POST 谓词向集合添加新的刷新对象。响应中的 Location 标头包含 requestId。由于操作是异步的，因此客户端应用程序可以断开连接并使用 requestId，以便稍后在必要时检查状态。

以下代码显示了示例请求：

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

请求正文可能类似于以下示例：

{
    "type": "Full",
    "commitMode": "transactional",
    "maxParallelism": 2,
    "retryCount": 2,
    "timeout": "02:00:00",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

注意

服务一次只接受一个模型刷新操作。如果当前有一个正在运行的刷新，而另一个请求已提交，则返回 400 Bad Request HTTP 状态代码。

参数

若要执行增强的刷新操作，必须在请求正文中指定一个或多个参数。指定的参数可以指定默认值或可选值。当请求指定参数时，所有其他参数都应用于具有其默认值的操作。如果请求未指定任何参数，则所有参数都使用其默认值，并发生标准刷新操作。

名字	类型	违约	描述
`type`	枚举	`automatic`	要执行的处理类型。类型与 TMSL 刷新命令类型保持一致：`full`、`clearValues`、`calculate`、`dataOnly`、`automatic`和 `defragment`。不支持 `add` 类型。
`commitMode`	枚举	`transactional`	确定是批量提交对象还是仅在完成时提交对象。模式为 `transactional` 和 `partialBatch`。使用 `partialBatch` 时，刷新操作不会在单个事务中进行。每个命令单独提交。如果发生故障，模型可能为空或仅包含一部分数据。若要防止故障，并在操作启动前保留模型中的数据，请使用 `commitMode = transactional`执行该操作。
`maxParallelism`	整型	`10`	确定可并行运行处理命令的最大线程数。此值与可以在 TMSL `Sequence` 命令中设置的 `MaxParallelism` 属性保持一致，也可以使用其他方法进行设置。
`retryCount`	整型	`0`	操作在失败前重试的次数。
`objects`	数组	整个模型	要处理的对象数组。每个对象在处理整个表时包括 `table`，或者在处理分区时 `table` 和 `partition`。如果未指定任何对象，则整个模型将刷新。
`applyRefreshPolicy`	布尔	`true`	如果定义了增量刷新策略，则确定是否应用策略。模式是 `true` 或 `false`。如果未应用策略，则整个进程将保留分区定义不变，并完全刷新表中的所有分区。如果 `commitMode` 是 `transactional`，则 `applyRefreshPolicy` 可以是 `true` 或 `false`。如果 `commitMode` 是 `partialBatch`，则不支持 `true` 的 `applyRefreshPolicy`，并且必须将 `applyRefreshPolicy` 设置为 `false`。
`effectiveDate`	日期	当前日期	如果应用增量刷新策略，`effectiveDate` 参数将替代当前日期。如果未指定，则使用 “刷新”下的时区配置来确定当前日期。
`timeout`	字符串	05：00：00 （5 小时）	如果指定了 `timeout`，则语义模型上的每次数据刷新操作都遵循该超时设定。如果指定了 `retryCount`，单个刷新请求可以包含多次尝试，这可能会导致总刷新持续时间超过指定的超时。例如，将 `timeout` 设置为 1 小时，`retryCount` 为 2 可能会导致总刷新持续时间长达 3 小时。用户可以调整 `timeout`，以缩短刷新持续时间，以加快故障检测速度，或者将刷新时间延长到默认 5 小时以上，以便进行更复杂的数据刷新。但是，总刷新持续时间（包括重试）不能超过 24 小时。

响应

202 Accepted

响应还包括一个 Location 响应标头字段，用于将调用方指向已创建和接受的刷新操作。 Location 是指请求创建的新资源的位置，其中包括一些增强型刷新操作所需的 requestId。例如，在以下响应中，requestId 是响应 87f31ef7-1e3a-4006-9b0b-191693e79e9e中的最后一个标识符。

x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e

GET /refreshes

使用 /refreshes 集合上的 GET 谓词列出历史刷新操作、当前刷新操作和挂起的刷新操作。

响应正文可能如以下示例所示：

[
    {
        "requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T02:06:57.1838734Z",
        "endTime": "2020-12-07T02:07:00.4929675Z",
        "status": "Completed",
        "extendedStatus": "Completed"
    },
    {
        "requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "refreshType": "ViaEnhancedApi",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

注意

如果短时间内请求过多，Power BI 可能会删除请求。 Power BI 执行刷新、将下一个请求排队，并删除其他所有请求。根据设计，无法查询已删除请求的状态。

响应属性

名字	类型	描述
`requestId`	Guid	刷新请求的标识符。需要 `requestId` 查询单个刷新操作状态或取消正在进行的刷新操作。
`refreshType`	字符串	`OnDemand` 指示刷新是通过 Power BI 门户以交互方式触发的。 `Scheduled` 指示模型刷新计划触发了刷新。 `ViaApi` 指示 API 调用触发刷新。 `ViaEnhancedApi` 指示 API 调用触发了增强刷新。
`startTime`	字符串	刷新开始的日期和时间。
`endTime`	字符串	刷新结束的日期和时间。
`status`	字符串	`Completed` 指示刷新操作已成功完成。 `Failed` 指示刷新操作失败。 `Unknown` 指示无法确定完成状态。在此状态中，`endTime` 为空。 `Disabled` 指示通过选择性刷新禁用了刷新。 `Cancelled` 指示刷新已成功取消。
`extendedStatus`	字符串	扩充 `status` 属性以提供更多信息。

注意

在 Azure Analysis Services 中，完成的 status 结果为 succeeded。如果将 Azure Analysis Services 解决方案迁移到 Power BI，可能需要修改解决方案。

限制返回的刷新操作数

Power BI REST API 支持使用可选的 $top 参数限制刷新历史记录中请求的条目数。如果未指定，则默认值为所有可用条目。

GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}

GET/refreshes/<requestId>

若要检查刷新操作的状态，请在刷新对象上使用 GET 方法，并指定 requestId。如果操作正在进行，status 返回 InProgress，如以下示例响应正文所示：

{
    "startTime": "2020-12-07T02:06:57.1838734Z",
    "endTime": "2020-12-07T02:07:00.4929675Z",
    "type": "Full",
    "status": "InProgress",
    "currentRefreshType": "Full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "InProgress"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "InProgress"
        }
    ]
}

DELETE/refreshes/<requestId>

若要取消正在进行的增强刷新操作，请在刷新对象上使用 DELETE 动词，并指定 requestId。

例如，

DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac

注意事项和限制

刷新操作具有以下注意事项和限制：

标准刷新操作

无法使用 DELETE /refreshes/<requestId> 取消通过在门户中选择“刷新”按钮触发的计划或按需模型刷新。
通过在门户中选择“刷新”按钮触发的计划和按需模型刷新不支持使用 GET /refreshes/<requestId> 获取刷新操作详细信息。
“获取详细信息”和“取消”是仅用于增强型刷新的新操作。标准刷新不支持这些操作。

Power BI Embedded

如果在 Power BI 门户中或使用 PowerShell 手动暂停了容量，或者发生系统中断，那么任何正在进行的增强型刷新操作将最多在 InProgress 状态保持 6 个小时。如果容量在 6 小时内恢复，则刷新操作会自动恢复。如果容量在 6 小时后才恢复，刷新操作可能返回超时错误。然后，必须重启刷新操作。

语义模型逐出

Power BI 使用动态内存管理来优化容量内存。如果在刷新操作期间从内存中逐出模型，可能会返回以下错误：

{
    "messages": [
        {
            "code": "0xC11C0020",
            "message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
            "type": "Error"
        }
    ]
}

解决方案是重新运行刷新操作。若要详细了解动态内存管理和模型逐出，请参阅模型逐出。

刷新操作时间限制

如果指定了 retryCount，刷新操作可能包括多次尝试。每次尝试的默认超时为 5 小时，可以使用 timeout 参数进行调整。总刷新持续时间（包括重试）不得超过 24 小时。

如果 retryCount 指定数字，则新的刷新操作将从超时限制开始。服务重试此操作，直到操作成功、达到 retryCount 限制，或达到第一次尝试后的 24 小时最大值。

可以调整 timeout 以缩短刷新持续时间，以加快故障检测速度，或者将刷新时间延长到默认 5 小时以上，以便进行更复杂的数据刷新。

使用刷新数据集 REST API 规划语义模型刷新时，请考虑时间限制和 retryCount 参数。如果初始尝试失败且 retryCount 设置为 1 或更大，刷新可能会超过超时。如果请求刷新时设置“retryCount”为1，且第一次尝试在 4 小时后失败，则会开始第二次尝试。如果此操作在 3 小时内成功，则刷新的总时间为 7 小时。

如果刷新操作定期失败、超出超时时间限制或超出所需的成功刷新操作时间，请考虑减少从数据源刷新的数据量。可以将刷新拆分为多个请求，例如为每个表发送一个请求。还可在 commitMode 参数中指定 partialBatch。

代码示例

有关入门的 C# 代码示例，请参阅 GitHub 上的 RestApiSample。

若要使用代码示例，请使用：

克隆或下载存储库。
打开 RestApiSample 解决方案。
查找 client.BaseAddress = … 行并提供基 URL。

该代码示例使用服务主体身份验证。

通过

使用 Power BI REST API 的增强型刷新

基 URL

要求

认证

POST /refreshes

参数

响应

GET /refreshes

响应属性

限制返回的刷新操作数

GET/refreshes/<requestId>

DELETE/refreshes/<requestId>

注意事项和限制

标准刷新操作

Power BI Embedded

语义模型逐出

刷新操作时间限制

代码示例

反馈

其他资源

通过

使用 Power BI REST API 的增强型刷新

基 URL

要求

认证

POST /refreshes

参数

响应

GET /refreshes

响应属性

限制返回的刷新操作数

GET/refreshes/<requestId>

DELETE/refreshes/<requestId>

注意事项和限制

标准刷新操作

Power BI Embedded

语义模型逐出

刷新操作时间限制

代码示例

相关内容

反馈

其他资源