retrieveMultipleRecords(클라이언트 API 참조)

테이블 레코드의 컬렉션을 검색합니다.

Syntax

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

매개 변수

Options

지원$select되는 시스템 쿼리 옵션은 다음과 $expand$top$filter$orderby같습니다.

$expand 시스템 쿼리 옵션을 사용하여 관련 테이블에서 반환되는 데이터를 제어합니다. 탐색 속성의 이름만 포함하는 경우 관련 레코드에 대한 모든 속성을 받게 됩니다. 탐색 속성 이름 뒤의 괄호 안에 시스템 쿼리 옵션을 사용하여 $select 관련 레코드에 대해 반환되는 속성을 제한할 수 있습니다. 단일 값 탐색 속성과 컬렉션 값 탐색 속성 모두에 이 옵션을 사용합니다. 오프라인의 경우 내부 중첩 $select 옵션만 지원합니다 $expand.

FetchXML 쿼리를 지정하려면 열을 사용하여 fetchXml 쿼리를 지정합니다.

로 ?시작하는 쿼리 옵션을 지정합니다. 쿼리 옵션을 구분하는 데 사용하여 & 여러 시스템 쿼리 옵션을 지정할 수도 있습니다.

매개 변수에 OData 쿼리 문자열을 options 지정하는 경우 특수 문자에 대해 쿼리 를 인코딩해야 합니다 .

매개 변수에 대한 FetchXML 쿼리를 options 지정하는 경우 쿼리를 인코딩하면 안 됩니다.

다양한 검색 시나리오 에 대한 매개 변수를 options 정의하는 방법을 보려면 예제를 참조하세요.

반환 값

성공하면 다음 속성을 사용하여 promise 개체를 successCallback 반환합니다.

모바일 오프라인에서 OData 쿼리 옵션에 대해 지원되지 않는 특성 유형

다음 열 형식은 모바일 오프라인 모드에서 OData 쿼리 문자열 옵션(예: $select 및$filter)을 사용하여 작업을 수행할 Xrm.WebApi.retrieveMultipleRecords 때 지원되지 않습니다. 작업해야 하는 특성 유형이 지원되지 않는 특성 형식 목록에 있는 경우 FetchXML을 사용해야 합니다.

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

모바일 오프라인에서 지원되지 않는 기능

모바일 오프라인에서는 다음 기능이 지원되지 않습니다.

• 그룹화 및 집계 기능

FetchXML을 사용하여 모바일 오프라인에서 특성 유형당 지원되는 필터 작업

FetchXML로 작업할 때 모든 특성 유형에 대해 다음 작업이 지원됩니다.

• Equals(eq)
• 같지 않음(neq)
• Null(null)
• Null이 아님(not-null)

다음 표에서는 각 특성 유형에 대해 지원되는 더 많은 작업을 나열합니다.

예시

Web API를 사용하여 쿼리 데이터에 언급된 대부분의 시나리오/예제는 retrieveMultipleRecords 메서드를 사용하여 달성할 수 있습니다. 일부 예제는 아래에 나열되어 있습니다.

기본 검색 다중

다음은 계정 테이블 집합을 쿼리하고 시스템 $top 쿼리 옵션을 사용하여 $select 처음 세 계정에 대한 이름 속성을 반환하는 예제입니다.

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의 비교는 오프라인 모드에서 지원되지 않습니다.

추가 정보: 조회 속성

두 시나리오 모두에 대한 코드 예제는 다음과 같습니다.

온라인 시나리오의 경우(서버에 연결됨)

다음은 계정 테이블 집합을 쿼리하고 시스템 $filter 쿼리 옵션을 사용하여 $select 특정 기본 연락처가 있는 계정에 대한 이름 및 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
    }
);

모바일 오프라인 시나리오의 경우

다음은 계정 테이블 집합을 쿼리하고 시스템 $filter 쿼리 옵션을 사용하여 $select 오프라인 모드에서 작업할 때 특정 기본 연락처가 있는 계정에 대한 이름 및 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 사용하여 조건과 일치하는 기본 연락처가 있는 계정 레코드의 속성과 primarycontactid 속성을 검색 name 할 수 있습니다.

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

이 예제에서는 세 개의 레코드와 다음 페이지에 대한 링크를 표시합니다. 브라우저 개발자 도구의 콘솔 출력 예제는 다음과 같습니다.

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

FetchXML 예제(온라인 시나리오)

다음 예제에서는 FetchXML의 매개 변수를 사용하여 count 페이지에 표시할 레코드 수(3)를 지정하는 방법을 보여 줍니다.

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 페이징 쿠키를 반환하여 다음 페이지의 결과를 검색합니다. 브라우저 개발자 도구의 콘솔 출력 예제는 다음과 같습니다.

{
   "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 시스템 쿼리 옵션을 사용하여 관련 테이블에서 반환되는 데이터를 제어합니다. 다음 예제에서는 모든 계정 레코드에 대한 연락처를 검색하는 방법을 보여 줍니다. 관련 연락처 레코드의 경우 다음 항목만 검색합니다fullname.contactid

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 매개 변수를 사용하여 하나 이상의 추가 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를 사용하여 데이터 쿼리를 참조하세요.

관련 문서

웹 API를 사용하여 데이터 쿼리
Xrm.WebApi.retrieveRecord
Xrm.WebApi