了解如何通过 Web API 按名称或 MetadataId 引用Microsoft Dataverse架构定义。 这些查询可帮助应用程序检索元数据并适应表和列配置更改。
注释
本文演示如何按名称检索架构定义。 还可以在执行其他操作时使用名称来创建、更新和删除架构实体。
按名称检索架构定义
所有可检索的定义项都有一个 MetadataId 主键，可用于检索单个项。 对于具有备用键的定义，可以按名称检索它们。
按名称检索定义项更容易，因为代码中可能已经有一些对项名称的引用。 下表列出了按名称检索此类项的备用键属性。
| 定义项 | 备用密钥 | 示例 |
|---|---|---|
| 实体 | LogicalName | GET /api/data/v9.2/EntityDefinitions(LogicalName='account') |
| Attribute | LogicalName | GET /api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(LogicalName='emailaddress1') |
| 关系 | SchemaName | GET /api/data/v9.2/RelationshipDefinitions(SchemaName='Account_Tasks') |
| 全局选项集 | Name | GET /api/data/v9.2/GlobalOptionSetDefinitions(Name='metric_goaltype') |
示例：按名称检索架构定义
要检索的常见定义项是为特定属性配置的选项。 以下示例演示如何检索 OptionSetGlobalOptionSetPicklistAttributeMetadata EntityType 的属性。
注释
无需同时扩展 OptionSetGlobalOptionSetPicklistAttributeMetadata EntityType 的单值导航属性。 无论属性是配置为使用全局选项集还是实体中的本地选项集，都可以从任一属性获取选项定义。
请求：
GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(LogicalName='accountcategorycode')/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet($select=Options),GlobalOptionSet($select=Options) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
响应：
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/Microsoft.Dynamics.CRM.PicklistAttributeMetadata(LogicalName,OptionSet(Options),GlobalOptionSet(Options))/$entity",
"MetadataId": "118771ca-6fb9-4f60-8fd4-99b6124b63ad",
"LogicalName": "accountcategorycode",
"OptionSet": {
"MetadataId": "b994cdd8-5ce9-4ab9-bdd3-8888ebdb0407",
"Options": [
{
"Value": 1,
"Color": null,
"IsManaged": true,
"ExternalValue": null,
"ParentValues": [],
"Tag": null,
"IsHidden": false,
"MetadataId": null,
"HasChanged": null,
"Label": {
"LocalizedLabels": [
{
"Label": "Preferred Customer",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
],
"UserLocalizedLabel": {
"Label": "Preferred Customer",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
},
"Description": {
"LocalizedLabels": [],
"UserLocalizedLabel": null
}
},
{
"Value": 2,
"Color": null,
"IsManaged": true,
"ExternalValue": null,
"ParentValues": [],
"Tag": null,
"IsHidden": false,
"MetadataId": null,
"HasChanged": null,
"Label": {
"LocalizedLabels": [
{
"Label": "Standard",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
],
"UserLocalizedLabel": {
"Label": "Standard",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
},
"Description": {
"LocalizedLabels": [],
"UserLocalizedLabel": null
}
}
]
},
"GlobalOptionSet": {
"MetadataId": "b994cdd8-5ce9-4ab9-bdd3-8888ebdb0407",
"Options": [
{
"Value": 1,
"Color": null,
"IsManaged": true,
"ExternalValue": null,
"ParentValues": [],
"Tag": null,
"IsHidden": false,
"MetadataId": null,
"HasChanged": null,
"Label": {
"LocalizedLabels": [
{
"Label": "Preferred Customer",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
],
"UserLocalizedLabel": {
"Label": "Preferred Customer",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
},
"Description": {
"LocalizedLabels": [],
"UserLocalizedLabel": null
}
},
{
"Value": 2,
"Color": null,
"IsManaged": true,
"ExternalValue": null,
"ParentValues": [],
"Tag": null,
"IsHidden": false,
"MetadataId": null,
"HasChanged": null,
"Label": {
"LocalizedLabels": [
{
"Label": "Standard",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
],
"UserLocalizedLabel": {
"Label": "Standard",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
},
"Description": {
"LocalizedLabels": [],
"UserLocalizedLabel": null
}
}
]
}
}
按 MetadataId 检索架构定义
MetadataId由于这是定义项的主键，因此检索各个项遵循用于检索业务数据表的相同模式。
| 定义项 | 示例 |
|---|---|
| 实体 | GET /api/data/v9.2/EntityDefinitions(<Entity MetadataId>) |
| Attribute | GET /api/data/v9.2/EntityDefinitions(<Entity MetadataId>)/Attributes(<Attribute MetadataId>) |
| 关系 | GET /api/data/v9.2/RelationshipDefinitions(<Relationship MetadataId>) |
| 全局选项集 | GET /api/data/v9.2/GlobalOptionSetDefinitions(<OptionSet MetadataId>) |
示例：按 MetadataId 检索架构定义
若要获取与示例相同的结果：按名称检索定义项，请执行一系列查询操作，以按实体LogicalName筛选，然后按属性LogicalName获取MetadataId。
请求：
GET [Organization URI]/api/data/v9.2/EntityDefinitions?$filter=LogicalName%20eq%20'account'&$select=MetadataId HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
响应：
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(MetadataId)","value":[
{
"MetadataId":"70816501-edb9-4740-a16c-6a5efbc05d84"
}
]
}
请求：
GET [Organization URI]/api/data/v9.2/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes?$filter=LogicalName%20eq%20'accountcategorycode'&$select=MetadataId HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
响应：
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(MetadataId)","value":[
{
"@odata.type": "#Microsoft.Dynamics.CRM.PicklistAttributeMetadata",
"MetadataId": "118771ca-6fb9-4f60-8fd4-99b6124b63ad"
}
]
}
请求：
GET [Organization URI]/api/data/v9.2/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(118771ca-6fb9-4f60-8fd4-99b6124b63ad)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet($select=Options),GlobalOptionSet($select=Options) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
响应：
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/Microsoft.Dynamics.CRM.PicklistAttributeMetadata(LogicalName,OptionSet(Options),GlobalOptionSet(Options))/$entity",
"MetadataId": "118771ca-6fb9-4f60-8fd4-99b6124b63ad",
"LogicalName": "accountcategorycode",
"OptionSet": {
"MetadataId": "b994cdd8-5ce9-4ab9-bdd3-8888ebdb0407",
"Options": [
{
"Value": 1,
"Color": null,
"IsManaged": true,
"ExternalValue": null,
"ParentValues": [],
"Tag": null,
"IsHidden": false,
"MetadataId": null,
"HasChanged": null,
"Label": {
"LocalizedLabels": [
{
"Label": "Preferred Customer",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
],
"UserLocalizedLabel": {
"Label": "Preferred Customer",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
},
"Description": {
"LocalizedLabels": [],
"UserLocalizedLabel": null
}
},
{
"Value": 2,
"Color": null,
"IsManaged": true,
"ExternalValue": null,
"ParentValues": [],
"Tag": null,
"IsHidden": false,
"MetadataId": null,
"HasChanged": null,
"Label": {
"LocalizedLabels": [
{
"Label": "Standard",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
],
"UserLocalizedLabel": {
"Label": "Standard",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
},
"Description": {
"LocalizedLabels": [],
"UserLocalizedLabel": null
}
}
]
},
"GlobalOptionSet": {
"MetadataId": "b994cdd8-5ce9-4ab9-bdd3-8888ebdb0407",
"Options": [
{
"Value": 1,
"Color": null,
"IsManaged": true,
"ExternalValue": null,
"ParentValues": [],
"Tag": null,
"IsHidden": false,
"MetadataId": null,
"HasChanged": null,
"Label": {
"LocalizedLabels": [
{
"Label": "Preferred Customer",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
],
"UserLocalizedLabel": {
"Label": "Preferred Customer",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
},
"Description": {
"LocalizedLabels": [],
"UserLocalizedLabel": null
}
},
{
"Value": 2,
"Color": null,
"IsManaged": true,
"ExternalValue": null,
"ParentValues": [],
"Tag": null,
"IsHidden": false,
"MetadataId": null,
"HasChanged": null,
"Label": {
"LocalizedLabels": [
{
"Label": "Standard",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
],
"UserLocalizedLabel": {
"Label": "Standard",
"LanguageCode": 1033,
"IsManaged": true,
"MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
"HasChanged": null
}
},
"Description": {
"LocalizedLabels": [],
"UserLocalizedLabel": null
}
}
]
}
}
另见
将 Web API 与表定义配合使用
使用 Web API 查询表定义
使用 Web API 创建和更新表定义
使用 Web API 创建和更新表关系
Web API 表架构操作示例
Web API 表架构作示例 （C#）