retrieveMultipleRecords (Referencia da API do cliente)

Recupera unha colección de rexistros de táboas.

Sintaxe

Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback);

Parámetros

Nome	Tipo	Obrigatorio	Descrición
entityLogicalName	String	Si	Nome lóxico da táboa dos rexistros que desexa recuperar. Por exemplo: account.
options	String	Non	Opcións de consulta do sistema OData ou consulta FetchXML para recuperar os datos. Ver opcións
maxPageSize	Número	Non	Especifique un número positivo que indique o número de rexistros da táboa que se devolverán por páxina. Se non especifica este parámetro, o valor está predeterminado no límite máximo de 5.000 rexistros para táboas estándar, 500 para táboas elásticas. Se o número de rexistros que se están a recuperar é maior que o valor especificado maxPageSize ou o límite máximo para o tipo de táboa, a nextLink columna do obxecto de promesa devolto conterá unha ligazón para recuperar rexistros.
successCallback	Function	Non	Función para chamar cando se recuperan os rexistros da táboa. Ver valor de devolución
errorCallback	Function	Non	Unha función a chamar cando a operación falla. Pasa un obxecto coas seguintes propiedades: - errorCode: Número. O código de erro é un número decimal positivo. Por exemplo, o código de erro documentado como 0x80040333 será devolto como 2147746611. - message: String. Mensaxe de erro que describe o problema.

Opcións

Soportan as seguintes opcións de consulta do sistema: $select, $top, $filter, $expande $orderby.

Use a opción de consulta do $expand sistema para controlar os datos das táboas relacionadas que se devolven. Se só inclúe o nome da propiedade de navegación, recibirá todas as propiedades dos rexistros relacionados. Pode limitar as propiedades devoltas para os rexistros relacionados usando a opción de $select consulta do sistema entre parénteses despois do nome da propiedade de navegación. Use isto tanto para propiedades de navegación dun só valor como para valores de colección . Teña en conta que para fóra de liña só soportamos a opción aniñada $select dentro do $expand.

Para especificar unha consulta FetchXML, use a fetchXml columna para especificar a consulta.

Nota

Debe usar sempre a opción de $selectconsulta do sistema para limitar as propiedades devoltas para un rexistro de táboa incluíndo unha lista separada por comas de nomes de propiedades. Esta é unha importante boa práctica de rendemento. Se as propiedades non se especifican usando $select, devolveranse todas as propiedades.

Especifica as opcións de consulta que comezan por ?. Tamén pode especificar varias opcións de consulta do sistema usando & para separar as opcións de consulta.

Cando se especifica unha cadea de consulta OData para o options parámetro, a consulta debe ser codificada para caracteres especiais.

Cando se especifica unha consulta FetchXML para o options parámetro, a consulta non debe ser codificada.

Vexa Exemplos para ver como se pode definir o options parámetro para varios escenarios de recuperación múltiple.

Devolver valor

En caso de éxito, devolve un obxecto de promesa coas successCallback seguintes propiedades:

Nome	Tipo	Descrición
entities	Array de obxectos JSON	Cada obxecto representa o rexistro da táboa recuperado que contén columnas e os seus valores como key: value pares. O ID do rexistro da táboa obtécese por defecto
nextLink	String	(opcional) Se o número de rexistros que se están a recuperar é maior que o valor especificado no maxPageSize parámetro da solicitude, isto devolve o URL para devolver a seguinte páxina de rexistros.
fetchXmlPagingCookie		(opcional) Para unha operación baseada en retrieveMultipleRecords fetchXML con paginación onde o número total de rexistros é maior que o valor de paginación, este atributo devolve a cookie de paginación que se pode usar para unha operación de fetchXml posterior para recuperar a seguinte páxina de rexistros.

Tipos de atributos non admitidos para as opcións de consulta OData en Mobile Offline

Os seguintes tipos de columna non están soportados cando se realiza unha Xrm.WebApi.retrieveMultipleRecords operación coas opcións de cadea de consulta OData (por exemplo, $select e $filter) no modo móbil sen conexión. Debería usar FetchXML se o tipo de atributo co que necesita traballar está nesta lista de tipos de atributos non admitidos.

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

Funcións non soportadas en Mobile Offline

As seguintes funcións non están soportadas en Mobile Offline:

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

Operacións de filtro soportadas por tipo de atributo en Mobile Offline usando FetchXML

Soportan as seguintes operacións para todos os tipos de atributos cando se traballa con FetchXML:

• Igual (eq)
• Non iguais (neq)
• Nulo (null)
• Non nulo (not-null)

Na seguinte táboa aparecen máis operacións soportadas para cada tipo de atributo:

Tipo de atributo	Operacións soportadas
BigInt, decimal, dobre, enteiro	Maior que (gt) Maior ou igual (gte) Menor que (lt) Menor ou igual (lte)
Booleano, Cliente	En (in) Non en (not-in)
EntityName, Picklist, State, Status	Gústame (like) Non como (not-like) Comeza por (begins-with) Non comeza con (not-begin-with) Remata con (ends-with) Non remata con (not-end-with) En (in) Non en (not-in)
Guid, Buscar	En (in) Non en (not-in) Igual a ID de usuario (eq-userid) Non é igual a ID de usuario (ne-userid)
Money	Maior que (gt) Maior ou igual (gte) Menor que (lt) Menor ou igual (lte) En (in) Non en (not-in)
Propietario	En (in) Non en (not-in) Igual a ID de usuario (eq-userid) Non é igual a ID de usuario (ne-userid) Igual a usuario ou equipo (eq-useroruserteams)
String	Gústame (like) Non como (not-like) Comeza por (begins-with) Non comeza con (not-begin-with) Remata con (ends-with) Non remata con (not-end-with)
Data e hora	Despois ou despois (on-or-after) En (on) Antes ou antes (on-or-before) Hoxe (today) Mañá (tomorrow) Onte (yesterday) Próximos sete días (next-seven-days) Últimos sete días (last-seven-days) A próxima semana (next-week) A semana pasada (last-week) Esta semana (this-week) O próximo mes (next-month) O mes pasado (last-month) Este mes (this-month) O próximo ano (next-year) O ano pasado (last-year) Este ano (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 anos (last-x-years) Próximos X anos (next-x-years) Maior que (gt) Maior ou igual (gte) Menor que (lt) Menor ou igual (lte)

Exemplos

A maioría dos escenarios / exemplos mencionados en Consultar datos usando a API web pódense conseguir usando o método retrieveMultipleRecords . Algúns dos exemplos están listados a continuación.

Recuperación básica de múltiples

Este exemplo consulta o conxunto de táboas de contas e usa as $select opcións de consulta do sistema e para devolver a propiedade $top name para as tres primeiras contas:

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

Este exemplo consulta a entidade account usando 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 ou filtrar por propiedades de busca

Para a maioría das propiedades de navegación de valor único atoparás unha propiedade calculada de só lectura que usa a seguinte convención de nomes: _<name>_value onde the <name> é o nome da propiedade de navegación de valor único. Para fins de filtrado, tamén se pode usar o valor específico da propiedade de navegación de valor único. Non obstante, para clientes móbiles en modo sen conexión, estas opcións de sintaxe non están soportadas e o nome da propiedade de navegación de valor único debe usarse tanto para a recuperación como para o filtrado. Ademais, a comparación de propiedades de navegación con null non está soportada no modo sen conexión.

Máis información: Propiedades de busca

Aquí tes exemplos de código para ambos os escenarios:

Escenario en liña (conectado ao servidor)

Este exemplo consulta o conxunto de táboas de contas e usa as $select opcións de consulta do sistema e $filter para devolver o nome e a propiedade primarycontactid para as contas que teñen un contacto principal particular:

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

Escenario móbil sen conexión

Este exemplo consulta o conxunto de táboas de contas e usa as $select opcións de consulta e $filter do sistema para devolver a propiedade name e primarycontactid para as contas que teñen un contacto principal particular cando traballan en modo sen 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
    }
);

Usar FetchXML para recuperar ou filtrar por propiedades de busca (escenario en liña e sen conexión)

Pode usar o FetchXML parámetro mentres está en liña ou sen conexión para recuperar a name propiedade and primarycontactid para os rexistros da conta que teñan un contacto principal que coincida cunha 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 o número de táboas a devolver nunha páxina

O seguinte exemplo móstrase o uso do maxPageSize parámetro para especificar o número de rexistros (3) que se mostrarán nunha páxina.

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 exemplo amosará tres rexistros e unha ligazón á seguinte páxina. Aquí tes un exemplo de saída da consola nas ferramentas de desenvolvemento do 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

Use a parte de consulta na URL da propiedade nextLink como valor para o options parámetro na posterior chamada retrieveMultipleRecords para solicitar o seguinte conxunto de rexistros. Non modifique nin engada máis opcións de consulta do sistema ao valor. Para cada solicitude posterior de máis páxinas, debería usar o mesmo maxPageSize valor usado na solicitude orixinal de recuperación múltiple. Ademais, almacene en caché os resultados devoltos ou o valor da propiedade nextLink para que se poidan devolver as páxinas recuperadas previamente.

Por exemplo, para obter a seguinte páxina de rexistros, pasaremos a parte de consulta do nextLink URL ao 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
    }
);

Isto devolverá a seguinte páxina do conxunto 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

O valor da nextLink propiedade está codificado por URI. Se codificas o valor antes de envialo, a información da cookie XML no URL causará un erro.

Exemplo de FetchXML (escenario en liña)

O seguinte exemplo mostra o uso do count parámetro de FetchXML para especificar o número de rexistros (3) que se mostrarán nunha páxina.

Nota

A cookie de paginación de FetchXML só se devolve para operacións en liña retrieveMultipleRecords . (Xrm.WebApi.online). Non está soportado sen conexión.

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 exemplo amosará tres rexistros e devolverá unha cookie de paginación FetchXML para recuperar os resultados da seguinte páxina se hai máis rexistros pertencentes ao conxunto de resultados. Aquí tes un exemplo de saída da consola nas ferramentas de desenvolvemento do 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\" />"
}

Podemos usar o fetchXmlPagingCookie como se mostra no exemplo seguinte para obter grandes conxuntos de resultados con paging.

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 táboas relacionadas expandindo as propiedades de navegación

Use a opción de consulta do sistema $expand nas propiedades de navegación para controlar os datos que se devolven das táboas relacionadas. O seguinte exemplo móstrase como recuperar o contacto para todos os rexistros da conta. Para os rexistros de contacto relacionados, só estamos recuperando o contactid e 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
    }
);

O código anterior devolve un resultado cun 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

De xeito similar ao escenario en liña, use a opción de consulta do sistema $expand para recuperar datos de táboas relacionadas sen conexión. Non obstante, as relacións moitos-a-moitos non están soportadas en offline.

Método obsoleto para o escenario de conexión móbil

Nota

Está @odata.nextLink obsoleto para escenarios sen conexión móbil. Aínda que aínda está soportado para as personalizacións existentes, xa non se recomenda usalo.

Unha operación de $expand sen conexión devolve unha @odata.nextLink anotación que contén información sobre como acceder á información do rexistro relacionado. Usamos o idparámetro , entityTypee options desa anotación para construír unha ou máis solicitudes adicionais Xrm.WebApi.offline.retrieveRecord . O seguinte anaco de código ofrece un exemplo completo de como facelo:

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 obter máis exemplos de recuperación de varios rexistros usando a API web, consulte Datos de consulta usando a API web.

Artigos relacionados

Consulta datos usando a API Web
Xrm.WebApi.retrieveRecord
Xrm.WebApi