Share via


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-8
    
  • Response

    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-8
    
  • Response

    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-8
    
  • Response

    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-8
    
  • Response

    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