Partager via

Query Microsoft Dynamics CRM 2013 data using the OData endpoint

  • Article

 

Applies To: Dynamics CRM 2013

To locate and retrieve data with the OData endpoint, manipulate the URI. All actions require that you begin with the service root URI. In Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online the service root URI is in the following example.

[Your Organization Root URL]/XRMServices/2011/OrganizationData.svc

Note

The organization root URL must include the organization name. Reference the service root by using the getClientUrl function in the context object. If a web resource will be hosted in a form, you can reference the Xrm.Page.context to call getClientUrl. Otherwise, you need to include a reference to the ClientGlobalContext.js.aspx page so that you can use the GetGlobalContext function to get the context object.

From the service root URI you identify specific resources using a resource path and further refine your query using system query options.

In This Topic

Accessing Microsoft Dynamics CRM entity data

Limitations on number of records returned

Entity properties

Microsoft Dynamics CRM complex types

  • EntityReference

  • OptionSetValue

  • Money

  • BooleanManagedProperty

Related entities

Accessing Microsoft Dynamics CRM entity data

Each Microsoft Dynamics CRM entity is represented in the conceptual schema definition language (CSDL) as a collection using the <EntitySet> element. The name of each collection follows the naming convention of [Entity Schema Name]+ Set. This name is used in the URL to access a collection of entity records. A list of all the collections available is listed when you view the service root URI. To create a query you append your criteria to the resource path.

For example, in your browser you can view the ATOM Account entity records (called ”entries”) using the path in the following example.

[Your Organization Root URL]/XRMServices/2011/OrganizationData.svc/AccountSet

After you view the list of account records, you can see how each of them can be referenced individually using the URL syntax in the following example.

[Your Organization Root URL]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')

Note

To view the data in Internet Explorer, you must first make sure that Internet Explorer is not enabled to format RSS feeds. In the Content tab of Internet Options. select Settings in the Feeds and Web Slices group. Then, click to clear the Turn on feed reading view option. Close and re-open Internet Explorer.

Limitations on number of records returned

Each time that you retrieve records, only the top 50 records in your query are returned. If there are more than 50 records, there will be a <link rel="next" href="<url to next set of records>" > node in XML or a JSON __next property at the end of the result set. You can use the URL value in that node or property to continue with the next set of records. The URL contains a $skiptoken parameter that provides information about the paging boundary.

To retrieve additional records you must create a method that detects the existence of this node or property and use the URL provided to retrieve the next set of records. For more information, see: Sample: Retrieve multiple records using the OData endpoint with JavaScript

Entity properties

Each conceptual schema definition language (CSDL) <EntitySet> refers to an <EntityType> element that describes the properties and relationships for an entity. Within the <EntityType> elements the <Property> elements correspond to Microsoft Dynamics CRM entity attributes. Each property is assigned a data type that corresponds to one of the primitive Entity Data Model (EDM) data types or a <ComplexType> defined specifically for Microsoft Dynamics CRM. The following table lists the data types.

OData type

Microsoft Dynamics CRM data type

Edm.Boolean

Boolean

Edm.DateTime

DateTime

Edm.Decimal

Decimal

Edm.Double

Double

Edm.Guid

UniqueIdentifier

Edm.Int32

Integer

Edm.Int64

BigInt

Edm.String

String
EntityName

Microsoft.Crm.Sdk.Data.Services.EntityReference

EntityReference
CustomerOwner

Microsoft.Crm.Sdk.Data.Services.OptionSetValue

OptionSetValue
State
Status

Microsoft.Crm.Sdk.Data.Services.Money

Money

Microsoft.Crm.Sdk.Data.Services.BooleanManagedProperty

BooleanManagedProperty

Microsoft Dynamics CRM complex types

Certain datatypes used by Microsoft Dynamics CRM cannot use the simple EDM datatypes.

Note

To set Microsoft Dynamics CRM complex type values to null, set each property of the complex type to null. For more information, see Setting complex types to null.

EntityReference

The Microsoft.Crm.Sdk.Data.Services.EntityReference type represents a lookup. It corresponds to EntityReference.The following table lists the properties.

Name

Type

Description

Id

GUID

The unique ID for the record associated in the lookup.

LogicalName

String

The name of the entity.

Name

String

The value of the primary attribute for the record associated in the lookup.

The following example is an ATOM XML EntityReference:

<d:PrimaryContactId m:type="Microsoft.Crm.Sdk.Data.Services.EntityReference">
<d:Id m:type="Edm.Guid">76713858-5e81-df11-afdb-00155dba380a</d:Id> 
<d:LogicalName>contact</d:LogicalName> 
<d:Name>Cat Francis (sample)</d:Name> 
</d:PrimaryContactId>

The following example is a JSON EntityReference:

"PrimaryContactId" :{
    "__metadata": {"type": "Microsoft.Crm.Sdk.Data.Services.EntityReference" },
    "Id": "78713858-5e81-df11-afdb-00155dba380a",
    "LogicalName": "contact",
    "Name": "Cathan Cook (sample)"
}

OptionSetValue

The Microsoft.Crm.Sdk.Data.Services.OptionSetValue type represents a picklist attribute. It corresponds to OptionSetValue. The following table lists properties.

Name

Type

Description

Value

Number

The selected value of the OptionSet attribute.

The following example is an ATOM XML OptionSetValue:

<d:PreferredContactMethodCode m:type="Microsoft.Crm.Sdk.Data.Services.OptionSetValue">
   <d:Value m:type="Edm.Int32">1</d:Value>
</d:PreferredContactMethodCode>

The following example is a JSON OptionSetValue:

"PreferredContactMethodCode" :{
    "__metadata": {"type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue" },
    "Value": 1
}

Money

The Microsoft.Crm.Sdk.Data.Services.Money type represents a Money attribute. It corresponds to Money The following table lists the properties.

Name

Type

Description

Value

Number

The amount of money.

The following example is an ATOM XML Money:

<d:CreditLimit m:type="Microsoft.Crm.Sdk.Data.Services.Money">
  <d:Value m:type="Edm.Decimal">500.0000</d:Value> 
</d:CreditLimit>

The following example is a JSON Money:

"CreditLimit" :{
    "__metadata": {"type": "Microsoft.Crm.Sdk.Data.Services.Money" },
    "Value": 500.0000
}

BooleanManagedProperty

Certain organization-owned entities have records that can be included in a solution, for example WebResource. Examples of managed properties include IsCustomizable, IsHidden, and CanBeDeleted. It corresponds to BooleanManagedProperty These Boolean properties control the behavior of managed solution components. For more information, see Use managed properties. The following table lists the BooleanManagedProperty.

Name

Type

Description

Value

Boolean

Indicates whether the managed property is in effect.

CanBeChanged

Boolean

Indicates whether the value of the managed property can be changed.

ManagedPropertyLogicalName

String

Specifies the name of the managed property.

This property is read-only.

The following example is an ATOM XML BooleanManagedProperty:

<d:IsCustomizable m:type="Microsoft.Crm.Sdk.Data.Services.BooleanManagedProperty">
  <d:Value m:type="Edm.Boolean">true</d:Value> 
  <d:CanBeChanged m:type="Edm.Boolean">true</d:CanBeChanged> 
  <d:ManagedPropertyLogicalName>iscustomizableanddeletable</d:ManagedPropertyLogicalName> 
  </d:IsCustomizable>

The following example is a JSON BooleanManagedProperty:

"IsCustomizable" :{
    "__metadata": { "type": "Microsoft.Crm.Sdk.Data.Services.BooleanManagedProperty" },
    "CanBeChanged": true,
    "ManagedPropertyLogicalName": "iscustomizableanddeletable",
    "Value": true
}

The conceptual schema definition language (CSDL) <NavigationProperty> element includes all the 1:N, and N:N relationships for the entity. If the relationship represents a self-referencing relationship, there will be two <NavigationProperty> elements for this relationship. The name of the relationship uses the prefix Referenced and Referencing to differentiate the role a specific record plays in the relationship. For more information, see Types of entity relationships.

Use the <NavigationProperty> when you want to create a query to retrieve related records. In the following example, if you want to retrieve a list of opportunities where a specific account is the customer, use the opportunity_customer_accounts entity relationship in the context of a specific account:

/AccountSet(guid'[GUID value]')/opportunity_customer_accounts

If you require only the URL addresses to related records you can use the $links query option shown in the following example:

/AccountSet(guid'[GUID value]')/$links/opportunity_customer_accounts

This will return only the URLs to the data for each related record. The results when viewed in the browser would resemble the following example.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?> 
<links xmlns="https://schemas.microsoft.com/ado/2007/08/dataservices">
<uri>[Your Organization Root URL]/xrmservices/2011/OrganizationData.svc/OpportunitySet(guid'a6713858-5e81-df11-afdb-00155dba380a')</uri>
<uri>[Your Organization Root URL]/xrmservices/2011/OrganizationData.svc/OpportunitySet(guid'1224342F-D024-4B47-A3F5-FB22D236E655')</uri>
<uri>[Your Organization Root URL]/xrmservices/2011/OrganizationData.svc/OpportunitySet(guid'7AF675A8-4FBE-42E7-8279-C32605D2B49B')</uri>
<uri>[Your Organization Root URL]/xrmservices/2011/OrganizationData.svc/OpportunitySet(guid'2DD9BA88-2A37-4F53-8946-68ABBDC73FC1')</uri>
</links>

If you want to include data from the related records when you retrieve a record, use the $expand system query option.

See Also

Use the OData endpoint with web resources
OData system query options using the OData endpoint
Perform basic data operations using the OData endpoint
Perform additional data operations using the OData endpoint
Use the OData endpoint with Ajax and JScript web resources
Sample: Create, retrieve, update, and delete using the OData endpoint with JavaScript and jQuery
Sample: Create, retrieve, update, and delete using the OData endpoint with JavaScript
Sample: OData endpoint jQuery contact editor
Open Data Protocol (OData)
Technical Article: Using Option Set Options with the REST Endpoint - JScript