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

  • 项目

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

针对大型复杂分区模型的优化刷新，习惯上是通过使用 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。 在下图中，多个“组”、“数据集”和“刷新”是集合。 单个“组”、“数据集”和“刷新”是对象。

Diagram that shows asynchronous refresh flow.

要求

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

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

根据基于 API 的 Pro 和 Premium 模型刷新的一般限制，对刷新次数进行了限制。

身份验证

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

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

注意

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

POST /refreshes

若要进行刷新，请在 /refreshes 集合中使用 POST 谓词将新的 refresh 对象添加到集合中。 响应中的 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,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

注意

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

parameters

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

名称 类型 默认 说明
type 枚举 automatic 要执行的处理类型。 类型与 TMSL refresh 命令类型一致：full、clearValues、calculate、dataOnly、automatic 和 defragment。 不支持 add 类型。
commitMode 枚举 transactional 确定是批量提交对象还是仅在完成后提交对象。 模式为 transactional 和 partialBatch。 使用 partialBatch 时，刷新操作不会在一个事务内发生。 每个命令单独提交。 如果出现故障，模型可能为空或仅包含数据的子集。 为了防止失败并保留在操作开始之前已位于模型中的数据，请使用 commitMode = transactional 执行操作。
maxParallelism int 10 确定可以并行运行处理命令的线程的最大数量。 此值与 MaxParallelism 属性一致，可在 TMSL Sequence 命令中或使用其他方法设置它。
retryCount int 0 操作在失败之前重试的次数。
objects 数组 整个模型 要处理的对象数组。 每个对象都包括 table（在处理整个表时），或者包括 table 和 partition（在处理分区时）。 如果没有指定对象，则刷新整个模型。
applyRefreshPolicy 布尔 true 如果定义了增量刷新策略，则确定是否应用该策略。 模式为 true 或 false。 如果未应用策略，完全处理会保持分区定义不变，并且会完全刷新表中的所有分区。

如果 commitMode 为 transactional，则 applyRefreshPolicy 可以为 true 或 false。 如果 commitMode 为 partialBatch，则不支持 applyRefreshPolicy 为 true，并且必须将 applyRefreshPolicy 设置为 false。
effectiveDate Date 当前日期 如果应用了增量刷新策略，则 effectiveDate 参数将替代当前日期。 如果未指定它，则使用 UTC 来确定当前日期。

响应

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",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

注意

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

响应属性

名称 Type 说明
requestId Guid 刷新请求的标识符。 你需要 requestId 查询各个刷新操作状态或取消正在进行的刷新操作。
refreshType String OnDemand 指示刷新是通过 Power BI 门户以交互方式触发的。
Scheduled 指示模型刷新计划触发了刷新。
ViaApi 指示 API 调用触发了刷新。
ViaEnhancedApi 指示 API 调用触发了增强型刷新。
startTime String 刷新开始的日期和时间。
endTime String 刷新结束的日期和时间。
status String Completed 指示刷新操作已成功完成。
Failed 指示刷新操作失败。
Unknown 指示无法确定完成状态。 在此状态下，endTime 为空。
Disabled 指示通过选择性刷新禁用了刷新。
Cancelled 指示已成功取消刷新。
extendedStatus String 补充 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>

若要检查刷新操作的状态，请通过指定 requestId 在 refresh 对象上使用 GET 谓词。 如果操作正在进行中，则 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>

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

例如，应用于对象的

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

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

刷新操作时间限制

单个刷新操作的最长时间为 5 小时。 如果刷新操作没有在五小时限制内成功完成，并且 retryCount 未指定或者在请求正文中被指定为 0（默认值），则返回超时错误。

如果 retryCount 指定 1 或另一个数字，则会启动限制为 5 小时的新刷新操作。 如果此重试操作失败，服务将继续重试刷新操作，直到到达 retryCount 指定的最大重试次数，或从第一次刷新请求开始起 24 小时内的增强型刷新处理时间限制。

使用刷新数据集 REST API 计划增强型模型刷新解决方案时，请务必考虑这些时间限制和 retryCount 参数。 如果初始刷新操作失败且 retryCount 指定 1 或更大数字，则刷新操作的成功完成可能会超过 5 小时。

例如，如果使用 "retryCount": 1 请求刷新操作，并且初始重试操作在开始时间四小时后失败，那么该请求的第二次刷新操作就开始了。 如果第二次刷新操作在三小时内成功，则成功执行刷新请求的总时间为 7 小时。

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

代码示例

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

使用代码示例的步骤：

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

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

相关内容