Обзор 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, но для этого предварительно необходимо отключить опцию "Включить показ ленты чтения канала" в настройках браузера.

Отключении опции "Включить показ ленты чтения канала" в 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 Указывает на то, что связанные записи должны быть получены вместе с основной (основными).
$filter Определяет выражение или функцию, которая будет использоваться для фильтрации запрошенных записей.
$orderby Определяет порядок следования записей.
$select Определяет набор возвращаемых полей.
$skip Исключает из выборки указанное количество записей.
$top Определяет максимальное количество записей возвращаемых запросом.

Опция $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-запросов. Вот список поддерживаемых операторов фильтрации:

Оператор Описание Аналог С# Пример
eq Равенство (Equal) == /AccountSet?$filter=Address1_City eq 'Redmond'
ne Неравенство (Not Equal) != /AccountSet?$filter=Address1_City ne null
gt Больше (Greater Than) > /AccountSet?$filter=CreditLimit/Value gt 1000
ge Больше или равно (Greater than or Equal) >= /AccountSet?&$filter=CreditLimit/Value ge 1000
lt Меньше (Less Than) < /AccountSet?$filter=CreditLimit/Value lt 1000
le Меньше или равно (Less than or Equal) <= /AccountSet?$filter=CreditLimit/Value le 1000
and Логическое И (Logical and) && /AccountSet?$filter=CreditLimit/Value ge 1000 and Address1_StateOrProvince eq 'TX'
or Логическое ИЛИ (Logical or) || /AccountSet?$filter=AccountCategoryCode/Value eq 2 or AccountRatingCode/Value eq 1
not Отрицание (Logical Negation) ! /AccountSet?$filter=(AccountCategoryCode/Value ne null) and not (AccountCategoryCode/Value eq 1)

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

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

Функция Пример
startswith /AccountSet?$filter=startswith(Name, 'a') eq true
substringof /AccountSet?$filter=substringof('store',Name) eq true
endswith /AccountSet?$filter=endswith(Name, '(sample)') eq true

Подробнее об опциии $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.

Ваша оценка: Пусто Средняя: 5 (1 голос)

Комментарии

Отправить комментарий

Содержание этого поля является приватным и не предназначено к показу.
  • Адреса страниц и электронной почты автоматически преобразуются в ссылки.
  • Доступны HTML теги: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Строки и параграфы переносятся автоматически.
  • Syntax highlight code surrounded by the {syntaxhighlighter SPEC}...{/syntaxhighlighter} tags, where SPEC is a Syntaxhighlighter options string or "class="OPTIONS" title="the title".

Подробнее о форматировании

Image CAPTCHA
Enter the characters shown in the image.
Работает на Drupal, система с открытым исходным кодом.