Partager via

Actualisation asynchrone avec l’API REST

  • Article

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, notamment la synchronisation de réplicas en lecture seule pour le scale-out de requêtes.

Les opérations d’actualisation des données peuvent prendre un certain temps en fonction de nombreux 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 (Tabular Model Scripting Language). Toutefois, ces méthodes requièrent souvent des connexions HTTP non fiables à longue durée d’exécution.

L’API REST pour Azure Analysis Services permet de réaliser de manière asynchrone des opérations d’actualisation de données. À l’aide de l’API REST, les connexions HTTP à longue durée d’exécution des applications clientes ne sont pas nécessaires. Il existe également d’autres fonctionnalités intégrées à des fins de fiabilité, telles que les tentatives automatiques et les validations par lot.

URL de base

L’URL de base suit ce 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. Le nom du serveur est :

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

L’URL de base pour ce nom de serveur est la suivante :

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 :

Diagramme montrant la logique de l’actualisation asynchrone.

  • Tout ce qui se termine par s est une collection.
  • Tout ce qui se termine par () est une fonction.
  • Tout autre élément est un objet ou une ressource.

Par exemple, vous pouvez utiliser le verbe POST sur la collection Refreshes pour effectuer une opération d’actualisation :

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

Authentification

Tous les appels doivent être authentifiés avec un jeton Microsoft Entra ID (OAuth 2) valide dans l’en-tête d’autorisation et doivent répondre aux exigences suivantes :

  • Le jeton doit être un jeton d’utilisateur ou un principal de service d’application.

  • Le jeton doit avoir l’audience définie exactement sur https://*.asazure.windows.net. Notez que * n’est pas un espace réservé ou un caractère générique, et que l’audience doit avoir le caractère * comme sous-domaine. Les audiences personnalisées, telles que https://customersubdomain.asazure.windows.net, ne sont pas prises en charge. La spécification d’une audience non valide entraîne un échec d’authentification.

  • L’utilisateur ou l’application doit avoir des autorisations suffisantes sur le serveur ou le modèle pour effectuer l’appel requis. Le niveau d’autorisation est déterminé par les rôles au sein du modèle ou du groupe d’administration sur le serveur.

    Important

    Actuellement, les autorisations du rôle administrateur du serveur sont nécessaires.

POST /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. L’en-tête d’emplacement dans la réponse inclut l’ID de l’actualisation. L’application cliente peut se déconnecter et vérifier l’état ultérieurement si nécessaire, car l’opération est asynchrone.

Une seule opération d’actualisation est acceptée à la fois pour un modèle. 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é.

Le corps doit ressembler à ceci :

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

Paramètres

La valeur par défaut est appliquée si le paramètre n’est pas spécifié.

Nom Type Description Default
Type Enum Type de traitement à effectuer. Les types sont alignés sur les types TMSL de commande d’actualisation : full, clearValues, calculate, dataOnly, automatic et defragment. Le type add n’est pas pris en charge. automatic
CommitMode Enum Détermine si les objets sont validés par lots ou validés uniquement lorsque l’opération entière est terminée. Modes inclus : transactional, partialBatch. transactional
MaxParallelism Int Cette valeur détermine le nombre maximal de threads sur lesquels exécuter des commandes de traitement en parallèle. 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. 10
RetryCount Int Indique le nombre de tentatives de l’opération avant échec. 0
Objects Tableau Tableau d’objets à traiter. Chaque objet inclut « table » lors du traitement de la table entière, ou « table » et « partition » lors du traitement d’une partition. Si aucun objet n’est spécifié, l’ensemble du modèle est actualisé. Traitement de l’ensemble du modèle

La spécification de partialBatch pour CommitMode est utile lors du chargement initial de grands jeux de données qui peut prendre des heures. 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).

Remarque

Au moment de l’écriture, la taille de lot est la valeur MaxParallelism, mais cette valeur peut changer.

Valeurs d’état

Valeur d’état Description
notStarted Opération pas encore commencée.
inProgress Opération en cours.
timedOut Délai de l’opération expiré conformément au délai d’expiration spécifié par l’utilisateur.
cancelled Opération annulée par l’utilisateur ou le système.
failed Échec de l’opération.
succeeded Opération réussie.

GET /refreshes/<refreshId>

Pour vérifier l’état d’une opération d’actualisation, utilisez le verbe GET sur l’ID de l’actualisation. Voici un exemple de corps de réponse. Si l’opération est en cours, inProgress est retourné dans l’état.

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

Pour obtenir la liste des opérations d’actualisation historiques pour un modèle, utilisez le verbe GET sur la collection /refreshes. Voici un exemple de corps de réponse.

Remarque

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é.

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

Pour annuler une opération d’actualisation en cours, utilisez le verbe DELETE sur l’ID de l’actualisation.

POST /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. L’en-tête d’emplacement dans la réponse inclut l’ID de l’opération de synchronisation.

GET /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. Voici un exemple de corps de réponse :

{
    "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 :

  • 0 : réplication. Les fichiers de base de données sont en cours de réplication vers un dossier cible.
  • 1 : réalimentation. La base de données est en cours réalimentation sur une ou plusieurs instances de serveur en lecture seule.
  • 2 : terminé. L’opération de synchronisation est terminée.
  • 3 : échec. L’opération de synchronisation a échoué.
  • 4 : finalisation. L’opération de synchronisation est terminée, mais des étapes de nettoyage sont en cours.

Exemple de code

Voici un exemple de code C# pour vous aider à démarrer, RestApiSample sur GitHub.

Pour utiliser l’exemple de code

  1. Clonez ou téléchargez le référentiel. Ouvrez la solution RestApiSample.
  2. Recherchez la ligne client.BaseAddress = et fournissez votre URL de base.

L’exemple de code utilise l’authentification d’un principal de service.

Principal du service

Pour plus d’informations, consultez Créer un principal de service – Portail Azure et Ajouter un principal de service au rôle d’administrateur du serveur et suivez les étapes permettant de configurer un principal de service et d’attribuer les autorisations nécessaires dans Azure AS. Effectuez ensuite les tâches supplémentaires suivantes :

  1. Dans l’exemple de code, recherchez string authority = …, puis remplacez common par l’ID de locataire de votre organisation.
  2. Ajoutez ou enlevez des marques de commentaire pour que la classe ClientCredential soit utilisée pour instancier l’objet d’informations d’identification. 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.
  3. Exécutez l’exemple.

Voir aussi

Exemples
REST API