Partager via

Rechercher les définitions de schéma

Les applications créées à l’aide de Dataverse doivent pouvoir s’adapter aux modifications apportées aux définitions de schéma. De nouvelles tables, colonnes, relations et étiquettes peuvent être ajoutées ou modifiées via la configuration ou en important une solution. Étant donné que les applications doivent pouvoir répondre à ces modifications, elles dépendent fréquemment de la récupération des définitions de schéma au démarrage. Toutefois, la quantité totale de données décrivant le schéma d’une organisation Dataverse peut être très importante. Vous devez être en mesure de 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 un temps d’amélioration significatif pour que votre application démarre. La gestion du cache est couverte dans les données de schéma du cache.

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

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

Le tableau suivant récapitule d’autres façons 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 de toutes les tables, y compris toutes les colonnes, privilèges et relations si vous le souhaitez.
Voir : Classes RetrieveAllEntitiesRequest et RetrieveAllEntitiesResponse .

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

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

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

Limitations : vous ne pouvez pas sélectionner les propriétés spécifiques souhaitées.
RetrieveAllOptionSets Vous pouvez récupérer des informations sur tous les choix globaux définis dans l’organisation.
Voir : Choix globaux d’insertion, de mise à jour, de suppression et de commande

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

Exemple de base de "RetrieveMetadataChanges"

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

À l’aide de l’API web, vous pouvez composer une requête comme suit :

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 retourne des données à partir des définitions de compte et de table de contact, puis développez toutes les définitions de colonnes où IsValidForCreate la valeur est true.

Les exemples suivants montrent comment composer la même requête à l’aide RetrieveMetadataChangesde .

/// <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 à l’aide d’EntityQueryExpression

Utilisez EntityQueryExpression pour définir la propriété RetrieveMetadataChangesQuery.

EntityQueryExpression a les propriétés suivantes :

Propriété Type Descriptif
Properties MetadataPropertiesExpression Définissez PropertyNames pour qu'il comporte une liste de noms de propriétés à renvoyer. Vous pouvez également définir AllProperties la valeur true pour renvoyer toutes les propriétés. Pour les éléments qui les possèdent, vous n'avez pas besoin d'ajouter les noms de propriétés MetadataId, LogicalName, ou HasChanged. Ces propriétés seront toujours incluses.
Criteria MetadataFilterExpression Voir Limiter les données retournées à l’aide de MetadataFilterExpression
AttributeQuery AttributeQueryExpression Suit le même modèle 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 Properties des demandes pour le EntityQueryExpression.
RelationshipQuery RelationshipQueryExpression Suit le même modèle 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, ils doivent être l'un des Properties demandés pour le EntityQueryExpression.
KeyQuery EntityKeyQueryExpression Suit le même modèle que EntityQueryExpression. EntityKeyQueryExpression a également Properties et Criteria pour contrôler quelles définitions alternatives de clé doivent être retournées.

Remarque : lorsque vous utilisez KeyQuery, Keys doit être l’une Properties des demandes pour le EntityQueryExpression.
LabelQuery LabelQueryExpression Utilisez laFilterLanguages propriété pour limiter les langues retournées. Si une organisation a provisionné de nombreuses langues, vous recevez des libellés pour toutes ces langues, ce qui pourrait augmenter considérablement les données retournées. Si votre application concerne un utilisateur individuel, vous devez inclure le code de langue LCID préféré de l’utilisateur. Voir Récupérer le code de langue préféré de l’utilisateur

Note

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

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

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

MetadataFilterExpression possède les propriétés suivantes :

Propriété Type Descriptif
FilterOperator LogicalOperator Contrôle comment les Conditions sont évalués, soit And ou Or.
Conditions DataCollection<MetadataConditionExpression> Collection de conditions à évaluer. Voir Définir des conditions à l’aide de MetadataConditionExpression
Filters DataCollection<MetadataFilterExpression> Plus de filtres à appliquer pour une requête plus complexe.

Définir des conditions à l’aide de MetadataConditionExpression

Utilisez MetadataConditionExpression pour la propriété MetadataFilterExpressionConditions .

MetadataConditionExpression possède les propriétés suivantes :

Propriété Type Descriptif
ConditionOperator MetadataConditionOperator Décrit le type de comparaison à appliquer à la Value propriété.
PropertyName ficelle Nom de la propriété à évaluer
Value objet Valeur (ou valeurs) à comparer.

En règle générale, vous pouvez uniquement utiliser des propriétés qui représentent des types de données simples, des énumérations, BooleanManagedProperty ou AttributeRequiredLevelManagedProperty dans un MetadataFilterExpression. Vous ne pouvez pas définir des clauses 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 de l’énumération MetadataConditionOperator

L’énumération MetadataConditionOperator comporte les membres suivants :

Champ Descriptif
Equals Les valeurs sont comparées pour l’égalité.
NotEquals Les deux valeurs ne sont pas égales.
In La valeur existe dans une liste de valeurs.
NotIn La valeur donnée n’est pas associée à 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 :

Propriété Type Descriptif
EntityMetadata EntityMetadataCollection Les définitions de table demandées. Lorsque vous interrogez des données ou que vous initialisez un cache, cette valeur peut être traitée comme la réponse du RetrieveAllEntities message. Si vous souhaitez accéder à une colonne, une relation ou une autre définition de clé, vous devez retourner la définition de table qui les contient.
ServerVersionStamp string Identificateur 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 ClientVersionStamp propriété dans les requêtes suivantes afin que seules les modifications apportées depuis la demande précédente soient retournées.
DeletedMetadata CollectionDeMétadonnéesSupprimées Données pour les éléments supprimés depuis la demande précédente. Cette valeur contient des données uniquement lorsque RetrieveMetadataChanges est envoyé avec les paramètres ClientVersionStamp et DeletedMetadataFilters. Pour plus d’informations, consultez Les données de schéma du cache

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

Les exemples suivants montrent comment récupérer le code de langage 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

Données de schéma mises en cache
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
Requête des définitions de table à l’aide de l’API web

  • Last updated on