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

文章
08/06/2024

您可以透過 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。在下方圖表中，群組、資料集和重新整理為集合。群組、資料集和重新整理是物件。

顯示異步重新整理流程的圖表。

需求

您需要下列需求才能使用 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,
    "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`。如果 `commitMode` `partialBatch`，則 `true` 的 `applyRefreshPolicy` 不受支援，且 `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

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",
        "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。

若要使用程式碼範例：

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

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

分享方式：

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

基礎 URL

需求

驗證

POST /refreshes

參數

回應

POST /refreshes

回覆屬性

限制傳回的重新整理作業數量

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

考量與限制

標準重新整理作業

Power BI Embedded

語意模型收回

重新整理作業時間限制

程式碼範例

意見反映

更多資源

分享方式：

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

基礎 URL

需求

驗證

POST /refreshes

參數

回應

POST /refreshes

回覆屬性

限制傳回的重新整理作業數量

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

考量與限制

標準重新整理作業

Power BI Embedded

語意模型收回

重新整理作業時間限制

程式碼範例

相關內容

意見反映

更多資源