retrieveMultipleRecords (referencia de la API de cliente)
Recupera una colección de registros de tabla.
Sintaxis
Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback);
Parámetros
| Name | Type | Obligatorio | Description |
|---|---|---|---|
entityLogicalName |
String | Sí | El nombre lógico de la tabla de los registros que desea recuperar. Por ejemplo: account. |
options |
String | No | Opciones de consulta del sistema OData o consulta FetchXML para recuperar los datos. Ver Opciones |
maxPageSize |
Number | No | Especifique un número positivo que indique el número de registros de tabla que se volverán por página. Si no especifica este parámetro, el valor predeterminado es el límite máximo de 5000 registros. Si el número de registros recuperados es superior al valor maxPageSize especificado o 5000 registros, la columna nextLink en el objeto de promesa devuelto contendrá un vínculo para recuperar registros. |
successCallback |
Function | No | Una función para llamar cuando se recuperan registros de tabla. Ver Valor de retorno |
errorCallback |
Function | No | Una función a la que se llama cuando la operación tiene error. |
Opciones
Se admiten las siguientes opciones de consulta del sistema: $select, $top, $filter, $expand y $orderby.
Use la opción de consulta del sistema $expand para controlar qué datos de tablas relacionadas se devuelven. Si incluye solo el nombre de la propiedad de navegación, recibirá todas las propiedades de registros relacionados. Puede limitar las propiedades devueltas para registros relacionados con la opción de la consulta del sistema $select entre paréntesis después del nombre de propiedad de navegación. Use esta opción para las propiedades de navegación de un solo valor y valoradas como colección. Tenga en cuenta que para fuera de línea solo admitimos la opción $select anidada dentro de $expand.
Para especificar una consulta FetchXML, use la columna fetchXml para especificar la consulta.
Nota
Siempre debe utilizar la opción de consulta del sistema $selectpara limitar las propiedades que se devuelven para un registro de tabla, incluida una lista separada por comas de nombres de propiedades. Esta es una práctica recomendada importante de rendimiento. Si las propiedades no se especifican utilizando $select, todas las propiedades se devolverán.
Especifique las opciones de consulta comenzando con ?. También puede especificar varias opciones de consulta del sistema usando & para separar las opciones de consulta.
Cuando especifica una cadena de consulta de OData para el parámetro options, la consulta debe estar codificada para caracteres especiales.
Cuando especifica una consulta FetchXML para el parámetro options, la consulta no debe estar codificada.
Vea los ejemplos más adelante en este tema para saber cómo puede definir el parámetro options para distintos escenarios de recuperación.
Valor devuelto
Si tiene éxito, devuelve un objeto de promesa al successCallback con las siguientes propiedades:
| Name | Type | Description |
|---|---|---|
entities |
Matriz de objetos JSON | Cada objeto representa el registro de tabla recuperado que contiene las columnas y sus valores como pares key: value. De forma predeterminada se recupera el ID del registro de tabla |
nextLink |
String | (opcional) Si el número de registros que se están recuperando es mayor que el valor especificado en el parámetro maxPageSize en la solicitud, este atributo devuelve la dirección URL para devolver la siguiente página de registros. |
fetchXmlPagingCookie |
(opcional) Para una operación retrieveMultipleRecords basada en fetchXml con paginación donde el recuento total de registros es mayor que el valor de paginación, este atributo devuelve la cookie de paginación que se puede usar para una operación fetchXml posterior para recuperar la siguiente página de registros. |
Tipos de atributos no admitidos para las opciones de consulta de OData en Mobile Offline
Los siguientes Tipos de columnas no se admiten cuando se realiza una operación Xrm.WebApi.retrieveMultipleRecords con opciones de cadena de consulta de OData (por ejemplo, $select y $filter) en modo móvil sin conexión. Debe usar FetchXML si el tipo de atributo con el que necesita trabajar no está en esta lista de tipos de atributos no admitidos.
MultiSelectPicklistFileImageManagedPropertyCalendarRulesPartyListVirtual
Funciones no admitidas en Mobile Offline
Las siguientes características no son compatibles en Mobile Offline:
- Características de agrupación y agregación
Operaciones de filtro admitidas por tipo de atributo en Mobile Offline usando FetchXML
Las siguientes operaciones son compatibles con todos los tipos de atributos cuando se trabaja con FetchXML:
- Es igual (
eq) - No es igual a (
neq) - Nulo (
null) - No es nulo (
not-null)
La siguiente tabla enumera las operaciones adicionales admitidas por cada tipo de atributo:
| Tipo de atributo | Operaciones admitidas |
|---|---|
| BigInt, Decimal, Doble, Entero | Mayor que (gt)Mayor o igual que ( gte)Menor que ( lt)Menor o igual que ( lte) |
| Booleano, Cliente | En (in)No está en ( not-in) |
| EntityName, Lista desplegable, Estado | Como (like)No como ( not-like)Empieza por ( begins-with)No comienza por ( not-begin-with)Termina por ( ends-with)No termina por ( not-end-with)En ( in)No está en ( not-in) |
| Guid, búsqueda | En (in)No está en ( not-in)Es igual al ID de usuario ( eq-userid)No es igual al ID de usuario ( ne-userid) |
| Money | Mayor que (gt)Mayor o igual que ( gte)Menor que ( lt)Menor o igual que ( lte)En ( in)No está en ( not-in) |
| Owner | En (in)No está en ( not-in)Es igual al ID de usuario ( eq-userid)No es igual al ID de usuario ( ne-userid)Es igual a usuario O equipo ( eq-useroruserteams) |
| String | Como (like)No como ( not-like)Empieza por ( begins-with)No comienza por ( not-begin-with)Termina por ( ends-with)No termina por ( not-end-with) |
| Fecha y hora | En o después del (on-or-after)En ( on)En o antes del ( on-or-before)Hoy ( today)Mañana ( tomorrow)Ayer ( yesterday)Próximos siete días ( next-seven-days)Últimos siete días ( last-seven-days)Próxima semana ( next-week)Semana pasada ( last-week)Esta semana ( this-week)Mes siguiente ( next-month)Mes pasado ( last-month)Este mes ( this-month)Año siguiente ( next-year)El año pasado ( last-year)Este año ( this-year)Últimos X días ( last-x-days)Próximos X días ( next-x-days)Últimas X semanas ( last-x-weeks)Próximas X semanas ( next-x-weeks)Últimos X meses ( last-x-months)Próximos X meses ( next-x-months)Últimos X años ( last-x-years)Próximos X años ( next-x-years)Mayor que ( gt)Mayor o igual que ( gte)Menor que ( lt)Menor o igual que ( lte) |
Ejemplos
La mayoría de los escenarios o ejemplos que se mencionan en Consultar datos utilizando la API web pueden lograrse con el método retrieveMultipleRecords. Algunos de los ejemplos se listan a continuación.
Recuperación básica de varios
Este ejemplo consulta el conjunto de tablas de cuenta y usa las opciones de consulta del sistema $select y $top para devolver la propiedad de nombre para las tres primeras cuentas:
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ón básica de varios con FetchXML
Este ejemplo consulta la entidad account mediante fetchXML.
var fetchXml = "?fetchXml=<fetch mapping='logical'><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 por propiedades de búsqueda
Para la mayoría de las propiedades de navegación de un solo valor encontrará una propiedad calculada de sólo lectura que use la convención de nomenclatura siguiente: _<name>_value donde <name> es el nombre de la propiedad de navegación de un solo valor. Para fines de filtrado, también se puede utilizar el valor específico de la propiedad de navegación de valor único. Sin embargo, para los clientes para dispositivos móviles en modo sin conexión, estas opciones de sintaxis no son compatibles y el nombre de la propiedad de navegación de valor único debe usarse tanto para la recuperación como para el filtrado. Además, la comparación de propiedades de navegación con nulos no se admite en el modo sin conexión.
Más información: Propiedades de búsqueda
Presentamos ejemplos de código para ambos escenarios:
Para escenario en línea (conectado al servidor)
Este ejemplo consulta el conjunto de tablas de cuenta y usa las opciones de consulta del sistema $select y $filter para devolver la propiedad primarycontactid para cuentas que tienen un contacto principal específico:
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
}
);
Para el escenario sin conexión móvil
Este ejemplo consulta el conjunto de tablas de cuenta y usa las opciones de consulta del sistema $select y $filter para devolver la propiedad primarycontactid para cuentas que tienen un contacto principal específico cuando se trabaja en modo desconectado:
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
}
);
Uso de FetchXML para recuperar o filtrar por propiedades de búsqueda (escenario en línea y sin conexión)
Puede usar el parámetro FetchXML mientras está en línea o sin conexión para recuperar la propiedad name y primarycontactid para los registros de cuenta que tienen un contacto principal que coincide con una condición:
var fetchXml = `?fetchXml=
<fetch mapping='logical'>
<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
}
);
Especificar el número de tablas para devolver a una página
En el ejemplo siguiente se muestra el uso del parámetro maxPageSize para especificar el número de registros (3) que mostrar 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
}
);
Este ejemplo mostrará tres registros y un vínculo a la página siguiente. Este es un ejemplo de salida de la consola en las herramientas de desarrollo del explorador:
{@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
Utilice la parte de la consulta en la dirección URL en la propiedad nextLink como el valor del parámetro options en la llamada subsiguiente retrieveMultipleRecords para solicitar el siguiente conjunto de registros. No cambie ni anexar más opciones de consulta del sistema al valor. Para cada solicitud posterior de más páginas, debe usar el mismo valor de preferencia de maxPageSize que usó en la solicitud original de recuperación de varios. Además, almacene en caché los resultados devueltos o el valor de la propiedad nextLink para que se pueda volver a páginas anteriormente recuperadas.
Por ejemplo, para obtener la siguiente página de registros, pasaremos en la consulta parte de la dirección URL nextLink al parámetro 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
}
);
Esto devolverá la siguiente página del conjunto de resultados:
{@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
Importante
El valor de la propiedad nextLink está codificado con URI. Si codifica con URI el valor antes de enviarlo, la información de cookie XML en la URL generará un error.
Ejemplo de FetchXML (escenario en línea)
El siguiente ejemplo demuestra el uso del parámetro count de FetchXML para especificar el número de registros (3) que se mostrarán en una página.
Nota
La cookie de paginación FetchXML solo se devuelve para operaciones en línea retrieveMultipleRecords. (Xrm.WebApi.online). No se admite sin conexión.
var fetchXml = "?fetchXml=<fetch mapping='logical' 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
}
);
Este ejemplo mostrará tres registros y devolverá una cookie de paginación FetchXML para recuperar los resultados de la página siguiente si hay más registros que pertenecen al conjunto de resultados. Este es un ejemplo de salida de la consola en las herramientas de desarrollo del explorador:
{
"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\" />"
}
Podemos usar fetchXmlPagingCookie como se muestra en el ejemplo siguiente para obtener conjuntos de resultados grandes con paginación.
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 mapping="logical"><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 tablas relacionadas ampliando las propiedades de navegación
Use la opción de consulta del sistema $expand en las propiedades de navegación para controlar los datos de tablas relacionadas que se devuelven. El ejemplo siguiente muestra cómo recuperar el contacto para todos los registros de la cuenta. Para los registros de contacto relacionados, solo recuperamos contactid y 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 fragmento de código anterior devuelve un resultado con un esquema como:
{
"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
Similar al escenario en línea, use la opción $expand de consulta del sistema para recuperar datos de tablas relacionadas sin conexión. Sin embargo, no se admiten las relaciones varios a varios sin conexión.
Método en desuso para escenario sin conexión móvil
Nota
@odata.nextLink es obsoleto para escenarios móviles sin conexión. Si bien todavía es compatible con las personalizaciones existentes, ya no se recomienda usarlo.
Una operación $expand sin conexión devuelve una anotación @odata.nextLink que contiene información sobre cómo llegar a la información del registro relacionado. Usamos los parámetros id, entityType y options de esa anotación para construir una o más peticiones Xrm.WebApi.offline.retrieveRecord adicionales. El siguiente fragmento de código proporciona un ejemplo completo de cómo hacer esto:
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
});
Para ver más ejemplos de recuperar varios registros mediante la API de web, consulte Consultar datos utilizando la API web.
Artículos relacionados
Consultar datos utilizando la API web
Xrm.WebApi.retrieveRecord
Xrm.WebApi
Nota
¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)
La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de