retrieveMultipleRecords (klient-API-referens)

Hämtar en samling tabellposter.

Syntax

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

Parameterar

Namn	Typ	Krävs	Description
entityLogicalName	String	Yes	Det logiska tabellnamnet för de poster som du vill hämta. Till exempel: account.
options	String	Nej	OData-systemfrågealternativ eller FetchXML-fråga för att hämta dina data. Se Alternativ
maxPageSize	Nummer	Nej	Ange ett positivt tal som anger antalet tabellposter som ska returneras per sida. Om du inte anger den här parametern är standardvärdet den maximala gränsen på 5 000 poster för standardtabeller och 500 för elastiska tabeller. Om antalet poster som du hämtar är mer än det angivna maxPageSize värdet eller den maximala gränsen för tabelltypen innehåller nextLink kolumnen i det returnerade promise-objektet en länk för att hämta poster.
successCallback	Funktion	Nej	En funktion som ska anropas när tabellposter hämtas. Se Returvärde
errorCallback	Funktion	Nej	En funktion som ska anropas när åtgärden misslyckas. Ett objekt med följande egenskaper skickas: - errorCode:Nummer. Felkoden som ett positivt decimaltal. Till exempel returneras felkoden som dokumenteras 0x80040333som 2147746611 . - message:Sträng. Ett felmeddelande som beskriver problemet.

Options

Följande systemfrågealternativ stöds: $select, $top, $filter, $expandoch $orderby.

Använd systemfrågealternativet $expand för att styra vilka data från relaterade tabeller som returneras. Om du bara inkluderar namnet på navigeringsegenskapen får du alla egenskaper för relaterade poster. Du kan begränsa de egenskaper som returneras för relaterade poster med hjälp $select av systemfrågealternativet inom parenteser efter namnet på navigeringsegenskapen. Använd det här alternativet för både navigeringsegenskaper med enkelvärde och samlingsvärde . För offline stöds endast kapslade $select alternativ inuti $expand .

Om du vill ange en FetchXML-fråga använder du fetchXml kolumnen för att ange frågan.

Anmärkning

Du måste alltid använda systemfrågealternativet $select för att begränsa de egenskaper som returneras för en tabellpost genom att inkludera en kommaavgränsad lista med egenskapsnamn. Den här metoden är viktig för prestanda. Om du inte anger egenskaper med hjälp $selectav returneras alla egenskaper.

Ange frågealternativ som börjar med ?. Du kan också ange flera systemfrågealternativ genom att använda & för att avgränsa frågealternativen.

När du anger en OData-frågesträng för parametern optionskodar du frågan efter specialtecken.

När du anger en FetchXML-fråga för parametern optionsska du inte koda frågan.

Mer information om hur du definierar parametern options för olika hämtningsscenarier finns i Exempel.

Returvärde

Vid lyckat resultat returnerar ett löftesobjekt till successCallback med följande egenskaper:

Namn	Typ	Description
entities	Matris med JSON-objekt	Varje objekt representerar den hämtade tabellposten som innehåller kolumner och deras värden som key: value par. ID:t för tabellposten hämtas som standard.
nextLink	String	(valfritt) Om antalet poster som hämtas är mer än det värde som anges i parametern maxPageSize i begäran returnerar detta URL:en för att returnera nästa sida med poster.
fetchXmlPagingCookie		(valfritt) För en fetchXml-baserad retrieveMultipleRecords åtgärd med växling där det totala antalet poster är större än växlingsvärdet returnerar det här attributet den växlingscookie som kan användas för en efterföljande fetchXml-åtgärd för att hämta nästa sida med poster.

Attributtyper som inte stöds för OData-frågealternativ i mobil offline

Följande kolumntyper stöds inte när du använder Xrm.WebApi.retrieveMultipleRecords OData-frågesträngsalternativ (till exempel $select och $filter) i mobilt offlineläge. Använd FetchXML om du behöver arbeta med en attributtyp i den här listan över attributtyper som inte stöds.

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

Funktioner som inte stöds i mobil offline

Följande funktioner stöds inte i mobil offline:

• Grupperings- och aggregeringsfunktioner

Filteråtgärder som stöds per attributtyp i mobil offline med FetchXML

Följande åtgärder stöds för alla attributtyper när du arbetar med FetchXML:

• Är lika med (eq)
• Inte lika med (neq)
• Null (null)
• Inte null (not-null)

I följande tabell visas fler åtgärder som stöds för varje attributtyp:

Attributtyp	Åtgärder som stöds
BigInt, Decimal, Double, Heltal	Större än (gt) Större än eller lika med (gte) Mindre än (lt) Mindre än eller lika med (lte)
Booleskt värde, kund	I (in) Inte i (not-in)
EntityName, Picklist, State, Status	Som (like) Inte som (not-like) Börjar med (begins-with) Inte börja med (not-begin-with) Slutar med (ends-with) Slutar inte med (not-end-with) I (in) Inte i (not-in)
Guid, Lookup	I (in) Inte i (not-in) Är lika med användar-ID (eq-userid) Inte lika med användar-ID (ne-userid)
Pengar	Större än (gt) Större än eller lika med (gte) Mindre än (lt) Mindre än eller lika med (lte) I (in) Inte i (not-in)
Ägare	I (in) Inte i (not-in) Är lika med användar-ID (eq-userid) Inte lika med användar-ID (ne-userid) Är lika med användare eller team (eq-useroruserteams)
String	Som (like) Inte som (not-like) Börjar med (begins-with) Inte börja med (not-begin-with) Slutar med (ends-with) Slutar inte med (not-end-with)
DateTime	På eller efter (on-or-after) På (on) På eller före (on-or-before) Idag (today) I morgon (tomorrow) Igår (yesterday) Kommande sju dagar (next-seven-days) Senaste sju dagarna (last-seven-days) Nästa vecka (next-week) Förra veckan (last-week) Den här veckan (this-week) Nästa månad (next-month) Förra månaden (last-month) Den här månaden (this-month) Nästa år (next-year) Förra året (last-year) Detta år (this-year) Senaste X-dagarna (last-x-days) Nästa X-dagar (next-x-days) Senaste X-veckorna (last-x-weeks) Nästa X-veckor (next-x-weeks) Senaste X-månaderna (last-x-months) Nästa X-månader (next-x-months) Senaste X-åren (last-x-years) Nästa X-år (next-x-years) Större än (gt) Större än eller lika med (gte) Mindre än (lt) Mindre än eller lika med (lte)

Examples

Du kan använda metoden retrieveMultipleRecords för att uppnå de flesta scenarier och exempel som nämns i Frågedata med hjälp av webb-API:et. Några av exemplen visas i följande avsnitt.

Grundläggande hämtning av flera

Det här exemplet frågar kontotabelluppsättningen och använder systemfrågealternativen $select och $top för att returnera namnegenskapen för de tre första kontona:

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

Basic hämtar flera med FetchXML

Det här exemplet frågar entiteten account med hjälp 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
    }
);

Hämta eller filtrera efter uppslagsegenskaper

För de flesta navigeringsegenskaper med en enda värde hittar du en beräknad, skrivskyddad egenskap som använder följande namngivningskonvention: _<name>_value där <name> är namnet på den enkelvärdesnavigeringsegenskapen. I filtreringssyfte kan du också använda det specifika värdet för navigeringsegenskapen med ett värde. Dessa syntaxalternativ stöds dock inte för mobila klienter i offlineläge. Använd namnet på navigeringsegenskapen med ett värde för både hämtning och filtrering. Offlineläget stöder inte heller jämförelsen av navigeringsegenskaper till null.

Mer information: Uppslagsegenskaper

Här är kodexempel för båda scenarierna:

För onlinescenario (anslutet till servern)

Det här exemplet frågar kontotabelluppsättningen och använder systemfrågealternativen $select och $filter för att returnera egenskapen name och primarycontactid för konton som har en viss primär kontakt:

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

För scenario med mobil offline

Det här exemplet frågar kontotabelluppsättningen och använder systemfrågealternativen $select och $filter för att returnera egenskapen name och primarycontactid för konton som har en viss primär kontakt när de arbetar i offlineläge:

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

Använda FetchXML för att hämta eller filtrera efter uppslagsegenskaper (online- och offlinescenario)

Använd parametern FetchXML när du är online eller offline för att hämta name egenskapen och primarycontactid för kontoposter som har en primär kontakt som matchar ett villkor:

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

Ange antalet tabeller som ska returneras på en sida

I följande exempel visas hur du använder parametern maxPageSize för att ange att varje sida visar 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
    }
);

I det här exemplet visas tre poster och en länk till nästa sida. Här är ett exempel på utdata från konsolen i webbläsarutvecklarverktygen:

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

Använd frågedelen i URL:en i nextLink egenskapen som värde för parametern options i nästa retrieveMultipleRecords-anrop för att begära nästa uppsättning poster. Ändra eller lägg inte till fler systemfrågealternativ i värdet. För varje efterföljande begäran om fler sidor använder du samma maxPageSize värde som du använde i den ursprungliga hämtningen av flera begäranden. Cachelagra också resultatet som returneras eller värdet för nextLink egenskapen så att appen kan returnera tidigare hämtade sidor.

Om du till exempel vill hämta nästa sida med poster skickar du frågedelen av nextLink URL:en till parametern 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
    }
);

Den här begäran returnerar nästa sida i resultatuppsättningen.

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

Viktigt!

Värdet för egenskapen nextLink är URI-kodat. Om du kodar värdet innan du skickar det orsakar XML-cookieinformationen i URL:en ett fel.

FetchXML-exempel (onlinescenario)

I följande exempel visas hur du använder parametern count i FetchXML för att ange att varje sida visar tre poster.

Anmärkning

FetchXML-växlingscookie returneras endast för onlineåtgärder retrieveMultipleRecords . (Xrm.WebApi.online). Det stöds inte offline.

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

Det här exemplet visar tre poster och returnerar en FetchXML-växlingscookie för att hämta resultatet från nästa sida om det finns fler poster i resultatuppsättningen. Här är ett exempel på utdata från konsolen i webbläsarutvecklarverktygen:

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

Om du vill hämta stora resultatuppsättningar med växling använder du det fetchXmlPagingCookie som visas i följande exempel.

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

Hämta relaterade tabeller genom att expandera navigeringsegenskaper

Använd alternativet $expand systemfråga i navigeringsegenskaperna för att styra de data som returneras från relaterade tabeller. I följande exempel visas hur du hämtar kontakten för alla kontoposter. För relaterade kontaktposter hämtar du bara fälten contactid och 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
    }
);

Föregående kod returnerar ett resultat med ett schema 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"
         }
      }
   ]
}

Anmärkning

På samma sätt som i onlinescenariot använder du alternativet $expand systemfråga för att hämta data från relaterade tabeller offline. Många-till-många-relationer stöds dock inte offline.

Inaktuell metod för scenario med mobil offline

Anmärkning

@odata.nextLink Är inaktuell för scenarier med mobil offline. Även om det fortfarande stöds för befintliga anpassningar ska du inte använda det längre.

En offline -$expand-åtgärd returnerar en @odata.nextLink kommentar som innehåller information om hur du kommer åt den relaterade postens information. Använd parametrarna id, entityTypeoch options för den kommentaren för att konstruera en eller flera ytterligare Xrm.WebApi.offline.retrieveRecord begäranden. Följande kod innehåller ett fullständigt exempel på hur du gör detta:

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

Fler exempel på hur du hämtar flera poster med hjälp av webb-API finns i Fråga efter data med hjälp av webb-API:et.

Relaterade artiklar

Fråga efter data med hjälp av webb-API:et
Xrm.WebApi.retrieveRecord
Xrm.WebApi