Бележка
Достъпът до тази страница изисква удостоверяване. Можете да опитате да влезете или да промените директориите.
Достъпът до тази страница изисква удостоверяване. Можете да опитате да промените директориите.
Извлича колекция от записи на таблица.
Синтаксис
Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback);
Параметри
| Име | Вид | Необходимо | Описание |
|---|---|---|---|
entityLogicalName |
String | Да | Логическото име на таблицата на записите, които искате да извлечете. Например: account. |
options |
String | Не | Опции за заявки за OData система или FetchXML заявка за извличане на вашите данни. Вижте опции |
maxPageSize |
Номер | Не | Задайте положително число, което показва броя на записите на таблицата, които трябва да бъдат върнати на страница. Ако не зададете този параметър, стойността по подразбиране е зададена на максималното ограничение от 5000 записа за стандартни таблици, 500 за еластични таблици. Ако броят на извлечените записи е по-голям от зададената maxPageSize стойност или максималното ограничение за типа на таблицата nextLink , колоната във върнатото обещание ще съдържа връзка за извличане на записи. |
successCallback |
Function | Не | Функция за извикване, когато се извличат записи на таблица. Вижте върнатата стойност |
errorCallback |
Function | Не | Функция, която да се извика, когато операцията е неуспешна. Подаден е обект със следните свойства: - errorCode:Номер. Кодът на грешката като положително десетично число. Например кодът на грешката, документиран като 0x80040333 ще бъде върнат като 2147746611.- message:Низ. Съобщение за грешка, описващо проблема. |
Опции
Поддържат се следните опции за системни заявки: $select, $top, $filter, $expandи $orderby.
Използвайте опцията $expand за системна заявка, за да управлявате какви данни от свързани таблици се връщат. Ако току-що включите името на свойството за навигация, ще получите всички свойства за свързани записи. Можете да ограничите свойствата, върнати за свързани записи, като използвате опцията $select за системна заявка в скоби след името на свойството за навигация. Използвайте това както за еднозначни , така и за свойства за навигация със стойност на колекция . Имайте предвид, че за офлайн поддържаме само вложена $select опция в $expand.
За да зададете заявка FetchXML, използвайте fetchXml колоната, за да зададете заявката.
Бележка
Винаги трябва да използвате опцията $selectза системна заявка, за да ограничите свойствата, върнати за запис на таблица, като включите разделен със запетаи списък с имена на свойства. Това е важна най-добра практика за представяне. Ако свойствата не са зададени с помощта на $select, ще бъдат върнати всички свойства.
Задавате опциите за заявка, започващи с ?. Можете също да зададете няколко опции за системни заявки, като използвате & за отделяне на опциите за заявки.
Когато зададете низ на заявка на OData за параметъра options , заявката трябва да бъде кодирана за специални знаци.
Когато зададете FetchXML заявка за параметъра options , заявката не трябва да се кодира.
Вижте Примери , за да видите как можете да дефинирате параметъра options за различни възможности за извличане на множество сценарии.
Връщана стойност
При успех връща обект на обещание със successCallback следните свойства:
| Име | Вид | Описание |
|---|---|---|
entities |
Масив от JSON обекти | Всеки обект представлява извлечения запис на таблица, съдържащ колоните и техните стойности като key: value двойки. ИД на записа на таблицата се извлича по подразбиране |
nextLink |
String | (незадължително) Ако броят на извлечените записи е по-голям от стойността, зададена в параметъра maxPageSize в искането, това връща URL адреса, за да върне следващата страница със записи. |
fetchXmlPagingCookie |
(незадължително) За операция, базирана retrieveMultipleRecords на fetchXml, със страниране, при която общият брой записи е по-голям от стойността за страниране, този атрибут връща бисквитката за виртуална памет, която може да се използва за последваща операция fetchXml за извличане на следващата страница със записи. |
Неподдържани типове атрибути за опциите за заявки на OData в Mobile Offline
Следните типове колони не се поддържат, когато се Xrm.WebApi.retrieveMultipleRecords извършва операция с опции за низ за заявка на OData (например $select и $filter) в режим на мобилен офлайн. Трябва да използвате FetchXML, ако типът атрибут, с който трябва да работите, е в този списък с неподдържани типове атрибути.
MultiSelectPicklistFileImageManagedPropertyCalendarRulesPartyListVirtual
Неподдържани функции в Mobile Offline
Следните функции не се поддържат в Mobile Offline:
- Функции за групиране и агрегиране
Поддържани операции за филтриране по тип атрибут в Mobile Offline с помощта на FetchXML
Следните операции се поддържат за всички типове атрибути, когато работите с FetchXML:
- Е равно на (
eq) - Не е равно на (
neq) - Null (
null) - Not Null (
not-null)
Следващата таблица съдържа още операции, поддържани за всеки тип атрибут:
| Тип атрибут | Поддържани операции |
|---|---|
| BigInt, Decimal, Double, Integer | По-голямо от (gt)По-голямо или равно на ( gte)По-малко от ( lt)По-малко или равно на ( lte) |
| Булев, клиент | В (in)Не е в ( not-in) |
| EntityName, Picklist, State, Status | Like (like)Not Like ( not-like)Започва с ( begins-with)Не започва с ( not-begin-with)Завършва с ( ends-with)Не завършва с ( not-end-with)В ( in)Не е в ( not-in) |
| Guid, справка | В (in)Не е в ( not-in)Равно на потребителски ИД ( eq-userid)Не е равно на потребителски ИД ( ne-userid) |
| Money | По-голямо от (gt)По-голямо или равно на ( gte)По-малко от ( lt)По-малко или равно на ( lte)В ( in)Не е в ( not-in) |
| Собственик | В (in)Не е в ( not-in)Равно на потребителски ИД ( eq-userid)Не е равно на потребителски ИД ( ne-userid)Равно на потребител или екип ( eq-useroruserteams) |
| String | Like (like)Not Like ( not-like)Започва с ( begins-with)Не започва с ( not-begin-with)Завършва с ( ends-with)Не завършва с ( not-end-with) |
| ДатаЧас | На или след (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 . Някои от примерите са изброени по-долу.
Основно извличане на няколко
Този пример прави заявки към набора от таблици за акаунти и използва опциите и $top системните $select заявки, за да върне свойството за име за първите три акаунта:
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 не се поддържа в офлайн режим.
Още информация: Свойства на справка
Ето примерни кодове за двата сценария:
За онлайн сценарий (свързан със сървър)
Този пример извършва заявки към набора от таблици за акаунти и използва опциите и $filter системните $select заявки, за да върне свойството name и 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
}
);
За сценарий офлайн за мобилни устройства
Този пример извършва заявки към набора от таблици за акаунти и използва опциите и $filter системните $select заявки, за да върне името и свойството 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, докато сте онлайн или офлайн, за да извлечете и primarycontactid свойството name за записите на акаунта, които имат основен контакт, който отговаря на условие:
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 във вашето последващо повикване retrieveMultipleRecords , за да поискате следващия набор от записи. Не променяйте и не добавяйте повече опции за системни заявки към стойността. За всяка следваща заявка за повече страници трябва да използвате същата maxPageSize стойност, използвана в първоначалното извличане на няколко заявки. Освен това кеширане на върнатите резултати или стойността на следващото свойствоLink, така че да могат да бъдат върнати по-рано извлечени страници.
Например за да получим следващата страница със записи, ще предадем на параметъра options частта на заявката nextLink от URL адреса:
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 бисквитката в URL адреса ще доведе до грешка.
Пример за FetchXML (онлайн сценарий)
Примерът по-долу показва използването на параметъра count FetchXML за задаване на броя на записите (3), които да се показват в една страница.
Бележка
Бисквитката за страниране 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
}
);
Този пример ще покаже три записа и ще върне бисквитка за страниране 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на тази анотация, за да съставим една или повече допълнителни Xrm.WebApi.offline.retrieveRecord заявки.optionsentityType Следната част от кода предоставя пълен пример как да направите това:
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