Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Načte kolekci záznamů tabulky.
Syntaxe
Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback);
Parametry
| Název | Typ | Povinné | Description |
|---|---|---|---|
entityLogicalName |
String | Ano | Logický název tabulky záznamů, které chcete načíst. Například: account. |
options |
String | Ne | Možnosti systémového dotazu OData nebo dotaz FetchXML pro načtení dat. Zobrazit možnosti |
maxPageSize |
Number | Ne | Zadejte kladné číslo, které označuje počet záznamů tabulky, které se mají vrátit na stránku. Pokud tento parametr nezadáte, výchozí hodnota je maximální limit 5 000 záznamů pro standardní tabulky a 500 pro elastické tabulky. Pokud je počet načtených záznamů větší než zadaná maxPageSize hodnota nebo maximální limit pro typ tabulky, nextLink obsahuje sloupec ve vrácených objektech příslibu odkaz na načtení záznamů. |
successCallback |
Funkce | Ne | Funkce, která se má volat při načtení záznamů tabulky. Zobrazit vrácenou hodnotu |
errorCallback |
Funkce | Ne | Funkce, která se má volat v případě selhání operace. Předá se objekt s následujícími vlastnostmi: - errorCode:Číslo. Kód chyby jako kladné desetinné číslo. Například kód chyby zdokumentovaný tak, jak 0x80040333 bude vrácen jako 2147746611.- message:Řetězec. Chybová zpráva popisující problém. |
Možnosti
Podporují se následující systémové možnosti dotazu: $select, $top, $filter, $expand, a $orderby.
Pomocí možnosti systémového $expand dotazu můžete určit, jaká data ze souvisejících tabulek se vrátí. Pokud pouze zahrnete název navigační vlastnosti, obdržíte všechny vlastnosti pro související záznamy. Vlastnosti vrácené pro související záznamy můžete omezit pomocí možnosti systémového $select dotazu v závorkách za názvem navigační vlastnosti. Tuto možnost použijte pro navigační vlastnosti s jednou hodnotou i pro hodnoty kolekce . Pro offline režim je podporována pouze vnořená $select možnost uvnitř.$expand
Pokud chcete zadat dotaz FetchXML, zadejte dotaz pomocí fetchXml sloupce.
Poznámka:
Pokud chcete omezit vlastnosti vrácené pro záznam tabulky tak, že zahrnete seznam názvů vlastností oddělených čárkami, musíte vždy použít $select možnost systémového dotazu. Tento postup je důležitý pro výkon. Pokud nezadáte vlastnosti pomocí $select, vrátí se všechny vlastnosti.
Zadejte možnosti dotazu začínající na ?. K oddělení možností dotazu můžete také použít několik systémových dotazů & .
Když pro parametr zadáte řetězec options dotazu OData, zakódujte dotaz na speciální znaky.
Pokud pro parametr zadáte dotaz options FetchXML, nezakódujte dotaz.
Informace o definování parametru options pro různé načtení více scénářů najdete v tématu Příklady.
Návratová hodnota
Při úspěchu vrátí objekt příslibu successCallback s následujícími vlastnostmi:
| Název | Typ | Description |
|---|---|---|
entities |
Pole objektů JSON | Každý objekt představuje načtený záznam tabulky obsahující sloupce a jejich hodnoty jako key: value páry. ID záznamu tabulky se ve výchozím nastavení načte. |
nextLink |
String | (volitelné) Pokud je počet načtených záznamů větší než hodnota zadaná v parametru maxPageSize v požadavku, vrátí se adresa URL pro vrácení další stránky záznamů. |
fetchXmlPagingCookie |
(volitelné) Pro operaci založenou na retrieveMultipleRecords fetchXml se stránkováním, kde je celkový počet záznamů větší než stránkovací hodnota, tento atribut vrátí stránkovací soubor cookie, který lze použít pro další operaci fetchXml k načtení další stránky záznamů. |
Nepodporované typy atributů pro možnosti dotazů OData v mobilním offline režimu
Následující typy sloupců nejsou podporovány při použití Xrm.WebApi.retrieveMultipleRecords s možnostmi řetězce dotazu OData (například $select a $filter) v režimu offline mobilního režimu. Pokud potřebujete pracovat s typem atributu v tomto seznamu nepodporovaných typů atributů, použijte FetchXML.
MultiSelectPicklistFileImageManagedPropertyCalendarRulesPartyListVirtual
Nepodporované funkce v mobilním offline režimu
Mobilní offline funkce nepodporují následující funkce:
- Seskupování a agregace
Podporované operace filtrování na typ atributu v mobilním režimu offline pomocí FetchXML
Při práci s FetchXML jsou podporovány následující operace pro všechny typy atributů:
- Rovná se (
eq) - Nerovná se (
neq) - Null (
null) - Not Null (
not-null)
Následující tabulka uvádí další operace podporované pro každý typ atributu:
| Typ atributu | Podporované operace |
|---|---|
| BigInt, Decimal, Double, Integer | Větší než (gt)Větší než nebo Rovná se ( gte)Menší než ( lt)Menší než nebo rovno ( lte) |
| Logická hodnota, Zákazník | V (in)Není v ( not-in) |
| EntityName, Picklist, State, Status | Like (like)Nelíbí se ( not-like)Začíná na ( begins-with)Nezačínat na ( not-begin-with)Končí na ( ends-with)Nekončit ( not-end-with)V ( in)Není v ( not-in) |
| Guid, vyhledávání | V (in)Není v ( not-in)Rovná se ID uživatele ( eq-userid)Nerovná se ID uživatele ( ne-userid) |
| Peníze | Větší než (gt)Větší než nebo Rovná se ( gte)Menší než ( lt)Menší než nebo rovno ( lte)V ( in)Není v ( not-in) |
| Vlastník | V (in)Není v ( not-in)Rovná se ID uživatele ( eq-userid)Nerovná se ID uživatele ( ne-userid)Rovná se uživateli nebo týmu ( eq-useroruserteams) |
| String | Like (like)Nelíbí se ( not-like)Začíná na ( begins-with)Nezačínat na ( not-begin-with)Končí na ( ends-with)Nekončit ( not-end-with) |
| DateTime | Zapnuto nebo za (on-or-after)Zapnuto ( on)Zapnuto nebo před ( on-or-before)Dnes ( today)Zítra ( tomorrow)Včera ( yesterday)Příštích sedm dnů ( next-seven-days)Posledních sedm dnů ( last-seven-days)Příští týden ( next-week)Minulý týden ( last-week)Tento týden ( this-week)Příští měsíc ( next-month)Minulý měsíc ( last-month)Tento měsíc ( this-month)Příští rok ( next-year)Minulý rok ( last-year)This Year ( this-year)Poslední X dny ( last-x-days)Další X dny ( next-x-days)Poslední X týdny ( last-x-weeks)Další X týdny ( next-x-weeks)Poslední X měsíce ( last-x-months)Další X měsíce ( next-x-months)Posledních X let ( last-x-years)Další X roky ( next-x-years)Větší než ( gt)Větší než nebo rovno ( gte)Menší než ( lt)Menší než nebo rovno ( lte) |
Examples
Pomocí metody retrieveMultipleRecords můžete dosáhnout většiny scénářů a příkladů uvedených v datech dotazů pomocí webového rozhraní API. Některé příklady jsou uvedené v následující části.
Základní načtení více
Tento příklad dotazuje sadu tabulek účtů a pomocí $select$top možností systémového dotazu vrátí vlastnost názvu pro první tři účty:
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
}
);
Základní načtení více pomocí FetchXML
Tento příklad dotazuje entitu account pomocí 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
}
);
Načtení nebo filtrování podle vlastností vyhledávání
U většiny vlastností navigace s jednou hodnotou najdete vypočítanou vlastnost jen pro čtení, která používá následující konvenci pojmenování: _<name>_value kde <name> je název jednohodnotové navigační vlastnosti. Pro účely filtrování můžete také použít konkrétní hodnotu jednohodnotové navigační vlastnosti. Tyto možnosti syntaxe ale mobilní klienti v offline režimu nepodporují. Pro načítání i filtrování použijte název vlastnosti navigace s jednou hodnotou. Offline režim také nepodporuje porovnání vlastností navigace s hodnotou null.
Další informace: Vlastnosti vyhledávání
Tady jsou příklady kódu pro oba scénáře:
Pro online scénář (připojený k serveru)
Tento příklad se dotazuje na sadu tabulek účtů a pomocí $select$filter možností systémového dotazu vrátí název a vlastnost primarycontactid pro účty, které mají konkrétní primární kontakt:
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
}
);
Scénář pro mobilní offline režim
Tento příklad dotazuje sadu tabulek účtů a používá $select možnosti systémového $filter dotazu k vrácení názvu a primárnícontactid vlastnosti pro účty, které mají konkrétní primární kontakt při práci v offline režimu:
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
}
);
Použití FetchXML k načtení nebo filtrování podle vlastností vyhledávání (online a offline scénář)
Pomocí parametru FetchXML při online nebo offline načtení name a primarycontactid vlastnosti pro záznamy účtů, které mají primární kontakt, který odpovídá podmínce:
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
}
);
Zadejte počet tabulek, které se mají vrátit na stránce.
Následující příklad ukazuje, jak pomocí parametru maxPageSize určit, že každá stránka zobrazuje tři záznamy.
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
}
);
Tento příklad zobrazí tři záznamy a odkaz na další stránku. Tady je příklad výstupu z konzoly v vývojářských nástrojích prohlížeče:
{@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
Část dotazu v adrese URL ve nextLink vlastnosti použijte jako hodnotu parametru options v dalším volání retrieveMultipleRecords k vyžádání další sady záznamů. Do hodnoty neměňte ani nepřidávejte žádné další možnosti systémového dotazu. Pro každý další požadavek na více stránek použijte stejnou maxPageSize hodnotu, jakou jste použili v původním načtení více požadavků. Výsledky vrácené do mezipaměti nebo hodnotu nextLink vlastnosti také ukládejte do mezipaměti, aby vaše aplikace vrátila dříve načtené stránky.
Pokud například chcete získat další stránku záznamů, předejte část nextLink dotazu adresy URL parametru 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
}
);
Tento požadavek vrátí další stránku sady výsledků.
{@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
Důležité
Hodnota nextLink vlastnosti je kódována identifikátorem URI. Pokud před odesláním zakódujete hodnotu identifikátorem URI, informace o souborech cookie XML v adrese URL způsobí chybu.
Příklad FetchXML (online scénář)
Následující příklad ukazuje, jak pomocí parametru count v FetchXML určit, že každá stránka zobrazuje tři záznamy.
Poznámka:
Stránkovací soubor cookie FetchXML se vrátí pouze pro online retrieveMultipleRecords operace. (Xrm.WebApi.online). Nepodporuje se offline.
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
}
);
Tento příklad zobrazí tři záznamy a vrátí stránkovací soubor cookie FetchXML, který načte výsledky další stránky, pokud je ve sadě výsledků více záznamů. Tady je příklad výstupu z konzoly v vývojářských nástrojích prohlížeče:
{
"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\" />"
}
Pokud chcete načíst velké sady výsledků se stránkováním, použijte to fetchXmlPagingCookie , jak je znázorněno v následujícím příkladu.
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
}
);
Načtení souvisejících tabulek rozšířením navigačních vlastností
Pomocí možnosti systémového dotazu $expand ve vlastnostech navigace můžete řídit data, která se vrací ze souvisejících tabulek. Následující příklad ukazuje, jak načíst kontakt pro všechny záznamy účtu. Pro související záznamy kontaktů načtete contactid pouze pole a fullname pole:
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
}
);
Předchozí kód vrátí výsledek se schématem, jako je:
{
"entities": [
{
"@odata.etag": "W/\"1459919\"",
"name": "Test Account",
"accountid": "119edfac-19c6-ea11-a81a-000d3af5e732",
"primarycontactid": {
"contactid": "6c63a1b7-19c6-ea11-a81a-000d3af5e732",
"fullname": "Test Contact"
}
}
]
}
Poznámka:
Podobně jako v online scénáři použijte možnost systémového dotazu $expand k načtení dat ze souvisejících tabulek v offline režimu. Relace M:N se ale v offline režimu nepodporují.
Zastaralá metoda pro scénář offline pro mobilní zařízení
Poznámka:
Tento @odata.nextLink stav je zastaralý pro scénáře offline mobilních zařízení. I když je stále podporovaná pro stávající vlastní nastavení, už ho nepoužívejte.
Operace offline $expand vrátí poznámku @odata.nextLink obsahující informace o tom, jak se dostat k informacím souvisejícího záznamu. Pomocí parametru id, entityTypea options parametrů této poznámky vytvořte jeden nebo více dalších Xrm.WebApi.offline.retrieveRecord požadavků. Následující kód poskytuje úplný příklad toho, jak to udělat:
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
});
Další příklady načítání více záznamů pomocí webového rozhraní API najdete v tématu Dotazování dat pomocí webového rozhraní API.
Související články
Dotazování na data pomocí webového rozhraní API
Xrm.WebApi.retrieveRecord
Xrm.WebApi