Freigeben über

Abfragetabellendefinitionen mithilfe der Web-API

Da Microsoft Dataverse eine metadatengesteuerte Anwendung ist, müssen Entwickler die Systemdefinitionen möglicherweise zur Laufzeit abfragen, um sich an die Konfiguration einer Organisation anzupassen. Dieses Feature verwendet einen RESTful-Abfragenstil.

Anmerkung

Sie können eine Abfrage auch mithilfe einer objektbasierten Formatvorlage erstellen, indem Sie den EntityQueryExpression ComplexType mit der RetrieveMetadataChanges-Funktion verwenden. Diese Funktion erfasst Änderungen an Tabellendefinitionen zwischen zwei Zeiträumen und gibt einen begrenzten Satz von Definitionen zurück, die von einer von Ihnen angegebenen Abfrage beschrieben werden. Weitere Informationen finden Sie unter Abfrageschemadefinitionen.

Abfragen des EntityMetadata-Entitätstyps

Verwenden Sie die gleichen Techniken, die in Abfragedaten mit der Web-API beschrieben sind, um EntityMetadata mit einigen Variationen abzufragen. Über den festgelegten Pfad der EntityDefinitions-Entität können Sie Informationen zu EntityMetadata EntityType abrufen. EntityMetadata-Entitäten enthalten viele Daten. Rufen Sie daher nur die benötigten Daten ab. Das folgende Beispiel zeigt die Daten, die nur für DisplayName, IsKnowledgeManagementEnabled und EntitySetName-Eigenschaften der Definition für die Account-Entität zurückgegeben werden. Der MetadataId-Eigenschaftswert wird immer zurückgegeben.

Anforderung:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=DisplayName,IsKnowledgeManagementEnabled,EntitySetName HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{  
 "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(DisplayName,IsKnowledgeManagementEnabled,EntitySetName)",  
 "value": [  
  {  
   "DisplayName": {  
    "LocalizedLabels": [  
     {  
      "Label": "Account",  
      "LanguageCode": 1033,  
      "IsManaged": true,  
      "MetadataId": "2a4901bf-2241-db11-898a-0007e9e17ebd",  
      "HasChanged": null  
     }  
    ],  
    "UserLocalizedLabel": {  
     "Label": "Account",  
     "LanguageCode": 1033,  
     "IsManaged": true,  
     "MetadataId": "2a4901bf-2241-db11-898a-0007e9e17ebd",  
     "HasChanged": null  
    }  
   },  
   "IsKnowledgeManagementEnabled": false,  
   "EntitySetName": "accounts",  
   "MetadataId": "70816501-edb9-4740-a16c-6a5efbc05d84"  
  }  
 ]  
}

Sie können jede der EntityMetadata Eigenschaften mit $select Systemabfrageoptionen verwenden. Sie können $filter auf alle Eigenschaften verwenden, die primitive oder Enumerationswerte verwenden.

Es gibt keine Grenzwerte für die Anzahl der Metadatenentitäten, die eine Abfrage zurückgibt. Es gibt kein Paging. Die erste Antwort gibt alle übereinstimmenden Ressourcen zurück.

Zurückgegebene Sprachen einschränken

Wenn in einer Umgebung viele Sprachen bereitgestellt werden, wird eventuell eine sehr große Datenmenge zurückgegeben. Um eine optimale Leistung zu erzielen, beschränken Sie die zurückgegebenen Sprachbezeichnungen mithilfe des LabelLanguages Parameters mit dem LCID-Wert der Sprache, die Sie zurückgeben möchten.

Sprachcodes sind vierstellige oder fünfstellige Locale-IDs. Gültige Gebietsschema-ID-Werte finden Sie unter Gebietsschema-ID-Diagramm (LCID).

Wenn Sie beispielsweise den folgenden Wert anfügen, werden die lokalisierten Sprachbeschriftungen auf Englisch beschränkt: &LabelLanguages=1033

Verwenden von Enum-Typen in $filter-Vorgängen

Wenn Sie Metadatenentitäten basierend auf dem Wert einer Eigenschaft filtern müssen, die eine Enumeration verwendet, schließen Sie den Namespace der Enumeration vor dem Zeichenfolgenwert ein. Enumerationstypen werden als Eigenschaftswerte nur in den Metadatenentitäten und komplexen Arten verwendet. Wenn Sie beispielsweise Entitäten basierend auf der OwnershipType-Eigenschaft filtern müssen, die den OwnershipTypes-Enumtyp verwendet, verwenden Sie die folgende $filter, um nur die Entitäten zurückzugeben, die UserOwned sind.

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=LogicalName&$filter=OwnershipType eq Microsoft.Dynamics.CRM.OwnershipTypes'UserOwned'

Verwendung von komplexen Typen in $filter-Vorgängen

Wenn Sie Metadatenentitäten basierend auf dem Wert einer Eigenschaft filtern müssen, die einen komplexen Typ verwendet, schließen Sie den Pfad zum zugrunde liegenden Grundtyp ein. Komplexe Typen werden als Eigenschaftswerte nur in den Metadatenentitäten verwendet. Wenn Sie beispielsweise Entitäten basierend auf der Eigenschaft CanCreateAttributes filtern müssen, die den BooleanManagedProperty ComplexType verwendet, verwenden Sie das folgende $filter, um nur die Entitäten zurückzugeben, die eine Value von true haben.

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=LogicalName&$filter=CanCreateAttributes/Value eq true

Dieses Muster verwendet BooleanManagedProperty ComplexType, da der einfache zu prüfende Wert eine Ebene tief ist. Dieses Muster funktioniert jedoch nicht für Eigenschaften von Label ComplexType.

Abfrage von EntityMetadata-Attributen

Sie können Entitätsattribute im Kontext einer Entität abfragen, indem Sie die Attributes Navigationseigenschaft mit Sammlungswert erweitern. Dieser Ansatz enthält nur die allgemeinen Eigenschaften, die im AttributeMetadata EntityType verfügbar sind, die alle Attribute gemeinsam nutzen. Die folgende Abfrage gibt beispielsweise die Entität LogicalName und alle erweiterten Attribute zurück, die einen AttributeType-Wert aufweisen, der dem AttributeTypeCode EnumType-Wert und Picklist entspricht.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=LogicalName&$expand=Attributes($select=LogicalName;$filter=AttributeType eq Microsoft.Dynamics.CRM.AttributeTypeCode'Picklist')

Sie können jedoch nicht die Sammlungswert-Navigationseigenschaften OptionSet oder GlobalOptionSet einschließen, die PicklistAttributeMetadata EntityType-Attribute im $select-Filter dieser Abfrage enthalten.

Um die Eigenschaften eines bestimmten Attributtyps abzurufen, casten Sie die Attributes kollektionswertige Navigierungseigenschaft in den gewünschten Typ um. Die folgende Abfrage gibt nur die Attribute "PicklistAttributeMetadata EntityType " zurück. Sie umfasst die LogicalName und erweitert die OptionSet- und GlobalOptionSet-Sammlungsnavigationseigenschaften.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet,GlobalOptionSet

Anmerkung

Obwohl die OptionSet und GlobalOptionSet Navigationseigenschaften mit Sammlungswert in EnumAttributeMetadata EntityType definiert sind, können Sie die Attribute nicht in diesen Typ konvertieren. Diese Einschränkung bedeutet, dass Sie separate Abfragen ausführen müssen, um nach anderen Typen zu filtern, die diese Eigenschaften erben. Weitere Informationen finden Sie unter Entitätstypen, die von EnumAttributeMetadata erben.

Ein weiteres Beispiel für diese Einschränkung ist der Zugriff auf die Eigenschaft, die in den Precision Attributen MoneyAttributeMetadata EntityType und DecimalAttributeMetadata EntityType verfügbar ist. Um auf diese Eigenschaft zuzugreifen, müssen Sie die Attributsammlung entweder als MoneyAttributeMetadata EntityType oder als DecimalAttributeMetadata EntityType casten. Ein Beispiel, das das Umwandeln zu MoneyAttributeMetadata veranschaulicht, wird hier angezeigt.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes/Microsoft.Dynamics.CRM.MoneyAttributeMetadata?$select=LogicalName,Precision

Filtern nach erforderlicher Ebene

Die AttributeMetadata EntityTypeRequiredLevel-Eigenschaft verwendet einen speziellen AttributeRequiredLevelManagedProperty ComplexType, bei dem die Value-Eigenschaft ein AttributeRequiredLevel EnumType ist. Um nach dieser eindeutigen Eigenschaft zu filtern, kombinieren Sie Muster, die in komplexen Typen in $filter Vorgängen verwendet werden, und verwenden Sie Enumerationstypen in $filter Vorgängen. Die folgende Abfrage filtert diese Attribute in der Kontoentität, die ApplicationRequired sind.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes?$select=SchemaName&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'

Abrufen von Attributen

Wenn Sie den MetadataId sowohl für den EntityMetadata als auch für den AttributeMetadata kennen oder den LogicalName-Wert für einen von beiden wissen, können Sie ein einzelnes Attribut abrufen und auf die Eigenschaftswerte zugreifen, indem Sie die folgende Abfrage verwenden. Diese Abfrage ruft die LogicalName Eigenschaft des Attributs ab und erweitert die Eigenschaft der OptionSet Sammlungswertnavigation. Sie müssen das Attribut als Microsoft.Dynamics.CRM.PicklistAttributeMetadata umwandeln, damit Sie auf die Sammlungswert-Navigationseigenschaft OptionSet zugreifen können.

Anforderung:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet HTTP/1.1  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0

{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata(LogicalName,OptionSet)/$entity",  
"LogicalName": "preferredappointmentdaycode",  
"MetadataId": "5967e7cc-afbb-4c10-bf7e-e7ef430c52be",  
"OptionSet@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet/$entity",  
"OptionSet": {  
 "Options": [  
  {  
   "Value": 0,  
   "Label": {  
    "LocalizedLabels": [  
     {  
      "Label": "Sunday",  
      "LanguageCode": 1033,  
      "IsManaged": true,  
      "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
      "HasChanged": null  
     }  
    ],  
    "UserLocalizedLabel": {  
     "Label": "Sunday",  
     "LanguageCode": 1033,  
     "IsManaged": true,  
     "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
     "HasChanged": null  
    }  
   },  
   "Description": {  
    "LocalizedLabels": [],  
    "UserLocalizedLabel": null  
   },  
   "Color": null,  
   "IsManaged": true,  
   "MetadataId": null,  
   "HasChanged": null  
  }  
Additional options removed for brevity  
 ],  
 "Description": {  
  "LocalizedLabels": [  
   {  
    "Label": "Day of the week that the account prefers for scheduling service activities.",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "1b67144d-ece0-4e83-a38b-b4d48e3f35d5",  
    "HasChanged": null  
   }  
  ],  
  "UserLocalizedLabel": {  
   "Label": "Day of the week that the account prefers for scheduling service activities.",  
   "LanguageCode": 1033,  
   "IsManaged": true,  
   "MetadataId": "1b67144d-ece0-4e83-a38b-b4d48e3f35d5",  
   "HasChanged": null  
  }  
 },  
 "DisplayName": {  
  "LocalizedLabels": [  
   {  
    "Label": "Preferred Day",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "ebb7e979-f9e3-40cd-a86d-50b479b1c5a4",  
    "HasChanged": null  
   }  
  ],  
  "UserLocalizedLabel": {  
   "Label": "Preferred Day",  
   "LanguageCode": 1033,  
   "IsManaged": true,  
   "MetadataId": "ebb7e979-f9e3-40cd-a86d-50b479b1c5a4",  
   "HasChanged": null  
  }  
 },  
 "IsCustomOptionSet": false,  
 "IsGlobal": false,  
 "IsManaged": true,  
 "IsCustomizable": {  
  "Value": true,  
  "CanBeChanged": false,  
  "ManagedPropertyLogicalName": "iscustomizable"  
 },  
 "Name": "account_preferredappointmentdaycode",  
 "OptionSetType": "Picklist",  
 "IntroducedVersion": null,  
 "MetadataId": "53f9933c-18a0-40a6-b4a5-b9610a101735",  
 "HasChanged": null  
}  
}

Wenn Sie keine Eigenschaften des Attributs benötigen und nur die Werte einer Sammlungswert-Navigationseigenschaft, wie OptionSet, benötigen, fügen Sie diese Eigenschaft in die URL ein und beschränken Sie die Eigenschaften mithilfe einer $select-Systemabfrageoption für eine effizientere Abfrage. Im folgenden Beispiel ist nur die Options Eigenschaft des OptionSet Objekts enthalten.

Anforderung:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet?$select=Options HTTP/1.1  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{  
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions('account')/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet(Options)/$entity",  
"Options": [{  
  "Value": 0,  
  "Label": {  
   "LocalizedLabels": [{  
    "Label": "Sunday",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
    "HasChanged": null  
   }],  
   "UserLocalizedLabel": {  
    "Label": "Sunday",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
    "HasChanged": null  
   }  
  },  
  "Description": {  
   "LocalizedLabels": [],  
   "UserLocalizedLabel": null  
  },  
  "Color": null,  
  "IsManaged": true,  
  "MetadataId": null,  
  "HasChanged": null  
 }  
Additional options removed for brevity  
],  
"MetadataId": "53f9933c-18a0-40a6-b4a5-b9610a101735"  
}

Abfragebeziehungsmetadaten

Sie können Beziehungsmetadaten im Kontext einer bestimmten Entität abrufen, ähnlich wie Beim Abfragen von Attributen. Sie können die ManyToManyRelationships, ManyToOneRelationships und OneToManyRelationships sammlungswertige Navigationseigenschaften genau wie die Attributes-Navigationseigenschaft mit Sammlungswerten abfragen. Weitere Informationen finden Sie unter QueryEntityMetadata Attributes.

Sie können jedoch auch Entitätsbeziehungen mithilfe des Entitätssatzes RelationshipDefinitions abfragen. Verwenden Sie eine Abfrage wie das folgende Beispiel, um die SchemaName Eigenschaft für jede Beziehung abzurufen.

GET [Organization URI]/api/data/v9.2/RelationshipDefinitions?$select=SchemaName

Die Eigenschaften, die verfügbar sind, wenn dieser Entitätssatz abgefragt wird, werden auf die im RelationshipMetadataBase EntityType beschränkt. Um auf Eigenschaften von den Entitätstypen zuzugreifen, die von RelationshipMetadataBase erben, schließen Sie eine Typumwandlung in die Abfrage ein, wie im folgenden Beispiel, um nur OneToManyRelationshipMetadata EntityType zurückzugeben.

GET [Organization URI]/api/data/v9.2/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName

Da die zurückgegebenen Entitäten als Typ OneToManyRelationshipMetadata typisiert werden, können Sie nach Eigenschaften wie ReferencedEntity filtern, um eine Abfrage zu erstellen, die nur die 1:n-Entitätsbeziehungen für eine bestimmte Entität zurückgibt, z. B. die in der folgenden Abfrage gezeigte Kontoentität:

GET [Organization URI]/api/data/v9.2/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName&$filter=ReferencedEntity eq 'account'

Diese Abfrage liefert im Wesentlichen dieselben Ergebnisse wie die folgende Abfrage, die gefiltert wird, weil sie im EntityMetadataOneToManyRelationships sammlungsbasierten Navigationsattribut der Kontoeinheit enthalten ist. Der Unterschied ist, dass Sie für die vorherige Abfrage nicht die MetadataId für die Kontenentität kennen müssen.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/OneToManyRelationships?$select=SchemaName

Globale Optionssätze abfragen

Sie können den festgelegten GlobalOptionSetDefinitions-Entitätspfad verwenden, um Informationen zu globalen Optionssätzen abzurufen, aber der Pfad unterstützt nicht die Verwendung der $filter-Systemabfrageoption. Sie können also nur einen einzelnen globalen Optionssatz abrufen, indem Sie entweder das MetadataId oder den eindeutigen Namen verwenden.

Beispiel: Nach Metadaten-ID

Das folgende Beispiel zeigt, wie Sie mithilfe der MetadataId ein globales Optionssatz abrufen können.

GET [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions(08fa2cb2-e3fe-497a-9b5d-ee887f5cc3cd)

Beispiel nach Name

Das folgende Beispiel zeigt, wie sie eine globale Option abrufen, die anhand des Namens festgelegt ist:

GET [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions(Name='incident_caseorigincode')

Sie können auch auf die Definition eines globalen Optionssatzes in der einzelwertigen GlobalOptionSet-Navigationseigenschaft für jedes Attribut, das diese verwendet, zugreifen. Diese Eigenschaft ist für alle abgeleiteten EnumAttributeMetadata EntityType-Typen verfügbar. Weitere Informationen finden Sie unter Abrufen von Attributen.

Siehe auch

Verwenden der Web-API mit Dataverse-Metadaten
Abrufen von Metadaten über den Namen oder die MetadataId
Metadaten-Entitäten und -Attribute unter Verwendung der Web-API
Metadaten-Entitätsbeziehungen modellieren mit Internet-API
Beispiel für Web-API-Tabellenschemavorgänge
Beispiel für Web-API-Tabellenschemavorgänge (C#)

  • Last updated on