Freigeben über

Abfrageschemadefinitionen

Anwendungen, die mit Dataverse erstellt wurden, müssen sich an Änderungen an Schemadefinitionen anpassen können. Neue Tabellen, Spalten, Beziehungen und Bezeichnungen können über die Konfiguration oder durch Importieren einer Lösung hinzugefügt oder geändert werden. Da Anwendungen auf diese Änderungen reagieren können müssen, hängen sie häufig davon ab, Schemadefinitionen abzurufen, wenn sie beginnen. Die Gesamtmenge der Daten, die das Schema einer Dataverse-Organisation beschreiben, kann jedoch sehr groß sein. Sie müssen wissen können, wie Sie nur die benötigten Daten abrufen können.

Die RetrieveMetadataChanges Nachricht bietet zwei Funktionen:

  1. Abfrage: Verfassen Sie eine einzelne Abfrage, um nur die benötigten Schemadaten abzurufen. Dieser Artikel konzentriert sich auf das Verfassen von Abfragen.
  2. Cache-Verwaltung: Wenn Sie die Schemadefinitionsdaten mit Ihrer App zwischenspeichern, können Sie mit RetrieveMetadataChanges effizient nur die Änderungen seit Ihrer letzten Abfrage abrufen. Verwenden Sie die Informationen zu diesen Änderungen, um Elemente im Cache hinzuzufügen oder zu entfernen. Das Zwischenspeichern kann die Startzeit Ihrer Anwendung erheblich verkürzen. Die Cacheverwaltung wird in Cacheschemadaten behandelt.

Auswerten anderer Optionen zum Abrufen von Schemadefinitionen

Beim Verfassen einer Abfrage zum Abrufen von Schemadefinitionen bietet die Nachricht einen Vorteil zum RetrieveMetadataChanges Definieren einer einzelnen Anforderung, die mehrere Tabellendefinitionen umfassen und Details für abgeleitete Typen zurückgeben und einen Cache im Laufe der Zeit verwalten kann.

In der folgenden Tabelle werden weitere Möglichkeiten zum Abrufen von Schemadefinitionen zusammengefasst, aber keiner davon bietet Funktionen zum Verwalten eines Caches im Laufe der Zeit.

Nachricht Beschreibung und Einschränkungen
RetrieveAllEntities Ruft Bei Bedarf Daten für alle Tabellen ab, einschließlich aller Spalten, Berechtigungen und Beziehungen.
Siehe: RetrieveAllEntitiesRequest - und RetrieveAllEntitiesResponse-Klassen .

Einschränkungen: Während Sie den EntityFilters Parameter verwenden können, um einige Teile auszuschließen, handelt es sich um einen sehr kostspieligen Vorgang.
RetrieveEntity Sie können bei Bedarf eine Definition einer beliebigen einzelnen Tabelle einschließlich aller Spalten, Berechtigungen und Beziehungen abrufen.
Siehe: Abrufen und Aktualisieren einer Tabelle

Einschränkungen: Während Sie den EntityFilters Parameter verwenden können, um einige Daten auszuschließen, können Sie nicht auswählen, welche spezifischen Eigenschaften Sie benötigen, es ist dennoch ein teurer Vorgang.
RetrieveAttribute Sie können die vollständige Definition eines beliebigen einzelnen Attributs abrufen.
Siehe: Abrufen einer Spalte

Einschränkungen: Sie können nicht auswählen, welche bestimmten Eigenschaften Sie benötigen.
RetrieveRelationship Sie können die vollständige Definition einer einzelnen Beziehung abrufen.
Siehe: Abrufen von Tabellenbeziehungen

Einschränkungen: Sie können nicht auswählen, welche bestimmten Eigenschaften Sie benötigen.
RetrieveAllOptionSets Sie können Informationen zu allen globalen Auswahlmöglichkeiten abrufen, die in der Organisation definiert sind.
Siehe: Einfügen, Aktualisieren, Löschen und Anordnen globaler Auswahlmöglichkeiten

Einschränkungen: Auswahlmöglichkeiten, die nur lokal innerhalb einer Spalte definiert sind, sind nicht enthalten.
RetrieveEntityKey Sie können die Definition für alle alternativen Schlüssel für eine bestimmte Tabelle abrufen.
Siehe:Abrufen und Löschen alternativer Schlüssel

Beispiel für einfache RetrieveMetadataChanges

Ein einfaches Beispiel dafür, was Sie mit RetrieveMetadataChanges tun können, ist der Vergleich dessen, was Sie mit der Web-API und dem Entitätssatz EntityDefinitions tun können.

Mithilfe der Web-API können Sie eine Abfrage wie folgt erstellen:

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)

Diese Abfrage gibt Daten aus den Account- und Kontakttabellendefinitionen zurück und erweitert alle Spalten, bei denen IsValidForCreate "true" ist.

Die folgenden Beispiele zeigen, wie Sie dieselbe Abfrage mithilfe von 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}");
        });
    });
}

Ausgabe:

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>

Erstellen einer Abfrage mithilfe von EntityQueryExpression

Verwenden Sie EntityQueryExpression, um die Eigenschaft RetrieveMetadataChangesQuery festzulegen.

EntityQueryExpression verfügt über die folgenden Eigenschaften:

Eigentum Typ Description
Properties MetadataPropertiesExpression Stellen Sie PropertyNames auf eine Liste mit Eigenschaftsnamen ein, die zurückgegeben werden sollen. Alternativ können Sie auf "true" festlegen AllProperties , um alle Eigenschaften zurückzugeben. Für Artikel, die sie enthalten, müssen Sie die Namen der Eigenschaften MetadataId, LogicalName oder HasChanged nicht hinzufügen. Diese Eigenschaften werden immer einbezogen.
Criteria MetadataFilterExpression Siehe Einschränken der zurückgegebenen Daten mithilfe von MetadataFilterExpression
AttributeQuery AttributeQueryExpression Folgt demselben Muster wie EntityQueryExpression. AttributeQueryExpression verfügt auch über Properties und Criteria zur Steuerung, welche Spaltendefinitionen zurückgegeben werden.

Hinweis: Wenn Sie AttributeQuery verwenden, muss Attributes eines der Properties sein, die für das EntityQueryExpression angefordert wurden.
RelationshipQuery RelationshipQueryExpression Folgt demselben Muster wie EntityQueryExpression. RelationshipQueryExpression außerdem muss Properties und Criteria steuern, welche Beziehungsdefinitionen zurückgegeben werden sollen.

Hinweis: Wenn Sie RelationshipQuery, OneToManyRelationships, ManyToOneRelationships oder ManyToManyRelationships verwenden, müssen sie zu den für EntityQueryExpression angeforderten Properties gehören.
KeyQuery EntityKeyQueryExpression Folgt demselben Muster wie EntityQueryExpression. EntityKeyQueryExpression außerdem muss Properties und Criteria steuern, welche alternativen Schlüsseldefinitionen zurückgegeben werden sollen.

Hinweis: Wenn Sie KeyQuery verwenden, muss Keys einer der Properties sein, die für das EntityQueryExpression angefordert wurden.
LabelQuery LabelQueryExpression Verwenden Sie dieFilterLanguages Eigenschaft, um die zurückgegebenen Sprachen einzuschränken. Wenn eine Organisation viele Sprachen bereitgestellt hat, erhalten Sie Bezeichnungen für alle Sprachen, die den zurückgegebenen Daten erheblich hinzugefügt werden können. Wenn Ihre App für einen einzelnen Benutzer vorgesehen ist, sollten Sie den bevorzugten LCID-Sprachcode des Benutzers einschließen. Siehe Abrufen des bevorzugten Sprachcodes des Benutzers

Hinweis

Der Query Parameter ist optional, sodass Sie ohne Filter verwenden RetrieveMetadataChanges können, aber dies entspricht der Verwendung RetrieveAllEntitieseines sehr kostspieligen Vorgangs.

Einschränken der zurückgegebenen Daten mithilfe von MetadataFilterExpression

Verwenden Sie MetadataFilterExpression für die Criteria Eigenschaft für EntityQueryExpression, AttributeQueryExpression, RelationshipQueryExpression und EntityKeyQueryExpression.

MetadataFilterExpression hat die folgenden Eigenschaften:

Eigentum Typ Description
FilterOperator LogicalOperator Steuert, wie die Conditions bewertet werden, entweder And oder Or.
Conditions DataCollection<MetadataConditionExpression> Eine Sammlung von Bedingungen, die ausgewertet werden sollen. Siehe Festlegen von Bedingungen mithilfe von MetadataConditionExpression
Filters DataCollection<MetadataFilterExpression> Weitere Filter, die für eine komplexere Abfrage angewendet werden sollen.

Festlegen von Bedingungen mithilfe von MetadataConditionExpression

Verwenden Sie MetadataConditionExpression für die MetadataFilterExpression-EigenschaftConditions .

MetadataConditionExpression hat die folgenden Eigenschaften:

Eigentum Typ Description
ConditionOperator MetadataConditionOperator Beschreibt den Typ des Vergleichs, der auf die Value Eigenschaft angewendet werden soll.
PropertyName Schnur Der Name der auszuwertenden Eigenschaft
Value Objekt Der zu vergleichende Wert (oder die Werte).

Im Allgemeinen können Sie nur Eigenschaften verwenden, die einfache Datentypen, Enumerationen, BooleanManagedProperty oder AttributeRequiredLevelManagedProperty in einem MetadataFilterExpression repräsentieren. Sie können keine Bedingungen für Eigenschaften festlegen, die Sammlungen oder Bezeichnungen sind. Wenn eine BooleanManagedProperty oder AttributeRequiredLevelManagedProperty angegeben ist, kann nur die Eigenschaft Value ausgewertet werden. Das Filtern auf "AttributeMetadata.SourceType"-Eigenschaft wird nicht unterstützt.

MetadataConditionOperator-Aufzählungswerte

Die MetadataConditionOperator-Aufzählung hat die folgenden Mitglieder:

Feld Description
Equals Die Werte werden für Gleichheit verglichen.
NotEquals Die beiden Werte sind nicht gleich.
In Der Wert ist in einer Liste von Werten vorhanden.
NotIn Der angegebene Wert wird nicht mit einem Wert in einer Liste abgeglichen.
GreaterThan Der Wert ist größer als der Vergleichswert.
LessThan Der Wert ist kleiner als der Vergleichswert.

Zurückgegebene Verarbeitungsdaten

Die RetrieveMetadataChangesResponse verfügt über die folgenden Eigenschaften:

Eigentum Typ Description
EntityMetadata EntityMetadataCollection Die angeforderten Tabellendefinitionen. Beim Abfragen von Daten oder beim Initialisieren eines Caches kann dieser Wert mit der Antwort der RetrieveAllEntities Nachricht identisch behandelt werden. Wenn Sie auf eine bestimmte Spalte, Beziehung oder alternative Schlüsseldefinition zugreifen möchten, müssen Sie die Tabellendefinition zurückgeben, die sie enthält.
ServerVersionStamp string Ein Zeitstempel-Identifikator für die abgerufenen Metadaten. Wenn Sie einen Cache von Schemadefinitionen verwalten, verwenden Sie diesen Wert als ClientVersionStamp Eigenschaft in nachfolgenden Anforderungen, sodass nur die Änderungen seit der vorherigen Anforderung zurückgegeben werden.
DeletedMetadata DeletedMetadataCollection Daten für die Elemente, die seit der vorherigen Anforderung gelöscht wurden. Dieser Wert enthält nur Daten, wenn RetrieveMetadataChanges mit den Parametern ClientVersionStamp und DeletedMetadataFilters gesendet wird. Weitere Informationen finden Sie unter Cache Schema Daten

Abrufen des bevorzugten Sprachcodes des Benutzers

Die folgenden Beispiele zeigen, wie Sie den bevorzugten LCID-Sprachcode des Benutzers abrufen können.

Sie können die bevorzugte Sprache des Benutzers aus der Spalte UserSettings.UILanguageId abrufen.

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;
}

Siehe auch

Cache-Schema-Daten
Web-API-Abfrageschemadefinitionen und Erkennen von Änderungen (Beispiel) (C#)
SDK für .NET-Abfrageschemadefinitionen und Erkennen von Änderungen (Beispiel) (C#)
SDK für .NET: Tabellendefinitionen in Microsoft Dataverse
Abfragen von Tabellendefinitionen mithilfe der Web-API

  • Last updated on