Partager via


Actualisation asynchrone avec l’API REST

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. Traditionnellement, ces opérations ont été appelées avec des méthodes existantes telles que l’utilisation de TOM (modèle objet tabulaire), d’applets de commande PowerShell ou de TMSL (langage de script de modèle tabulaire). 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 d’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 de rôle d’administrateur de 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 Catégorie Descriptif Par défaut
Type Énumération Type de traitement à effectuer. Les types sont alignés avec les types de commandes d’actualisation TMSL : full, , clearValuescalculate, , dataOnly, automaticet defragment. Le type add n’est pas pris en charge. automatic
CommitMode Énumération 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. Cette valeur est alignée avec la propriété MaxParallelism qui peut être définie dans la commande De séquence TMSL ou à l’aide 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 Descriptif
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 du corps du message 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 commencer, RestApiSample sur GitHub.

Pour utiliser l’exemple de code

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

L’exemple de code utilise l’authentification du principal de service .

Principal de service

Consultez Créer un principal de service - Portail Azure et Ajouter un principal de service au rôle d’administrateur de serveur pour plus d’informations et suivez les étapes de configuration d’un principal de service et attribuez les autorisations nécessaires dans Azure AS. Effectuez ensuite les tâches supplémentaires suivantes :

  1. Dans l’exemple de code, recherchez chaîne de caractères authority = ..., 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

Échantillons
REST API