Nota
L'accés a aquesta pàgina requereix autorització. Pots provar d'iniciar sessió o canviar de directori.
L'accés a aquesta pàgina requereix autorització. Pots provar de canviar directoris.
Recupera una col·lecció de registres de taula.
Sintaxi
Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback);
Paràmetres
| Nom | Tipus | Necessari | Descripció |
|---|---|---|---|
entityLogicalName |
String | Sí | Nom lògic de la taula dels registres que voleu recuperar. Per exemple: account. |
options |
String | No | Opcions de consulta del sistema OData o consulta FetchXML per recuperar les dades. Veure opcions |
maxPageSize |
Nombre | No | Especifiqueu un nombre positiu que indiqui el nombre de registres de taula que s'han de retornar per pàgina. Si no especifiqueu aquest paràmetre, el valor per defecte és el límit màxim de 5.000 registres per a taules estàndard i 500 per a taules elàstiques. Si el nombre de registres que s'estan recuperant és superior al valor especificat maxPageSize o al límit màxim per al tipus de taula, la nextLink columna de l'objecte de promesa retornat contindrà un enllaç per recuperar registres. |
successCallback |
Function | No | Funció per cridar quan es recuperen registres de taula. Vegeu el valor retornat |
errorCallback |
Function | No | Una funció per cridar quan l'operació falla. Es passa un objecte amb les propietats següents: - errorCode:Número. El codi d'error com a nombre decimal positiu. Per exemple, el codi d'error documentat com es 0x80040333 retornarà com 2147746611a .- message:Corda. Un missatge d'error que descriu el problema. |
Opcions
S'admeten les opcions de consulta del sistema següents: $select, $top, $filter, $expandi $orderby.
Utilitzeu l'opció de $expand consulta del sistema per controlar quines dades de les taules relacionades es retornen. Si només incloeu el nom de la propietat de navegació, rebreu totes les propietats dels registres relacionats. Podeu limitar les propietats retornades per als registres relacionats mitjançant l'opció $select de consulta del sistema entre parèntesis després del nom de la propietat de navegació. Utilitzeu-ho per a les propietats de navegació d'un sol valor i de valor de col·lecció . Tingueu en compte que per a fora de línia només admetem l'opció imbricada $select dins del $expand.
Per especificar una consulta FetchXML, utilitzeu la fetchXml columna per especificar la consulta.
Nota
Sempre heu d'utilitzar l'opció de $selectconsulta del sistema per limitar les propietats retornades per a un registre de taula incloent una llista separada per comes de noms de propietats. Aquesta és una bona pràctica de rendiment important. Si les propietats no s'especifiquen mitjançant $selectel , es retornaran totes les propietats.
Especifiqueu les opcions de consulta que comencen per ?. També podeu especificar diverses opcions de consulta del sistema utilitzant & per separar les opcions de consulta.
Quan especifiqueu una cadena de consulta OData per al options paràmetre, la consulta s'ha de codificar per a caràcters especials.
Quan especifiqueu una consulta FetchXML per al options paràmetre, la consulta no s'ha de codificar.
Vegeu Exemples per veure com podeu definir el options paràmetre per a diversos escenaris de recuperació múltiple.
Valor de retorn
En cas d'èxit, retorna un objecte de promesa a la successCallback amb les propietats següents:
| Nom | Tipus | Descripció |
|---|---|---|
entities |
Matriu d'objectes JSON | Cada objecte representa el registre de taula recuperat que conté columnes i els seus valors com key: value a parells. L'identificador del registre de taula es recupera per defecte |
nextLink |
String | (opcional) Si el nombre de registres que s'estan recuperant és superior al valor especificat al maxPageSize paràmetre de la sol·licitud, es retorna l'adreça URL per retornar la pàgina següent de registres. |
fetchXmlPagingCookie |
(opcional) Per a una operació basada en retrieveMultipleRecords fetchXML amb paginació on el recompte total de registres és més gran que el valor de paginació, aquest atribut retorna la galeta de paginació que es pot utilitzar per a una operació fetchXml posterior per recuperar la pàgina següent de registres. |
Tipus d'atributs no admesos per a les opcions de consulta OData al Mobile Offline
Els tipus de columna següents no s'admeten quan es fa una Xrm.WebApi.retrieveMultipleRecords operació amb opcions de cadena de consulta OData (per exemple, $select i $filter) en mode Mobile Offline. Hauríeu d'utilitzar FetchXML si el tipus d'atribut amb el qual heu de treballar es troba en aquesta llista de tipus d'atributs no admesos.
MultiSelectPicklistFileImageManagedPropertyCalendarRulesPartyListVirtual
Funcions no admeses a Mobile Offline
Les funcions següents no són compatibles amb Mobile Offline:
- Característiques d'agrupació i agregació
Operacions de filtre admeses per tipus d'atribut al Mobile Offline mitjançant FetchXML
Les operacions següents són compatibles per a tots els tipus d'atributs quan es treballa amb FetchXML:
- Igual a (
eq) - No és igual (
neq) - Nul (
null) - No nul (
not-null)
A la taula següent es mostren més operacions admeses per a cada tipus d'atribut:
| Tipus d'atribut | Operacions admeses |
|---|---|
| BigInt, decimal, doble, enter | Major que (gt)Major o igual a ( gte)Menor que ( lt)Menor o igual a ( lte) |
| Booleà, Client | A (in)No a ( not-in) |
| EntityName, Llista de selecció, Estat, Estat | M'agrada (like)No com ( not-like)Comença per ( begins-with)No comença per ( not-begin-with)Acaba amb ( ends-with)No acaba amb ( not-end-with)A ( in)No a ( not-in) |
| Guid, Cerca | A (in)No a ( not-in)És igual a ID d'usuari ( eq-userid)No és igual a ID d'usuari ( ne-userid) |
| Money | Major que (gt)Major o igual a ( gte)Menor que ( lt)Menor o igual a ( lte)A ( in)No a ( not-in) |
| Propietari | A (in)No a ( not-in)És igual a ID d'usuari ( eq-userid)No és igual a ID d'usuari ( ne-userid)És igual a usuari o equip ( eq-useroruserteams) |
| String | M'agrada (like)No com ( not-like)Comença per ( begins-with)No comença per ( not-begin-with)Acaba amb ( ends-with)No acaba amb ( not-end-with) |
| DataHora | El O Després (on-or-after)Activat ( on)El o abans ( on-or-before)Avui ( today)Demà ( tomorrow)Ahir ( yesterday)Propers set dies ( next-seven-days)Darrers set dies ( last-seven-days)La setmana vinent ( next-week)La setmana passada ( last-week)Aquesta setmana ( this-week)El mes següent ( next-month)Darrer mes ( last-month)Aquest mes ( this-month)L'any vinent ( next-year)L'any passat ( last-year)Aquest any ( this-year)Darrers X dies ( last-x-days)Propers X dies ( next-x-days)Últimes X setmanes ( last-x-weeks)Properes X setmanes ( next-x-weeks)Darrers X mesos ( last-x-months)Propers X mesos ( next-x-months)Darrers X anys ( last-x-years)Propers X anys ( next-x-years)Major que ( gt)Major o igual ( gte)Menor que ( lt)Menor o igual ( lte) |
Exemples
La majoria dels escenaris/exemples esmentats a Consulta de dades mitjançant l'API web es poden aconseguir mitjançant el mètode retrieveMultipleRecords . Alguns dels exemples s'enumeren a continuació.
Recuperació bàsica de múltiples
En aquest exemple es consulta el conjunt de taules de comptes i s'utilitzen les $select opcions de consulta i $top del sistema per retornar la propietat name dels tres primers comptes:
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
}
);
Recuperació bàsica de múltiples amb FetchXML
Aquest exemple consulta l'entitat account mitjançant 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
}
);
Recuperar o filtrar per propietats de cerca
Per a la majoria de propietats de navegació d'un sol valor, trobareu una propietat calculada de només lectura que utilitza la convenció de nomenclatura següent: _<name>_value on the <name> és el nom de la propietat de navegació d'un sol valor. Per filtrar, també es pot utilitzar el valor específic de la propietat de navegació d'un sol valor. Tanmateix, per als clients mòbils en mode fora de línia, aquestes opcions de sintaxi no s'admeten i el nom de la propietat de navegació d'un sol valor s'ha d'utilitzar tant per recuperar com per filtrar. A més, la comparació de propietats de navegació amb nul·la no s'admet en mode fora de línia.
Més informació: Propietats de cerca
A continuació es mostren exemples de codi per a tots dos escenaris:
Per a l'escenari en línia (connectat al servidor)
En aquest exemple es consulta el conjunt de taules comptes i s'utilitzen les opcions de consulta i $filter del $select sistema per retornar el nom i la propietat primarycontactid per als comptes que tenen un contacte principal concret:
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
}
);
Per a l'escenari Mobile Offline
En aquest exemple es consulta el conjunt de taules accounts i s'utilitzen les $select opcions de consulta i $filter system per retornar el nom i la propietat primarycontactid per als comptes que tenen un contacte principal concret quan es treballa en mode fora de línia:
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
}
);
Ús de FetchXML per recuperar o filtrar per propietats de cerca (escenari en línia i fora de línia)
Podeu utilitzar el FetchXML paràmetre en línia o fora de línia per recuperar la name propietat and primarycontactid dels registres de compte que tenen un contacte principal que coincideixi amb una condició:
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
}
);
Especifiqueu el nombre de taules que s'han de retornar en una pàgina
L'exemple següent demostra l'ús del maxPageSize paràmetre per especificar el nombre de registres (3) que es mostraran en una pàgina.
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
}
);
En aquest exemple es mostraran tres registres i un enllaç a la pàgina següent. Aquí teniu un exemple de sortida de la consola a les eines de desenvolupament del navegador:
{@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
Utilitzeu la part de consulta de l'adreça URL de la nextLink propietat com a valor del paràmetre de la options crida retrieveMultipleRecords posterior per sol·licitar el següent conjunt de registres. No canvieu ni afegiu més opcions de consulta del sistema al valor. Per a cada sol·licitud posterior de més pàgines, hauríeu d'utilitzar el mateix maxPageSize valor utilitzat a la sol·licitud original de recuperació múltiple. A més, emmagatzemeu a la memòria cau els resultats retornats o el valor de la propietat nextLink perquè es puguin retornar les pàgines recuperades anteriorment.
Per exemple, per obtenir la pàgina següent de registres, passarem la part de consulta de l'URL nextLink al options paràmetre:
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
}
);
Això retornarà la pàgina següent del conjunt de resultats:
{@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
Important
El valor de la nextLink propietat està codificat per URI. Si codifiqueu l'URI del valor abans d'enviar-lo, la informació de la galeta XML de l'URL provocarà un error.
Exemple de FetchXML (escenari en línia)
L'exemple següent demostra l'ús del count paràmetre de FetchXML per especificar el nombre de registres (3) que es mostraran en una pàgina.
Nota
La galeta de paginació FetchXML només es retorna per a operacions en línia retrieveMultipleRecords . (Xrm.WebApi.online). No s'admet fora de línia.
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
}
);
En aquest exemple es mostraran tres registres i es retornarà una galeta de paginació FetchXML per recuperar els resultats de la pàgina següent si hi ha més registres que pertanyen al conjunt de resultats. Aquí teniu un exemple de sortida de la consola a les eines de desenvolupament del navegador:
{
"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\" />"
}
Podem utilitzar el fetchXmlPagingCookie com es mostra a l'exemple següent per obtenir grans conjunts de resultats amb paginació.
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
}
);
Recuperar taules relacionades expandint les propietats de navegació
Utilitzeu l'opció $expand consulta del sistema a les propietats de navegació per controlar les dades que es retornen de les taules relacionades. A l'exemple següent es mostra com recuperar el contacte de tots els registres del compte. Per als registres de contacte relacionats, només recuperem el contactid i 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
}
);
El tros de codi anterior retorna un resultat amb un esquema com:
{
"entities": [
{
"@odata.etag": "W/\"1459919\"",
"name": "Test Account",
"accountid": "119edfac-19c6-ea11-a81a-000d3af5e732",
"primarycontactid": {
"contactid": "6c63a1b7-19c6-ea11-a81a-000d3af5e732",
"fullname": "Test Contact"
}
}
]
}
Nota
De manera similar a l'escenari en línia, utilitzeu l'opció de consulta del sistema $expand per recuperar dades de taules relacionades fora de línia. Tanmateix, les relacions de diversos a diversos no s'admeten fora de línia.
Mètode obsolet per a l'escenari Mobile Offline
Nota
El @odata.nextLink està obsolet per a escenaris Mobile Offline. Tot i que encara és compatible amb personalitzacions existents, no es recomana utilitzar-lo més.
Una operació de $expand fora de línia retorna una @odata.nextLink anotació que conté informació sobre com accedir a la informació del registre relacionat. Utilitzem el idparàmetre , entityType, and options d'aquesta anotació per construir una o més sol·licituds addicionals Xrm.WebApi.offline.retrieveRecord . El següent tros de codi proporciona un exemple complet de com fer-ho:
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
});
Per obtenir més exemples de recuperació de diversos registres mitjançant l'API web, vegeu Consulta de dades mitjançant l'API web.
Articles relacionats
Consulta de dades mitjançant l'API web
Xrm.WebApi.retrieveRecord
Xrm.WebApi