retrieveMultipleRecords (referência da API do Cliente)

Recupera uma coleção de registros de tabela.

Sintaxe

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

Parâmetros

Nome Tipo Obrigatório Description
entityLogicalName String Yes O nome lógico da tabela dos registros que você deseja recuperar. Por exemplo: account.
options String Não Opções de consulta do sistema OData ou consulta FetchXML para recuperar seus dados. Ver Opções
maxPageSize Número Não Especifique um número positivo que indica o número de registros de tabela a serem retornados por página. Se você não especificar esse parâmetro, o valor padrão será o limite máximo de 5.000 registros para tabelas padrão e 500 para tabelas elásticas.

Se o número de registros que você está recuperando for maior que o valor especificado maxPageSize ou o limite máximo para o tipo de tabela, a nextLink coluna no objeto promise retornado conterá um link para recuperar registros.
successCallback Função Não Uma função a ser chamada quando os registros de tabela são recuperados. Consulte o valor retornado
errorCallback Função Não Uma função a ser chamada quando a operação falhar. Um objeto com as seguintes propriedades é passado:
- errorCode:Número. O código de erro como um número decimal positivo. Por exemplo, o código de erro documentado como 0x80040333 será retornado como 2147746611.
- message:Corda. Uma mensagem de erro descrevendo o problema.

Opções

Há suporte para as seguintes opções de consulta do sistema: $select, , $top, $filter, $expande $orderby.

Use a opção de consulta do $expand sistema para controlar quais dados de tabelas relacionadas são retornados. Se você incluir apenas o nome da propriedade de navegação, receberá todas as propriedades para registros relacionados. Você pode limitar as propriedades retornadas para registros relacionados usando a opção de consulta do $select sistema em parênteses após o nome da propriedade de navegação. Use essa opção para propriedades de navegação com valor único e com valor de coleção . Para offline, há suporte apenas para a opção aninhada $select dentro do $expand .

Para especificar uma consulta FetchXML, use a fetchXml coluna para especificar a consulta.

Observação

Você sempre deve usar a opção de consulta do $select sistema para limitar as propriedades retornadas para um registro de tabela, incluindo uma lista separada por vírgulas de nomes de propriedades. Essa prática é importante para o desempenho. Se você não especificar propriedades usando $select, todas as propriedades serão retornadas.

Especifique as opções de consulta começando com ?. Você também pode especificar várias opções de consulta do sistema usando & para separar as opções de consulta.

Quando você especifica uma cadeia de caracteres de consulta OData para o options parâmetro, codifica a consulta para caracteres especiais.

Quando você especificar uma consulta FetchXML para o options parâmetro, não codifique a consulta.

Para saber como definir o options parâmetro para vários cenários de recuperação, consulte Exemplos.

Valor de devolução

Com êxito, retorna um objeto de promessa para as successCallback seguintes propriedades:

Nome Tipo Description
entities Matriz de objetos JSON Cada objeto representa o registro de tabela recuperado que contém colunas e seus valores como key: value pares. A ID do registro da tabela é recuperada por padrão.
nextLink String (opcional) Se o número de registros que estão sendo recuperados for maior do que o valor especificado no maxPageSize parâmetro na solicitação, isso retornará a URL para retornar a próxima página de registros.
fetchXmlPagingCookie (opcional) Para uma operação baseada em retrieveMultipleRecords fetchXml com paginação em que a contagem total de registros é maior que o valor de paginação, esse atributo retorna o cookie de paginação que pode ser usado para uma operação fetchXml subsequente para recuperar a próxima página de registros.

Tipos de atributo sem suporte para opções de consulta OData no dispositivo móvel offline

Os tipos de coluna a seguir não têm suporte quando você usa Xrm.WebApi.retrieveMultipleRecords com opções de cadeia de caracteres de consulta OData (como $select e $filter) no modo offline móvel. Use FetchXML se precisar trabalhar com um tipo de atributo nesta lista de tipos de atributo sem suporte.

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

Recursos sem suporte em dispositivos móveis offline

Não há suporte para os seguintes recursos no dispositivo móvel offline:

  • Recursos de agrupamento e agregação

Operações de filtro com suporte por tipo de atributo no dispositivo móvel offline usando FetchXML

As operações a seguir têm suporte para todos os tipos de atributo ao trabalhar com FetchXML:

  • Igual a (eq)
  • Not Equals (neq)
  • Nulo (null)
  • Não nulo (not-null)

A tabela a seguir lista mais operações com suporte para cada tipo de atributo:

Tipo de Atributo Operações com suporte
BigInt, Decimal, Double, Integer Maior que (gt)
Maior ou Igual a (gte)
Menor que (lt)
Menor ou Igual a (lte)
Booliano, Cliente Em (in)
Não dentro (not-in)
EntityName, Picklist, State, Status Like (like)
Não Como (not-like)
Começa com (begins-with)
Não comece com (not-begin-with)
Termina com (ends-with)
Não terminar com (not-end-with)
Em (in)
Não dentro (not-in)
Guid, Pesquisa Em (in)
Não dentro (not-in)
Igual à ID do Usuário (eq-userid)
ID de usuário não igual a (ne-userid)
Dinheiro Maior que (gt)
Maior ou Igual a (gte)
Menor que (lt)
Menor ou Igual a (lte)
Em (in)
Não dentro (not-in)
Proprietário Em (in)
Não dentro (not-in)
Igual à ID do Usuário (eq-userid)
ID de usuário não igual a (ne-userid)
É igual a usuário ou equipe (eq-useroruserteams)
String Like (like)
Não Como (not-like)
Começa com (begins-with)
Não comece com (not-begin-with)
Termina com (ends-with)
Não terminar com (not-end-with)
DateTime Ativado ou Após (on-or-after)
Ativado (on)
Ativado ou anterior (on-or-before)
Hoje (today)
Amanhã (tomorrow)
Ontem (yesterday)
Próximos sete dias (next-seven-days)
Últimos sete dias (last-seven-days)
Próxima semana (next-week)
Semana passada (last-week)
Esta semana (this-week)
Próximo mês (next-month)
Mês Passado (last-month)
Este mês (this-month)
Ano que vem (next-year)
Ano Passado (last-year)
Este ano (this-year)
Últimos X Dias (last-x-days)
Próximos X Dias (next-x-days)
Últimas Semanas X (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 a (gte)
Menor que (lt)
Menor ou igual a (lte)

Exemplos

Você pode usar o método retrieveMultipleRecords para obter a maioria dos cenários e exemplos mencionados em Dados de Consulta usando a API Web. Alguns dos exemplos são listados na seção a seguir.

Recuperação básica múltipla

Este exemplo consulta o conjunto de tabelas de contas e usa as $select opções de consulta e $top sistema para retornar a propriedade de nome para as três 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
    }
);

Recuperação básica múltipla com FetchXML

Este exemplo consulta a account entidade 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 propriedades de pesquisa

Para a maioria das propriedades de navegação com valor único, você encontra uma propriedade computada somente leitura que usa a seguinte convenção de nomenclatura: _<name>_value onde o <name> nome da propriedade de navegação de valor único. Para fins de filtragem, você também pode usar o valor específico da propriedade de navegação com valor único. No entanto, essas opções de sintaxe não têm suporte para clientes móveis no modo offline. Use o nome da propriedade de navegação de valor único para recuperação e filtragem. Além disso, o modo offline não dá suporte à comparação das propriedades de navegação com nulo.

Mais informações: Propriedades de pesquisa

Aqui estão exemplos de código para ambos os cenários:

Para cenário online (conectado ao servidor)

Este exemplo consulta o conjunto de tabelas de contas e usa as $select opções de consulta e $filter sistema para retornar o nome e a propriedade primarycontactid para contas que têm um contato primário 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 cenário offline móvel

Este exemplo consulta o conjunto de tabelas de contas e usa as $select opções de consulta e $filter sistema para retornar o nome e a propriedade primarycontactid para contas que têm um contato primário específico ao trabalhar no modo offline:

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 ou filtrar por propriedades de pesquisa (cenário online e offline)

Use o FetchXML parâmetro enquanto estiver online ou offline para recuperar a name propriedade e primarycontactid os registros de conta que têm um contato primário que corresponda a uma condição:

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 tabelas a serem retornadas em uma página

O exemplo a seguir mostra como usar o maxPageSize parâmetro para especificar que cada página exibe três 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
    }
);

Este exemplo exibe três registros e um link para a próxima página. Aqui está um exemplo de saída do Console nas ferramentas de desenvolvedor 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 na nextLink propriedade como o valor do options parâmetro na próxima chamada retrieveMultipleRecords para solicitar o próximo conjunto de registros. Não altere ou adicione mais opções de consulta do sistema ao valor. Para cada solicitação subsequente para mais páginas, use o mesmo maxPageSize valor usado na solicitação de recuperação múltipla original. Além disso, armazene em cache os resultados retornados ou o valor da propriedade para nextLink que seu aplicativo possa retornar páginas recuperadas anteriormente.

Por exemplo, para obter a próxima página de registros, passe a parte da consulta da nextLink URL para o 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
    }
);

Essa solicitação retorna a próxima página do 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

O valor da nextLink propriedade é codificado em URI. Se você codificar o valor antes de enviá-lo, as informações de cookie XML na URL causarão um erro.

Exemplo de FetchXML (cenário online)

O exemplo a seguir mostra como usar o count parâmetro em FetchXML para especificar que cada página exibe três registros.

Observação

O cookie de paginação FetchXML só é retornado para operações online retrieveMultipleRecords . (Xrm.WebApi.online). Não há suporte para offline.

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 exibe três registros e retorna um cookie de paginação FetchXML para recuperar os resultados da próxima página se houver mais registros no conjunto de resultados. Aqui está um exemplo de saída do Console nas ferramentas de desenvolvedor 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\" />"
}

Para buscar grandes conjuntos de resultados com paginação, use o fetchXmlPagingCookie exemplo a seguir, conforme mostrado.

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

Use a opção de consulta do sistema $expand nas propriedades de navegação para controlar os dados que retornam de tabelas relacionadas. O exemplo a seguir mostra como recuperar o contato de todos os registros da conta. Para os registros de contato relacionados, você só recupera os campos efullname:contactid

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 retorna um resultado com um 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"
         }
      }
   ]
}

Observação

Semelhante ao cenário online, use a opção de consulta do sistema $expand para recuperar dados de tabelas relacionadas em offline. No entanto, não há suporte para relações muitos para muitos no offline.

Método preterido para cenário offline móvel

Observação

A @odata.nextLink preterida para cenários offline móveis. Embora ainda tenha suporte para personalizações existentes, não a use mais.

Uma operação de $expand offline retorna uma @odata.nextLink anotação que contém informações sobre como acessar as informações do registro relacionado. Use o parâmetro e o idparâmetro dessa anotação para construir uma ou mais solicitações adicionaisXrm.WebApi.offline.retrieveRecord.optionsentityType O código a seguir fornece um exemplo completo de como fazer isso:

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 mais exemplos de recuperação de vários registros usando a API Web, consulte Dados de Consulta usando a API Web.

Consultar dados usando a API Web
Xrm.WebApi.retrieveRecord
Xrm.WebApi