Metadaten mit Web-API abfragen

Artikel
03/04/2017

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Da Microsoft Dynamics 365 eine metadatengesteuerte Anwendung ist, müssen Entwickler unter Umständen die Systemmetadaten zur Laufzeit abfragen, um die Konfiguration der Organisation anzupassen. Diese Funktion ist mit der Web-API und dem Organisationsservice verfügbar, indem RetrieveMetadataChangesRequest und die Klassen des Microsoft.Xrm.Sdk.Metadata.Query-Namespace verwendet werden. Die Web-API ermöglicht das Abfragen der Metadaten, bietet jedoch nicht die Option, Änderungen der Metadaten von einem Zeitpunkt aus zu ermitteln.

In diesem Thema

Abfragen des EntityMetadata-Entitätstyps

Verwendung von Enumerationstypen in $filter-Vorgängen

Verwendung von komplexen Typen in $filter-Vorgängen

Abfragen von EntityMetadata-Attributen

Abrufen von Attributen

Abfragen von Beziehungsmetadaten

Abfragen von globalen OptionSets

Abfragen des EntityMetadata-Entitätstyps

Sie verwenden die gleichen Techniken wie in Datenabfrage mit Web-API beschrieben, wenn Sie EntityMetadata abfragen, 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 sicher darauf achten möchten, dass Sie nur die Daten abrufen, die Sie benötigen. Im folgenden Beispiel werden die Daten angezeigt, die nur für die DisplayName-, IsKnowledgeManagementEnabled- und EntitySetName-Eigenschaften der Metadaten für die Account-Entität zurückgegeben werden. Der MetadataId-Eigenschaftswert wird immer zurückgegeben.

Anforderung

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=DisplayName,IsKnowledgeManagementEnabled,EntitySetName&$filter=SchemaName eq 'Account' 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": "cc_WebAPI_ServiceURI/$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.

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 filtern müssen auf Basis der OwnershipType-Eigenschaft, die OwnershipTypes EnumType verwendet, können Sie folgende $filter verwenden, um nur die Entitäten zurückzugeben, die UserOwned sind.

GET cc_WebAPI_ServiceURI/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 filtern müssen auf Basis der CanCreateAttributes-Eigenschaft, die BooleanManagedProperty ComplexType verwendet, können Sie folgende $filter verwenden, um nur die Entitäten zurückzugeben, die den Value „true” aufweisen.

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=CanCreateAttributes/Value eq true

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

Abfragen von EntityMetadata-Attributen

Entitätsattribute können Sie im Rahmen einer Entität abfragen, indem Sie die sammlungswertige Attributes-Navigationseigenschaft 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 Attributes, die einen AttributeType-Wert besitzen, der dem AttributeTypeCode EnumType-Wert Picklist entspricht.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)?$select=LogicalName&$expand=Attributes($select=LogicalName;$filter=AttributeType eq Microsoft.Dynamics.CRM.AttributeTypeCode'Picklist')

Sie können jedoch nicht die sammlungswertigen OptionSet- oder GlobalOptionSet-Navigationseigenschaften 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-Attribute zurück und enthält den LogicalName und erweitert die sammlungswertigen OptionSet- und GlobalOptionSet-Navigationseigenschaften

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet,GlobalOptionSet

Hinweis

Obwohl die sammlungswertigen OptionSet- und GlobalOptionSet-Navigationseigenschaften 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 Entity types that inherit from activitypointer), müssen Sie separate Abfragen zum Filtern für jeden Typ ausführen.

Ein anderes Beispiel hierfür ist der Zugriff auf die Precision-Eigenschaft, die in MoneyAttributeMetadata EntityType- und DecimalAttributeMetadata EntityType-Attributen verfügbar ist. Damit Sie auf diese Eigenschaft zugreifen können, müssen Sie die Attributsammlung entweder als MoneyAttributeMetadata oder als DecimalAttributeMetadata umwandeln. Ein Beispiel, das das Umwandeln zu MoneyAttributeMetadata veranschaulicht, wird hier angezeigt.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.MoneyAttributeMetadata?$select=LogicalName,Precision

Filtern nach erforderlicher Ebene

Die AttributeMetadata EntityTypeRequiredLevel-Eigenschaft verwendet einen speziellen AttributeRequiredLevelManagedProperty ComplexType, wobei die Value-Eigenschaft ein AttributeRequiredLevel EnumType ist. In diesem Fall müssen die Muster, die unter Verwendung von komplexen Typen in $filter-Vorgängen und Verwendung von Enumerationstypen in $filter-Vorgängen vorhanden sind, kombiniert werden, um nach dieser eindeutigen Eigenschaft zu filtern. In der folgenden Abfrage werden solche Attribute in der Firmenentität gefiltert, die ApplicationRequired sind.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes?$select=SchemaName&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'

Abrufen von Attributen

Wenn Sie die MetadataId für EntityMetadata und AttributeMetadata 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. Beachten Sie, dass Sie das Attribut als Microsoft.Dynamics.CRM.PicklistAttributeMetadata umwandeln müssen, um auf die sammlungswertige OptionSet-Navigationseigenschaft zuzugreifen.

Anforderung

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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": "cc_WebAPI_ServiceURI/$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": "cc_WebAPI_ServiceURI/$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 sammlungswertigen Navigationseigenschaft wie OptionsSet benötigen, können Sie diese in die URL einschließen und die Eigenschaften mit einer $select-Systemabfrageoption für eine etwas effizientere Abfrage beschränken. Im folgenden Beispiel wird nur die Options-Eigenschaft von OptionSet einbezogen.

Anforderung

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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": "cc_WebAPI_ServiceURI/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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:Abfragen von EntityMetadata-Attributen

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 cc_WebAPI_ServiceURI/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 in der Abfrage einschließen wie die folgende, um nur OneToManyRelationshipMetadata EntityType zurückzugeben.

GET cc_WebAPI_ServiceURI/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 cc_WebAPI_ServiceURI/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 sammlungswertigen EntityMetadataOneToManyRelationships-Navigationseigenschaft der Firmenentitä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 cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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. Sofern Sie also nicht die MetadataId für einen bestimmten globalen Optionssatz kennen, können Sie nur alle von ihnen abrufen. 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 für alle Entity types that inherit from activitypointer verfügbar.Weitere Informationen:Abrufen von Attributen

Siehe auch

Verwenden der Web-API mit Dynamics 365-Metadaten
Abrufen von Metadaten über den Namen oder die MetadataId
Erstellen und Aktualisieren von Entitätsdefinitionen mit der Web-API
Erstellen und Aktualisieren von Entitätsbeziehungen mit der Web-API

Microsoft Dynamics 365

Teilen über

Metadaten mit Web-API abfragen

In diesem Thema

Abfragen des EntityMetadata-Entitätstyps

Verwendung von Enumerationstypen in $filter-Vorgängen

Verwendung von komplexen Typen in $filter-Vorgängen

Abfragen von EntityMetadata-Attributen

Filtern nach erforderlicher Ebene

Abrufen von Attributen

Abfragen von Beziehungsmetadaten

Abfragen von globalen OptionSets

Siehe auch

Zusätzliche Ressourcen