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 FetchXML consulta para recuperar sus 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 FetchXML consulta, utilice 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 se especifica una consulta FetchXML para el parámetro options , la consulta no debe codificarse.

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 utilizar FetchXML si el tipo de atributo con el que necesita trabajar está en esta lista de tipos de atributos no admitidos.

• MultiSelectPicklist
• File
• Image
• ManagedProperty
• CalendarRules
• PartyList
• Virtual

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 dispositivos móviles sin conexión 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/ejemplos mencionados en Consultar datos usando la API web se pueden lograr utilizando 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 múltiple 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 fuera de línea)

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.

FetchXML Ejemplo (escenario en línea)

El siguiente ejemplo demuestra el uso del parámetro count de FetchXML para especificar la cantidad de registros (3) que se mostrarán en una página.

Nota

La cookie de paginación solo se devuelve para operaciones en línea. FetchXML 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 para recuperar los resultados de la siguiente página si hay más registros que pertenecen al conjunto de resultados. FetchXML 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 obtener más ejemplos de recuperación de múltiples registros mediante la API web, consulte Consultar datos mediante la API web.

Artículos relacionados

Consultar datos mediante 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).