使用 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.chinacloudapi.cn/servers/<serverName>/models/<resource>/

例如,假设某个模型名为 AdventureWorks,位于中国北部 Azure 区域中名为 myserver 的服务器上。For example, consider a model named AdventureWorks on a server named myserver, located in the China North Azure region. 此服务器名称为:The server name is:

asazure://chinanorth.asazure.chinacloudapi.cn/myserver 

此服务器名称的基 URL 为:The base URL for this server name is:

https://chinanorth.asazure.chinacloudapi.cn/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.

例如,可以在 Refreshes 集合中使用 POST 谓词来执行刷新操作:For example, you can use the POST verb on the Refreshes collection to perform a refresh operation:

https://chinanorth.asazure.chinacloudapi.cn/servers/myserver/models/AdventureWorks/refreshes

身份验证Authentication

所有调用必须使用 Authorization 标头中的有效 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.chinacloudapi.cnThe token must have the correct audience set to https://*.asazure.chinacloudapi.cn.

  • 用户或应用程序必须在服务器或模型中具有足够的权限才能发出请求的调用。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.

    Important

    目前,服务器管理员角色权限是必需的。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 标头包含刷新 ID。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"
        }
    ]
}

parametersParameters

不需要指定参数。Specifying parameters is not required. 将应用默认值。The default is applied.

名称Name 类型Type 说明Description 默认Default
Type 枚举Enum 要执行的处理类型。The type of processing to perform. 类型与 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. 模式包括: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. 10 个10
RetryCount intInt 指示操作在失败之前要重试的次数。Indicates the number of times the operation will retry before failing. 00
Objects ArrayArray 要处理的对象数组。An array of objects to be processed. 每个对象包含:“table”(处理整个表时),或者“table”和“partition”(处理分区时)。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. 针对大型数据集执行可能需要几个小时的初始加载时,将会使用 CommitMode。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).

Note

在撰写本文时,批大小为 MaxParallelism 值,但可以更改此值。At time of writing, the batch size is the MaxParallelism value, but this value could change.

状态值Status values

状态值Status value 说明Description
notStarted 操作尚未开始。Operation not yet started.
inProgress 操作正在进行。Operation in progress.
timedOut 根据用户指定的超时,操作已超时。Operation timed out based on user specified timeout.
cancelled 用户或系统已取消操作。Operation canceled by user or system.
failed 操作失败。Operation failed.
succeeded 操作成功。Operation succeeded.

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

若要检查刷新操作的状态,可以在刷新 ID 中使用 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. 如果操作正在进行,则会在状态中返回 inProgressIf 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"
        }
    ]
}

GET /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.

Note

在撰写本文时,将存储并返回过去 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>

若要取消正在进行的刷新操作,可以在刷新 ID 中使用 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 标头包含同步操作 ID。The Location header in the response includes the sync operation ID.

GET /sync statusGET /sync status

若要检查同步操作的状态,可以使用 GET 谓词,以参数的形式传递操作 ID。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

下面是一个可以帮助你入门的 C# 代码示例:GitHub 上的 RestApiSampleHere'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 AS 中设置服务主体和分配必要权限的详细信息,请参阅创建服务主体 - 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 = … ,将 login.windows.net 替换为 login.chinacloudapi.cn,并将 common 替换为你组织的租户 ID。In the code sample, find string authority = …, replace login.windows.net with login.chinacloudapi.cn, and common with your organization’s tenant ID.

    Note

    必须修改从 GitHub 上的 RestApiSample 下载或引用的代码示例,以适合 Azure 中国云环境。Code Sample you downloaded or referenced from RestApiSample on GitHub must be modified in order to fit in the Azure China Cloud Environment. 例如,替换某些终结点(将“blob.core.windows.net”替换为“blob.core.chinacloudapi.cn”,将“cloudapp.azure.com”替换为“chinacloudapp.cn”);必要时更改某些不受支持的 VM 映像、VM 大小、SKU 以及资源提供程序的 API 版本。For example, replace some endpoints -- "blob.core.windows.net" by "blob.core.chinacloudapi.cn", "cloudapp.azure.com" by "chinacloudapp.cn"; change some unsupported VM images, VM sizes, SKU and resource-provider's API Version when necessary.

  2. 注释/取消注释,以便使用 ClientCredential 类来实例化 cred 对象。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