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

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.

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:

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.

• 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 Mobile Offline usando FetchXML 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:

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 múltiple con FetchXML

Este ejemplo consulta la entidad account mediante 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 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
    }
);

Usando 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>
       <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

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.

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
    }
);

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><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"
         }
      }
   ]
}

Método en desuso para escenario sin conexión móvil

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