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

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

構文

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

Parameters

オプション

次のシステム クエリ オプションがサポートされています: $select、 $top、 $filter、 $expand、そして $orderby。

$expand システム クエリ オプションを使用して、関連テーブルからどのデータが返されるかをコントロールします。 単にナビゲーション プロパティ名を含めた場合は、関連レコードのすべてのプロパティが表示されます。 ナビゲーション プロパティ名の後にかっこで示される、$select システム クエリ オプションを使用して、関連レコードに対して返されるプロパティを制限できます。 これは、単一値とコレクション値のナビゲーション プロパティの両方で使用します。 オフラインの場合、$expand 内の入れ子になった $select オプションのみがサポートされることに注意してください。

クエリを指定するには、クエリを指定するための列を使用します。 FetchXML fetchXml

? で始まるクエリ オプションを指定します。 クエリ オプションを & で区切って、複数のシステム クエリ オプションを指定することもできます。

optionsパラメータの OData クエリ文字列を指定する場合、クエリを特殊文字用にエンコードする必要があります。

パラメータにクエリを指定する場合、クエリはエンコードしないでください FetchXML 。 options ·

複数取得のさまざまなシナリオ向けに options パラメーターを定義する方法については、このトピックの以降の 例 を参照してください。

戻り値

成功すると、Promiseオブジェクトを successCallback 次のプロパティを使用します。

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)

次の表に、各属性の種類でサポートされる追加の操作を示します。

使用例

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

FetchXML 例（オンラインシナリオ）

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

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 注釈を返します。 その注釈の 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を使用してデータをクエリする」を参照してください。

関連記事

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