使用 Web API 查询元数据

项目
03/04/2017

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

由于 Microsoft Dynamics 365 是元数据驱动的应用程序，所以系统开发人员可能需要在运行时查询系统元数据，以适应组织的配置方式。此功能通过使用 RetrieveMetadataChangesRequest 和 Microsoft.Xrm.Sdk.Metadata.Query 命名空间的类，使用 Web API 以及组织服务提供。 Web API 允许查询元数据，但是不能检测某个时间点对元数据的更改。

在本主题中

查询 EntityMetadata 实体类型

在 $filter 操作中使用枚举类型

在 $filter 操作中使用复杂类型

查询 EntityMetadata 属性

检索属性

查询关系元数据

查询全局选项集

查询 EntityMetadata 实体类型

查询 EntityMetadata 时，您将使用使用 Web API 查询数据中描述的相同技术，但需要做一些改变。使用 EntityDefinitions 实体集路径检索有关 EntityMetadata EntityType 的信息。EntityMetadata 实体包含大量数据，因此您需要小心谨慎，仅检索需要的数据。以下示例显示了仅为 Account 实体的 DisplayName、IsKnowledgeManagementEnabled 和 EntitySetName 属性返回的数据。始终返回 MetadataId 属性值。

请求

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

响应

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

您可以对 $select 系统查询选项使用任何 EntityMetadata 属性，对 $filter 使用采用原始或枚举值的任何属性。

不限制查询中返回的元数据实体数量。不存在分页。所有匹配的资源在第一个响应中返回。

在 $filter 操作中使用枚举类型

如果需要根据使用枚举的属性的值筛选元数据实体，则必须在字符串值前面添加枚举的命名空间。枚举类型只有在元数据实体和复杂类型中才用作属性值。例如，如果需要根据 OwnershipType 属性（该属性使用 OwnershipTypes EnumType）筛选实体，可使用以下 $filter 仅返回 UserOwned 的实体。

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=OwnershipType eq Microsoft.Dynamics.CRM.OwnershipTypes'UserOwned'

在 $filter 操作中使用复杂类型

如果需要根据使用复杂类型的属性的值筛选元数据实体，则必须添加基础原始类型的路径。复杂类型只有在元数据实体和复杂类型中才用作属性值。例如，如果需要根据 CanCreateAttributes 属性（该属性使用 BooleanManagedProperty ComplexType）筛选实体，可使用以下 $filter 仅返回 Value 为 true 的实体。

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

此模式支持 BooleanManagedProperty ComplexType，因为要检查的原始值的深度只有一级。不过，此模式不支持 Label ComplexType 的属性。

查询 EntityMetadata 属性

可以通过扩展 Attributes 集合值导航属性在实体的上下文中查询实体属性，但是这样将仅包括 AttributeMetadata EntityType 中所有属性共享的可用公共属性。例如，以下查询将返回实体的 LogicalName 和 AttributeType 值等于 Picklist 的 AttributeTypeCode EnumType 值的所有扩展的 Attributes。

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

但不能在此属性的 $select 筛选器内添加 PicklistAttributeMetadata EntityType 属性拥有的 OptionSet 或 GlobalOptionSet 集合值导航属性。

要检索特定类型属性的属性，必须将 Attributes 集合值导航属性转换为所需类型。以下查询将仅返回 PicklistAttributeMetadata 属性，并且包括 LogicalName 且扩展 OptionSet 和 GlobalOptionSet 集合值导航属性

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

备注

尽管 OptionSet 和 GlobalOptionSet 集合值导航属性是在 EnumAttributeMetadata EntityType 中定义的，您仍然不能将属性转换为此类型。这意味着，如果您要筛选也继承了这些属性的其他类型（请参阅Entity types that inherit from activitypointer），则必须执行单独的查询来筛选每种类型。

另一个这样的示例是访问 MoneyAttributeMetadata EntityType 和 DecimalAttributeMetadata EntityType 属性中的 Precision 属性。若要访问此属性，必须将属性集转换为 MoneyAttributeMetadata 或 DecimalAttributeMetadata。下面显示转换为 MoneyAttributeMetadata 的示例。

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

按所需级别筛选

AttributeMetadata EntityTypeRequiredLevel 属性使用 Value 属性为 AttributeRequiredLevel EnumType 的特殊 AttributeRequiredLevelManagedProperty ComplexType。在这种情况下，必须组合在在 $filter 操作中使用复杂类型和在 $filter 操作中使用枚举类型中发现的模式来按这个唯一属性筛选。以下查询将筛选客户实体中属于 ApplicationRequired 的属性。

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

检索属性

如果您知道 EntityMetadata 和 AttributeMetadata 的 MetadataId，可使用如下查询检索单个属性和访问属性值。该查询检索该属性的 LogicalName 属性，并扩展 OptionSet 集合值导航属性。请注意，必须将该属性转换为 Microsoft.Dynamics.CRM.PicklistAttributeMetadata，才能访问 OptionSet 集合值导航属性。

请求

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

响应

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

如果不需要此属性的任何属性，仅需要 OptionsSet 之类集合值导航属性的值，您可以将其添加到 URL 中，并使用 $select 系统查询选项限制属性的值，以提高查询的效率。在下面的示例中，仅包括 OptionSet 的 Options 属性。

请求

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

响应

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

查询关系元数据

您可以按查询属性的几乎相同方式在给定实体的上下文中检索关系元数据。ManyToManyRelationships、ManyToOneRelationships 和 OneToManyRelationships 集合值导航属性的查询方式可以与 Attributes 集合值导航查询的一样。详细信息：查询 EntityMetadata 属性

不过，也可以使用 RelationshipDefinitions 实体集查询实体关系。您可以使用如下查询获取每种关系的 SchemaName 属性。

GET cc_WebAPI_ServiceURI/RelationshipDefinitions?$select=SchemaName

查询此实体集时可用的属性仅限 RelationshipMetadataBase EntityType 中的属性。要从继承自 RelationshipMetadataBase 的实体类型访问属性，需要在查询中添加如下转换，以便仅返回 OneToManyRelationshipMetadata EntityType。

GET cc_WebAPI_ServiceURI/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName

因为返回的实体类型为 OneToManyRelationshipMetadata，您可以筛选 ReferencedEntity 之类属性，以便构造查询来仅返回特定实体（如以下查询中显示的客户实体）的一对多实体关系：

GET cc_WebAPI_ServiceURI/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName&$filter=ReferencedEntity eq 'account'

该查询本质上与以下查询返回相同的结果，并且之所以筛选该查询，是因为它包含在客户实体的 EntityMetadataOneToManyRelationships 集合值导航属性中。区别是，对于前一个查询，您不需要了解客户实体的 MetadataId。

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/OneToManyRelationships?$select=SchemaName

查询全局选项集

您可以使用 GlobalOptionSetDefinitions 实体集路径检索有关全局选项集的信息，但是，此路径不支持使用 $filter 系统查询选项。所以除非您了解特定全局选项集的 MetadataId，否则只能全部检索。也可以从使用某个全局选项集的任何属性的 GlobalOptionSet 单值导航属性内访问该全局选项集的定义。所有 Entity types that inherit from activitypointer 均支持此操作。详细信息：检索属性

另请参阅

使用具有 Dynamics 365 元数据的 Web API
按名称或 MetadataId 检索元数据
 使用 Web API 创建更新实体定义
 使用 Web API 创建和更新实体关系

Microsoft Dynamics 365

使用 Web API 查询元数据

在本主题中

查询 EntityMetadata 实体类型

在 $filter 操作中使用枚举类型

在 $filter 操作中使用复杂类型

查询 EntityMetadata 属性

按所需级别筛选

检索属性

查询关系元数据

查询全局选项集

另请参阅

其他资源