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 los registros relacionados mediante la opción de consulta del $select sistema entre paréntesis después del nombre de la propiedad de navegación. Use esta opción para las propiedades de navegación con valores únicos y con valores de colección . Para sin conexión, solo se admite la opción anidada $select dentro de $expand .

Para especificar una consulta FetchXML, use la columna fetchXml para especificar la consulta.

Especifique las opciones de consulta a partir de ?. También puede especificar varias opciones de consulta del sistema usando & para separar las opciones de consulta.

Al especificar una cadena de consulta de OData para el options parámetro , codifique la consulta para caracteres especiales.

Al especificar una consulta FetchXML para el options parámetro , no codifique la consulta.

Para obtener información sobre cómo definir el options parámetro para varios escenarios, consulte Ejemplos.

Valor de retorno

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 dispositivos móviles sin conexión

Los siguientes tipos de columna no se admiten cuando se usan Xrm.WebApi.retrieveMultipleRecords con opciones de cadena de consulta OData (como $select y $filter) en modo sin conexión móvil. Use FetchXML si necesita trabajar con un tipo de atributo en esta lista de tipos de atributos no admitidos.

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

Características no admitidas en dispositivos móviles sin conexión

Las siguientes características no se admiten en dispositivos móviles sin conexión:

• Características de agrupación y agregación

Operaciones de filtro admitidas por tipo de atributo en dispositivos móviles sin conexión mediante 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

Puede usar el método retrieveMultipleRecords para lograr la mayoría de los escenarios y ejemplos mencionados en Datos de consulta mediante la API web. Algunos de los ejemplos se enumeran en la sección siguiente.

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 con valores únicos, se encuentra una propiedad calculada de solo lectura que usa la siguiente convención de nomenclatura: _<name>_value donde <name> es el nombre de la propiedad de navegación con un solo valor. Con fines de filtrado, también puede usar el valor específico de la propiedad de navegación de un solo valor. Sin embargo, estas opciones de sintaxis no se admiten para los clientes móviles en modo sin conexión. Use el nombre de la propiedad de navegación de un solo valor para recuperar y filtrar. Además, el modo sin conexión no admite la comparación de las propiedades de navegación con null.

Más información: Propiedades de búsqueda

Estos son 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

En este ejemplo se consulta el conjunto de tablas de cuentas y se usan las opciones de consulta del $select sistema y $filter para devolver el nombre y la propiedad primarycontactid para las cuentas que tienen un contacto principal determinado al trabajar en modo sin conexión:

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)

Use el FetchXML parámetro mientras está en línea o sin conexión para recuperar la name propiedad 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 cómo usar el maxPageSize parámetro para especificar que cada página muestra tres registros.

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 este ejemplo se muestran 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

Use el elemento de consulta en la dirección URL de la nextLink propiedad como valor para el parámetro en la options siguiente llamada retrieveMultipleRecords para solicitar el siguiente conjunto de registros. No cambie ni agregue más opciones de consulta del sistema al valor. Para cada solicitud posterior de más páginas, use el mismo maxPageSize valor que usó en la solicitud original para recuperar varias solicitudes. Además, almacene en caché los resultados devueltos o el valor de la nextLink propiedad para que la aplicación pueda devolver páginas recuperadas previamente.

Por ejemplo, para obtener la siguiente página de registros, pase la parte de consulta de la nextLink dirección URL al options parámetro :

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

Esta solicitud devuelve la página siguiente 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)

En el ejemplo siguiente se muestra cómo usar el count parámetro en FetchXML para especificar que cada página muestra tres registros.

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 este ejemplo se muestran tres registros y se devuelve una cookie de paginación FetchXML para recuperar los resultados de la página siguiente si hay más registros en el 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\" />"
}

Para capturar grandes conjuntos de resultados con paginación, use como fetchXmlPagingCookie se muestra en el ejemplo siguiente.

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 que devuelven de tablas relacionadas. En el ejemplo siguiente se muestra cómo recuperar el contacto para todos los registros de la cuenta. Para los registros de contacto relacionados, solo se recuperan los contactid campos 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 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. Use los idparámetros , entityTypey options de esa anotación para construir una o varias solicitudes adicionales Xrm.WebApi.offline.retrieveRecord . El código siguiente proporciona un ejemplo completo de cómo hacerlo:

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 varios registros mediante la API web, consulte Consulta de datos mediante la API web.

Artículos relacionados

Consultar datos utilizando la API web
Xrm.WebApi.retrieveRecord
Xrm.WebApi