使用 Web API 查询表定义

由于 Microsoft Dataverse 是元数据驱动的应用程序，因此开发人员可能需要在运行时查询系统定义，以适应组织的配置方式。此功能使用 RESTful 查询样式。

注释

还可以通过使用 EntityQueryExpression ComplexType 和 RetrieveMetadataChanges 函数，使用基于对象的样式构造查询。此函数捕获两个时间段之间的表定义的更改，并返回指定的查询描述的有限定义集。有关详细信息，请参阅查询架构定义。

查询 EntityMetadata 实体类型

在查询 EntityMetadata 时，使用Query data using the Web API中所述的相同技术，但会有一些不同之处。使用EntityDefinitions实体集路径来检索EntityMetadata EntityType的信息。 EntityMetadata 实体包含大量数据，因此仅检索所需的数据。以下示例显示了仅针对DisplayName实体的定义中IsKnowledgeManagementEnabled、EntitySetName和Account属性返回的数据。 MetadataId 属性值始终被返回。

请求：

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

响应：

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

可以将任何EntityMetadata属性与$select系统查询选项一起使用。可以在 $filter 任何使用基元或枚举值的属性上使用。

查询返回的元数据实体数没有限制。不支持分页。第一个响应返回所有匹配的资源。

限制返回的语言

当环境预配了多种语言时，返回的数据量可能会增大。为了获得最佳性能，请使用带有所需语言 LCID 值的参数 LabelLanguages，以限制返回的语言标签。

四位数或五位数区域设置 ID 的语言代码。可在区域设置 ID (LCID) 图表中找到有效区域设置 ID 值。

例如，将以下值追加将本地化语言标签限制为英语： &LabelLanguages=1033

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

如果需要根据使用枚举的属性的值筛选元数据实体，请在字符串值之前包含枚举的命名空间。枚举类型仅在元数据实体和复杂类型中用作属性值。例如，若需根据使用 OwnershipTypes Enumtype 的 OwnershipType 属性筛选实体，请使用以下 $filter 仅返回属于 UserOwned 的实体。

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

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

如果需要根据使用复杂类型的属性的值筛选元数据实体，请包含基础基元类型的路径。复杂类型仅在元数据实体中用作属性值。例如，若需根据使用 BooleanManagedProperty ComplexType 的 CanCreateAttributes 属性筛选实体，请使用以下 $filter 仅返回 Value 为 true 的实体。

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

此模式适用于 BooleanManagedProperty ComplexType ，因为要检查的基元值深度为一级。但是，此模式不适用于 Label ComplexType 的属性。

查询 EntityMetadata 属性

通过扩展 Attributes 集合值导航属性，可以在实体的上下文中查询实体属性。此方法仅包括所有属性共享的 AttributeMetadata EntityType 中可用的通用属性。例如，以下查询将返回实体 LogicalName 以及所有扩展属性，这些属性的 AttributeType 值等于的 Picklist 值。

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

但是，不能在此查询的OptionSet筛选器中包含 GlobalOptionSet 属性所具有的或$select集合值导航属性。

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

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

注释

虽然OptionSet和GlobalOptionSet的集合值导航属性定义在EnumAttributeMetadata EntityType中，但这些属性无法强制转换为这种类型。此限制意味着必须执行单独的查询来筛选继承这些属性的其他类型。有关详细信息，请参阅继承自 EnumAttributeMetadata 的实体类型。

此限制的另一个示例是访问 PrecisionMoneyAttributeMetadata EntityType 和 DecimalAttributeMetadata EntityType 属性中可用的属性。若要访问此属性，必须将属性集合强制转换为 MoneyAttributeMetadata EntityType 或 DecimalAttributeMetadata EntityType。此处展示了一个将类型转换为 MoneyAttributeMetadata 的示例。

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

按所需级别进行筛选

AttributeMetadata EntityTypeRequiredLevel 属性使用特殊的 AttributeRequiredLevelManagedProperty ComplexType，其中Value属性是 AttributeRequiredLevel EnumType。若要按此唯一属性进行筛选，请合并 $filter作中的“使用复杂类型”中的模式，并在 $filter作中使用枚举类型。以下查询在帐户实体中筛选出那些标记为 ApplicationRequired 的属性。

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

检索属性

如果您知道 MetadataId 和 EntityMetadata 的 AttributeMetadata，或者任一属性的 LogicalName 值，则可以使用类似于以下示例的查询来检索单个属性并访问属性值。此查询检索 LogicalName 属性的属性并展开 OptionSet 集合值导航属性。为了访问 Microsoft.Dynamics.CRM.PicklistAttributeMetadata 集合值导航属性，必须将该属性转化为 OptionSet。

请求：

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

响应：

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

如果你不需要使用该属性的任何具体属性，而只是希望获取集合值导航属性的值，例如 OptionSet，可以在 URL 中包含该属性，并通过使用系统查询选项$select来限制其属性，从而提高查询效率。在下面的示例中，仅 Options 的 OptionSet 属性被包含。

请求：

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

响应：

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

查询关系元数据

可以在给定实体的上下文中检索关系元数据，类似于查询属性的方式。可以像查询ManyToManyRelationships集合值导航属性一样，查询ManyToOneRelationships、OneToManyRelationships和Attributes集合值导航属性。有关详细信息，请参阅 QueryEntityMetadata 属性。

但是，还可以使用 RelationshipDefinitions 实体集查询实体关系。若要获取 SchemaName 每个关系的属性，请使用类似于以下示例的查询。

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

查询此实体集时可用的属性仅限于 RelationshipMetadataBase EntityType 中的属性。若要访问从 RelationshipMetadataBase 继承的实体类型的属性，请在查询中包含如下示例所示的强制类型转换，以仅返回 OneToManyRelationshipMetadata EntityType。

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

由于返回的实体被类型化为 OneToManyRelationshipMetadata，您可以通过筛选属性（例如 ReferencedEntity）来构造查询，该查询仅返回特定实体的一对多关系，比如以下查询中所示的帐户实体。

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

此查询实质上返回的结果与以下查询相同，该查询经过筛选，因为它包含在帐户实体的集合值导航属性中 EntityMetadataOneToManyRelationships 。区别在于，对于前一个查询，您无需知道账户实体的 MetadataId。

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

查询全局选项集

可以使用 GlobalOptionSetDefinitions 实体集路径检索有关全局选项集的信息，但此路径不支持使用 $filter 系统查询选项。因此，只能通过MetadataId或者唯一名称来检索单个全局选项集。

示例：按 MetadataId

以下示例演示如何使用 MetadataId 检索全局选项集。

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

按名称命名的示例

以下示例演示如何按名称检索全局选项集：

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

对于任何使用全局选项集的属性，您还可以通过其 GlobalOptionSet 单值导航属性访问该选项集的定义。此属性适用于所有 EnumAttributeMetadata EntityType 派生类型。有关详细信息，请参阅 “检索属性”。

另请参阅

将 Web API 与 Dataverse 元数据配合使用
 按名称或 MetadataId 检索元数据
 使用 Web API 的元数据实体和属性
 使用 Web API 的元数据实体关系
 Web API 表架构操作示例
 Web API 表架构作示例（C#）

反馈

此页面是否有帮助？

Last updated on 2026-03-11

使用 Web API 查询表定义

查询 EntityMetadata 实体类型

限制返回的语言

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

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

查询 EntityMetadata 属性

按所需级别进行筛选

检索属性

查询关系元数据

查询全局选项集

示例：按 MetadataId

按名称命名的示例

另请参阅

反馈

其他资源