retrieveMultipleRecords (Klient-API-referanse)

Henter en samling av tabellposter.

Syntaks

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

Parametere

Alternativer

Følgende alternativer for systemspørring støttes: $select, , $top$filter, $expandog $orderby.

$expand Bruk alternativet for systemspørring til å kontrollere hvilke data fra relaterte tabeller som returneres. Hvis du bare inkluderer navnet på navigasjonsegenskapen, mottar du alle egenskapene for relaterte poster. Du kan begrense egenskapene som returneres for relaterte poster ved hjelp $select av alternativet for systemspørring i parenteser etter navnet på navigasjonsegenskapen. Bruk dette alternativet for både navigasjonsegenskaper med enkel verdi og samlingsverdi . Bare nestet $select alternativ i $expand frakoblet modus støttes.

Hvis du vil angi en FetchXML-spørring, bruker fetchXml du kolonnen til å angi spørringen.

Angi spørringsalternativene som starter med ?. Du kan også angi flere alternativer for systemspørring ved å bruke & til å skille spørringsalternativene.

Når du angir en OData-spørringsstreng for parameteren options , koder du spørringen for spesialtegn.

Når du angir en FetchXML-spørring for parameteren options , må du ikke kode spørringen.

Hvis du vil lære hvordan du definerer parameteren options for ulike hente flere scenarier, kan du se Eksempler.

returverdi

Ved vellykket, returnerer et løfteobjekt til successCallback med følgende egenskaper:

Attributtyper som ikke støttes for OData-spørringsalternativer i frakoblet mobil

Følgende kolonnetyper støttes ikke når du bruker Xrm.WebApi.retrieveMultipleRecords med alternativer for OData-spørringsstreng (for eksempel $select og $filter) i mobil frakoblet modus. Bruk FetchXML hvis du må arbeide med en attributtype i denne listen over attributttyper som ikke støttes.

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

Funksjoner som ikke støttes i mobil frakoblet modus

Følgende funksjoner støttes ikke i mobil frakoblet modus:

• Grupperings- og aggregasjonsfunksjoner

Støttede filteroperasjoner per attributttype i mobil frakoblet bruk av FetchXML

Følgende operasjoner støttes for alle attributtyper når du arbeider med FetchXML:

• Er lik (eq)
• Er ikke lik (neq)
• Null (null)
• Ikke null (not-null)

Tabellen nedenfor viser flere operasjoner som støttes for hver attributtype:

Eksempler

Du kan bruke metoden retrieveMultipleRecords til å oppnå de fleste scenarioene og eksemplene nevnt i spørringsdata ved hjelp av web-API-en. Noen av eksemplene er oppført i avsnittet nedenfor.

Grunnleggende hent flere

Dette eksemplet spør kontotabellsettet og bruker $select$top alternativene for systemspørring til å returnere navneegenskapen for de tre første kontoene:

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

Grunnleggende hent flere med FetchXML

Dette eksemplet spør enheten account ved hjelp av 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
    }
);

Hente eller filtrere etter oppslagsegenskaper

For de fleste navigasjonsegenskaper med én verdi finner du en beregnet, skrivebeskyttet egenskap som bruker følgende navnekonvensjon: _<name>_value der <name> er navnet på navigasjonsegenskapen med én verdi. For filtreringsformål kan du også bruke den bestemte verdien for navigasjonsegenskapen med én verdi. Disse syntaksalternativene støttes imidlertid ikke for mobilklienter i frakoblet modus. Bruk navigasjonsegenskapsnavnet med én verdi for både henting og filtrering. Frakoblet modus støtter heller ikke sammenligning av navigasjonsegenskaper til null.

Mer informasjon: Oppslagsegenskaper

Her er kodeeksempler for begge scenarioene:

For nettbasert scenario (koblet til server)

Dette eksemplet spør kontotabellsettet og bruker $select$filter alternativene for systemspørring til å returnere navnet og primarycontactid-egenskapen for kontoer som har en bestemt primærkontakt:

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

For et frakoblet scenario for mobil

Dette eksemplet spør kontotabellsettet og bruker $select$filter alternativene for systemspørring til å returnere navnet og primarycontactid-egenskapen for kontoer som har en bestemt primærkontakt når du arbeider i frakoblet modus:

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

Bruke FetchXML til å hente eller filtrere etter oppslagsegenskaper (tilkoblet og frakoblet scenario)

Bruk parameteren FetchXML mens du er tilkoblet eller frakoblet for å hente name og primarycontactid egenskapen for kontooppføringer som har en primærkontakt som samsvarer med en betingelse:

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

Angi antall tabeller som skal returneres på en side

Følgende eksempel viser hvordan du bruker parameteren maxPageSize til å angi at hver side viser tre poster.

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

Dette eksemplet viser tre poster og en kobling til neste side. Her er et eksempel på utdata fra konsollen i utviklerverktøyene for nettleseren:

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

Bruk spørringsdelen i nettadressen i nextLink egenskapen som verdi for parameteren options i neste retrieveMultipleRecords-kall for å be om neste sett med poster. Ikke endre eller legg til flere alternativer for systemspørring i verdien. For hver etterfølgende forespørsel om flere sider bruker du den samme maxPageSize verdien du brukte i den opprinnelige hent flere forespørsler. Hurtigbufre resultatene som returneres eller verdien for nextLink egenskapen, slik at appen kan returnere tidligere hentet sider.

Hvis du for eksempel vil hente den neste siden med poster, sender du spørringsdelen av nextLink nettadressen til parameteren 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
    }
);

Denne forespørselen returnerer neste side i resultatsettet.

{@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-eksempel (nettbasert scenario)

Følgende eksempel viser hvordan du bruker parameteren count i FetchXML til å angi at hver side viser tre poster.

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

Dette eksemplet viser tre poster og returnerer en Informasjonskapsel for FetchXML-sideveksling for å hente resultatene fra neste side hvis det er flere poster i resultatsettet. Her er et eksempel på utdata fra konsollen i utviklerverktøyene for nettleseren:

{
   "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\" />"
}

Hvis du vil hente store resultatsett med sideveksling, bruker fetchXmlPagingCookie du som vist i eksemplet nedenfor.

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

Hente relaterte tabeller ved å utvide navigasjonsegenskaper

Bruk alternativet $expand systemspørring i navigasjonsegenskapene til å kontrollere dataene som returneres fra relaterte tabeller. Følgende eksempel viser hvordan du henter kontakten for alle forretningsforbindelsesoppføringene. Når det gjelder relaterte kontaktoppføringer, henter contactid du bare feltene og 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
    }
);

Den forrige koden returnerer et resultat med et skjema som:

{
   "entities": [
      {
         "@odata.etag": "W/\"1459919\"",
         "name": "Test Account",
         "accountid": "119edfac-19c6-ea11-a81a-000d3af5e732",
         "primarycontactid": {
            "contactid": "6c63a1b7-19c6-ea11-a81a-000d3af5e732",
            "fullname": "Test Contact"
         }
      }
   ]
}

Avskrevet metode for frakoblet mobilscenario

En frakoblet $expand operasjon returnerer en @odata.nextLink merknad som inneholder informasjon om hvordan du får tilgang til informasjonen i den relaterte posten. Bruk merknadene , og options parameterne for denne merknaden idtil å konstruere én eller flere tilleggsforespørsler Xrm.WebApi.offline.retrieveRecordentityType. Følgende kode gir et fullstendig eksempel på hvordan du gjør dette:

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

Hvis du vil ha flere eksempler på henting av flere poster ved hjelp av web-API, kan du se Spørringsdata ved hjelp av web-API-en.

Relaterte artikler

Spørringsdata ved hjelp av web-API-en
Xrm.WebApi.retrieveRecord
Xrm.WebApi