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

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 isso para propriedades de navegação de valor único e com valor de coleção . Observe que, para offline, só há suporte para a opção aninhada $select dentro do $expand.

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

Você especifica 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, a consulta deve ser codificada para caracteres especiais.

Quando você especifica uma consulta FetchXML para o options parâmetro, a consulta não deve ser codificada.

Veja exemplos para ver como você pode definir o options parâmetro para vários cenários de recuperação.

Valor de retorno

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

Tipos de atributo sem suporte para opções de consulta OData no Mobile Offline

Não há suporte para os tipos de coluna a seguir ao fazer uma Xrm.WebApi.retrieveMultipleRecords operação com opções de cadeia de caracteres de consulta OData (por exemplo, $select e $filter) no modo offline móvel. Você deve usar FetchXML se o tipo de atributo com o qual você precisa trabalhar estiver nessa lista de tipos de atributo sem suporte.

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

Recursos sem suporte no Mobile Offline

Não há suporte para os seguintes recursos no Mobile Offline:

• Recursos de agrupamento e agregação

Operações de filtro com suporte por tipo de atributo no mobile 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:

Exemplos

A maioria dos cenários/exemplos mencionados em Dados de Consulta usando a API Web pode ser obtida usando o método retrieveMultipleRecords . Alguns dos exemplos estão listados abaixo.

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ê encontrará 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, o valor específico da propriedade de navegação com valor único também pode ser usado. No entanto, para clientes móveis no modo offline, essas opções de sintaxe não têm suporte e o nome da propriedade de navegação de valor único deve ser usado para recuperação e filtragem. Além disso, não há suporte para a comparação das propriedades de navegação com nulo no modo offline.

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)

Você pode usar 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 demonstra o uso do maxPageSize parâmetro para especificar o número de registros (3) a ser exibido em uma 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 exemplo exibirá 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 em sua chamada retrieveMultipleRecords subsequente para solicitar o próximo conjunto de registros. Não altere ou acrescente mais opções de consulta do sistema ao valor. Para cada solicitação subsequente para mais páginas, você deve usar 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 nextLink para que as páginas recuperadas anteriormente possam ser retornadas.

Por exemplo, para obter a próxima página de registros, passaremos a parte de 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
    }
);

Isso retornará 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

Exemplo de FetchXML (cenário online)

O exemplo a seguir demonstra o uso do count parâmetro fetchXML para especificar o número de registros (3) a ser exibido em uma 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 exemplo exibirá três registros e retornará um Cookie de Paginação FetchXML para recuperar os resultados da próxima página se houver mais registros pertencentes ao 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\" />"
}

Podemos usar o fetchXmlPagingCookie conforme mostrado no exemplo abaixo para buscar grandes conjuntos de resultados com paginação.

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 tabelas relacionadas expandindo as propriedades de navegação

Use a opção de consulta do sistema $expand nas propriedades de navegação para controlar os dados retornados de tabelas relacionadas. O exemplo a seguir demonstra como recuperar o contato de todos os registros da conta. Para os registros de contato relacionados, estamos apenas 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
    }
);

A parte de código acima 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"
         }
      }
   ]
}

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

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. Usamos o parâmetro e options o identityTypeparâmetro dessa anotação para construir uma ou mais solicitações adicionaisXrm.WebApi.offline.retrieveRecord. 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.

Artigos relacionados

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