Utiliser le suivi des modifications pour synchroniser les données avec les systèmes externes

Article
08/03/2023

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. Cet article explique comment activer et 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 le suivi des modifications est activé pour cette table.

Vous pouvez vérifier si cette fonctionnalité est activée ou l’activer en utilisant Power Apps. Sélectionnez Données > Tables et la table spécifique. Sous Options avancées, vous trouverez la propriété Suivi des modifications.

Vous pouvez définir cela par programme en définissant la propriété EntityMetadata.ChangeTrackingEnabled sur True.

Notes

Une fois que le suivi des modifications a été activé pour une table, il n’est pas possible de le désactiver.

Pour plus d’informations sur la manière d’utiliser Power Apps : Créer et modifier les tables avec Power Apps

Il existe deux façons de vérifier si le suivi des modifications est activé pour une table à l’aide de l’API web Dataverse.

Vous pouvez interroger EntityDefinitions avec la requête GET suivante :
```
GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$filter=ChangeTrackingEnabled eq true
```
Il existe des tables système avec le suivi des modifications activé, par exemple Audit (Audit). Vous pouvez utiliser la requête suivante pour voir la liste complète :
```
GET [Organization URI]/api/data/v9.2/EntityDefinitions?$filter=ChangeTrackingEnabled eq true and IsCustomEntity eq false&$select=LogicalName
```
Pour plus d’informations : Interroger les définitions de table à l’aide de l’API Web
Vous trouverez ces informations dans le document du service $metadata de l’API web. L’annotation Org.OData.Capabilities.V1.ChangeTracking est définie sur les groupes d’entités pour lesquelles le suivi des modifications est activé.

Pour afficher les annotations dans le document de service Web API CDSL, utilisez cette requête Web API :
```
GET [Organization URI]/api/data/v9.2/$metadata?annotations=true
```
Les ensembles d’entités qui représentent des tables où le suivi des modifications est activé ont cette annotation :
```
<Annotation Term="Org.OData.Capabilities.V1.ChangeTracking">
   <Record>
         <PropertyValue Property="Supported" Bool="true" />
   </Record>
</Annotation>
```
Plus d’informations : Annotations de métadonnées.

Tables non éligibles au suivi des modifications

Certaines tables ne peuvent pas être activées pour le suivi des modifications. Vous pouvez vérifier si une table est éligible au suivi des modifications en vérifiant la valeur de la propriété gérée EntityMetadata.CanChangeTrackingBeEnabled. Pour voir quelles tables ne peuvent pas être activées pour le suivi des modifications, utilisez cette requête d’API web :

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName,ChangeTrackingEnabled&$filter=ChangeTrackingEnabled eq false and CanChangeTrackingBeEnabled/Value eq false

Pour plus d’informations :

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 l’en-tête Prefer: odata.track-changes. Cet en-tête exige qu’un lien delta soit renvoyé pour une utilisation ultérieure afin de 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 de résultats pour lesquels les modifications sont suivies. Par exemple, la requête qui a généré les résultats contenant le lien 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. Plus d’information : 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 à la table 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
OData-Version: 4.0
Content-Type: application/json

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.track-changes

{
  "@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"
           }
       ]
}

L’Uri @odata.deltaLink renvoyée de l’exemple précédent peut être utilisé pour extraire les modifications apportées aux tables. Dans cet exemple, un 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
OData-Version: 4.0
Content-Type: application/json

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0

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

Vous pouvez ajouter $count 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
OData-Version: 4.0
Content-Type: application/json

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 Prefer: odata.track-changes comme en-tête de la requête de l’API web. Un message d’erreur : The \"${filter|orderby|expand|top}\" query parameter isn't supported when Change Tracking is enabled. 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 Kit de développement logiciel (SDK) .NET

Lorsque le suivi des modifications est activé pour une table, vous pouvez utiliser le message RetrieveEntityChanges avec la classe 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 RetrieveEntityChanges 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 RetrieveEntityChanges 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 sont pas renvoyés.
Les modifications sont renvoyées si le dernier jeton est situé dans le délai par défaut de 7 jours. Cette durée est contrôlée par la valeur de la colonne ExpireChangeTrackingInDays de la table d’organisation et peut être modifiée. S’il existe des modifications non traitées antérieures à la valeur configurée, le système lève une exception.
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’appelant 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.
L’utilisateur appelant doit disposer d’un accès en lecture au niveau de l’organisation pour la table. Si l’utilisateur dispose d’un accès en lecture limité, le système génère une erreur de vérification des privilèges.

Exemple de code Kit de développement logiciel (SDK) pour .NET

L’extrait de code suivant montre comment le message RetrieveEntityChanges 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 d’une clé secondaire pour référencer un enregistrement
Mettre à jour Dynamics 365 avec des données externes à l′aide de Upsert
Interroger les définitions de table à l′aide de l′API Web

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

Utiliser le suivi des modifications pour synchroniser les données avec les systèmes externes

Activer le suivi des modifications pour une table

Tables non éligibles au suivi des modifications

Récupérer les modifications d’une table à l’aide de l’API web

Exemple de récupération des modifications apportées aux tables à l’aide de l’API web

Récupérer le nombre des modifications apportées aux tables à l’aide de l’API web

Options non prises en charge par la requête de suivi des modifications de l’API web

Récupérer les modifications d’une table à l’aide du Kit de développement logiciel (SDK) .NET

Exemple de code Kit de développement logiciel (SDK) pour .NET

Voir aussi

Commentaires

Ressources supplémentaires