共用方式為

使用 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 的群組識別碼和資料集識別碼。
  • 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 int 10 決定可以平行執行處理命令的線程數量上限。 這個值會與可以在 TMSL Sequence 命令中設定的 MaxParallelism 屬性或使用其他方法設定的屬性一致。
retryCount int 0 作業在失敗前重試的次數。
objects 陣列 整個模型 待處理的物件陣列。 在處理整個資料表時，每個物件都包含 table，或在處理分割區時包含 table 和 partition。 如果尚未指定任何物件，則整個模型會重新整理。
applyRefreshPolicy 布林值 true 如果已定義一個累加式重新整理原則，則判斷是否要套用原則。 模式是 true 或 false。 如果未套用此原則，則完整流程會將資料分割定義保留不變，而且會完整重新整理資料表中的所有資料分割。

如果 commitMode 是 transactional，applyRefreshPolicy 可以是 true 或 false。 如果 commitModepartialBatch，則 true 的 applyRefreshPolicy 不受支援，且 applyRefreshPolicy 必須設定為 false。
effectiveDate Date 目前日期 如果套用累加式重新整理原則，effectiveDate 參數會覆寫目前日期。 如果未指定，則會使用 'Refresh' 底下的時區組態來判斷目前日期。
timeout String 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

POST /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 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，以在重新整理物件上使用 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，以在重新整理物件上使用 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 六小時。 如果容量在六小時內恢復，那麼重新整理作業會自動恢復。 如果容量在超過六小時後恢復，重新整理作業可能會傳回逾時錯誤。 接下來，您必須重新啟動重新整理作業。

語意模型收回

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。

若要使用程式碼範例：

  1. 複製或下載存放庫。
  2. 開啟 RestApiSample 解決方案。
  3. 尋找行 client.BaseAddress = …，並提供您的基礎 URL。

程式碼範例會使用服務主體驗證。

相關內容