使用 REST API 進行非同步重新整理Asynchronous refresh with the REST API

使用任何支援 REST 呼叫的程式設計語言,您可以對 Azure Analysis Services 表格式模型執行非同步的資料重新整理作業。By using any programming language that supports REST calls, you can perform asynchronous data-refresh operations on your Azure Analysis Services tabular models. 這包括相應放大查詢的唯讀複本同步處理。This includes synchronization of read-only replicas for query scale-out.

資料重新整理作業可能需要一些時間,取決於數個因素,包括資料磁碟區、使用資料分割的最佳化層級等等。這些作業傳統上是以現有的方法叫用,例如使用 TOM (表格式物件模型)、PowerShell Cmdlet 或 TMSL (表格式模型指令碼語言)。Data-refresh operations can take some time depending on a number of factors including data volume, level of optimization using partitions, etc. These operations have traditionally been invoked with existing methods such as using TOM (Tabular Object Model), PowerShell cmdlets, or TMSL (Tabular Model Scripting Language). 不過,這些方法可能需要通常不太可靠的長時間執行 HTTP 連線。However, these methods can require often unreliable, long-running HTTP connections.

Azure Analysis Services 的 REST API 可讓資料重新整理作業以非同步方式進行。The REST API for Azure Analysis Services enables data-refresh operations to be carried out asynchronously. 使用 REST API,便不需要來自用戶端應用程式的長時間執行 HTTP 連線。By using the REST API, long-running HTTP connections from client applications aren't necessary. 針對可靠性還有其他內建的功能,例如自動重試次數、批次認可。There are also other built-in features for reliability, such as auto retries and batched commits.

基底 URLBase URL

基底 URL 遵循以下格式:The base URL follows this format:

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

例如,名為 AdventureWorks 的模型,在名為 myserver 的伺服器上,位於 West US Azure 區域。For example, consider a model named AdventureWorks on a server named myserver, located in the West US Azure region. 伺服器名稱是:The server name is:

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

此伺服器名稱的基底 URL 是:The base URL for this server name is:

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

藉由使用基底 URL,可以根據下列參數附加資源和作業:By using the base URL, resources and operations can be appended based on the following parameters:

非同步重新整理

  • 任何以 s 結尾的項目是集合。Anything that ends in s is a collection.
  • 任何以 () 結尾的項目是函式。Anything that ends with () is a function.
  • 任何其他項目是資源/物件。Anything else is a resource/object.

例如,您可以對重新整理集合使用 POST 動詞以執行重新整理作業:For example, you can use the POST verb on the Refreshes collection to perform a refresh operation:

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

AuthenticationAuthentication

所有呼叫必須使用授權標頭中的有效 Azure Active Directory (OAuth 2) 權杖進行驗證,而且必須符合下列需求:All calls must be authenticated with a valid Azure Active Directory (OAuth 2) token in the Authorization header and must meet the following requirements:

  • 權杖必須是使用者權杖或應用程式服務主體。The token must be either a user token or an application service principal.

  • 權杖的對象必須正確設定為 https://*.asazure.windows.netThe token must have the correct audience set to https://*.asazure.windows.net.

  • 使用者或應用程式必須具有對伺服器或模型足夠的權限,才能執行要求的呼叫。The user or application must have sufficient permissions on the server or model to make the requested call. 權限層級由模型中的角色或伺服器上的系統管理員群組決定。The permission level is determined by roles within the model or the admin group on the server.

    重要

    現階段需要伺服器管理員角色權限。Currently, server admin role permissions are necessary.

POST /refreshesPOST /refreshes

若要執行重新整理作業,對 /refreshes 集合使用 POST 動詞以在集合中新增重新整理項目。To perform a refresh operation, use the POST verb on the /refreshes collection to add a new refresh item to the collection. 回應中的位置標頭 (Location) 包含重新整理識別碼。The Location header in the response includes the refresh ID. 用戶端應用程式可以中斷連線,如果必要可在稍後再檢查狀態,因為這是非同步的。The client application can disconnect and check the status later if required because it is asynchronous.

模型一次只會接受一個重新整理作業。Only one refresh operation is accepted at a time for a model. 如果目前正在執行重新整理作業時又送出另一個,會傳回 409 衝突 HTTP 狀態碼。If there's a current running refresh operation and another is submitted, the 409 Conflict HTTP status code is returned.

主體大概像這樣:The body may resemble the following:

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

參數Parameters

不一定要指定參數。Specifying parameters is not required. 會套用預設值。The default is applied.

名稱Name 類型Type 說明Description 預設值Default
Type 例舉Enum 要執行的處理類型。The type of processing to perform. Type 對應於 TMSL 的 refresh 命令類型:full、clearValues、calculate、dataOnly、automatic 和 defragment。The types are aligned with the TMSL refresh command types: full, clearValues, calculate, dataOnly, automatic, and defragment. 不支援 Add 類型。Add type is not supported. automaticautomatic
CommitMode 例舉Enum 決定物件要批次認可或只在完成時認可。Determines if objects will be committed in batches or only when complete. CommitMode 包括:default、transactional、partialBatch。Modes include: default, transactional, partialBatch. transactionaltransactional
MaxParallelism IntInt 這個值決定了可以平行執行處理命令的執行緒數目上限。This value determines the maximum number of threads on which to run processing commands in parallel. 此值與 MaxParallelism 屬性對應,後者可以在 TMSL 的 sequence 命令中設定,或使用其他方法設定。This value aligned with the MaxParallelism property that can be set in the TMSL Sequence command or using other methods. 1010
RetryCount IntInt 表示作業失敗之前重試的次數。Indicates the number of times the operation will retry before failing. 00
Objects 陣列Array 要處理的物件陣列。An array of objects to be processed. 每個物件包含:「資料表」(處理整份資料表時),或「資料表」和「分割區」(處理資料分割時)。Each object includes: "table" when processing the entire table or "table" and "partition" when processing a partition. 如未指定物件,會重新整理整個模型。If no objects are specified, the whole model is refreshed. 處理整個模型Process the entire model

CommitMode 等於 partialBatch。CommitMode is equal to partialBatch. 當進行大型資料集的初始載入需要數小時時,會使用它。It's used when doing an initial load of large datasets that could take hours. 如果在成功認可一或多個批次之後,重新整理作業失敗,已成功認可的批次會保留認可 (不會回復已成功認可的批次)。If the refresh operation fails after successfully committing one or more batches, the successfully committed batches will remain committed (it will not roll back successfully committed batches).

注意

在本文撰寫之際,批次大小是 MaxParallelism 值,但此值無法變更。At time of writing, the batch size is the MaxParallelism value, but this value could change.

GET /refreshes/<refreshId>GET /refreshes/<refreshId>

若要檢查重新整理作業的狀態,請對重新整理識別碼使用 GET 動詞命令。To check the status of a refresh operation, use the GET verb on the refresh ID. 以下是回應主體的範例。Here's an example of the response body. 如果作業正在進行中,會傳回 inProgress 狀態。If the operation is in progress, inProgress is returned in status.

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

POST /refreshesGET /refreshes

若要取得模型過去的重新整理作業清單,對 /refreshes 集合使用 GET 動詞。To get a list of historical refresh operations for a model, use the GET verb on the /refreshes collection. 以下是回應主體的範例。Here's an example of the response body.

注意

在本文撰寫之際,系統會儲存並傳回過去 30 天的重新整理作業,但此數字無法變更。At time of writing, the last 30 days of refresh operations are stored and returned, but this number could change.

[
    {
        "refreshId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "startTime": "2017-12-09T01:58:04.76",
        "endTime": "2017-12-09T01:58:12.607",
        "status": "succeeded"
    },
    {
        "refreshId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2017-12-07T02:05:48.32",
        "endTime": "2017-12-07T02:05:54.913",
        "status": "succeeded"
    }
]

DELETE /refreshes/<refreshId>DELETE /refreshes/<refreshId>

若要取消進行中的重新整理作業,請對重新整理識別碼使用 DELETE 動詞。To cancel an in-progress refresh operation, use the DELETE verb on the refresh ID.

POST /syncPOST /sync

執行重新整理作業後,可能需要將新的資料與相應放大查詢的複本同步處理。若要為模型執行同步處理作業,對 /sync 函式使用 POST 動詞。Having performed refresh operations, it may be necessary to synchronize the new data with replicas for query scale-out. To perform a synchronize operation for a model, use the POST verb on the /sync function. 回應中的位置標頭 (Location) 包含重新整理作業的識別碼。The Location header in the response includes the sync operation ID.

GET /sync statusGET /sync status

若要查看同步處理作業的狀態,請使用 GET 動詞,並傳遞作業識別碼作為參數。To check the status of a sync operation, use the GET verb passing the operation ID as a parameter. 以下是回應主體的範例:Here's an example of the response body:

{
    "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 的值:Values for syncstate:

  • 0︰複寫。0: Replicating. 資料庫檔案會被複寫到目標資料夾。Database files are being replicated to a target folder.
  • 1:重新序列化。1: Rehydrating. 只有唯讀伺服器執行個體上的資料庫會被序列化。The database is being rehydrated on read-only server instance(s).
  • 2:完成。2: Completed. 同步處理作業順利完成。The sync operation completed successfully.
  • 3:失敗。3: Failed. 同步處理作業失敗。The sync operation failed.
  • 4:正在結束。4: Finalizing. 同步處理作業已完成,但正在執行清除步驟。The sync operation has completed but is performing cleanup steps.

程式碼範例Code sample

GitHub 上的 RestApiSample 是 C# 程式碼範例,可協助您開始。Here's a C# code sample to get you started, RestApiSample on GitHub.

使用程式碼範例To use the code sample

  1. 複製或下載存放庫。Clone or download the repo. 開啟 RestApiSample 解決方案。Open the RestApiSample solution.
  2. 找到 client.BaseAddress = … 這一行Find the line client.BaseAddress = … 並提供您的基底 URLand provide your base URL.

此程式碼範例會使用服務主體驗證。The code sample uses service principal authentication.

服務主體Service principal

如需關於如何在 Azure 中設定服務主體及指派必要權限的詳細資訊,請參閱建立服務主體 - Azure 入口網站將服務主體新增至伺服器管理員角色See Create service principal - Azure portal and Add a service principal to the server administrator role for more info on how to set up a service principal and assign the necessary permissions in Azure AS. 完成這些步驟後,請完成下列額外步驟:Once you've completed the steps, complete the following additional steps:

  1. 在程式碼範例中,找到 string authority = …,將 common 取代為貴組織的租用戶識別碼。In the code sample, find string authority = …, replace common with your organization’s tenant ID.
  2. 註解/取消註解,以便使用 ClientCredential 類別來具現化認證物件。Comment/uncomment so the ClientCredential class is used to instantiate the cred object. 請確定目前存取 <App ID> 和 <App Key> 值的方式很安全,或為服務主體使用憑證型驗證。Ensure the <App ID> and <App Key> values are accessed in a secure way or use certificate-based authentication for service principals.
  3. 執行範例。Run the sample.

請參閱See also

範例 Samples
REST APIREST API