Обзор MSCRM 2011 beta SDK - Использование REST: запросы и фильтры

Итак, надеюсь, теперь стало понятно, что же такое REST в Microsoft Dynamics CRM. Настало время показать примеры его использования.

Напомню, что все REST-запросы производятся к базовому URI:

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

О том как лучше всего сформировать этот путь читайте в статье "Xrm.Page.context и функция GetGlobalContext".

Доступ к записям

Все записи Microsoft Dynamics CRM сгруппированы в так называемые EntitySet-коллекции. Доступ к определённому типу сущностей осуществляется через базовый URI плюс указание типа записей по следующей маске: [Entity Schema Name]+Set.

Например, чтобы получить список организаций, необходимо обратиться по такому адресу:

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet

Для обращения к конкретной организации URI дополняется идентификатором организации:

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')

Просматривать данные REST-службы можно прямо в окне Internet Explorer, но для этого предварительно необходимо отключить опцию "Включить показ ленты чтения канала" в настройках браузера.

Стоит иметь в виду, что за раз служба возвращает 50 записей в списке. Если записей больше 50, в ответе службы будет ссылка на следующую партию записей в теге (или в свойстве __next в случае с JSON).

Связанные записи

Доступ к связанным записям можно получить через родительскую. Для этого необходимо дополнить адрес указателем на связь. Укзатель формируется по следующему правилу (для 1:N): основная запись (сторона "1") _ [имя_поля-ссылки] _ связанные записи (сторона "N"). Полный список доступных связей приведён в SDK в описании каждой сущности (сразу же за списком полей в подразделах "One-to-Many Relationships" и "Many-to-Many Relationships").

Вот пример для получения коллекции возможных сделок конкретной организации:

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'[GUID value]')/opportunity_customer_accounts

А вот так можно получить список контактных лиц организации:

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'[GUID value]')/contact_customer_accounts

Помимо самой коллекции связанных записей, можно получить массив ссылок на них. Для этого в запрос вставляется опция $links:

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'[GUID value]')/$links/opportunity_customer_accounts

Опции запросов OData

Рассмотрим подробнее опции запросов.

Опция $expand

Указывает на то, что связанные записи должны быть получены вместе с основной (основными).

Пример: вам необходимо одновременно получить набор организаций и все возможные сделки связанные с ними. Для этого достаточно дополнить приведённый ранее запрос уточняющей опцией:

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet?$expand=opportunity_customer_accounts

Если вы ограничиваете набор полей, возвращаемых запросом, вы должны включить имя "раскрываемого" поля в запрос. Следующий запрос вернёт только имена организаций и их возможные сделки.

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts

К сожалению Microsoft Dynamics CRM 2011 не поддерживает доступ к связанным записям с глубиной вложения более одной. Т.е. нельзя получить "связанные записи связанной записи". Следующий запрос не будет выполнен:

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts/opportunity_owning_user

По умолчанию можно определить до шести связей, которые могут быть возвращены. Пример с двумя связями:

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet?$select=Name,opportunity_customer_accounts,user_accounts&$expand=opportunity_customer_accounts,user_accounts

Подробнее об опциии $expand можно прочитать в спецификации OData: Expand System Query Option ($expand).

Опция $filter

Определяет выражение или функцию, которая будет использоваться для фильтрации запрошенных записей.

Здесь всё как в фильтрации Fetch-запросов. Вот список поддерживаемых операторов фильтрации:

При сравнении дат необходимо придерживаться следующего формата: datetime’<time value>’. Пример: datetime'2010-10-07' или datetime'2010-11-07T18:22:29Z'

Помимо операторов в Microsoft Dynamics CRM 2011 доступны следующие функции фильтрации (хочется надеяться, что в будущем этот список расширится всеми функциями из спецификации):

Подробнее об опциии $filter можно прочитать в спецификации OData: Filter System Query Option ($filter).

Опция $orderby

Определяет порядок следования записей. По умолчанию используется порядок "по возрастанию" (ключевое слово ‘asc’). Используйте ключевое слово ‘desc’ для упорядочивания по убыванию.

Пример упорядочивания организаций по стране и по городу:

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet?$select=Address1_Country,Address1_City,Name&$orderby=Address1_Country,Address1_City desc&$filter=(Address1_Country ne null) and (Address1_City ne null)

Подробнее об опциии $orderby можно прочитать в спецификации OData: Orderby System Query Option ($orderby).

Опция $select

Определяет набор возвращаемых полей. По умолчанию возвращает все поля записи, что эквивалентно запросу $select=*.

[ROOT_URL]/XRMServices/2011/OrganizationData.svc/AccountSet?$select=Name,PrimaryContactId

Подробнее об опциии $select можно прочитать в спецификации OData: Select System Query Option ($select).

Опция $skip

Исключает из выборки указанное количество записей.

Подробнее об опциии $skip можно прочитать в спецификации OData: Skip System Query Option ($skip).

Опция $top

Определяет максимальное количество записей возвращаемых запросом.

Подробнее об опциии $top можно прочитать в спецификации OData: Top System Query Option ($top).

Неподдерживаемые опции запросов

Я уже упомянул, что поддерживается сильно урезанный список функций опции $filter с весьма полезными операциями. Помимо этого Microsoft Dynamics CRM 2011 не поддерживает следующие опции запросов OData:

• $inlinecount
• $count
• $format

Подробно об опциях Open Data Protocol: OData: URI Conventions.

Необходимо также упомянуть, что максимальная длина GET-запроса в Internet Explorer ограничена 2048 символами за вычетом количества символов в текущем пути. Необходимо помнить об этом ограничении при построении сложных запросов и/или перечислении списка возвращаемых полей в опции $select. Данное ограничение должно легко обходиться при использовании в URL только основного пути (Service Root URI), а все опции передавать POST-запросом. Подробнее о данном ограничении: Microsoft KB 208427.