使用 REST API 执行异步刷新

项目
08/26/2024

使用支持 REST 调用的任何编程语言，可以针对 Azure Analysis Services 表格模型执行异步数据刷新操作，包括用于查询扩展的只读副本的同步。

数据刷新操作可能需要一段时间，具体取决于许多因素，包括数据卷、使用分区的优化级别，等等。传统上，这些操作是使用现有方法调用的，例如，使用 TOM（表格对象模型）、PowerShell cmdlet，或 TMSL（表格模型脚本语言）。但是，这些方法可能需要通常不可靠的且长时间运行的 HTTP 连接。

使用 Azure Analysis Services 的 REST API 能够以异步方式执行数据刷新操作。如果使用 REST API，则不需要从客户端应用程序建立长时间运行的 HTTP 连接。还有其他内置功能可以确保可靠性，例如自动重试和分批提交。

基 URL

基 URL 遵循以下格式：

https://<rollout>.asazure.chinacloudapi.cn/servers/<serverName>/models/<resource>/

例如，假设某个模型名为 AdventureWorks，位于中国北部 Azure 区域中名为 myserver 的服务器上。此服务器名称为：

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

此服务器名称的基 URL 为：

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

使用基 URL 可以根据以下参数追加资源和操作：

显示异步刷新逻辑的示意图。

以 s 结尾的任何内容是集合。
以 () 结尾的任何内容是函数。
其他任何内容是资源/对象。

例如，可以在 Refreshes 集合中使用 POST 谓词来执行刷新操作：

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

身份验证

所有调用必须使用授权标头中的有效 Microsoft Entra ID (OAuth 2) 令牌进行身份验证，并且必须满足以下要求：

令牌必须是用户令牌或应用程序服务主体。
令牌必须将受众准确地设置为 https://*.asazure.chinacloudapi.cn。请注意，* 不是占位符或通配符，并且受众必须使用 * 字符作为子域。不支持自定义受众（如 https://customersubdomain.asazure.chinacloudapi.cn）。指定无效的受众会导致身份验证失败。
用户或应用程序必须在服务器或模型中具有足够的权限才能发出请求的调用。权限级别由模型或者服务器上的管理员组中的角色确定。

重要

目前，服务器管理员角色权限是必需的。

POST /refreshes

若要执行刷新操作，可以在 /refreshes 集合中使用 POST 谓词将一个新的刷新项添加到该集合。响应中的 Location 标头包含刷新 ID。以后，客户端应用程序可以根据需要断开连接并检查状态，因为它是异步的。

模型每次只接受一个刷新操作。如果当前正在运行一个刷新操作并提交了另一个刷新操作，则会返回“409 冲突”HTTP 状态代码。

正文可如下所示：

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

参数

如果未指定此参数，则会应用默认值。

名称	Type	描述	默认
`Type`	枚举	要执行的处理类型。类型与 TMSL refresh 命令类型一致：`full`、`clearValues`、`calculate`、`dataOnly`、`automatic` 和 `defragment`。不支持 `add` 类型。	`automatic`
`CommitMode`	Enum	确定对象是分批提交还是仅在整个操作完成时才提交。模式包括 `transactional` 和 `partialBatch`。	`transactional`
`MaxParallelism`	int	此值确定用于并行运行处理命令的最大线程数。此值与 MaxParallelism 属性（可以在 TMSL Sequence 命令中或使用其他方法设置此属性）相符。	10
`RetryCount`	int	指示操作在失败之前要重试的次数。	0
`Objects`	Array	要处理的对象数组。每个对象包含：“table”（处理整个表时），或者“table”和“partition”（处理分区时）。如果未指定任何对象，则会刷新整个模型。	处理整个模型

针对大型数据集执行可能需要几个小时的初始加载时，为 CommitMode 指定 partialBatch 非常有用。如果在成功提交一个或多个批之后刷新操作失败，则成功提交的批将保留已提交状态（不会回滚已成功提交的批）。

注意

在撰写本文时，批大小为 MaxParallelism 值，但可以更改此值。

状态值

状态值	说明
`notStarted`	操作尚未开始。
`inProgress`	操作正在进行。
`timedOut`	根据用户指定的超时，操作已超时。
`cancelled`	用户或系统已取消操作。
`failed`	操作失败。
`succeeded`	操作成功。

GET /refreshes/<refreshId>

若要检查刷新操作的状态，可以在刷新 ID 中使用 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>

若要取消正在进行的刷新操作，可以在刷新 ID 中使用 DELETE 谓词。

POST /sync

执行刷新操作后，可能需要将新数据与副本同步，以进行查询扩展。若要对模型执行同步操作，可以在 /sync 函数中使用 POST 谓词。响应中的 Location 标头包含同步操作 ID。

GET /sync status

若要检查同步操作的状态，可以使用 GET 谓词，以参数的形式传递操作 ID。下面是响应正文的示例：

{
    "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:正在完成。同步操作已完成，但正在执行清理步骤。

代码示例

下面是一个可以帮助你入门的 C# 代码示例：GitHub 上的 RestApiSample。

使用代码示例

克隆或下载存储库。打开 RestApiSample 解决方案。
查找“client.BaseAddress = …”行并提供基 URL。

此代码示例使用服务主体身份验证。

服务主体

请参阅创建服务主体 - Azure 门户和将服务主体添加到服务器管理员角色来了解更多信息，并遵循有关如何在 Azure AS 中设置服务主体和分配必要权限的步骤。然后，完成以下额外的步骤：

在代码示例中，查找字符串 authority = …，将 login.windows.net 替换为 login.chinacloudapi.cn，将 common 替换为你的组织的租户 ID。

注意

必须修改从 GitHub 上的 RestApiSample 下载或引用的代码示例，以适应由世纪互联运营的 Azure 环境。例如，替换某些终结点（将“blob.core.windows.net”替换为“blob.core.chinacloudapi.cn”，将“cloudapp.azure.com”替换为“chinacloudapp.cn”）；必要时更改某些不受支持的 VM 映像、VM 大小、SKU 以及资源提供程序的 API 版本。
注释/取消注释，以便使用 ClientCredential 类来实例化 cred 对象。确保以安全方式访问 <App ID> 和 <App Key> 值，或者对服务主体使用基于证书的身份验证。
运行该示例。

另请参阅

示例
 REST API

通过