Query Microsoft Dynamics CRM 2011 Data Using the REST Endpoint
Applies To: Dynamics CRM 2011
To locate and retrieve data with the REST endpoint, manipulate the URI. All actions require that you begin with the service root URI. In Microsoft Dynamics CRM 2011 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 getServerUrl function in the context object. If a web resource will be hosted in a form, you can reference the Xrm.Page.context to call getServerUrl. 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.
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. |
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:
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 |
Microsoft.Crm.Sdk.Data.Services.EntityReference | EntityReference |
Microsoft.Crm.Sdk.Data.Services.OptionSetValue | OptionSetValue |
Microsoft.Crm.Sdk.Data.Services.Money | |
Microsoft.Crm.Sdk.Data.Services.BooleanManagedProperty |
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. |
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)" }
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 }
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 }
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="http://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.
Use the REST Endpoint for Web Resources
OData System Query Options Using the REST Endpoint
Perform Basic Data Operations in Microsoft Dynamics CRM 2011 Using the REST Endpoint
Perform Additional Data Operations in Microsoft Dynamics CRM 2011 Using the REST Endpoint
Use the REST Endpoint with Ajax and JScript Web Resources
Use the REST Endpoint with Silverlight Web Resources
Sample: Create, Retrieve, Update and Delete Using the REST Endpoint with JavaScript and jQuery
Sample: Create, Retrieve, Update and Delete Using the REST Endpoint with JavaScript
Sample: Create, Retrieve, Update and Delete Using the REST Endpoint with Silverlight
Sample: REST Endpoint jQuery Contact Editor
Sample: REST Endpoint Silverlight Contact Editor
Open Data Protocol (OData)
Technical Article: Using Option Set Options with the REST Endpoint - JScript
Microsoft Dynamics CRM 2011
© Microsoft Corporation. All rights reserved. Copyright
