Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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 indique o número de registos de tabela a devolver por página. Se não especificar este parâmetro, o valor padrão é o limite máximo de 5.000 registos para tabelas padrão e 500 para tabelas elásticas. Se o número de registos que está a recuperar for superior ao valor especificado maxPageSize ou ao limite máximo para o tipo de tabela, a nextLink coluna no objeto de promessa devolvida contém um link para recuperar registos. |
successCallback |
Função | Não | Uma função a ser chamada quando os registros de tabela são recuperados. Ver Valor de Retorno |
errorCallback |
Função | Não | Uma função para chamar 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: Fio. Uma mensagem de erro descrevendo o problema. |
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. Pode limitar as propriedades devolvidas para registos relacionados usando a $select opção de consulta do sistema entre parênteses após o nome da propriedade de navegação. Use esta opção tanto para propriedades de navegação de valor único como de valor de coleção . Para offline, apenas a opção $expand aninhada $select dentro do é suportada.
Para especificar uma consulta FetchXML, use a fetchXml coluna para especificar a consulta.
Observação
Deve sempre usar a $select opção de consulta do sistema para limitar as propriedades devolvidas para um registo de tabela, incluindo uma lista separada por vírgulas dos nomes das propriedades. Esta prática é importante para o desempenho. Se não especificar propriedades usando $select, todas as propriedades são devolvidas.
Especifique as opções de consulta que começam por ?. Você também pode especificar várias opções de consulta do sistema usando & para separar as opções de consulta.
Quando especificar uma string de consulta OData para o options parâmetro, codifique a consulta para caracteres especiais.
Quando especificar uma consulta FetchXML para o options parâmetro, não codifique a consulta.
Para aprender a definir o options parâmetro para vários cenários de recuperação múltipla, veja Exemplos.
Valor de retorno
Quando for bem-sucedido, retorna um objeto promise para o successCallback com as seguintes propriedades:
| Nome | Tipo | Description |
|---|---|---|
entities |
Matriz de objetos JSON | Cada objeto representa o registro de tabela recuperado contendo colunas e seus valores como key: value pares. O ID do registo da tabela é recuperado por defeito. |
nextLink |
String | (facultativo) 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 |
(facultativo) Para uma operação baseada em retrieveMultipleRecords fetchXml com paginação em que a contagem total de registros é maior do 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 atributos não suportados para opções de consulta OData em dispositivos móveis offline
Os seguintes tipos de colunas não são suportados quando utilizas Xrm.WebApi.retrieveMultipleRecords opções de string de consulta OData (como $select e $filter) em modo offline móvel. Use o FetchXML se precisar de trabalhar com um tipo de atributo nesta lista de tipos de atributos não suportados.
MultiSelectPicklistFileImageManagedPropertyCalendarRulesPartyListVirtual
Funcionalidades não suportadas em dispositivos móveis offline
As seguintes funcionalidades não são suportadas em dispositivos móveis offline:
- Características de agrupamento e agregação
Operações de filtro suportadas por tipo de atributo em dispositivos móveis 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:
| Tipo de atributo | Operações suportadas |
|---|---|
| BigInt, Decimal, Duplo, Inteiro | Maior que (gt)Maior que ou igual ( gte)Menos de ( lt)Menor ou igual ( lte) |
| Booleano, Cliente | Em (in)Não em ( not-in) |
| EntityName, Picklist, Estado, Status | Gosto (like)Não gosto ( not-like)Começa com ( begins-with)Não começar com ( not-begin-with)Termina com ( ends-with)Não terminar com ( not-end-with)Em ( in)Não em ( not-in) |
| Guid, Pesquisa | Em (in)Não em ( not-in)Igual a ID de usuário ( eq-userid)Não é igual a ID de usuário ( ne-userid) |
| Dinheiro | Maior que (gt)Maior que ou igual ( gte)Menos de ( lt)Menor ou igual ( lte)Em ( in)Não em ( not-in) |
| Proprietário | Em (in)Não em ( not-in)Igual a ID de usuário ( eq-userid)Não é igual a ID de usuário ( ne-userid)Igual a Usuário ou Equipe ( eq-useroruserteams) |
| String | Gosto (like)Não gosto ( not-like)Começa com ( begins-with)Não começar com ( not-begin-with)Termina com ( ends-with)Não terminar com ( not-end-with) |
| DateTime | Ligado ou Depois (on-or-after)Ativado ( on)Em ou antes ( 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)Última Semana ( last-week)Esta semana ( this-week)Próximo mês ( next-month)Mês passado ( last-month)Este mês ( this-month)Próximo Ano ( next-year)Ano passado ( last-year)Este ano ( this-year)Últimos X Dias ( last-x-days)Próximos X Dias ( 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 que ou igual ( gte)Menos de ( lt)Menor ou igual ( lte) |
Examples
Pode usar o método retrieveMultipleRecords para alcançar a maioria dos cenários e exemplos mencionados em Query Data usando a Web API. Alguns dos exemplos estão listados na secção seguinte.
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, encontra-se uma propriedade calculada, apenas de leitura, que utiliza a seguinte convenção de nomenclatura: _<name>_value onde o <name> é o nome da propriedade de navegação de valor único. Para efeitos de filtragem, também pode usar o valor específico da propriedade de navegação de valor único. No entanto, estas opções de sintaxe não são suportadas para clientes móveis em modo offline. Use o nome da propriedade de navegação de valor único tanto para recuperar como para filtrar. Além disso, o modo offline não suporta a comparação das propriedades de navegação com o null.
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 utiliza as $select opções de consulta do sistema $filter e e para devolver a propriedade name e primarycontactid para contas que têm um contacto primário específico quando trabalham em 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 online ou offline para recuperar a name propriedade e primarycontactid para registos de conta que tenham um contacto principal 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 seguinte mostra como usar o maxPageSize parâmetro para especificar que cada página apresenta três registos.
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 apresenta três registos e um link para a página seguinte. 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 da consulta na URL da nextLink propriedade como valor para o options parâmetro na sua próxima chamada retrieveMultipleRecords para solicitar o próximo conjunto de registos. Não altere nem adicione mais opções de consulta do sistema ao valor. Para cada pedido subsequente para mais páginas, use o mesmo maxPageSize valor que usou no pedido original de recuperar múltiplos pedidos. Além disso, armazene em cache os resultados devolvidos ou o valor da nextLink propriedade para que a sua aplicação possa devolver as páginas já recuperadas.
Por exemplo, para obter a página seguinte de registos, 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
}
);
Este pedido devolve a página seguinte 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 propriedade é codificado nextLink por URI. Se codificar o valor por URI antes de o enviar, a informação de cookies XML na URL causa um erro.
Exemplo de FetchXML (cenário online)
O exemplo seguinte mostra como usar o count parâmetro no FetchXML para especificar que cada página apresenta três registos.
Observação
O cookie de paginação FetchXML só é retornado para operações online retrieveMultipleRecords . (Xrm.WebApi.online). Não é suportado 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 apresenta três registos e devolve um cookie de paginação FetchXML para recuperar os resultados da página seguinte, caso haja mais registos 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 obter grandes conjuntos de resultados com paginação, use o fetchXmlPagingCookie como mostrado no exemplo seguinte.
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 que retornam das tabelas relacionadas. O exemplo seguinte mostra como recuperar o contacto de todos os registos da conta. Para os registos de contacto relacionados, apenas recupera os contactid campos 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 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 $expand consulta do sistema para recuperar dados de tabelas relacionadas offline. No entanto, relações muitos-para-muitos não são suportadas offline.
Método preterido para cenário móvel offline
Observação
O @odata.nextLink foi preterido para cenários móveis offline. Embora ainda seja suportado para personalizações existentes, não o uses mais.
Uma operação de $expand offline retorna uma @odata.nextLink anotação contendo informações sobre como chegar às informações do registro relacionado. Use os idparâmetros , entityType, e options dessa anotação para construir um ou mais pedidos adicionais Xrm.WebApi.offline.retrieveRecord . O código seguinte fornece um exemplo completo de como fazer isto:
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 mais exemplos de recuperação de múltiplos registos usando Web API, consulte Query Data using the Web API.
Artigos relacionados
Consultar dados usando a API da Web
Xrm.WebApi.retrieveRecord
Xrm.WebApi