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. 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 :
- 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. 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
- Clonez ou téléchargez le référentiel. Ouvrez la solution RestApiSample.
- 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 :
- Dans l’exemple de code, recherchez string authority = …, puis remplacez common par l’ID de locataire de votre organisation.
- 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.
- Exécutez l’exemple.
Voir aussi
Commentaires
Prochainement : Tout au long de l'année 2024, nous supprimerons progressivement les GitHub Issues en tant que mécanisme de retour d'information pour le contenu et nous les remplacerons par un nouveau système de retour d'information. Pour plus d’informations, voir: https://aka.ms/ContentUserFeedback.
Soumettre et afficher des commentaires pour