次の方法で共有


retrieveMultipleRecords (クライアント API 参照)

テーブル レコードのコレクションを取得します。

構文

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

Parameters

件名 タイプ Required Description
entityLogicalName String はい 取得するレコードのテーブルの論理名。 例: account
options String いいえ ODataシステム クエリ オプションまたは FetchXML クエリを使用してデータを取得します。 オプション を見る
maxPageSize 回数 いいえ ページごとに返されるテーブル レコードの数を表す正の数を指定します。 このパラメーターを指定しない場合、値は既定で最大制限 5000 レコードとなります。

取得されるレコード数が、指定された maxPageSize 値または 5000 レコードより多い場合は、返された Promise オブジェクト内の nextLink 属性に、レコードを取得するためのリンクが含まれます。
successCallback Function いいえ テーブル レコードを取得した場合に呼び出す関数。 戻り値 を見る
errorCallback Function いいえ 処理が失敗したときに呼び出す関数。

オプション

次のシステム クエリ オプションがサポートされています: $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 String (オプション) 取得されるレコードの件数が、要求内の maxPageSize パラメーターで指定された値より多い場合、レコードの次のページを返す URL を返します。
fetchXmlPagingCookie (オプション) 合計レコード数がページング値よりも大きいページングを使用する fetchXml ベースの retrieveMultipleRecords 操作の場合、この属性は、レコードの次のページを取得するための後続の fetchXml 操作に使用できるページング Cookie を返します。

Mobile Offline の OData クエリ オプションでサポートされていない属性の種類

Mobile Offline モードで OData クエリ文字列オプション ($select および $filter など) を使用して Xrm.WebApi.retrieveMultipleRecords を実行する場合は、次の 列タイプ はサポートされません。 操作する必要がある属性タイプがサポートされていない属性タイプのリストに含まれている場合は、 FetchXML を使用する必要があります。

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

Mobile Offline でサポートされていない機能

次の機能は、モバイル オフラインではサポートされていません。

  • グループ化と集計機能

モバイルオフラインで属性タイプごとにサポートされているフィルター操作 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)

使用例

Web APIを使用したデータのクエリ で説明されているシナリオ/例のほとんどは、 retrieveMultipleRecords メソッドを使用して実現できます。 いくつかの例を以下に示します。

基本的な複数取得

この例は、取引先企業テーブル セットをクエリし、$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 mapping='logical'><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 mapping='logical'>
       <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

nextLink プロパティの URL のクエリ部分を、レコードの次のセットを要求するための次の retrieveMultipleRecords 呼び出しで options パラメーター の値として使用します。 値に対する追加のシステム クエリ オプションを変更または追加しないでください。 以降の追加ページの要求のすべてで、元の複数取得要求で使用したものと同じ 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 例(オンラインシナリオ)

次の例は、 count の FetchXML パラメータを使用して、ページに表示されるレコード数 (3) を指定する方法を示しています。

注意

FetchXML ページング クッキーはオンライン retrieveMultipleRecords 操作に対してのみ返されます。 (Xrm.WebApi.online). オフラインではサポートされていません。

var fetchXml = "?fetchXml=<fetch mapping='logical' 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 mapping="logical"><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 注釈を返します。 その注釈の identityType、および 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を使用してデータをクエリする」を参照してください。

Web APIを使用してデータをクエリする
Xrm.WebApi.retrieveRecord
Xrm.WebApi

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。