Поделиться через


retrieveMultipleRecords (справочник по API клиента)

Извлекает коллекцию записей таблиц.

Синтаксис

Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback);

Параметры

Имя Тип Обязательно Description
entityLogicalName String Да Логическое имя таблицы записей, которые требуется извлечь. Например: account.
options String нет Параметры системного запроса OData или запрос FetchXML для получения данных. См . параметры
maxPageSize Number нет Укажите положительное число, указывающее количество возвращаемых записей таблицы на страницу. Если этот параметр не указан, значение по умолчанию по умолчанию равно максимальному ограничению в 5000 записей для стандартных таблиц, 500 для эластичных таблиц.

Если количество извлекаемых записей превышает указанное maxPageSize значение или максимальное ограничение для типа таблицы, nextLink столбец в возвращаемом объекте promise будет содержать ссылку для получения записей.
successCallback Функция нет Функция для вызова при извлечении записей таблиц. См . возвращаемое значение
errorCallback Функция нет Функция, вызываемая при сбое операции. Передается объект со следующими свойствами:
- errorCode:Число. Код ошибки в виде положительного десятичного числа. Например, код ошибки, который задокументирован как 0x80040333 будет возвращен.2147746611
- message:Струна. Сообщение об ошибке с описанием проблемы.

Options

Поддерживаются следующие параметры системного запроса: $select, $top, , $expand$filterи $orderby.

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

Чтобы указать запрос FetchXML, используйте fetchXml столбец для указания запроса.

Замечание

Для ограничения свойств, возвращаемых для записи таблицы, всегда следует использовать $selectпараметр системного запроса, включив разделенный запятыми список имен свойств. Это важная рекомендация по повышению производительности. Если свойства не указаны с помощью $select, будут возвращены все свойства.

Параметры запроса указываются, начиная с ?. Можно также указать несколько параметров системного запроса, используя & для разделения параметров запроса.

При указании строки запроса OData для options параметра запрос должен быть закодирован для специальных символов.

При указании запроса FetchXML для options параметра запрос не должен быть закодирован.

Ознакомьтесь с примерами, чтобы узнать, как определить options параметр для различных сценариев извлечения нескольких сценариев.

Возвращаемое значение

При успешном выполнении возвращает объект successCallback promise в указанные ниже свойства:

Имя Тип Description
entities Массив объектов JSON Каждый объект представляет полученную запись таблицы, содержащую столбцы и их значения в виде key: value пар. Идентификатор записи таблицы извлекается по умолчанию
nextLink String (необязательно) Если количество извлекаемых записей превышает значение, указанное в maxPageSize параметре в запросе, это возвращает URL-адрес для возврата следующей страницы записей.
fetchXmlPagingCookie (необязательно) Для операции на основе retrieveMultipleRecords fetchXml с разбиением на страницы, где общее число записей больше значения разбиения на страницы, этот атрибут возвращает файл cookie на страницы, который можно использовать для последующей операции извлечения Xml для получения следующей страницы записей.

Неподдерживаемые типы атрибутов для параметров запросов OData в автономном режиме mobile

Следующие типы столбцов не поддерживаются при выполнении Xrm.WebApi.retrieveMultipleRecords операции с параметрами строки запроса OData (например, $select и $filter) в автономном режиме мобильных устройств. Следует использовать FetchXML, если тип атрибута, с которым необходимо работать, находится в этом списке неподдерживаемых типов атрибутов.

  • MultiSelectPicklist
  • File
  • Image
  • ManagedProperty
  • CalendarRules
  • PartyList
  • Virtual

Неподдерживаемые функции в автономном режиме для мобильных устройств

Следующие функции не поддерживаются в mobile Offline:

  • Функции группировки и агрегирования

Поддерживаемые операции фильтрации для типа атрибутов в мобильном режиме в автономном режиме с помощью FetchXML

Следующие операции поддерживаются для всех типов атрибутов при работе с FetchXML:

  • Равно (eq)
  • Not Equals (neq)
  • Null (null)
  • Не null (not-null)

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

Тип атрибута Поддерживаемые операции
BigInt, Десятичное, Двойное, Целое число Больше (gt)
Больше или равно (gte)
Меньше (lt)
Меньше или равно (lte)
Boolean, Customer В (in)
Не в (not-in)
EntityName, Picklist, State, Status Like (like)
Не нравится (not-like)
Начинается с (begins-with)
Не начинается с (not-begin-with)
Заканчивается с (ends-with)
Не заканчивается (not-end-with)
В (in)
Не в (not-in)
Guid, поиск В (in)
Не в (not-in)
Равно идентификатору пользователя (eq-userid)
Не равен идентификатору пользователя (ne-userid)
Деньги Больше (gt)
Больше или равно (gte)
Меньше (lt)
Меньше или равно (lte)
В (in)
Не в (not-in)
Владелец В (in)
Не в (not-in)
Равно идентификатору пользователя (eq-userid)
Не равен идентификатору пользователя (ne-userid)
Равно пользователю или команде (eq-useroruserteams)
String Like (like)
Не нравится (not-like)
Начинается с (begins-with)
Не начинается с (not-begin-with)
Заканчивается с (ends-with)
Не заканчивается (not-end-with)
DateTime Включено или после (on-or-after)
Включено (on)
Включено или раньше (on-or-before)
Сегодня (today)
Завтра (tomorrow)
Вчера (yesterday)
Следующие семь дней (next-seven-days)
Последние семь дней (last-seven-days)
На следующей неделе (next-week)
На прошлой неделе (last-week)
На этой неделе (this-week)
Следующий месяц (next-month)
Прошлый месяц (last-month)
В этом месяце (this-month)
Следующий год (next-year)
Прошлый год (last-year)
В этом году (this-year)
Последние X дни (last-x-days)
Следующие X дни (next-x-days)
Последние X недели (last-x-weeks)
Следующие X недели (next-x-weeks)
Последние X месяцы (last-x-months)
Следующие X месяцы (next-x-months)
Последние X годы (last-x-years)
Следующие X годы (next-x-years)
Больше (gt)
Больше или равно (gte)
Меньше (lt)
Меньше или равно (lte)

Примеры

Большинство сценариев и примеров, упомянутых в запросе данных с помощью веб-API , можно достичь с помощью метода retrieveMultipleRecords . Ниже перечислены некоторые примеры.

Базовый извлечение нескольких

В этом примере запрашивается набор таблиц учетных записей и используются $select$top параметры системного запроса для возврата свойства имени для первых трех учетных записей:

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name&$top=3").then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }                    
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Базовое получение нескольких с помощью FetchXML

В этом примере сущность запрашивается account с помощью fetchXML.

var fetchXml = "?fetchXml=<fetch><entity name='account'><attribute name='accountid'/><attribute name='name'/></entity></fetch>";

Xrm.WebApi.retrieveMultipleRecords("account", fetchXml).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }                    

        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Получение или фильтрация по свойствам подстановки

Для большинства свойств навигации с одним значением вы найдете вычисляемое свойство только для чтения, которое использует следующее соглашение об именовании: _<name>_value где <name> имя свойства навигации с одним значением. Для фильтрации также можно использовать конкретное значение свойства навигации с одним значением. Однако для мобильных клиентов в автономном режиме эти параметры синтаксиса не поддерживаются, а для извлечения и фильтрации следует использовать имя свойства навигации с одним значением. Кроме того, сравнение свойств навигации с null не поддерживается в автономном режиме.

Дополнительные сведения: свойства подстановки

Ниже приведены примеры кода для обоих сценариев:

Для интерактивного сценария (подключено к серверу)

В этом примере запрашивается набор таблиц учетных записей и используются $select$filter параметры системного запроса для возврата имени и свойства primarycontactid для учетных записей, имеющих определенный первичный контакт:

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name,_primarycontactid_value&$filter=primarycontactid/contactid eq a0dbf27c-8efb-e511-80d2-00155db07c77").then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }                    
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Автономный сценарий для мобильных устройств

В этом примере запрашивается набор таблиц учетных записей и используются $select$filter параметры системного запроса для возврата имени и свойства primarycontactid для учетных записей, имеющих определенный первичный контакт при работе в автономном режиме:

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name,primarycontactid&$filter=primarycontactid eq a0dbf27c-8efb-e511-80d2-00155db07c77").then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }                    
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Использование FetchXML для получения или фильтрации по свойствам подстановки (в сети и автономном сценарии)

Параметр можно использовать FetchXML в режиме "в сети" или "в автономном режиме", чтобы получить name записи учетной записи и primarycontactid свойства, имеющие основной контакт, соответствующий условию:

var fetchXml = `?fetchXml=
    <fetch>
       <entity name='account'>
          <attribute name='name'/>
          <attribute name='primarycontactid'/>
          <link-entity name='contact' from='contactid' to='primarycontactid'>
             <filter type='and'>
                <condition attribute='lastname' operator='eq' value='Contoso'/>
             </filter>
          </link-entity>
       </entity>
    </fetch>`;

Xrm.WebApi.retrieveMultipleRecords("account", fetchXml).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }                    

        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Укажите количество таблиц, возвращаемых на странице

В следующем примере показано использование maxPageSize параметра для указания количества записей (3), отображаемых на странице.

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name", 3).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }
        console.log("Next page link: " + result.nextLink);
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

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

{@odata.etag: "W/"1035541"", name: "A. Datum", accountid: "475b158c-541c-e511-80d3-3863bb347ba8"}
@odata.etag: "W/"1035541""accountid: "475b158c-541c-e511-80d3-3863bb347ba8"name: "A. Datum"__proto__: Object
VM5595:4 
{@odata.etag: "W/"947306"", name: "Adventure Works", accountid: "a8a19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5595:4 
{@odata.etag: "W/"1033754"", name: "Alpine Ski House", accountid: "aaa19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5595:6 
Next page link: [Organization URI]/api/data/v9.0/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257bAAA19CDD-88DF-E311-B8E5-6C3BE5A8B200%257d%2522%2520first%253d%2522%257b475B158C-541C-E511-80D3-3863BB347BA8%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E

Используйте часть запроса в URL-адресе свойства в nextLink качестве значения параметра options в последующем вызове getMultipleRecords , чтобы запросить следующий набор записей. Не изменяйте или не добавляйте к значению параметры системного запроса. Для каждого последующего запроса на дополнительные страницы следует использовать то же maxPageSize значение, которое используется в исходном запросе на получение нескольких. Кроме того, кэшируйте результаты, возвращаемые или значение свойства nextLink, чтобы ранее полученные страницы можно было вернуть.

Например, чтобы получить следующую страницу записей, мы передадим часть nextLink запроса URL-адреса параметру options :

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257bAAA19CDD-88DF-E311-B8E5-6C3BE5A8B200%257d%2522%2520first%253d%2522%257b475B158C-541C-E511-80D3-3863BB347BA8%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E", 3).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }
        console.log("Next page link: " + result.nextLink);
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Будет возвращена следующая страница набора результатов:

{@odata.etag: "W/"1035542"", name: "Blue Yonder Airlines", accountid: "aca19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5597:4 
{@odata.etag: "W/"1031348"", name: "City Power & Light", accountid: "aea19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5597:4 
{@odata.etag: "W/"1035543"", name: "Coho Winery", accountid: "b0a19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5597:6 
Next page link: [Organization URI]/api/data/v9.0/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%223%22%20pagingcookie=%22%253ccookie%2520page%253d%25222%2522%253e%253caccountid%2520last%253d%2522%257bB0A19CDD-88DF-E311-B8E5-6C3BE5A8B200%257d%2522%2520first%253d%2522%257bACA19CDD-88DF-E311-B8E5-6C3BE5A8B200%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E

Это важно

Значение nextLink свойства в кодировке URI. Если URI кодирует значение перед отправкой, данные XML-файла cookie в URL-адресе вызывают ошибку.

Пример FetchXML (сценарий в сети)

В следующем примере показано использование count параметра FetchXML для указания количества записей (3), отображаемых на странице.

Замечание

Файл cookie для разбиения на страницах FetchXML возвращается только для онлайн-операций retrieveMultipleRecords . (Xrm.WebApi.online). Он не поддерживается в автономном режиме.

var fetchXml = "?fetchXml=<fetch count='3'><entity name='account'><attribute name='accountid'/><attribute name='name'/></entity></fetch>";

Xrm.WebApi.online.retrieveMultipleRecords("account", fetchXml).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }          

        console.log("Paging cookie: " + result.fetchXmlPagingCookie);

        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

В этом примере отображаются три записи и возвращается файл cookie Paging FetchXML, чтобы получить результаты следующей страницы, если в результирующем наборе есть больше записей. Ниже приведен пример выходных данных консоли в средствах разработчика браузера:

{
   "entities": [
      {
         "@odata.etag": "W/\"1035542\"",
         "accountid": "aca19cdd-88df-e311-b8e5-6c3be5a8b200",
         "name": "Blue Yonder Airlines"
      },
      {
         "@odata.etag": "W/\"1031348\"",
         "accountid": "aea19cdd-88df-e311-b8e5-6c3be5a8b200",
         "name": "City Power & Light"
      },
      {
         "@odata.etag": "W/\"1035543\"",
         "accountid": "b0a19cdd-88df-e311-b8e5-6c3be5a8b200",
         "name": "Coho Winery"
      }
   ],
   "fetchXmlPagingCookie": "<cookie pagenumber=\"2\" pagingcookie=\"%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b0748C6EC-55A8-EB11-B1B5-000D3AFEF6FA%257d%2522%2520first%253d%2522%257bFC47C6EC-55A8-EB11-B1B5-000D3AFEF6FA%257d%2522%2520%252f%253e%253c%252fcookie%253e\" istracking=\"False\" />"
}

Мы можем использовать приведенный fetchXmlPagingCookie ниже пример, чтобы получить большие результирующие наборы с разбиением по страницам.

function CreateXml(fetchXml, pagingCookie, page, count) {
  var domParser = new DOMParser();
  var xmlSerializer = new XMLSerializer();

  var fetchXmlDocument = domParser.parseFromString(fetchXml, "text/xml");

  if (page) {
    fetchXmlDocument
      .getElementsByTagName("fetch")[0]
      .setAttribute("page", page.toString());
  }

  if (count) {
    fetchXmlDocument
      .getElementsByTagName("fetch")[0]
      .setAttribute("count", count.toString());
  }

  if (pagingCookie) {
    var cookieDoc = domParser.parseFromString(pagingCookie, "text/xml");
    var innerPagingCookie = domParser.parseFromString(
      decodeURIComponent(
        decodeURIComponent(
          cookieDoc
            .getElementsByTagName("cookie")[0]
            .getAttribute("pagingcookie")
        )
      ),
      "text/xml"
    );
    fetchXmlDocument
      .getElementsByTagName("fetch")[0]
      .setAttribute(
        "paging-cookie",
        xmlSerializer.serializeToString(innerPagingCookie)
      );
  }

  return xmlSerializer.serializeToString(fetchXmlDocument);
}

function retrieveAllRecords(entityName, fetchXml, page, count, pagingCookie) {
  if (!page) {
    page = 0;
  }

  return retrievePage(entityName, fetchXml, page + 1, count, pagingCookie).then(
    function success(pageResults) {
      if (pageResults.fetchXmlPagingCookie) {
        return retrieveAllRecords(
          entityName,
          fetchXml,
          page + 1,
          count,
          pageResults.fetchXmlPagingCookie
        ).then(
          function success(results) {
            if (results) {
              return pageResults.entities.concat(results);
            }
          },
          function error(e) {
            throw e;
          }
        );
      } else {
        return pageResults.entities;
      }
    },
    function error(e) {
      throw e;
    }
  );
}

function retrievePage(entityName, fetchXml, pageNumber, count, pagingCookie) {
  var fetchXml =
    "?fetchXml=" + CreateXml(fetchXml, pagingCookie, pageNumber, count);

  return Xrm.WebApi.online.retrieveMultipleRecords(entityName, fetchXml).then(
    function success(result) {
      return result;
    },
    function error(e) {
      throw e;
    }
  );
}

var count = 3;
var fetchXml =
  '<fetch><entity name="account"><attribute name="accountid"/><attribute name="name"/></entity></fetch>';

retrieveAllRecords("account", fetchXml, null, count, null).then(
  function success(result) {
    console.log(result);

    // perform additional operations on retrieved records
  },
  function error(error) {
    console.log(error.message);
    // handle error conditions
  }
);

Используйте параметр $expand системного запроса в свойствах навигации для управления данными, возвращаемыми из связанных таблиц. В следующем примере показано, как получить контакт для всех записей учетной записи. Для связанных записей контактов мы извлекаем contactid только следующие записи.fullname

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name&$top=3&$expand=primarycontactid($select=contactid,fullname)", 3).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }        
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Приведенный выше фрагмент кода возвращает результат со схемой, например:

{
   "entities": [
      {
         "@odata.etag": "W/\"1459919\"",
         "name": "Test Account",
         "accountid": "119edfac-19c6-ea11-a81a-000d3af5e732",
         "primarycontactid": {
            "contactid": "6c63a1b7-19c6-ea11-a81a-000d3af5e732",
            "fullname": "Test Contact"
         }
      }
   ]
}

Замечание

Как и в интерактивном сценарии, используйте параметр системного запроса $expand для получения данных из связанных таблиц в автономном режиме. Однако связи "многие ко многим" не поддерживаются в автономном режиме.

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

Замечание

Не @odata.nextLink рекомендуется использовать для мобильных автономных сценариев. Хотя он по-прежнему поддерживается для существующих настроек, его больше не рекомендуется использовать.

Операция автономного $expand возвращает заметку @odata.nextLink , содержащую сведения о том, как получить сведения о связанной записи. Для создания одного или нескольких дополнительных Xrm.WebApi.offline.retrieveRecord запросов используется identityTypeпараметр и options параметр этой заметки. В следующем фрагменте кода приведен полный пример этого.

Xrm.WebApi.offline.retrieveMultipleRecords("account", "?$select=name&$top=3&$expand=primarycontactid($select=contactid,fullname)").then(function(resultSet) {
    /**
     *  resultSet has a structure like:
     *  {
     *      "entities": [
     *          {
     *              "accountid": "119edfac-19c6-ea11-a81a-000d3af5e732",
     *              "name": "Test Account",
     *              "primarycontactid@odata.nextLink": {
     *                  "API": "{Xrm.Mobile.offline}.{retrieveRecord}",
     *                  "id": "119edfac-19c6-ea11-a81a-000d3af5e732",
     *                  "entityType": "account",
     *                  "options": "?$select=accountid&$expand=primarycontactid($select=contactid,fullname)&$getOnlyRelatedEntity=true"
     *              },
     *              "primarycontactid": {}
     *          }
     *      ]
     *  }
     *
     *  Notice the empty `primarycontactid` property but an additional `primarycontactid@odata.nextLink` 
     *  annotation that lets us know how to get to the linked data that we need.
     **/

    var promises = resultSet.entities.map(function(outerItem) {
        // We do a retrieveRecord() for every item in the result set of retrieveMultipleRecords() and then
        // combine the results into the retrieveMultipleRecords() result set itself.
       return Xrm.WebApi.offline.retrieveRecord(
           outerItem["primarycontactid@odata.nextLink"].entityType, 
           outerItem["primarycontactid@odata.nextLink"].id,
           outerItem["primarycontactid@odata.nextLink"].options
        ).then(function(innerResult) {            
            if (innerResult.value.length === 0) {
                return outerItem;
            }
            outerItem.primarycontactid = innerResult.value[0];
            return outerItem;
        });
    });

    return Promise.all(promises);
}).then(function(allResults) {
    for (var i = 0; i < allResults.length; i++) {
        console.log(allResults[i]);
    }
    // perform additional operations on retrieved records
}, function(error) {
    console.error(error);
    // handle error conditions
});

Дополнительные примеры получения нескольких записей с помощью веб-API см. в разделе "Запрос данных" с помощью веб-API.

Запрос данных с помощью веб-API
Xrm.WebApi.retrieveRecord
Xrm.WebApi