Share via

使用 Power BI REST API 增強式重新整理

  • 發行項

您可以使用任何支援 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。 在下圖中，群組、數據集和重新整理是集合。 群組、 數據集和 重新 整理是 物件。

Diagram that shows asynchronous refresh flow.

需求

您需要下列需求才能使用 REST API：

  • Power BI 中的語意模型 進階版、每個使用者 進階版 或 Power BI Embedded。
  • 要用於要求 URL 的群組標識碼和數據集標識碼。
  • Dataset.ReadWrite.All 許可權範圍。

Pro 和 進階版 模型的 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,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

注意

服務一次只接受一個模型重新整理作業。 如果有目前執行的重新整理，並提交另一個 400 Bad Request 要求，HTTP 狀態代碼會傳回。

參數

若要執行增強式重新整理作業，您必須在要求本文中指定一或多個參數。 指定的參數可以指定預設值或選擇性值。 當要求指定參數時，所有其他參數都會套用至具有其預設值的作業。 如果要求未指定任何參數，則所有參數都會使用其預設值，而且會發生標準重新整理作業。

名稱 類型 預設 描述
type 列舉 automatic 要執行的處理類型。 類型與TMSL重新整理命令類型對齊：full、、clearValues、、dataOnlycalculate、 automatic和 defragment。 add不支援此類型。
commitMode 列舉 transactional 判斷是否要在批次中認可對象，還是只在完成時認可物件。 模式為 transactional 和 partialBatch。 使用 partialBatch 重新整理作業時，不會在一筆交易內發生。 每個命令都會個別認可。 如果失敗，模型可能是空的，或只包含數據的子集。 若要防止失敗，並在作業啟動前保留模型中的數據，請使用 commitMode = transactional執行作業。
maxParallelism int 10 決定可以平行執行處理命令的線程數目上限。 這個值會與 MaxParallelism 可以在TMSL Sequence 命令中或使用其他方法設定的屬性一致。
retryCount int 0 作業在失敗前重試的次數。
objects 陣列 整個模型 要處理的物件陣列。 每個物件都包含table在處理整個數據表時，或tablepartition處理分割區時。 如果未指定任何物件，則整個模型會重新整理。
applyRefreshPolicy 布林值 true 如果已定義累加式重新整理原則，則判斷是否要套用原則。 模式為 true 或 false。 如果未套用原則，則完整進程會將分割區定義維持不變，並完整重新整理數據表中的所有分割區。

如果 commitMode 為 transactional， applyRefreshPolicy 可以是 true 或 false。 如果 commitMode 為 partialBatch， applyRefreshPolicytrue 則不支援 ，且 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 會重新整理、將下一個要求排入佇列，並捨棄所有其他要求。 根據設計，您無法在已卸除的要求上查詢狀態。

回覆屬性

名稱 類型​​ 描述
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"
        }
    ]
}

解決方案是重新執行重新整理作業。 若要深入瞭解易失記憶體管理和模型收回，請參閱 模型收回。

重新整理作業時間限制

單一重新整理作業的時間上限為5小時。 如果重新整理作業未在五小時內成功完成，且 retryCount 未在要求本文中指定或指定為 0 （預設值），則會傳回逾時錯誤。

如果 retryCount 指定 1 或另一個數位，則會啟動具有五小時限制的新重新整理作業。 如果此重試作業失敗，服務會繼續重試重新整理作業，最多指定次數 retryCount ，或從第一次重新整理要求開始的增強式重新整理處理時間限制 24 小時。

當您使用重新整理資料集 REST API 規劃增強的模型重新整理解決方案時，請務必考慮這些時間限制和 retryCount 參數。 如果初始重新整理作業失敗並 retryCount 指定 1 或更多，則成功的重新整理完成可能會超過五小時。

例如，如果您使用 要求重新整理作業 "retryCount": 1，且初始重試作業從開始時間起四小時失敗，該要求的第二次重新整理作業就會開始。 如果第二次重新整理作業在三小時內成功，重新整理要求成功執行的總時間是 7 小時。

如果重新整理作業定期失敗、超過五小時的時間限制，或超過您所需的成功重新整理作業時間，請考慮減少從數據源重新整理的數據量。 您可以將重新整理分割成多個要求，例如每個數據表的要求。 您也可以在 commitMode 參數中指定 partialBatch 。

程式碼範例

如需開始使用 C# 程式代碼範例，請參閱 GitHub 上的 RestApiSample 。

若要使用程式代碼範例：

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

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

相關內容