Utiliser le suivi des modifications pour synchroniser les données avec les systèmes externes
La fonctionnalité de suivi des modifications de Microsoft Dataverse vous permet de préserver la synchronisation des données efficacement en détectant les données qui ont changé depuis leur extraction initiale ou leur dernière synchronisation. Auparavant, sans cette nouvelle fonctionnalité, il était difficile de créer un mécanisme fiable et efficace pour déterminer les enregistrements qui avaient été modifiés dans Dataverse. Cet article explique comment récupérer les modifications pour une table.
Activer le suivi des modifications pour une table
Avant de récupérer les modifications pour une table, vérifiez que la fonctionnalité de suivi des modifications est activée pour cette table. Cette fonctionnalité peut être activée via l’interface utilisateur de personnalisation ou par programme en définissant la propriété ChangeTrackingEnabled sur True. L’annotation Org.OData.Capabilities.V1.ChangeTracking est ajoutée aux groupes de tables pour lesquelles le suivi des modifications est activé. Pour afficher les annotations dans les définitions de table,
GET [Organization URI]/api/data/v9.0/$metadata?annotations=true
Lisez plus d’informations sur les annotations des métadonnées dans Annotations des métadonnées.
Pour plus d’informations sur l’utilisation de l’interface utilisateur de personnalisation, voir Activer le suivi des modifications pour contrôler la synchronisation des données.
Récupérer les modifications d’une table à l’aide de l’API web
Les modifications apportées aux tables peuvent être suivies à l’aide de requêtes de l’API web en ajoutant odata.track-changes comme en-tête de préférence. L’en-tête de préférence odata.track-changes est utilisé pour demander le renvoi d’un lien delta qui peut ultérieurement être utilisé pour récupérer les modifications de table.
Les liens delta sont des liens opaques générés par le service que le client utilise pour récupérer les modifications ultérieures d’un résultat. Ils sont basés sur une requête de définition qui décrit l’ensemble des résultats pour lesquels les modifications sont suivies ; par exemple, la requête qui a généré les résultats contenant le lien de delta. Le lien delta code la collection des tables pour lesquelles les modifications font l’objet d’un suivi, avec un point de départ du suivi des modifications. Vous trouverez davantage d’informations sur les liens delta ici Oasis OData Version 4.0 – Liens delta
Exemple de récupération des modifications apportées aux tables à l’aide de l’API web
Cet exemple explique comment récupérer les modifications apportées à des données de comptes en utilisant l’API web.
Demande
GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax HTTP/1.1
Prefer: odata.track-changes
Cache-Control: no-cache
OData-Version: 4.0
Content-Type: application/json
Réponse
{
"@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts(name,accountnumber,telephone1,fax)",
"@odata.deltaLink": "[Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44",
"value":[
{
"@odata.etag":"W/\"915244\"",
"name":"Monte Orton",
"accountnumber":null,
"telephone1":"555000",
"fax":"10101",
"accountid":"60c4e274-0d87-e711-80e5-00155db19e6d"
}
]
}
Le lien delta renvoyé de l’exemple précédent peut être utilisé pour extraire les modifications apportées aux tables. Dans cet exemple, un nouveau compte a été créé et un compte existant a été supprimé. Le lien delta renvoyé par la requête précédente extrait ces modifications, comme décrit dans l’exemple ci-dessous.
Demande
GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44
Réponse
{
"@odata.context":"[Organization URI]/data/v9.0/$metadata#accounts(name,telephone1,fax)/$delta",
"@odata.deltaLink":"[Organization URI]/api/data/v9.0/accounts?$select=name,telephone1,fax&$deltatoken=919058%2108%2f22%2f2017%2008%3a21%3a20",
"value":
[
{
"@odata.etag":"W/\"915244\"",
"name":"Monte Orton",
"telephone1":"555000",
"fax":"10101",
"accountid":"60c4e274-0d87-e711-80e5-00155db19e6d"
},
{
"@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts/$deletedEntity",
"id":"2e451703-c686-e711-80e5-00155db19e6d",
"reason":"deleted"
}
]
}
La réponse au lien delta renvoyé dans la requête d’origine de suivi des modifications contient un autre lien delta. Ce lien delta permet de récupérer toutes les modifications ultérieures des tables. Une réponse JSON vide est renvoyée si aucune modification de table n’a eu lieu après l’appel de la requête initiale de suivi des modifications.
Récupérer le nombre des modifications apportées aux tables à l’aide de l’API web
$count peut être ajouté au lien delta renvoyé par la requête initiale de suivi des modifications, comme décrit dans l’exemple ci-dessous, pour obtenir le nombre de modifications apportées.
Demande
GET [Organization URI]/api/data/v9.0/accounts/$count?$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44
Options non prises en charge par la requête de suivi des modifications de l’API web
Les options de requête système $filter, $orderby, $expand et $top ne sont pas prises en charge avec odata.track-changes comme en-tête de la requête de l’API web. Un message d’erreur indiquant « Le paramètre de requête $filter/ $orderby/ $expand / $top n’est pas pris en charge si le suivi des modifications est activé. » est renvoyé lors de l’utilisation de ces options de requête dans la requête de l’API web.
Récupérer les modifications d’une table à l’aide du service d’organisation
Lorsque le suivi des modifications est activé pour une table, vous pouvez utiliser le message RetrieveEntityChangesRequest pour récupérer les modifications pour cette table. La première fois que ce message est utilisé, il retourne tous les enregistrements de la table et ces données peuvent être utilisées pour remplir le stockage externe. Le message retourne également un numéro de version qui sera renvoyé lors de l’utilisation suivante du message RetrieveEntityChangesRequest afin que seules les données relatives aux modifications produites depuis cette version soient retournées.
Vous devez connaître les contraintes suivantes lorsque vous récupérez les modifications pour une table :
Une seule table est suivie lors de la récupération des modifications. Si la récupération des modifications est exécutée sans version ni jeton, le serveur la traite comme la version système minimale et retourne tous les enregistrements comme nouveau. Les objets supprimés ne seront pas retournés.
Les modifications seront retournées si le dernier jeton est situé dans le délai par défaut de 90 jours. S’il est situé au-delà de 90 jours, le système retournera tous les enregistrements.
Si un client a un ensemble de modifications pour une table, que nous appelons version 1, et qu’un enregistrement est créé et supprimé avant la requête suivante relative aux modifications, l’article supprimé est retourné même s’il n’était pas présent au début.
Les enregistrements sont récupérés dans l’ordre déterminé par la logique côté serveur. Généralement, l’utilisateur final obtient toujours tous les enregistrements nouveaux ou mis à jour en premier (triés par numéro de version), suivis des enregistrements supprimés. S’il y a 3 000 enregistrements créés ou mis à jour et 2 000 enregistrements supprimés, Dataverse retourne une collection de 5 000 enregistrements. Les 3 000 premières entrées sont constituées des enregistrements nouveaux ou mis à jour et les 2 000 entrées suivantes sont constituées des enregistrements supprimés.
Si la collection d’articles nouvelle ou mise à jour est supérieure à 5 000, l’utilisateur peut parcourir la collection.
Exemple de code
L’extrait de code suivant montre comment le message RetrieveEntityChangesRequest est utilisé pour récupérer les modifications pour une table. Pour voir l’exemple complet, consultez Synchroniser les informations avec les systèmes externes avec le suivi des modifications.
string token;
// Initialize page number.
int pageNumber = 1;
List<Entity> initialrecords = new List<Entity>();
// Retrieve records by using Change Tracking feature.
RetrieveEntityChangesRequest request = new RetrieveEntityChangesRequest();
request.EntityName = _customBooksEntityName.ToLower();
request.Columns = new ColumnSet("sample_bookcode", "sample_name", "sample_author");
request.PageInfo = new PagingInfo() { Count = 5000, PageNumber = 1, ReturnTotalRecordCount = false };
// Initial Synchronization. Retrieves all records as well as token value.
Console.WriteLine("Initial synchronization....retrieving all records.");
while (true)
{
RetrieveEntityChangesResponse response = (RetrieveEntityChangesResponse)_serviceProxy.Execute(request);
initialrecords.AddRange(response.EntityChanges.Changes.Select(x => (x as NewOrUpdatedItem).NewOrUpdatedEntity).ToArray());
initialrecords.ForEach(x => Console.WriteLine("initial record id:{0}", x.Id));
if (!response.EntityChanges.MoreRecords)
{
// Store token for later query
token = response.EntityChanges.DataToken;
break;
}
// Increment the page number to retrieve the next page.
request.PageInfo.PageNumber++;
// Set the paging cookie to the paging cookie returned from current results.
request.PageInfo.PagingCookie = response.EntityChanges.PagingCookie;
}
Voir aussi
Définition de clés secondaires pour la table
Utilisation de clés secondaires
Mettre à jour Dynamics 365 avec des données externes à l’aide de Upsert
Notes
Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)
Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).
Commentaires
Envoyer et afficher des commentaires pour