テーブル レコードのコレクションを取得します。
構文
Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback);
Parameters
| 件名 | タイプ | Required | プロパティ |
|---|---|---|---|
entityLogicalName |
String | 可 | 取得するレコードのテーブルの論理名。 例: account。 |
options |
String | いいえ | データを取得する OData システム クエリ オプションまたは FetchXML クエリ。 オプション を見る |
maxPageSize |
回数 | いいえ | 1 ページあたりに返すテーブル レコードの数を示す正の数を指定します。 このパラメーターを指定しない場合、既定値は標準テーブルの場合は 5,000 レコード、エラスティック テーブルの場合は 500 レコードの上限です。 取得するレコードの数が、指定した maxPageSize 値またはテーブルの種類の上限を超えている場合、返される promise オブジェクトの nextLink 列には、レコードを取得するためのリンクが含まれます。 |
successCallback |
Function | いいえ | テーブル レコードを取得した場合に呼び出す関数。 戻り値 を見る |
errorCallback |
Function | いいえ | 処理が失敗したときに呼び出す関数。 次のプロパティを持つオブジェクトが渡されます: - errorCode: 数。 正の 10 進数でのエラー コード。 たとえば、0x80040333 として文書化されたエラー コードは、2147746611 として返されます。- message: 文字列。 問題を示すエラー メッセージが表示されます。 |
オプション
次のシステム クエリ オプションがサポートされています: $select、 $top、 $filter、 $expand、そして $orderby。
$expand システム クエリ オプションを使用して、関連テーブルからどのデータが返されるかをコントロールします。 単にナビゲーション プロパティ名を含めた場合は、関連レコードのすべてのプロパティが表示されます。 関連レコードに対して返されるプロパティを制限するには、ナビゲーション プロパティ名の後にかっこで囲まれた $select システム クエリ オプションを使用します。 このオプションは、 単一値 ナビゲーション プロパティと コレクション値 ナビゲーション プロパティの両方に使用します。 オフラインの場合、$expand内の入れ子になった$select オプションのみがサポートされます。
FetchXML クエリを指定するには、クエリを指定する fetchXml 列を使用します。
ヒント
プロパティ名のコンマ区切りリストを含めることで、テーブル レコードに返されるプロパティを制限するには、常に $select システム クエリ オプションを使用する必要があります。 この方法は、パフォーマンスにとって重要です。
$selectを使用してプロパティを指定しない場合は、すべてのプロパティが返されます。
?で始まるクエリ オプションを指定します。 クエリ オプションを & で区切って、複数のシステム クエリ オプションを指定することもできます。
options パラメーターに OData クエリ文字列を指定する場合は、特殊文字のクエリをエンコードします。
options パラメーターに FetchXML クエリを指定する場合は、クエリをエンコードしないでください。
さまざまな取得複数のシナリオに対して options パラメーターを定義する方法については、「 例」を参照してください。
戻り値
成功すると、Promiseオブジェクトを successCallback 次のプロパティを使用します。
| 件名 | タイプ | プロパティ |
|---|---|---|
entities |
JSON オブジェクトのアレイ | 各オブジェクトが列とその値を key: value ペアとして取得されたテーブル レコードを表します。 テーブル レコードの ID は、既定で取得されます。 |
nextLink |
String | (オプション) 取得されるレコードの件数が、要求内の maxPageSize パラメーターで指定された値より多い場合、レコードの次のページを返す URL を返します。 |
fetchXmlPagingCookie |
(オプション) 合計レコード数がページング値よりも大きいページングを使用する fetchXml ベースの retrieveMultipleRecords 操作の場合、この属性は、レコードの次のページを取得するための後続の fetchXml 操作に使用できるページング Cookie を返します。 |
モバイル オフラインでの OData クエリ オプションでサポートされていない属性の種類
次の列の種類は、モバイル オフライン モードで OData クエリ文字列オプション ($selectや$filterなど) でXrm.WebApi.retrieveMultipleRecordsを使用する場合はサポートされません。 このサポートされていない属性型の一覧で属性型を操作する必要がある場合は、FetchXML を使用します。
MultiSelectPicklistFileImageManagedPropertyCalendarRulesPartyListVirtual
モバイル オフラインでサポートされていない機能
モバイル オフラインでは、次の機能はサポートされていません。
- グループ化機能と集計機能
FetchXML を使用したモバイル オフラインでの属性の種類ごとのフィルター操作のサポート
FetchXML を使用する場合、すべての属性の種類で次の操作がサポートされます。
- 等しい (
eq) - 等しくない (
neq) - Null (
null) - Null ではない (
not-null)
次の表に、各属性の種類でサポートされる追加の操作を示します。
| 属性の種類 | サポートされている操作 |
|---|---|
| BigInt、Decimal、Double、Integer | 次の値より大きい (gt)以上 ( gte)次の値より小さい ( lt)以下 ( lte) |
| Boolean、Customer | 含まれる (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) |
| Money | 次の値より大きい (gt)以上 ( gte)次の値より小さい ( lt)以下 ( lte)含まれる ( in)含まれない ( not-in) |
| Owner | 含まれる (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) |
| DateTime | 次の日付以降 (on-or-after)次の日付と等しい ( on)次の日付以前 ( on-or-before)今日 ( today)明日 ( tomorrow)昨日 ( yesterday)今後 7 日間 ( 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 システム クエリ オプションを使用して、最初の 3 つの取引先企業の名前プロパティを返します。
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 システム クエリ オプションを使用して、オフライン モードで作業するときに特定のプライマリ連絡先を持つアカウントの名前と 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 パラメーターを使用して、各ページに 3 つのレコードが表示されることを指定する方法を示します。
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
}
);
次の使用例は、3 つのレコードと次のページへのリンクを表示します。 以下に示すのは、ブラウザー開発ツールの コンソール からの出力例です。
{@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 呼び出しのoptions パラメーターの値として、nextLink プロパティの URL のクエリ 部分を使用して、次のレコード セットを要求します。 値にシステム クエリ オプションを変更したり追加したりしないでください。 それ以上のページに対する後続の要求ごとに、元の複数の要求を取得するときに使用したのと同じ maxPageSize 値を使用します。 また、返された結果または nextLink プロパティの値をキャッシュして、アプリが以前に取得したページを返すことができるようにします。
たとえば、レコードの次のページを取得するには、 nextLink URL のクエリ部分を 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 パラメーターを使用して、各ページに 3 つのレコードが表示されることを指定する方法を示しています。
ヒント
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
}
);
次の使用例は、3 つのレコードを表示し、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 フィールドと 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 システム クエリ オプションを使用して、オフラインで関連するテーブルからデータを取得します。 ただし、多対多リレーションシップはオフラインではサポートされていません。
モバイル オフライン シナリオの廃止されたメソッド
ヒント
@odata.nextLink は、モバイル オフライン シナリオでは非推奨です。 既存のカスタマイズについては引き続きサポートされていますが、もう使用しないでください。
オフラインの $expand 操作は、関連レコードの情報を取得する方法に関する情報を含む @odata.nextLink 注釈を返します。 その注釈の id、 entityType、および options パラメーターを使用して、1 つ以上の追加の 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 を 使用したデータのクエリ」を参照してください。