Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Извлекает коллекцию записей таблиц.
Синтаксис
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, , $filter$expandи $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 в автономном режиме
Следующие типы столбцов не поддерживаются при использовании Xrm.WebApi.retrieveMultipleRecords с параметрами строки запроса OData (например $select , и $filter) в автономном режиме мобильных устройств. Используйте FetchXML, если необходимо работать с типом атрибута в этом списке неподдерживаемых типов атрибутов.
MultiSelectPicklistFileImageManagedPropertyCalendarRulesPartyListVirtual
Неподдерживаемые функции в автономном режиме для мобильных устройств
Следующие функции не поддерживаются в автономном режиме для мобильных устройств.
- Функции группировки и агрегирования
Поддерживаемые операции фильтрации для типа атрибутов в мобильном режиме в автономном режиме с помощью 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) |
Примеры
Метод retrieveMultipleRecords можно использовать для достижения большинства сценариев и примеров, упомянутых в запросах данных с помощью веб-API. Некоторые примеры перечислены в следующем разделе.
Базовый извлечение нескольких
В этом примере запрашивается набор таблиц учетных записей и используются $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 параметр для указания того, что каждая страница отображает три записи.
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, чтобы указать, что каждая страница отображает три записи.
Замечание
Файл 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 разбиения на страницы 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 , содержащую сведения о том, как получить сведения о связанной записи.
id
entityType
options Используйте и параметры этой заметки для создания одного или нескольких дополнительных Xrm.WebApi.offline.retrieveRecord запросов. В следующем коде приведен полный пример этого.
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