Partager via

Mettre en cache les données de schéma

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 lors de la déconnexion du serveur Dataverse.
  • Applications sensibles à une bande passante réseau limitée, comme 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 de schéma que vous souhaitez mettre en cache, utilisez d’autres fonctionnalités du RetrieveMetadataChanges message pour créer et gérer un cache de données de 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. Trouvez un moyen de conserver ces données qui conviennent 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, consultez Supprimer les éléments supprimés.

Détecter les changements

Aucun événement n’existe pour détecter quand des modifications de définition de schéma se produisent. Actualisez le cache en fonction des besoins de votre application. En règle générale, vous récupérez 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, suivez le moment où 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. Prenez la ServerVersionStamp valeur de la réponse précédente et utilisez-la comme valeur pour le RetrieveMetadataChangesRequest.ClientVersionStamp moment où vous l’envoyez à nouveau à l’aide de 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 est plus petit et plus rapide que l’exécution de la requête d’origine.

Gérer le cache expiré

Dataverse stocke des informations sur les modifications pendant 90 jours par défaut. Cette valeur est stockée dans la propriété Organization.ExpireSubscriptionsInDays. Si vous envoyez une requête avec une ClientVersionStamp valeur antérieure à la valeur de paramètre, Dataverse retourne une ExpiredVersionStamp erreur (0x80044352). Préparez-vous à gérer cette erreur spécifique et à réinitialiser votre cache lorsqu’il se produit.

Note

Préparez-vous à gérer cette erreur même si vous pensez que votre valeur est toujours inférieure à 90 jours. Cette erreur se produit quand des modifications sur le serveur affectent le suivi précis des données de schéma supprimées. Par exemple, la modification de la Organization.ExpireSubscriptionsInDays propriété invalide toutes les valeurs précédentes VersionStamp . Certaines de ces modifications peuvent ne pas être provoquées par des actions que vous effectuez, mais peuvent être déclenchées par la maintenance du système.

Ajouter des éléments modifiés

Tout comme lorsque vous effectuez votre requête initiale pour initialiser votre cache, la RetrieveMetadataChangesResponse.EntityMetadata propriété retournée pour les requêtes suivantes à l’aide 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 qui peut être nulle. Lorsque cette valeur est false, cela signifie que l’élément actuel n’a pas changé, mais que quelque chose en dessous de celle-ci dans la hiérarchie a changé. Lorsque la HasChanged valeur est true, cela signifie que l’élément actuel de la hiérarchie a changé.

Note

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

Options de suivi

Une zone où le suivi des modifications 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.

Lorsque vous ajoutez une nouvelle option à une colonne de choix, les données suivantes dans la hiérarchie sont retournées via la RetrieveMetadataChangesResponse.EntityMetadata propriété :

Vous savez que les EntityMetadata et EnumAttributeMetadata n'ont pas changé parce que la propriété HasChanged est fausse. 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 OptionMetadata.HasChanged propriété est vraie uniquement lorsque l’une de ses propriétés (comme Color ou Label) change.

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 DeletedMetadataFilters valeurs d’énumération et vous pouvez utiliser ces valeurs pour accéder à un sous-ensemble des valeurs supprimées.

Note

Le DeletedMetadataFilters paramètre est facultatif. L’inclusion peut affecter les performances, car le processus récupère des données directement à partir de la base de données plutôt qu’à partir 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 Guid valeurs ne se trouvent pas dans votre cache, mais les Guid valeurs 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.

Note

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. Utilisez Default à la place.

Options de suivi supprimées

Remarquez que DeletedMetadataFilters enum contient un membre pour OptionSet, mais pas d’option. Si vous supprimez des options 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 pour .NET : Interroger les définitions de schéma et détecter les modifications (C#)
Rechercher les définitions de schéma

  • Last updated on