Abfragen von Tabellendefinitionen mithilfe der Web-API

Artikel
06/03/2023

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

Hinweis

Sie können auch eine Abfrage mithilfe eines objektbasierten Stils unter Verwendung des EntityQueryExpression ComplexType mit der RetrieveMetadataChanges Function erstellen. Diese Funktion ermöglicht das Erfassen von Änderungen an Tabellendefinitionen zwischen zwei Zeiträumen sowie das Zurückgeben eines begrenzten Satzes von Definitionen, die durch eine von Ihnen angegebene Abfrage beschrieben werden. Weitere Informationen: Abfrageschemadefinitionen

Abfragen des EntityMetadata-Entitätstyps

Sie verwenden beim Abfragen von EntityMetadata die gleichen Techniken, die unter Abfragen von Daten mit der Web-API beschrieben sind, allerdings mit einigen Variationen. Über den festgelegten Pfad der EntityDefinitions-Entität können Sie Informationen zu EntityMetadata EntityType abrufen. EntityMetadata-Entitäten enthalten viele Daten, sodass Sie unbedingt darauf achten sollten, dass Sie nur die Daten abrufen, die Sie benötigen. 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 den $select-Systemabfrageoptionen verwenden und Sie können $filter für alle Eigenschaften verwenden, die einfache oder Enumerationswerte verwenden.

Es gibt keine Beschränkungen zur Anzahl der Metadatenentitäten, die in einer Abfrage zurückgegeben werden. Es gibt kein Auslagern. Alle entsprechenden Ressourcen werden mit der ersten Antwort zurückgegeben.

Zurückgegebene Sprachen einschränken

Wenn in einer Umgebung viele Sprachen bereitgestellt werden, wird eventuell eine sehr große Datenmenge zurückgegeben. Um die beste Leistung zu erzielen, beschränken Sie die zurückgegebenen Sprachbezeichnungen mithilfe des Parameters LabelLanguages auf den LCID-Wert der Sprache, die zurückgegeben werden soll.

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

Wenn Sie beispielsweise &LabelLanguages=1033 anhängen, werden die lokalisierten Sprachbezeichnungen auf Englisch beschränkt.

Verwendung von Enumerationstypen in $filter-Vorgängen

Wenn Sie Metadatenentitäten auf Grundlage des Werts einer Eigenschaft filtern müssen, die eine Enumeration verwendet, muss zudem der Namespace der Enumeration vor dem Zeichenfolgenwert enthalten sein. Enumerationstypen werden als Eigenschaftswerte nur in den Metadatenentitäten und komplexen Arten verwendet. Wenn Sie z. B. Entitäten basierend auf der OwnershipType-Eigenschaft filtern müssen, die OwnershipTypes Enumtype verwendet, können Sie folgenden $filter verwenden, 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 auf Grundlage des Werts einer Eigenschaft filtern müssen, die einen komplexen Typen verwendet, muss zudem der Pfad zum zugrundeliegenden einfachen Typen enthalten sein. Komplexe Typen werden als Eigenschaftswerte nur in den Metadatenentitäten verwendet. Wenn Sie z. B. Entitäten auf Basis der CanCreateAttributes-Eigenschaft filtern müssen, die BooleanManagedProperty ComplexType verwendet, können Sie folgende $filter verwenden, damit nur Entitäten zurückgegeben werden, die einen Value von true aufweisen.

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. Bei Eigenschaften Beschriftung ComplexType funktioniert es jedoch nicht.

EntityMetadata-Attributen abfragen

Entitätsattribute können Sie im Rahmen einer Entität abfragen, indem Sie die Sammlungswert-Navigationseigenschaft Attributes erweitern. Dies enthält jedoch nur die allgemeinen Eigenschaften, die in AttributeMetadata EntityType verfügbar sind, das alle Attribute gemeinsam haben. So gibt die folgende Abfrage den LogicalName der Entität zurück, und alle erweiterten Attribute, die einen AttributeType-Wert besitzen, der dem AttributeTypeCode EnumType-Wert von 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 Typs eines Attributs abzurufen, müssen Sie die sammlungswertige Attributes-Navigationseigenschaft in den gewünschten Typ umwandeln. Die folgende Abfrage gibt nur die PicklistAttributeMetadata EntityType-Attribute zurück und enthält den LogicalName und erweitert die Sammlungswert-Navigationseigenschaften OptionSet und GlobalOptionSet

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

Hinweis

Obwohl die Sammlungswert-Navigationseigenschaften OptionSet und GlobalOptionSet in EnumAttributeMetadata EntityType definiert werden, können Sie die Attribute nicht in diesen Typ umwandeln. Das bedeutet, dass wenn Sie nach anderen Typen filtern möchten, die ebenfalls diese Eigenschaften erben (siehe Entitätstypen, die von EnumAttributeMetadata erben ), müssen Sie separate Abfragen zum Filtern für jeden Typ ausführen.

Ein weiteres Beispiel hierfür ist der Zugriff auf die Precision Eigenschaft, die in den Attributen MoneyAttributeMetadata EntityType und DecimalAttributeMetadata EntityType verfügbar ist. Um auf diese Eigenschaft zuzugreifen, müssen Sie die Attributesammlung entweder als MoneyAttributeMetadata EntityType oder DecimalAttributeMetadata EntityType verfügbar ist. 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 EntityType RequiredLevel-Eigenschaft verwendet einen speziellen AttributeRequiredLevelManagedProperty ComplexType, bei dem die Value-Eigenschaft ein AttributeRequiredLevel EnumType ist. In diesem Fall müssen Sie die Muster in Verwendung von komplexen Typen in $filter-Vorgängen und Verwendung von Enumerationstypen in $filter-Vorgängen kombinieren, um diese spezielle Eigenschaft zu verwenden. In der folgenden Abfrage werden solche Attribute in der Firmenentität gefiltert, 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'

Attribute abrufen

Wenn Sie die MetadataId für EntityMetadata und AttributeMetadata oder den LogicalName-Wert für einen davon kennen, können Sie ein einzelnes Attribut abrufen und auf die Eigenschaftswerte zugreifen, indem Sie eine Abfrage wie die folgende verwenden. Diese Abfrage ruft die LogicalName-Eigenschaft des Attributs ab und erweitert die sammlungswertige OptionSet-Navigationseigenschaft. 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  
}  
}

Sofern Sie keine Eigenschaften des Attributs benötigen und nur die Werte einer Sammlungswert-Navigationseigenschaft wie OptionsSet benötigen, können Sie diese in die URL einschließen und die Eigenschaften mit einer $select-Systemabfrageoption für eine effizientere Abfrage beschränken. Im folgenden Beispiel wird nur die Options-Eigenschaft von OptionSet einbezogen.

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

Abfragen von Beziehungsmetadaten

Sie können Beziehungsmetadaten im Kontext einer bestimmten Entität ganz ähnlich abrufen wie Sie Attribute abfragen können. Die sammlungswertigen ManyToManyRelationships-, ManyToOneRelationships- und OneToManyRelationships-Navigationseigenschaften können genauso abgefragt werden wie die sammlungswertige Attributes-Navigationseigenschaft. Weitere Informationen: EntityMetadata-Attributen abfragen

Entitätsbeziehungen können jedoch auch mit dem RelationshipDefinitions-Entitätssatz abgefragt werden. Sie können eine Abfrage wie die folgende verwenden, 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 Entitätstypen zuzugreifen, die von RelationshipMetadataBase erben, müssen Sie eine Umwandlung wie die folgende in der Abfrage einschließen, damit nur OneToManyRelationshipMetadata EntityType zurückgegeben wird.

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

Da die zurückgegebenen Entitäten als OneToManyRelationshipMetadata eingegeben werden, können Sie nach den Eigenschaften wie ReferencedEntity filtern, um eine Abfrage zu erstellen, die nur 1: n-Entitätsbeziehungen für eine bestimmte Entität zurückgibt, wie die Firmenentität, siehe folgende Abfrage:

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

Diese Abfrage gibt im Wesentlichen die gleichen Ergebnisse wie die folgende Abfrage zurück, die gefiltert wird, da sie in der Sammlungswert-Navigationseigenschaft EntityMetadataOneToManyRelationships der Kontoentität enthalten ist. Der Unterschied ist, dass Sie für die vorherige Abfrage nicht die MetadataId für die Firmenentität kennen müssen.

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

Abfragen von globalen OptionSets

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 ein einzelnes globales Optionssatz abrufen, indem Sie entweder die MetadataId oder der eindeutige Name verwenden.

Beispiel: Nach MetadataId

Das folgende Beispiel zeigt das Abrufen eines globalen Optionssatz mithilfe der MetadataId.

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

Beispiel nach Name

Das folgende Beispiel zeigt das Abrufen eines globalen Optionssatz mithilfe des Namens:

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. Dies ist verfügbar für alle Abgeleitete Typen EnumAttributeMetadata EntityType. Weitere Informationen: Attribute abrufen

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#)

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).

Freigeben über

Abfragen von Tabellendefinitionen mithilfe der Web-API

Abfragen des EntityMetadata-Entitätstyps

Zurückgegebene Sprachen einschränken

Verwendung von Enumerationstypen in $filter-Vorgängen

Verwendung von komplexen Typen in $filter-Vorgängen

EntityMetadata-Attributen abfragen

Filtern nach erforderlicher Ebene

Attribute abrufen

Abfragen von Beziehungsmetadaten

Abfragen von globalen OptionSets

Beispiel: Nach MetadataId

Beispiel nach Name

Siehe auch

Zusätzliche Ressourcen