retrieveMultipleRecords (客户端 API 参考)

检索表记录的集合。

Syntax

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

参数

Name 类型 必选 Description
entityLogicalName String 是的 要检索的记录的表逻辑名称。 例如: account。
options String 否 OData 系统查询选项或 FetchXML 查询以检索数据。 请参阅 选项
maxPageSize 编号 否 指定一个正数,指示每页要返回的表记录数。 如果未指定此参数,则默认值是标准表的最大限制为 5,000 条记录,弹性表为 500 条。

如果要检索的记录数大于指定 maxPageSize 值或表类型的最大限制, nextLink 则返回的 promise 对象中的列包含用于检索记录的链接。
successCallback 功能 否 检索表记录时要调用的函数。 请参阅 返回值
errorCallback 功能 否 作失败时要调用的函数。 传递具有以下属性的对象:
- errorCode:数。 错误代码为正十进制数。 例如,将按原样0x80040333记录的错误代码作为返回 。2147746611
- message:字符串。 描述问题的错误消息。

选项

支持以下系统查询选项:$select、、$top$filter、$expand和$orderby。

$expand使用系统查询选项控制返回相关表中的数据。 如果只是包含导航属性的名称,则会收到相关记录的所有属性。 可以使用导航属性名称后面的括号中的系统查询选项来限制为相关记录 $select 返回的属性。 对 单值 导航属性和 集合值 导航属性使用此选项。 对于脱机,仅 $select 支持嵌套 $expand 选项。

若要指定 FetchXML 查询,请使用 fetchXml 列指定查询。

注释

必须始终使用 $select 系统查询选项来限制表记录返回的属性,方法是包括以逗号分隔的属性名称列表。 这种做法对于性能非常重要。 如果未使用 $select指定属性,则返回所有属性。

指定以 . 开头的 ?查询选项。 还可以通过使用 & 分隔查询选项来指定多个系统查询选项。

为参数指定 OData 查询字符串 options 时,对特殊字符的查询 进行编码 。

为参数指定 FetchXML 查询 options 时, 请勿对查询进行编码 。

若要了解如何为各种检索多个方案定义 options 参数,请参阅 示例。

返回值

成功后,向具有以下属性的 successCallback promise 对象返回:

Name 类型 Description
entities JSON 对象的数组 每个对象表示包含列及其值作为 key: value 对的检索表记录。 默认情况下检索表记录的 ID。
nextLink String (可选)如果检索的记录数大于请求中参数中指定的 maxPageSize 值,则返回 URL 以返回下一页记录。
fetchXmlPagingCookie (可选)对于基于 fetchXml 的作(其中总记录计数大于分页值)的 retrieveMultipleRecords 基于 fetchXml 的作,此属性返回可用于后续 fetchXml作的分页 Cookie 来检索下一页记录。

移动脱机中的 OData 查询选项不支持的属性类型

在移动脱机模式下与 OData 查询字符串选项(如$select和$filter)一起使用Xrm.WebApi.retrieveMultipleRecords时,不支持以下列类型。 如果需要在此不受支持的属性类型列表中处理属性类型,请使用 FetchXML。

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

移动脱机中不支持的功能

移动脱机不支持以下功能:

  • 分组和聚合功能

使用 FetchXML 在移动脱机移动中支持按属性类型的筛选器操作

使用 FetchXML 时,所有属性类型都支持以下作:

  • 等于 (eq)
  • 不等于 (neq)
  • Null (null)
  • 非 Null (not-null)

下表列出了每种属性类型支持的更多作:

属性类型 支持的作
BigInt、Decimal、Double、Integer 大于 (gt)
大于或等于 (gte)
小于 (lt)
小于或等于 (lte)
布尔值、客户 在 (in) 中
不在 (not-in)
EntityName、Picklist、State、Status 赞 (like)
不喜欢 (not-like)
以 (begins-with) 开头
不以 (not-begin-with)
结尾为 (ends-with)
不以 (not-end-with)
在 (in) 中
不在 (not-in)
Guid、Lookup 在 (in) 中
不在 (not-in)
等于用户 ID (eq-userid)
不等于用户 ID (ne-userid)
金钱 大于 (gt)
大于或等于 (gte)
小于 (lt)
小于或等于 (lte)
在 (in) 中
不在 (not-in)
所有者 在 (in) 中
不在 (not-in)
等于用户 ID (eq-userid)
不等于用户 ID (ne-userid)
等于用户或团队 (eq-useroruserteams)
String 赞 (like)
不喜欢 (not-like)
以 (begins-with) 开头
不以 (not-begin-with)
结尾为 (ends-with)
不以 (not-end-with)
日期时间 打开或之后 (on-or-after)
在 (on)
打开或之前 (on-or-before)
今天(today)
明天(tomorrow)
昨天(yesterday)
接下来的七天(next-seven-days)
过去七天(last-seven-days)
下周 (next-week)
上周(last-week)
本周(this-week)
下个月(next-month)
上个月 (last-month)
本月 (this-month)
明年(next-year)
去年(last-year)
今年(this-year)
过去 X 天 (last-x-days)
下一个 X 天 (next-x-days)
过去 X 周 (last-x-weeks)
接下来的 X 周 (next-x-weeks)
过去 X 个月 (last-x-months)
接下来的 X 个月 (next-x-months)
过去 X 年 (last-x-years)
未来 X 年 (next-x-years)
大于 (gt)
大于或等于 (gte)
小于 (lt)
小于或等于 (lte)

例子

可以使用 retrieveMultipleRecords 方法来实现 使用 Web API 的查询数据中提到的大多数方案和示例。 以下部分列出了一些示例。

基本检索多个

此示例查询帐户表集,并使用 $select 系统 $top 查询选项返回前三个帐户的名称属性:

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

基本使用 FetchXML 检索多个

此示例使用 fetchXML 查询 account 实体。

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

按查找属性检索或筛选

对于大多数单值导航属性,可以找到使用以下命名约定的计算只读属性: _<name>_value 其中 <name> 单值导航属性的名称。 出于筛选目的,还可以使用单值导航属性的特定值。 但是,脱机模式下的移动客户端不支持这些语法选项。 使用单值导航属性名称来检索和筛选。 此外,脱机模式不支持将导航属性与 null 进行比较。

详细信息: 查找属性

下面是这两种方案的代码示例:

对于联机方案(已连接到服务器)

此示例查询帐户表集,并使用 $select 系统 $filter 查询选项返回具有特定主要联系人的帐户的名称和 primarycontactid 属性:

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

对于移动脱机方案

此示例查询帐户表集,并使用 $select 系统 $filter 查询选项返回处于脱机模式时具有特定主要联系人的帐户的名称和主联系人属性:

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

使用 FetchXML 按查找属性(联机和脱机方案)检索或筛选

联机或脱机时使用 FetchXML 参数检索 name 具有与条件匹配的主要联系人的帐户记录的 and primarycontactid 属性:

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

指定要在页面中返回的表数

以下示例演示如何使用 maxPageSize 参数指定每页显示三条记录。

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

此示例显示三条记录和一个指向下一页的链接。 下面是浏览器开发人员工具中 控制台 的示例输出:

{@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

使用属性中 URL 中的nextLink查询部件作为下一个 retrieveMultipleRecords 调用中参数的值options来请求下一组记录。 不要更改或向值添加更多系统查询选项。 对于每个后续页面请求,请使用在原始检索多个请求中使用的相同 maxPageSize 值。 此外,缓存返回的结果或属性的值 nextLink ,以便应用可以返回以前检索的页面。

例如,若要获取下一页记录,请将 URL 的 nextLink 查询部分传递给 options 参数:

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

此请求返回结果集的下一页。

{@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

重要

属性的值 nextLink 经过 URI 编码。 如果在发送值之前 URI 对值进行编码,则 URL 中的 XML Cookie 信息会导致错误。

FetchXML 示例(联机方案)

以下示例演示如何使用 count FetchXML 中的参数来指定每页显示三条记录。

注释

仅针对联机 retrieveMultipleRecords 作返回 FetchXML 分页 Cookie。 (Xrm.WebApi.online)。 不支持脱机。

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

本示例显示三条记录,并返回 FetchXML 分页 Cookie,以检索下一页的结果(如果结果集中有更多记录)。 下面是浏览器开发人员工具中 控制台 的示例输出:

{
   "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\" />"
}

若要提取具有分页的大型结果集,请使用 fetchXmlPagingCookie 以下示例所示。

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

使用导航属性中的 $expand 系统查询选项来控制从相关表返回的数据。 以下示例演示如何检索所有帐户记录的联系人。 对于相关的联系人记录,你仅检索和contactidfullname字段:

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

前面的代码返回架构如下的结果:

{
   "entities": [
      {
         "@odata.etag": "W/\"1459919\"",
         "name": "Test Account",
         "accountid": "119edfac-19c6-ea11-a81a-000d3af5e732",
         "primarycontactid": {
            "contactid": "6c63a1b7-19c6-ea11-a81a-000d3af5e732",
            "fullname": "Test Contact"
         }
      }
   ]
}

注释

与联机方案类似,请使用 $expand 系统查询选项从脱机相关表中检索数据。 但是,脱机不支持多对多关系。

移动脱机方案的弃用方法

注释

对于 @odata.nextLink 移动脱机方案,已弃用此功能。 尽管现有自定义项仍受支持,但不再使用它。

脱机 $expand 作返回一个 @odata.nextLink 批注,其中包含有关如何访问相关记录的信息。 id options entityType使用该批注的参数构造一个或多个其他Xrm.WebApi.offline.retrieveRecord请求。 以下代码提供了有关如何执行此操作的完整示例:

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

有关使用 Web API 检索多个记录的更多示例,请参阅 使用 Web API 的查询数据。

使用 Web API 查询数据
Xrm.WebApi.retrieveRecord
Xrm.WebApi