Retrieve metadata by name or MetadataId
Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Your applications can adapt to configuration changes by querying the metadata. When you know one of the key properties of a metadata item, you can retrieve metadata definitions using the Web API.
In this topic
Retrieve metadata items by name
Retrieve metadata items by MetadataId
Retrieve metadata items by name
Note
This capability was added with December 2016 update for Dynamics 365 (online and on-premises).
All retrievable metadata items have a MetadataId primary key that can be used to retrieve individual items. For those types of metadata which have a defined alternate key, you can retrieve them by name.
Retrieving items by name is generally easier because you probably already have some reference to the metadata item name in your code. The following table lists the alternate key properties for retrieving metadata items by name
Metadata item |
Alternate Key |
Example |
|---|---|---|
Entity |
LogicalName |
GET /api/data/v8.2/EntityDefinitions(LogicalName='account') |
Attribute |
LogicalName |
GET /api/data/v8.2/EntityDefinitions(LogicalName='account')/Attributes(LogicalName='emailaddress1') |
Relationship |
SchemaName |
GET /api/data/v8.2/RelationshipDefinitions(SchemaName='Account_Tasks') |
Global Option Set |
Name |
GET /api/data/v8.2/GlobalOptionSetDefinitions(Name='metric_goaltype') |
Example: Retrieve metadata items by name
A common item of metadata that people want to retrieve are the options configured for a particular attribute. The following example shows how to retrieve the OptionSet and GlobalOptionSet properties of a PicklistAttributeMetadata EntityType.
Note
Expanding both the OptionSet and GlobalOptionSet single-valued navigation properties of PicklistAttributeMetadata EntityType allows you to get the option definition whether the attribute is configured to use global optionsets or the 'local' optionset within the entity. If it is a 'local' optionset, the GlobalOptionSet property will be null as shown below.
If the attribute used a global optionset, the GlobalOptionSet property would contain the defined options and the OptionSet property would be null.
Request
GET [Organization URI]/api/data/v8.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-8Response
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context": "[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions('account')/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata(LogicalName,OptionSet,GlobalOptionSet,OptionSet(Options),GlobalOptionSet(Options))/$entity", "LogicalName": "accountcategorycode", "MetadataId": "118771ca-6fb9-4f60-8fd4-99b6124b63ad", "OptionSet@odata.context": "[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions('account')/Attributes(118771ca-6fb9-4f60-8fd4-99b6124b63ad)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet(Options)/$entity", "OptionSet": { "Options": [{ "Value": 1, "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 }, "Color": null, "IsManaged": true, "MetadataId": null, "HasChanged": null }, { "Value": 2, "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 }, "Color": null, "IsManaged": true, "MetadataId": null, "HasChanged": null }], "MetadataId": "b994cdd8-5ce9-4ab9-bdd3-8888ebdb0407" }, "GlobalOptionSet": null }
Retrieve metadata items by MetadataId
Because the MetadataId is the primary key for metadata items, retrieving individual items follows the same pattern used to retrieve business data entities.
Metadata item |
Example |
|---|---|
Entity |
GET /api/data/v8.2/EntityDefinitions(<Entity MetadataId>) |
Attribute |
GET /api/data/v8.2/EntityDefinitions(<Entity MetadataId>)/Attributes(<Attribute MetadataId>) |
Relationship |
GET /api/data/v8.2/RelationshipDefinitions(<Relationship MetadataId>) |
Global Option Set |
GET /api/data/v8.2/GlobalOptionSetDefinitions(<OptionSet MetadataId>) |
Example: Retrieve metadata items by MetadataId
To achieve the same result as shown in Example: Retrieve metadata items by name, you will need to perform a series of query operations to get the MetadataId by filtering by the entity LogicalName and then by the attribute LogicalName.
Request
GET [Organization URI]/api/data/v8.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-8Response
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context":"[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions(MetadataId)","value":[ { "MetadataId":"70816501-edb9-4740-a16c-6a5efbc05d84" } ] }Request
GET [Organization URI]/api/data/v8.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-8Response
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context": "[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(MetadataId)","value":[ { "@odata.type": "#Microsoft.Dynamics.CRM.PicklistAttributeMetadata", "MetadataId": "118771ca-6fb9-4f60-8fd4-99b6124b63ad" } ] }Request
GET [Organization URI]/api/data/v8.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-8Response
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context": "[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata(LogicalName,OptionSet,GlobalOptionSet,OptionSet(Options),GlobalOptionSet(Options))/$entity", "LogicalName": "accountcategorycode", "MetadataId": "118771ca-6fb9-4f60-8fd4-99b6124b63ad", "OptionSet@odata.context": "[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(118771ca-6fb9-4f60-8fd4-99b6124b63ad)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet(Options)/$entity", "OptionSet": { "Options": [{ "Value": 1, "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 }, "Color": null, "IsManaged": true, "MetadataId": null, "HasChanged": null }, { "Value": 2, "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 }, "Color": null, "IsManaged": true, "MetadataId": null, "HasChanged": null }], "MetadataId": "b994cdd8-5ce9-4ab9-bdd3-8888ebdb0407" }, "GlobalOptionSet": null }
See Also
Use the Web API with Dynamics 365 metadata
Query metadata using the Web API
Create and update entity definitions using the Web API
Create and update entity relationships using the Web API
Microsoft Dynamics 365
© 2016 Microsoft. All rights reserved. Copyright