Actualisation asynchrone avec l’API RESTAsynchronous refresh with the REST API

En utilisant n’importe quel langage de programmation qui prend en charge les appels REST, vous pouvez effectuer des opérations d’actualisation des données asynchrones sur vos modèles tabulaires 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. Cela inclut la synchronisation des réplicas en lecture seule pour la montée en puissance des requêtes.This includes synchronization of read-only replicas for query scale-out.

Les opérations d’actualisation des données peuvent prendre un certain temps en fonction de plusieurs facteurs, notamment le volume de données, le niveau d’optimisation à l’aide de partitions, etc. Ces opérations sont généralement appelées avec des méthodes existantes, telles que TOM (modèle d’objet tabulaire),les cmdlets PowerShell ou TMSL (langage de script de modèle tabulaire).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). Toutefois, ces méthodes requièrent souvent des connexions HTTP non fiables à longue durée d’exécution.However, these methods can require often unreliable, long-running HTTP connections.

L’API REST pour Azure Analysis Services permet de réaliser de manière asynchrone des opérations d’actualisation de données.The REST API for Azure Analysis Services enables data-refresh operations to be carried out asynchronously. À l’aide de l’API REST, les connexions HTTP à longue durée d’exécution des applications clientes ne sont pas nécessaires.By using the REST API, long-running HTTP connections from client applications aren't necessary. Il existe également d’autres fonctionnalités intégrées à des fins de fiabilité, telles que les tentatives automatiques et les validations par lot.There are also other built-in features for reliability, such as auto retries and batched commits.

URL de baseBase URL

L’URL de base suit ce format :The base URL follows this format:

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

Prenons l’exemple d’un modèle nommé AdventureWorks sur un serveur nommé myserver, situé dans la région Azure USA Ouest.For example, consider a model named AdventureWorks on a server named myserver, located in the West US Azure region. Le nom du serveur est :The server name is:

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

L’URL de base pour ce nom de serveur est la suivante :The base URL for this server name is:

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

Avec l’URL de base, il est possible d’ajouter des ressources et des opérations en fonction des paramètres suivants :By using the base URL, resources and operations can be appended based on the following parameters:

Actualisation asynchrone

  • Tout ce qui se termine par s est une collection.Anything that ends in s is a collection.
  • Tout ce qui se termine par () est une fonction.Anything that ends with () is a function.
  • Tout autre élément est un objet ou une ressource.Anything else is a resource/object.

Par exemple, vous pouvez utiliser le verbe POST sur la collection Refreshes pour effectuer une opération d’actualisation :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

AuthentificationAuthentication

Tous les appels doivent être authentifiés avec un jeton d’Azure Active Directory (OAuth 2) valide dans l’en-tête d’autorisation et doivent respecter les conditions suivantes :All calls must be authenticated with a valid Azure Active Directory (OAuth 2) token in the Authorization header and must meet the following requirements:

  • Le jeton doit être un jeton d’utilisateur ou un principal de service d’application.The token must be either a user token or an application service principal.

  • L’audience appropriée pour le jeton doit avoir la valeur https://*.asazure.windows.net.The token must have the correct audience set to https://*.asazure.windows.net.

  • L’utilisateur ou l’application doit avoir des autorisations suffisantes sur le serveur ou le modèle pour effectuer l’appel requis.The user or application must have sufficient permissions on the server or model to make the requested call. Le niveau d’autorisation est déterminé par les rôles au sein du modèle ou du groupe d’administration sur le serveur.The permission level is determined by roles within the model or the admin group on the server.

    Important

    Actuellement, les autorisations du rôle administrateur du serveur sont nécessaires.Currently, server admin role permissions are necessary.

POST /refreshesPOST /refreshes

Pour effectuer une opération d’actualisation, utilisez le verbe POST sur la collection /refreshes pour ajouter un nouvel élément d’actualisation à la collection.To perform a refresh operation, use the POST verb on the /refreshes collection to add a new refresh item to the collection. L’en-tête d’emplacement dans la réponse inclut l’ID de l’actualisation.The Location header in the response includes the refresh ID. L’application cliente peut se déconnecter et vérifier l’état ultérieurement si nécessaire, car l’opération est asynchrone.The client application can disconnect and check the status later if required because it is asynchronous.

Une seule opération d’actualisation est acceptée à la fois pour un modèle.Only one refresh operation is accepted at a time for a model. Si une opération d’actualisation est en cours d’exécution et qu’une autre est soumise, le code d’état HTTP Conflit 409 est renvoyé.If there's a current running refresh operation and another is submitted, the 409 Conflict HTTP status code is returned.

Le corps doit ressembler à ceci :The body may resemble the following:

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

ParamètresParameters

La spécification des paramètres n’est pas nécessaire.Specifying parameters is not required. La valeur par défaut est appliquée.The default is applied.

NomName TypeType DescriptionDescription DefaultDefault
Type EnumEnum Type de traitement à effectuer.The type of processing to perform. Les types sont alignés sur les types de commande d’actualisation TMSL : full, clearValues, calculate, dataOnly, automatic et defragment.The types are aligned with the TMSL refresh command types: full, clearValues, calculate, dataOnly, automatic, and defragment. Le type add n’est pas pris en charge.Add type is not supported. automatiqueautomatic
CommitMode EnumEnum Détermine si les objets doivent être validés par lot ou uniquement à la fin.Determines if objects will be committed in batches or only when complete. Modes inclus : default, transactional, partialBatch.Modes include: default, transactional, partialBatch. transactionaltransactional
MaxParallelism IntInt Cette valeur détermine le nombre maximal de threads sur lesquels exécuter des commandes de traitement en parallèle.This value determines the maximum number of threads on which to run processing commands in parallel. Elle s’aligne sur la propriété MaxParallelism qui peut être définie dans la commande de séquence TMSL ou par d’autres méthodes.This value aligned with the MaxParallelism property that can be set in the TMSL Sequence command or using other methods. 1010
RetryCount IntInt Indique le nombre de tentatives de l’opération avant échec.Indicates the number of times the operation will retry before failing. 00
Objects ArrayArray Tableau d’objets à traiter.An array of objects to be processed. Chaque objet inclut « table » lors du traitement de la table entière, ou « table » et « partition » lors du traitement d’une partition.Each object includes: "table" when processing the entire table or "table" and "partition" when processing a partition. Si aucun objet n’est spécifié, l’ensemble du modèle est actualisé.If no objects are specified, the whole model is refreshed. Traitement de l’ensemble du modèleProcess the entire model

CommitMode équivaut à partialBatch.CommitMode is equal to partialBatch. Il est utilisé lors du chargement initial de jeux de données volumineux qui peuvent prendre des heures.It's used when doing an initial load of large datasets that could take hours. Si l’opération d’actualisation échoue après la validation correcte d’un ou plusieurs lots, les lots validés restent validés (la validation n’est pas annulée).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).

Notes

Au moment de l’écriture, la taille de lot est la valeur MaxParallelism, mais cette valeur peut changer.At time of writing, the batch size is the MaxParallelism value, but this value could change.

Valeurs d’étatStatus values

Valeur d’étatStatus value DescriptionDescription
notStarted Opération pas encore commencée.Operation not yet started.
inProgress Opération en cours.Operation in progress.
timedOut Délai de l’opération expiré conformément au délai d’expiration spécifié par l’utilisateur.Operation timed out based on user specified timeout.
cancelled Opération annulée par l’utilisateur ou le système.Operation canceled by user or system.
failed Échec de l’opération.Operation failed.
succeeded Opération réussie.Operation succeeded.

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

Pour vérifier l’état d’une opération d’actualisation, utilisez le verbe GET sur l’ID de l’actualisation.To check the status of a refresh operation, use the GET verb on the refresh ID. Voici un exemple de corps de réponse.Here's an example of the response body. Si l’opération est en cours, inProgress est retourné dans l’état.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"
        }
    ]
}

GET /refreshesGET /refreshes

Pour obtenir la liste des opérations d’actualisation historiques pour un modèle, utilisez le verbe GET sur la collection /refreshes.To get a list of historical refresh operations for a model, use the GET verb on the /refreshes collection. Voici un exemple de corps de réponse.Here's an example of the response body.

Notes

Au moment de l’écriture, les opérations d’actualisation des 30 derniers jours sont stockées et renvoyées, mais ce nombre peut être modifié.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-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 /refreshes/<refreshId>

Pour annuler une opération d’actualisation en cours, utilisez le verbe DELETE sur l’ID de l’actualisation.To cancel an in-progress refresh operation, use the DELETE verb on the refresh ID.

POST /syncPOST /sync

Après l’exécution d’opérations d’actualisation, il peut être nécessaire de synchroniser les nouvelles données avec des réplicas pour la montée en puissance des requêtes. Pour effectuer une opération de synchronisation pour un modèle, utilisez le verbe POST sur la fonction /sync.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. L’en-tête d’emplacement dans la réponse inclut l’ID de l’opération de synchronisation.The Location header in the response includes the sync operation ID.

GET /sync statusGET /sync status

Pour vérifier l’état d’une opération de synchronisation, utilisez le verbe GET en transmettant l’ID de l’opération en tant que paramètre.To check the status of a sync operation, use the GET verb passing the operation ID as a parameter. Voici un exemple de corps de réponse :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
}

Valeurs possibles de syncstate :Values for syncstate:

  • 0 : Réplication.0: Replicating. Les fichiers de base de données sont en cours de réplication vers un dossier cible.Database files are being replicated to a target folder.
  • 1 : Réalimentation.1: Rehydrating. La base de données est en cours réalimentation sur une ou plusieurs instances de serveur en lecture seule.The database is being rehydrated on read-only server instance(s).
  • 2 : Terminé.2: Completed. L’opération de synchronisation est terminée.The sync operation completed successfully.
  • 3 : Échec.3: Failed. L’opération de synchronisation a échoué.The sync operation failed.
  • 4 : Finalisation.4: Finalizing. L’opération de synchronisation est terminée, mais des étapes de nettoyage sont en cours.The sync operation has completed but is performing cleanup steps.

Exemple de codeCode sample

Voici un exemple de code C# pour vous aider à démarrer, RestApiSample sur GitHub.Here's a C# code sample to get you started, RestApiSample on GitHub.

Pour utiliser l’exemple de codeTo use the code sample

  1. Clonez ou téléchargez le référentiel.Clone or download the repo. Ouvrez la solution RestApiSample.Open the RestApiSample solution.
  2. Recherchez la ligne client.BaseAddress = ...Find the line client.BaseAddress = … et indiquez votre URL de base.and provide your base URL.

L’exemple de code utilise l’authentification d’un principal de service.The code sample uses service principal authentication.

Principal du serviceService principal

Consultez Créer un principal du service – Portail Azure et Ajouter un principal du service au rôle d’administrateur du serveur pour plus d’informations sur la configuration du principal du service et l’attribution des autorisations nécessaires dans Azure AS.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. Après cette procédure, suivez les étapes complémentaires suivantes :Once you've completed the steps, complete the following additional steps:

  1. Dans l’exemple de code, recherchez string authority = … , puis remplacez common par l’ID de locataire de votre organisation.In the code sample, find string authority = …, replace common with your organization's tenant ID.
  2. Ajoutez ou enlevez des marques de commentaire pour que la classe ClientCredential soit utilisée pour instancier l’objet d’informations d’identification.Comment/uncomment so the ClientCredential class is used to instantiate the cred object. Vérifiez que les valeurs <App ID> et <App Key> sont accessibles de manière sécurisée, ou utilisez l’authentification par certificat pour les principaux de service.Ensure the <App ID> and <App Key> values are accessed in a secure way or use certificate-based authentication for service principals.
  3. Exécutez l’exemple.Run the sample.

Voir aussiSee also

Exemples Samples
REST APIREST API