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

As seguintes opções de consulta do sistema são suportadas: $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 dos registros relacionados. Você pode limitar as propriedades retornadas para registros relacionados usando a opção de consulta do $select sistema entre parênteses após o nome da propriedade de navegação. Use isso para propriedades de navegação com valor único e com valor de coleção . Observe que, para off-line, só suportamos 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.

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

Valor de retorno

Quando for bem-sucedido, retorna um objeto promise para o successCallback com as seguintes propriedades:

Tipos de atributos não suportados para opções de consulta OData no Mobile Offline

Os seguintes tipos de coluna não são suportados 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 móvel offline. Você deve usar FetchXML se o tipo de atributo com o qual você precisa trabalhar estiver nesta lista de tipos de atributos sem suporte.

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

Recursos não suportados no Mobile Offline

Os seguintes recursos não são suportados no Mobile Offline:

• Recursos de agrupamento e agregação

Operações de filtro suportadas por tipo de atributo no Mobile Offline usando FetchXML

As seguintes operações são suportadas para todos os tipos de atributos ao trabalhar com FetchXML:

• Igual (eq)
• Não é igual (neq)
• Nulo (null)
• Não nulo (not-null)

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

Examples

A maioria dos cenários/exemplos mencionados em Query Data usando a API da 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 name 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 de múltiplos 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 de valor único, você encontrará uma propriedade somente leitura computada que usa a seguinte convenção de nomenclatura: _<name>_value onde o <name> é o nome da propriedade de navegação de valor único. Para fins de filtragem, o valor específico da propriedade de navegação de valor único também pode ser usado. No entanto, para clientes móveis no modo offline, essas opções de sintaxe não são suportadas e o nome da propriedade de navegação de valor único deve ser usado para recuperação e filtragem. Além disso, a comparação de propriedades de navegação com null não é suportada no modo offline.

Para obter 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 a propriedade name e 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 mobile offline

Este exemplo consulta o conjunto de tabelas de contas e usa as $select opções de consulta e $filter sistema para retornar a propriedade name e 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 online ou offline para recuperar a name propriedade e primarycontactid para registros de conta que têm um contato principal que corresponde 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 serem exibidos 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 para o options parâmetro em sua chamada retrieveMultipleRecords subsequente para solicitar o próximo conjunto de registros. Não altere nem acrescente mais opções de consulta do sistema ao valor. Para cada solicitação subsequente de 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 FetchXML (cenário online)

O exemplo a seguir demonstra o uso do count parâmetro do FetchXML para especificar o número de registros (3) a serem exibidos 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 como 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 $expand consulta do sistema nas propriedades de navegação para controlar os dados retornados de tabelas relacionadas. O exemplo a seguir demonstra como recuperar o contato para todos os registros de conta. Para os registros de contato relacionados, estamos recuperando apenas 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 móvel offline

Uma operação de $expand offline retorna uma @odata.nextLink anotação contendo informações sobre como chegar às informações do registro relacionado. Usamos o id, entityTypee options parâmetro dessa anotação para construir uma ou mais solicitações adicionais Xrm.WebApi.offline.retrieveRecord . A parte de 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 da Web, consulte Consultar dados usando a API da Web.

Artigos relacionados

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