Asynchronous refresh with the REST API

  • Article
  • v minutes to read

Past using any programming language that supports REST calls, y'all can perform asynchronous data-refresh operations on your Azure Analysis Services tabular models. This includes synchronization of read-only replicas for query scale-out.

Information-refresh operations can take some time depending on a number of factors including information volume, level of optimization using partitions, etc. These operations accept traditionally been invoked with existing methods such as using TOM (Tabular Object Model), PowerShell cmdlets, or TMSL (Tabular Model Scripting Linguistic communication). Withal, these methods tin require often unreliable, long-running HTTP connections.

The REST API for Azure Analysis Services enables data-refresh operations to be carried out asynchronously. By using the REST API, long-running HTTP connections from customer applications aren't necessary. There are also other congenital-in features for reliability, such as motorcar retries and batched commits.

Base URL

The base URL follows this format:

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

For example, consider a model named AdventureWorks on a server named myserver, located in the West US Azure region. The server proper noun is:

              asazure://westus.asazure.windows.internet/myserver

The base of operations URL for this server name is:

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

By using the base URL, resources and operations can be appended based on the following parameters:

Async refresh

  • Anything that ends in due south is a drove.
  • Anything that ends with () is a role.
  • Anything else is a resource/object.

For instance, you tin use the Mail verb on the Refreshes collection to perform a refresh operation:

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

Authentication

All calls must exist authenticated with a valid Azure Active Directory (OAuth 2) token in the Authority header and must run into the following requirements:

  • The token must be either a user token or an application service master.

  • The token must have the correct audition prepare to https://*.asazure.windows.internet.

  • The user or application must have sufficient permissions on the server or model to make the requested call. The permission level is determined past roles within the model or the admin group on the server.

    Of import

    Currently, server admin part permissions are necessary.

POST /refreshes

To perform a refresh operation, use the POST verb on the /refreshes collection to add a new refresh item to the drove. The Location header in the response includes the refresh ID. The client application can disconnect and check the condition later if required because information technology is asynchronous.

Only one refresh functioning is accepted at a fourth dimension for a model. If there'southward a current running refresh performance and some other is submitted, the 409 Conflict HTTP condition code is returned.

The body may resemble the post-obit:

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

Parameters

Specifying parameters is non required. The default is applied.

Proper name Type Description Default
Type Enum The type of processing to perform. The types are aligned with the TMSL refresh control types: full, clearValues, calculate, dataOnly, automated, and defragment. Add type is not supported. automatic
CommitMode Enum Determines if objects will be committed in batches or only when complete. Modes include: default, transactional, partialBatch. transactional
MaxParallelism Int This value determines the maximum number of threads on which to run processing commands in parallel. This value aligned with the MaxParallelism holding that can be ready in the TMSL Sequence command or using other methods. x
RetryCount Int Indicates the number of times the functioning will retry earlier failing. 0
Objects Array An array of objects to be processed. Each object includes: "table" when processing the entire tabular array or "table" and "partition" when processing a partition. If no objects are specified, the whole model is refreshed. Process the entire model

CommitMode is equal to partialBatch. Information technology'southward used when doing an initial load of large datasets that could take hours. If the refresh functioning fails later on successfully committing one or more batches, the successfully committed batches will remain committed (it will not curl back successfully committed batches).

Notation

At time of writing, the batch size is the MaxParallelism value, only this value could change.

Status values

Status value Clarification
notStarted Operation not even so started.
inProgress Operation in progress.
timedOut Operation timed out based on user specified timeout.
cancelled Operation canceled by user or system.
failed Functioning failed.
succeeded Operation succeeded.

To check the condition of a refresh operation, use the Get verb on the refresh ID. Hither's an example of the response body. 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": "total",     "objects": [         {             "tabular array": "DimCustomer",             "sectionalization": "DimCustomer",             "status": "succeeded"         },         {             "table": "DimDate",             "segmentation": "DimDate",             "condition": "succeeded"         }     ] }

GET /refreshes

To get a list of historical refresh operations for a model, use the GET verb on the /refreshes collection. Here'southward an example of the response body.

Annotation

At time of writing, the last 30 days of refresh operations are stored and returned, just this number could alter.

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

To cancel an in-progress refresh functioning, apply the DELETE verb on the refresh ID.

Post /sync

Having performed refresh operations, it may exist necessary to synchronize the new data with replicas for query scale-out. To perform a synchronize functioning for a model, utilize the POST verb on the /sync part. The Location header in the response includes the sync performance ID.

GET /sync condition

To cheque the status of a sync operation, use the GET verb passing the performance ID as a parameter. Here'due south an instance of the response body:

              {     "operationId": "cd5e16c6-6d4e-4347-86a0-762bdf5b4875",     "database": "AdventureWorks2",     "UpdatedAt": "2017-12-09T02:44:26.eighteen",     "StartedAt": "2017-12-09T02:44:20.743",     "syncstate": ii,     "details": zilch }

Values for syncstate:

  • 0: Replicating. Database files are being replicated to a target binder.
  • 1: Rehydrating. The database is being rehydrated on read-simply server example(south).
  • 2: Completed. The sync operation completed successfully.
  • 3: Failed. The sync performance failed.
  • 4: Finalizing. The sync operation has completed but is performing cleanup steps.

Code sample

Hither's a C# code sample to go you lot started, RestApiSample on GitHub.

To utilize the code sample

  1. Clone or download the repo. Open up the RestApiSample solution.
  2. Detect the line client.BaseAddress = … and provide your base of operations URL.

The code sample uses service principal hallmark.

Service primary

Meet Create service principal - Azure portal and Add together a service main to the server administrator office for more info on how to ready a service master and assign the necessary permissions in Azure AS. In one case you lot've completed the steps, complete the post-obit additional steps:

  1. In the code sample, find string authority = …, replace common with your organization'due south tenant ID.
  2. Comment/uncomment and so the ClientCredential grade is used to instantiate the cred object. Ensure the <App ID> and <App Key> values are accessed in a secure way or utilise certificate-based authentication for service principals.
  3. Run the sample.

See besides

Samples
Rest API