Rechercher les définitions de schéma

  • Article

Les applications créées à l’aide de Dataverse doivent pouvoir s’adapter aux modifications apportées aux définitions de schéma. De nouveaux tableaux, colonnes, relations et étiquettes peuvent être ajoutés ou modifiés via la configuration ou en important une solution. Étant donné que les applications doivent être en mesure de répondre à ces modifications, elles dépendent souvent de la récupération des définitions de schéma lorsqu’elles démarrent. Cependant, la quantité totale de données décrivant le schéma d’une organisation Dataverse peut être très grande. Vous devez savoir comment obtenir uniquement les données dont vous avez besoin.

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. Cet article se concentre sur la composition de requêtes.
  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 peut entraîner une amélioration significative du temps de démarrage de votre application. La gestion du cache est traitée dans Données de schéma de cache.

Évaluer d’autres options pour récupérer les définitions de schéma

Lors de la composition d’une requête pour récupérer des définitions de schéma, le message RetrieveMetadataChanges offre l’avantage de définir une requête unique qui peut s’étendre sur plusieurs définitions de table et renvoyer des détails pour les types dérivés et gérer un cache au fil du temps.

Le tableau suivant récapitule les autres manières de récupérer des définitions de schéma, mais aucune d’entre elles ne fournit de fonctionnalités pour gérer un cache au fil du temps.

Message Description et limitations
RetrieveAllEntities Récupère les données pour toutes les tables, y compris toutes les colonnes, tous les privilèges et toutes les relations que vous souhaitez
Voir : classes RetrieveAllEntitiesRequest et RetrieveAllEntitiesResponse.

Limitations : bien que vous puissiez utiliser le paramètre EntityFilters pour exclure certaines parties, c’est une opération très coûteuse.
RetrieveEntity Vous pouvez récupérer la définition de toute table, y compris toutes les colonnes, tous les privilèges et toutes les relations si vous le souhaitez.
Voir : Récupérer et mettre à jour une table

Limitations : bien que vous puissiez utiliser le paramètre EntityFilters pour exclure certaines données, vous ne pouvez pas sélectionner les propriétés spécifiques que vous voulez. Cela reste une opération coûteuse.
RetrieveAttribute Vous pouvez récupérer la définition complète de n’importe quel attribut.
Voir : Récupérer une colonne

Limitations : vous ne pouvez pas sélectionner les propriétés spécifiques que vous souhaitez.
RetrieveRelationship Vous pouvez récupérer la définition complète de n’importe quelle relation.
Voir : Récupérer des relations de ligne de table

Limitations : vous ne pouvez pas sélectionner les propriétés spécifiques que vous souhaitez.
RetrieveAllOptionSets Vous pouvez récupérer des informations sur tous les choix globaux définis dans l’organisation.
Voir : Insérer, mettre à jour, supprimer et ordonner les choix globaux

Limitations : les choix qui ne sont définis que localement dans une colonne ne sont pas inclus.
RetrieveEntityKey Vous pouvez récupérer la définition de toutes les clés alternatives d’une table spécifique.
Voir : Récupérer et supprimer des clés secondaires

Exemple de base RetrieveMetadataChanges

Pour un exemple simple de ce que vous pouvez faire avec RetrieveMetadataChanges, comparez ce que vous pouvez faire avec l’API Web et l’ensemble d’entités EntityDefinitions.

À l’aide de l’API Web, vous pouvez composer une requête comme celle-ci :

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$filter=LogicalName eq 'account' or LogicalName eq 'contact'&$expand=Attributes($select=LogicalName;$filter=IsValidForCreate eq true)

Cette requête renvoie les données des définitions de table de compte et de contact, et développe toutes les définitions de colonne où IsValidForCreate est vrai.

Les exemples suivants montrent comment composer la même requête en utilisant RetrieveMetadataChanges.

/// <summary>
/// Get the SchemaName for the account and contact tables together with
/// the LogicalName of any attributes which are valid for create
/// </summary>
/// <param name="service"></param>
static void SimpleRetrieveMetadataChangesExample(IOrganizationService service) {

    var query = new EntityQueryExpression
    {
        Properties = new MetadataPropertiesExpression("SchemaName", "Attributes"),
        Criteria = new MetadataFilterExpression(filterOperator: LogicalOperator.Or)
        {
            Conditions = {
                {
                    new MetadataConditionExpression(
                        propertyName:"LogicalName",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value:"account")
                },
                {
                    new MetadataConditionExpression(
                        propertyName:"LogicalName",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value:"contact")
                }
            }, 
        },
        AttributeQuery = new AttributeQueryExpression
        {
            Properties = new MetadataPropertiesExpression("LogicalName"),
            Criteria = new MetadataFilterExpression(filterOperator: LogicalOperator.And)
            {
                Conditions = {
                    {
                        new MetadataConditionExpression(
                        propertyName:"IsValidForCreate",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value:true)
                    }
                }
            }            
        },
        LabelQuery = new LabelQueryExpression { 
             FilterLanguages = {
                { 1033 }
            } 
        }
        
    };

    var request = new RetrieveMetadataChangesRequest
    {
        Query = query
    };

    var response = (RetrieveMetadataChangesResponse)service.Execute(request);

    response.EntityMetadata.ToList().ForEach(em => {

        Console.WriteLine($"Entity SchemaName:{em.SchemaName}");
        em.Attributes.ToList().ForEach(a => {
            Console.WriteLine($"\tAttribute LogicalName:{a.LogicalName}");
        });
    });
}

Sortie :

Entity SchemaName:Account
        Attribute LogicalName:emailaddress3
        Attribute LogicalName:emailaddress1
        Attribute LogicalName:address1_city
    <List truncated for brevity>
Entity SchemaName:Contact
        Attribute LogicalName:contactid
        Attribute LogicalName:emailaddress3
        Attribute LogicalName:emailaddress2
    <List truncated for brevity>

Créer une requête avec EntityQueryExpression

Utilisez EntityQueryExpression pour définir la propriété RetrieveMetadataChanges Query.

EntityQueryExpression a les propriétés suivantes :

Property Type Description
Properties MetadataPropertiesExpression Définit PropertyNames sur une liste de noms de propriétés à renvoyer. Ou vous pouvez définir AllProperties sur true pour retourner toutes les propriétés. Pour les articles qui en ont, vous n’avez pas besoin d’ajouter les noms de propriété MetadataId, LogicalName, ou HasChanged. Ces propriétés sont toujours incluses.
Criteria MetadataFilterExpression Voir Limiter les données renvoyées à l’aide de MetadataFilterExpression
AttributeQuery AttributeQueryExpression Suit le même schéma en tant que EntityQueryExpression. AttributeQueryExpression a également Properties et Criteria pour contrôler les définitions de colonne à retourner.

Remarque : lorsque vous utilisez AttributeQuery, Attributes doit être l’une des Properties demandées pour la EntityQueryExpression.
RelationshipQuery RelationshipQueryExpression Suit le même schéma en tant que EntityQueryExpression. RelationshipQueryExpression a également Properties et Criteria pour contrôler les définitions de relation à retourner.

Remarque : lorsque vous utilisez RelationshipQuery, OneToManyRelationships, ManyToOneRelationships ou ManyToManyRelationships doit être l’une des Properties demandées pour la EntityQueryExpression.
KeyQuery EntityKeyQueryExpression Suit le même schéma en tant que EntityQueryExpression. EntityKeyQueryExpression a également Properties et Criteria pour contrôler les définitions de clé secondaire à retourner.

Remarque : lorsque vous utilisez KeyQuery, Keys doit être l’une des Properties demandées pour la EntityQueryExpression.
LabelQuery LabelQueryExpression Utilisez la propriété FilterLanguages pour limiter les langues renvoyées. Si une organisation a plusieurs langues provisionnées, vous recevez des étiquettes pour toutes les langues qui pourraient ajouter considérablement aux données renvoyées. Si votre application est destinée à un utilisateur individuel, vous devez inclure les préférences de l’utilisateur en matière de Code de langue LCID. Voir Récupérer le code de langue préféré de l’utilisateur

Notes

Le paramètre Query est facultatif, vous pouvez donc utiliser RetrieveMetadataChanges sans aucun filtre, mais cela équivaut à utiliser RetrieveAllEntities, une opération très coûteuse.

Limiter les données renvoyées à l’aide de MetadataFilterExpression

Utilisez MetadataFilterExpression pour la propriété Criteria pour EntityQueryExpression, AttributeQueryExpression, RelationshipQueryExpression et EntityKeyQueryExpression.

MetadataFilterExpression contient les propriétés suivantes :

Property Type Description
FilterOperator LogicalOperator Contrôle la façon dont les Conditions sont évaluées, soit And ou Or.
Conditions DataCollection<MetadataConditionExpression> Un ensemble de conditions à évaluer. Voir Définir les conditions à l’aide de MetadataConditionExpression
Filters DataCollection<MetadataFilterExpression> Autres filtres à appliquer pour une requête plus complexe.

Définir les conditions à l’aide de MetadataConditionExpression

Utilisez MetadataConditionExpression pour la propriété MetadataFilterExpression Conditions.

MetadataConditionExpression contient les propriétés suivantes :

Property Type Description
ConditionOperator MetadataConditionOperator Décrit le type de comparaison à appliquer à la propriété Value.
PropertyName string Nom de la propriété à évaluer
Value object Valeur (ou valeurs) à comparer.

Généralement, vous ne pouvez utiliser que des propriétés qui représentent des types de données simples, des énumérations, BooleanManagedPropertyBooleanManagedProperty ou AttributeRequiredLevelManagedPropertyAttributeRequiredLevelManagedProperty dans une MetadataFilterExpression. Vous ne pouvez pas définir de conditions sur les propriétés qui sont des collections ou des étiquettes. Si BooleanManagedProperty ou AttributeRequiredLevelManagedProperty est spécifié, seule la propriété Value est évaluée. Le filtrage sur la propriété AttributeMetadata.SourceType n’est pas pris en charge.

Valeurs MetadataConditionOperator Enum

MetadataConditionOperator Enum a les membres suivants :

Champ Description
Equals Les valeurs sont comparées en termes d’égalité.
NotEquals Les deux valeurs ne sont pas égales.
In La valeur existe dans une liste de valeurs.
NotIn La valeur donnée ne correspond pas à une valeur dans une liste.
GreaterThan La valeur est supérieure à la valeur comparée.
LessThan La valeur est inférieure à la valeur comparée.

Traiter les données retournées

RetrieveMetadataChangesResponse a les propriétés suivantes :

Property Type Description
EntityMetadata EntityMetadataCollection Les définitions de table demandées. Lorsque vous interrogez des données ou lors de l’initialisation d’un cache, cette valeur peut être traitée de la même manière que la réponse du message RetrieveAllEntities. Si vous souhaitez accéder à une colonne, une relation ou une définition clé secondaire spécifique, vous devez renvoyer la définition de table qui les contient.
ServerVersionStamp string Un identifiant d’horodatage pour les métadonnées récupérées. Lorsque vous gérez un cache de définitions de schéma, utilisez cette valeur comme propriété ClientVersionStamp dans les requêtes suivantes afin que seules les modifications depuis la requête précédente soient renvoyées.
DeletedMetadata DeletedMetadataCollection Données des éléments supprimés depuis la demande précédente. Cette valeur ne contient des données que lorsque RetrieveMetadataChanges est envoyé avec les paramètres ClientVersionStamp et DeletedMetadataFilters . Pour plus d’informations, voir Mettre en cache les données du schéma

Récupérer le code de langue préféré de l’utilisateur

Les exemples suivants montrent comment vous pouvez récupérer le code de langue LCID préféré de l’utilisateur.

Vous pouvez récupérer la langue préférée de l’utilisateur à partir de la colonne UserSettings.UILanguageId.

static int? RetrieveUserUILanguageCode(IOrganizationService service)
{
   // To get the current user's systemuserid
   var whoIAm = (WhoAmIResponse)service.Execute(new WhoAmIRequest());

   var query = new QueryExpression("usersettings")
   {
         ColumnSet = new ColumnSet("uilanguageid", "systemuserid"),
         Criteria = new FilterExpression
         {
            Conditions = {
                  {
                     new ConditionExpression(
                        attributeName:"systemuserid",
                        conditionOperator:ConditionOperator.Equal,
                        value: whoIAm.UserId)
                  }
            }
         },
         TopCount = 1
   };

   EntityCollection userSettings = service.RetrieveMultiple(query: query);
   if (userSettings.Entities.Count > 0)
   {
         return (int)userSettings.Entities[0]["uilanguageid"];
   }
   return null;
}

Voir aussi

Mettre en cache les données de schéma
Exemple d’API Web Rechercher les définitions de schéma et détecter les modifications (C#)
Kit de développement logiciel (SDK) pour .NET : exemple pour rechercher les définitions de schéma et détecter les modifications (C#)
SDK pour .NET : Définitions de table dans Microsoft Dataverse
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é).