Partage via

Mettre en cache les données de schéma

  • Article

Certaines applications bénéficient du maintien d’un cache persistant des définitions de schéma pour une organisation Dataverse. Par exemple :

  • Applications qui doivent fonctionner tout en étant déconnectées du serveur Dataverse
  • Applications sensibles à la bande passante réseau limitée, telles que les applications mobiles

Dataverse a beaucoup de données de définition de schéma, et peu d’applications doivent les suivre toutes. Limiter la quantité de données à mettre en cache est essentiel.

Le message RetrieveMetadataChanges offre deux fonctionnalités :

  1. Requête : composez une seule requête pour récupérer uniquement les données de schéma dont vous avez besoin. La composition de requêtes est abordée dans Définitions du schéma de la requête.
  2. Gestion du cache : si vous mettez en cache les données de définition de schéma avec votre application, vous pouvez utiliser RetrieveMetadataChanges pour récupérer efficacement uniquement les modifications depuis votre dernière requête. Utilisez les informations sur ces modifications pour ajouter ou supprimer des éléments dans votre cache. La mise en cache des données du schéma peut entraîner une amélioration significative du temps de démarrage de votre application et constitue l’objet de cet article.

Après avoir défini une requête pour les données du schéma que vous souhaitez mettre en cache, vous pouvez utiliser d’autres fonctionnalités du message RetrieveMetadataChanges pour créer et maintenir un cache des données du schéma Dataverse.

Créer un cache

Comme décrit dans Définitions du schéma de la requête, la première étape consiste à créer une requête qui définit le type d’informations sur le schéma qui vous intéresse. Puis utilisez le message RetrieveMetadataChanges pour exécuter cette requête et mettre en cache les définitions de schéma renvoyées dans votre application. Vous devez trouver un moyen de conserver ces données qui soit adapté aux besoins de votre application. Vous pouvez l’enregistrer en tant que fichier que votre application lit au démarrage. Vous devez également enregistrer les données sur la dernière exécution de la requête. Structurez votre cache d’une manière qui a du sens pour votre application. Pour gérer la suppression des éléments supprimés, il est important que votre cache utilise MetadataId comme identificateur unique. Pour plus d’informations : Retirer les articles supprimés.

Détecter les changements

Aucun événement n’est disponible pour détecter quand des modifications de la définition du schéma se produisent. Les besoins de votre application doivent motiver l’actualisation du cache. Les utilisateurs récupèrent généralement les modifications au démarrage de l’application. Mais vous pouvez interroger le système régulièrement si vous souhaitez détecter les changements au fil du temps. Quelle que soit votre stratégie, il est important de garder une trace de l’heure à laquelle vous avez envoyé la demande précédente.

La propriété RetrieveMetadataChangesResponse.ServerVersionStamp contient des informations sur le moment où la demande de RetrieveMetadataChanges a eu lieu. Vous devez prendre la valeur ServerVersionStamp de la réponse précédente et l’utiliser comme valeur pour RetrieveMetadataChangesRequest.ClientVersionStamp lorsque vous l’envoyez à nouveau en utilisant la même requête.

Lorsque vous incluez la propriété ClientVersionStamp dans la demande, la propriété RetrieveMetadataChangesResponse.EntityMetadata renvoyée contient uniquement les données du schéma modifiées ou ajoutées depuis la demande précédente. Vous pouvez les ajouter à votre cache.

Si vous incluez également le paramètre DeletedMetadataFilters, tous les éléments du schéma supprimés depuis la demande précédente sont inclus dans la propriété RetrieveMetadataChangesResponse.DeletedMetadata. Vous pouvez les retirer de votre cache.

Ce résultat doit être plus petit et plus rapide que la réexécution de la requête d’origine.

Gérer le cache expiré

Les informations sur les modifications sont stockées pendant 90 jours par défaut. Cette valeur est stockée dans la propriété Organization.ExpireSubscriptionsInDays. Si vous envoyez une demande avec une valeur ClientVersionStamp plus ancienne que la valeur du paramètre, Dataverse renvoie une erreur ExpiredVersionStamp (0x80044352). Vous devez être prêt à gérer cette erreur spécifique et à réinitialiser votre cache lorsqu’elle se produit.

Notes

Vous devez être prêt à gérer cette erreur même si vous pensez que votre valeur est toujours inférieure à 90 jours. Cette erreur est générée lorsque des modifications sur le serveur ont un impact sur le suivi précis des données de schéma supprimées. Par exemple, changer la propriété Organization.ExpireSubscriptionsInDays invalidera toutes les valeurs VersionStamp précédentes. Certaines de ces modifications peuvent ne pas être causées par des actions que vous entreprenez, mais peuvent être déclenchées par la maintenance du système.

Ajouter des éléments modifiés

Tout comme lorsque vous exécutez votre requête initiale pour initialiser votre cache, la propriété RetrieveMetadataChangesResponse.EntityMetadata renvoyée pour les demandes ultérieures utilisant RetrieveMetadataChangesRequest.ClientVersionStamp inclut la hiérarchie complète des éléments modifiés.

Chaque élément de la hiérarchie a une valeur HasChanged booléenne définie sur Nullable. Lorsque cette valeur est false, cela signifie que l’élément actuel n’a pas changé, mais que quelque chose en dessous dans la hiérarchie a changé. Quand la valeur HasChanged est définie sur true, cela signifie que l’élément actuel dans la hiérarchie a changé.

Notes

Si vous demandez EntityMetadata.Privileges dans votre requête, les privilèges sont toujours renvoyés, qu’ils aient changé ou non. Les privilèges ne changent généralement pas.

Options de suivi

Une zone qui peut ne pas sembler intuitive est la façon dont les options pour les colonnes de choix sont suivies. Cette zone est un bon exemple pour comprendre la propriété HasChanged.

Lorsqu’une nouvelle option est ajoutée à une colonne de choix, les données suivantes dans la hiérarchie seront renvoyées avec la propriété RetrieveMetadataChangesResponse.EntityMetadata :

Vous savez que EntityMetadata et EnumAttributeMetadata n’ont pas été modifiés parce que la propriété HasChanged a la valeur false. Seule la propriété OptionSetMetadata.HasChanged a la valeur true. Toutes les options valides actuelles sont renvoyées. La propriété OptionMetadata.HasChanged pour toutes les options, y compris la nouvelle, est nulle.

Seule l’option nouvellement créée contient des données pour la propriété Label. La propriété OptionMetadata.HasChanged a la valeur true uniquement lorsque l’une de ses propriétés (comme Color ou Label) est modifiée.

Retirer les éléments supprimés

Lorsque vous incluez les paramètres ClientVersionStamp et DeletedMetadataFilters pour un message RetrieveMetadataChanges, la propriété RetrieveMetadataChangesResponse.DeletedMetadata contient des données sur tous les éléments supprimés. Cette propriété est une DeletedMetadataCollection qui contient un ensemble de Keys et Values. Les clés sont des valeurs d’énumération DeletedMetadataFilters et vous pouvez utiliser ces valeurs pour accéder à un sous-ensemble des valeurs supprimées.

Notes

Le paramètre DeletedMetadataFilters est facultatif et il y a un impact sur les performances lorsque vous l’incluez, car les données sont extraites directement de la base de données plutôt que du cache interne. Utilisez-le uniquement lorsque vous devez détecter des éléments supprimés et définissez la valeur du filtre sur la quantité minimale de données que vous devez renvoyer.

Les valeurs supprimées sont renvoyées sous la forme d’une collection de valeurs Guid. Les valeurs des éléments supprimés ne sont pas filtrées en fonction de votre requête. De nombreuses valeurs Guid ne figurent pas dans votre cache, mais les valeurs Guid de votre élément mis en cache sont incluses. Vous devez rechercher toute valeur Guid correspondante et supprimer ces éléments. Ignorez toutes les valeurs qui ne sont pas présentes dans votre cache.

Notes

La définition de l’API web DeletedMetadataFilters EnumType est légèrement différent du kit de développement logiciel DeletedMetadataFilters Enum.

L’API web DeletedMetadataFilters EnumType n’a pas le membre Entity. Vous devez utiliser à la place Default.

Options de suivi des suppressions

Remarquez que DeletedMetadataFilters enum contient un membre pour OptionSet, mais pas d’option. Si des options sont supprimées d’une colonne de choix, vous ne trouverez pas de référence à une option spécifique qui a été supprimée. Vous devez accéder à vos options mises en cache et les comparer aux options actuelles renvoyées pour OptionSet.

Voir aussi

Exemple d’API web Rechercher les définitions de schéma et détecter les modifications (C#)
Exemple de SDK Rechercher les définitions de schéma et détecter les modifications (C#)
Rechercher les définitions de schéma

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