使用 REST API 進行非同步重新整理

發行項
10/24/2023

藉由使用任何支援 REST 呼叫的程式設計語言，您可以在 Azure Analysis Services 表格式模型上執行非同步資料重新整理作業。這包括查詢向外延展的唯讀複本同步處理。

資料重新整理作業可能需要一些時間，視許多因素而定，包括資料量、使用資料分割的優化層級等等。這些作業傳統上是以現有的方法叫用，例如使用 TOM （表格式物件模型）、 PowerShell Cmdlet 或 TMSL （表格式模型指令碼語言）。不過，這些方法通常需要不可靠且長時間執行的 HTTP 連線。

Azure Analysis Services 的 REST API 可讓資料重新整理作業以非同步方式執行。藉由使用 REST API，不需要從用戶端應用程式進行長時間執行的 HTTP 連線。還有其他內建功能可用於可靠性，例如自動重試和批次認可。

基礎 URL

基底 URL 遵循下列格式：

https://<rollout>.asazure.windows.net/servers/<serverName>/models/<resource>/

例如，假設位於美國西部 Azure 區域的伺服器上名為 myserver AdventureWorks 的模型。伺服器名稱為：

asazure://westus.asazure.windows.net/myserver

此伺服器名稱的基底 URL 為：

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/

藉由使用基底 URL，可以根據下列參數附加資源和作業：

Diagram that shows asynchronous refresh logic.

以結尾的任何專案都是集合。
以（）結尾的任何專案都是函式。
任何其他專案都是資源/物件。

例如，您可以使用 Refreshes 集合上的 POST 動詞來執行重新整理作業：

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/refreshes

驗證

所有呼叫都必須使用授權標頭中的有效 Microsoft Entra ID （OAuth 2）權杖進行驗證，且必須符合下列需求：

權杖必須是使用者權杖或應用程式服務主體。
權杖必須將正確的物件設定為 https://*.asazure.windows.net 。
使用者或應用程式必須有足夠的伺服器或模型許可權，才能進行要求的呼叫。許可權等級取決於伺服器上的模型或系統管理員群組內的角色。

重要

目前， 需要伺服器管理員 角色許可權。

POST /refreshes

若要執行重新整理作業，請使用 /refreshes 集合上的 POST 動詞，將新的重新整理專案新增至集合。回應中的 Location 標頭包含重新整理識別碼。用戶端應用程式稍後可以中斷連線，並視需要檢查狀態，因為它是非同步。

模型一次只接受一個重新整理作業。如果有目前執行的重新整理作業，另一個作業已提交，則會傳回 409 衝突 HTTP 狀態碼。

本文可能如下所示：

{
    "Type": "Full",
    "CommitMode": "transactional",
    "MaxParallelism": 2,
    "RetryCount": 2,
    "Objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

參數

不需要指定參數。會套用預設值。

名稱	類型	描述	預設
`Type`	列舉	要執行的處理類型。這些類型會與 TMSL 重新整理命令類型一致：full、clearValues、calculate、dataOnly、automatic 和 defragment。不支援新增類型。	automatic
`CommitMode`	列舉	判斷物件是否會在批次中認可，或只有在完成時才會認可。模式包括：預設、交易式、partialBatch。	transactional
`MaxParallelism`	int	這個值會決定平行執行處理命令的執行緒數目上限。這個值與可以在 TMSL Sequence 命令中設定的 MaxParallelism 屬性一致，或使用其他方法。	10
`RetryCount`	int	指出作業在失敗前會重試的次數。	0
`Objects`	陣列	要處理的物件陣列。處理整個資料表或處理分割區時，每個物件都包含：「table」和「partition」。如果未指定任何物件，則會重新整理整個模型。	處理整個模型

CommitMode 等於 partialBatch。執行可能需要數小時的大型資料集初始載入時，會使用它。如果重新整理作業在成功認可一或多個批次之後失敗，則成功認可的批次將會維持認可（不會回復成功認可的批次）。

注意

在撰寫時，批次大小是 MaxParallelism 值，但此值可能會變更。

狀態值

狀態值	描述
`notStarted`	作業尚未啟動。
`inProgress`	進行中的作業。
`timedOut`	作業已根據使用者指定的逾時時間逾時。
`cancelled`	使用者或系統取消的作業。
`failed`	作業失敗。
`succeeded`	作業成功。

GET /refreshes/ < refreshId>

若要檢查重新整理作業的狀態，請在重新整理識別碼上使用 GET 動詞命令。以下是回應本文的範例。如果作業正在進行中， inProgress 則會以狀態傳回。

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

GET /refreshes

若要取得模型的歷程記錄重新整理作業清單，請在 /refreshes 集合上使用 GET 動詞。以下是回應本文的範例。

注意

在寫入時，會儲存並傳回過去 30 天的重新整理作業，但這個數位可能會變更。

[
    {
        "refreshId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "startTime": "2017-12-07T02:06:57.1838734Z",
        "endTime": "2017-12-07T02:07:00.4929675Z",
        "status": "succeeded"
    },
    {
        "refreshId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2017-12-07T01:05:54.157324Z",
        "endTime": "2017-12-07T01:05:57.353371Z",
        "status": "succeeded"
    }
]

DELETE /refreshes/ < refreshId>

若要取消進行中的重新整理作業，請在重新整理識別碼上使用 DELETE 動詞。

POST /sync

執行重新整理作業之後，可能需要將新的資料與查詢向外延展的複本同步處理。若要執行模型的同步處理作業，請在 /sync 函式上使用 POST 動詞。回應中的 Location 標頭包含同步作業識別碼。

GET /sync status

若要檢查同步作業的狀態，請使用 GET 動詞將作業識別碼傳遞為參數。以下是回應本文的範例：

{
    "operationId": "cd5e16c6-6d4e-4347-86a0-762bdf5b4875",
    "database": "AdventureWorks2",
    "UpdatedAt": "2017-12-09T02:44:26.18",
    "StartedAt": "2017-12-09T02:44:20.743",
    "syncstate": 2,
    "details": null
}

syncstate的值：

0：複寫。資料庫檔案正在複寫至目的檔案夾。
1：補水。資料庫正在唯讀伺服器實例上解除凍結。
2：已完成。同步作業已順利完成。
3：失敗。同步作業失敗。
4：完成。同步作業已完成，但正在執行清除步驟。

程式碼範例

以下是可讓您在 GitHub 上開始使用的 C# 程式碼範例 RestApiSample。

若要使用程式碼範例

複製或下載存放庫。開啟 RestApiSample 解決方案。
尋找行 用戶端。BaseAddress = ... 並提供您的基底 URL 。

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

服務主體

如需如何在 Azure AS 中設定服務主體及指派必要許可權的詳細資訊，請參閱建立服務主體 - Azure 入口網站和將服務主體新增至伺服器管理員角色。完成這些步驟之後，請完成下列其他步驟：

在程式碼範例中，尋找 字串授權單位 = ... ，以組織的租使用者識別碼取代 Common 。
批註/取消批註，以便使用 ClientCredential 類別來具現化 cred 物件。 <請確定應用程式識別碼 > 和 < 應用程式金鑰 > 值是以安全的方式存取，或使用服務主體的憑證式驗證。
執行範例。

另請參閱

範例
 REST API