Partager via

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

La fonctionnalité de suivi des modifications dans Microsoft Dataverse permet de conserver les données synchronisées efficacement en détectant les données modifiées depuis l’extraction initiale ou la dernière synchronisation des données. 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 d’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é Suivre les modifications .

Définissez cette propriété par programmation en définissant entityMetadata.ChangeTrackingEnabled Property sur True.

Note

Après avoir activé le suivi des modifications pour une table, vous ne pouvez pas le désactiver.

Pour plus d’informations sur l’utilisation de Power Apps, consultez Créer et modifier des tables à l’aide de Power Apps.

Pour vérifier si le suivi des modifications est activé pour une table à l’aide de l’API Web Dataverse, utilisez l’une des méthodes suivantes :

  1. Requête EntityDefinitions à l’aide de la requête suivante GET :

    GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$filter=ChangeTrackingEnabled eq true

    Certaines tables système ont le suivi des modifications activé, telles que Audit (audit). Pour afficher la liste complète, utilisez la requête suivante :

    GET [Organization URI]/api/data/v9.2/EntityDefinitions?$filter=ChangeTrackingEnabled eq true and IsCustomEntity eq false&$select=LogicalName

    Pour plus d’informations, consultez Définitions de table de requête à l’aide de l’API web.

  2. Consultez le document de 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 jeux d’entités qui représentent les 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>

    Pour plus d’informations, consultez annotations de métadonnées.

Tables non éligibles au suivi des modifications

Vous ne pouvez pas activer le suivi des modifications pour certaines tables. Pour vérifier si une table est éligible au suivi des modifications, vérifiez la valeur de propriété managé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

Vous pouvez suivre les modifications apportées dans les tables à l’aide de requêtes d’API web qui incluent l’en-tête Prefer: odata.track-changes . Cet en-tête demande qu’un lien delta soit retourné, que vous pouvez utiliser ultérieurement 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 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. Pour plus d’informations, consultez 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 montre comment récupérer les modifications apportées à la table de compte à l’aide de 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"
           }
       ]
}

Utilisez l’URI @odata.deltaLink retourné à partir de l’exemple précédent pour extraire les modifications dans les tables. Dans cet exemple, vous avez créé un compte et supprimé un compte existant. Le lien delta retourné par la requête précédente extrait ces modifications, comme illustré dans l’exemple suivant.

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. Si aucune modification de table ne se produit après la demande de suivi des modifications initiale, la réponse contient un JSON vide.

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

Pour obtenir le nombre de modifications, ajoutez $count le lien delta retourné par la demande de suivi des modifications initiale, comme illustré dans l’exemple suivant.

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 de requête non prises en charge par la requête de l'API Web de suivi des modifications

Les options $filterde requête système, $orderbyet $expand$topne sont pas prises en charge lorsque vous utilisez l’en-tête Prefer: odata.track-changes dans une requête d’API web. Si vous utilisez ces options de requête dans la demande d’API web, vous obtenez un message d’erreur : The \"${filter|orderby|expand|top}\" query parameter isn't supported when Change Tracking is enabled..

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

Lorsque vous activez le suivi des modifications pour une table, utilisez le message avec la RetrieveEntityChangesclasse RetrieveEntityChangesRequest pour récupérer les modifications de cette table.

La première fois que vous utilisez ce message, il renvoie tous les enregistrements de la table. Vous pouvez utiliser ces données pour remplir le stockage externe. Le message retourne également un numéro de version que vous renvoyez lors de l'utilisation suivante du message RetrieveEntityChanges afin que seules les données liées aux modifications survenues depuis cette version soient retournées.

Tenez compte des contraintes suivantes lors de la récupération des modifications pour une table :

  • Une seule table peut être suivie lors de la récupération des modifications. Si vous exécutez RetrieveEntityChanges sans version ou jeton, le serveur le traite comme la version minimale du système et retourne tous les enregistrements comme nouveaux. Les objets supprimés ne sont pas retournés.
  • Les modifications sont retournées si le dernier jeton se trouve dans une valeur par défaut de sept jours. La valeur de la colonne ExpireChangeTrackingInDays de la table Organisation contrôle cette durée et peut être modifiée. Si les modifications non traitées sont antérieures à la valeur configurée, le système lève une exception.
  • Si un client possède un ensemble de modifications pour une table, par exemple la version 1, et qu’un enregistrement est créé puis supprimé avant la requête suivante pour les modifications, le client récupère l’élément supprimé même s’il ne l’avait pas au départ.
  • Les enregistrements sont récupérés dans l’ordre déterminé par la logique côté serveur. En règle générale, l’appelant obtient 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 renvoie une collection de 5 000 enregistrements pour les tables standard, qui sont les 3 000 premières entrées composées d’enregistrements nouveaux ou mis à jour et les 2 000 dernières entrées pour les 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 du Kit de développement logiciel (SDK) .NET

L’extrait de code suivant montre comment utiliser le RetrieveEntityChanges message pour récupérer les modifications d’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éfinir des clés alternatives pour une 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
Requête des définitions de table à l’aide de l’API web

  • Last updated on