擷取資料表記錄的集合。
語法
Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback);
參數
| 名稱 | 類型 | 為必填項目 | Description |
|---|---|---|---|
entityLogicalName |
繩子 | Yes | 您要擷取之記錄的資料表邏輯名稱。 例如： account 。 |
options |
繩子 | 否 | OData 系統查詢選項或 FetchXML 查詢來擷取您的資料。 查看 選項 |
maxPageSize |
Number | 否 | 指定一個正數值，表示每頁要回傳的表格記錄數量。 如果你沒有指定這個參數，預設值是標準資料表的最大紀錄上限為 5,000 筆，彈性資料表則是 500 筆。 如果你要取得的記錄數量超過指定 maxPageSize 值或資料表類型的最大限制， nextLink 回傳的承諾物件欄位會包含一個連結來取回記錄。 |
successCallback |
功能 | 否 | 擷取資料表記錄時要呼叫的函式。 請參閱 傳回值 |
errorCallback |
功能 | 否 | 作業失敗時要呼叫的函式。 會傳遞具有下列屬性的物件： - errorCode：數。 錯誤碼為正十進位數。 例如，記載為 0x80040333 的錯誤碼將傳回為 2147746611。- message：繩子。 描述問題的錯誤訊息。 |
選項
支援下列系統查詢選項：$select、、、$top$filter、 和 $expand$orderby。
使用 $expand 系統查詢選項來控制傳回相關表格中的哪些資料。 如果您只包含導覽內容的名稱，您會收到相關記錄的所有內容。 你可以在導覽屬性名稱後方使用括號內的 $select 系統查詢選項，限制相關紀錄回傳的屬性。 此選項 可用於單值 與 集合值 的導覽屬性。 離線時，只支援巢$expand狀$select選項。
若要指定 FetchXML 查詢，請使用資料 fetchXml 行來指定查詢。
備註
你必須始終使用 $select 系統查詢選項，透過包含逗號分隔的屬性名稱清單來限制資料表記錄回傳的屬性。 這種練習對表演非常重要。 如果你沒有用 $select來指定屬性，所有屬性都會被回傳。
指定以 ?為開頭的查詢選項。 您也可以使用 來 & 指定多個系統查詢選項，以分隔查詢選項。
當你指定參數的 options OData 查詢字串時，請將查詢 編碼 為特殊字元。
當你為參數指定 FetchXML 查詢 options 時， 不要直接編碼 查詢。
欲了解如何定義 options 各種檢索多重情境的參數，請參閱 範例。
返回值
成功時，會傳回具有下列屬性的 Promise successCallback 物件：
| 名稱 | 類型 | Description |
|---|---|---|
entities |
JSON 物件陣列 | 每一個物件都代表擷取的資料表記錄，其中包含資料行及其值作為配對。key: value 表格記錄的 ID 預設會被取用。 |
nextLink |
繩子 | （選用）如果擷取的記錄數目大於要求中參數中 maxPageSize 指定的值，則會傳回 URL 以傳回下一頁記錄。 |
fetchXmlPagingCookie |
（選用）對於具有分頁的 fetchXml 型 retrieveMultipleRecords 作業，其中記錄計數總數大於分頁值，此屬性會傳回分頁 Cookie，該 Cookie 可用於後續 fetchXml 作業，以擷取下一頁記錄。 |
行動離線 OData 查詢選項中不支援的屬性類型
以下 欄位類型 在行動離線模式下使用 Xrm.WebApi.retrieveMultipleRecords OData 查詢字串選項（如 $select$filter和 ）時不被支援。 如果你需要處理這份不支援屬性類型清單中的某個屬性型別，請使用 FetchXML。
MultiSelectPicklistFileImageManagedPropertyCalendarRulesPartyListVirtual
行動離線中不支援的功能
以下功能在行動端離線模式下不支援：
- 群組與聚合功能
支援在行動端離線中使用 FetchXML 的屬性類型過濾操作
使用 FetchXML 時，所有屬性類型都支援下列作業：
- 等於 （
eq） - 不等於 （
neq） - 空 （
null） - 非空值 （
not-null）
下表列出每個屬性類型支援的更多作業：
| 屬性類型 | 支援的作業 |
|---|---|
| BigInt、十進位、雙精度、整數 | 大於 （gt）大於或等於 （ gte）小於 （ lt）小於或等於 （ lte） |
| 布林值，客戶 | 在 （in） 中不在 （ not-in） 中 |
| 實體名稱、選項清單、狀態、狀態 | 喜歡 （like）不像 （ not-like）以 （ begins-with） 開頭不以 （ not-begin-with） 開頭以 （ ends-with） 結尾不以 （ not-end-with） 結尾在 （ in） 中不在 （ not-in） 中 |
| 引導、查閱 | 在 （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） |
| 繩子 | 喜歡 （like）不像 （ not-like）以 （ begins-with） 開頭不以 （ not-begin-with） 開頭以 （ ends-with） 結尾不以 （ not-end-with） 結尾 |
| DateTime | 在或之後 （on-or-after）關於 ( on) 在或之前 （ on-or-before）今天 （ today）明天 （ tomorrow）昨天 （ yesterday）未來七天 （ next-seven-days）過去 7 天 （ 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 系統查詢選項來傳回前三個帳戶的 name 屬性：
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 擷取多個的基本
此範例 account 會使用 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
}
);
依查閱屬性擷取或篩選
對於大多數單值導覽屬性，你會找到一個計算出的唯讀屬性，使用以下命名慣例： _<name>_value 其中 是 <name> 該單值導覽屬性的名稱。 為了篩選，你也可以使用單一值導覽屬性的具體值。 不過，這些語法選項在離線模式下不支援行動用戶端。 在檢索和篩選時，請使用單一值的導覽屬性名稱。 另外，離線模式不支援將導航屬性與空模式比較。
其他資訊： 查閱屬性
以下是兩種情境的程式碼範例：
對於線上場景（連接到伺服器）
此範例會查詢帳戶資料表集，並使用 $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 and $filter 系統查詢選項，回傳擁有特定主要聯絡人帳戶的名稱與 primarycontactid 屬性，適用於離線模式下：
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 帳戶記錄中的主要聯絡人符合條件的 和 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
在你下一次 retrieveMultipleRecords 呼叫時，利用 URL nextLink 中的查詢部分作為options參數值，來請求下一組記錄。 不要更改或新增任何系統查詢選項。 對於每次後續請求更多頁面，使用與原本 Retrieve multiple 請求相同的 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 範例（線上情境）
以下範例說明如何在 FetchXML 中使用 count 參數，指定每個頁面顯示三條紀錄。
備註
FetchXML 分頁 Cookie 只會針對線上 retrieveMultipleRecords 作業傳回。 （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 系統查詢選項來控制從相關資料表回傳的資料。 以下範例說明如何取得所有帳戶紀錄的聯絡方式。 對於相關的聯絡紀錄，你只需取得 contactid and 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
}
);
前述程式碼回傳的結果結構如下：
{
"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 系統查詢選項，離線從相關資料表擷取資料。 然而，線下關係並不支持多對多關係。
Mobile Offline 案例已取代的方法
備註
對於 @odata.nextLink 行動離線案例，已棄用。 雖然現有自訂功能仍支援，但不要再用了。
離線 $expand 作業會傳回註釋， @odata.nextLink 其中包含如何取得相關記錄資訊的相關資訊。 利用 id該註解的 、 entityType和 options 參數來構建一個或多個額外的 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 查詢資料」。