Freigeben über

Seitenergebnisse mit FetchXML

Sie können die Anzahl der für jede Anforderung abgerufenen Zeilen einschränken, indem Sie eine Seitengröße festlegen. Mithilfe von Paging können Sie aufeinander folgende Datenseiten abrufen, sodass Sie effizient alle Datensätze abrufen, die den Kriterien einer Abfrage entsprechen.

Die Standard- und maximale Seitengröße beträgt 5.000 für Standardtabellen und 500 für elastische Tabellen. Wenn Sie kein Seitenformat festlegen, gibt Dataverse je nach Tabellentyp jeweils 5.000 oder 500 Datenzeilen zurück. Um mehr Zeilen zu erhalten, müssen Sie zusätzliche Anfragen senden.

Anmerkung

  • Verwenden Sie das Attribut fetch elementtop nicht mit der Seitenerstellung. Diese verschiedenen Methoden zum Einschränken der Ergebnisse einer Abfrage sind nicht kompatibel.
  • Die Reihenfolge spielt eine wichtige Rolle für konsistente Paginationsergebnisse. Erfahren Sie mehr über Sortierung und Paging.

FetchXml-Pagingmodelle

FetchXml verfügt über zwei Pagingmodelle: einfache und paging Cookies:

Einfach

  • Verwendet nur die Attribute fetch elementcount und page
  • Nur für kleine Datasets geeignet
  • Ein Dataset, das größer als 50.000 Datensätze ist, kann nicht zurückgegeben werden.
  • Die Leistung verringert sich, wenn die Anzahl der Zeilen erhöht wird.

Paging-Cookies

Einfache Seiteneinordnung

Fordern Sie die erste Seite an, indem Sie das Fetch-Element-Attributpage auf 1 und das count Attribut auf die Seitengröße festlegen, bevor Sie die Anforderung senden:

<fetch count='3' page='1'>
  <entity name='account'>
    <attribute name='name' />
    <order attribute='name' />
    <order attribute='accountid' />
  </entity>
</fetch>

Um die nächsten drei Datensätze zu erhalten, erhöhen Sie den Wert page und senden Sie eine weitere Anforderung.

<fetch count='3' page='2'>
  <entity name='account'>
    <attribute name='name' />
    <order attribute='name' />
    <order attribute='accountid' />    
  </entity>
</fetch>

Mithilfe von einfachem Paging, manchmal als Legacy-Paging bezeichnet, ruft Dataverse alle Ergebnisse der Abfrage bis zur aktuellen Seite ab. Es wählt die Anzahl der datensätze aus, die für die Seite erforderlich sind, und ignoriert dann den Rest. Diese Methode erleichtert das Zurück- und Vorwärtsblättern durch die Daten oder das Springen zu einer bestimmten Seite. Die Gesamtzahl der Datensätze ist jedoch auf 50.000 beschränkt. Außerdem können komplexe Abfragen und willkürlich sortierte eindeutige Abfrageergebnisse zu Leistungsproblemen führen.

Einfaches Paging eignet sich gut für kleine Datasets. Aber da die Anzahl der Zeilen im Dataset zunimmt, leidet die Leistung. Die Gesamtzahl der Zeilen, die Sie mithilfe des einfachen Paging abrufen können, beträgt 50.000. Um in allen Fällen optimale Leistung zu erzielen, verwenden Sie Paging-Cookies konsistent.

Paging-Cookies

Wenn nach dem Anfordern der ersten Seite weitere Zeilen abgerufen werden müssen, gibt Dataverse in der Regel ein Paging-Cookie zurück, das in den folgenden Anforderungen für die nächsten Seiten verwendet werden soll.

Das Paging-Cookie enthält Daten zum ersten und letzten Datensatz in den Ergebnissen. Es hilft Dataverse, die nächste Datenzeile so schnell wie möglich abzurufen. Verwenden Sie das Paging-Cookie, wenn es verfügbar ist. Ändern Sie die Daten im Auslagerungscookie nicht. Legen Sie den Wert auf das Fetch-Element-Attributpaging-cookie fest und erhöhen Sie den page Attributwert für nachfolgende Anforderungen.

Abfragen, die keine Seitencookies unterstützen

Einige Abfragen unterstützen keine Seitencookies. Wenn eine Abfrage keine Paging-Cookies unterstützt, gibt die Abfrage keinen Paging-Cookiewert mit dem Ergebnis zurück. Abfragen, die mithilfe eines link-entity-Attributs sortiert sind, unterstützen möglicherweise keine Paging-Cookies.

Wenn Dataverse kein Seitenpaginierungs-Cookie zurückgibt, fällt das Seitenpaginierungsmodell auf eine einfache Paginierung zurück, mit allen damit verbundenen Einschränkungen.

Wie Sie Paging-Cookies verwenden, hängt davon ab, ob Sie das SDK für .NET oder Web-API verwenden.

Die folgende RetrieveAll statische Methode gibt alle Datensätze zurück, die der FetchXML-Abfrage entsprechen. Es sendet mehrere Anforderungen, wenn die Anzahl der Datensätze die Seitengröße überschreitet.

Nach jeder Anforderung überprüft die Methode die EntityCollection.MoreRecords-Eigenschaft , um festzustellen, ob weitere Datensätze den Kriterien entsprechen. Wenn mehr Datensätze vorhanden sind, legt die Methode den Wert der zurückgegebenen EntityCollection.PagingCookie-Eigenschaft auf das paging-cookie-Attribut des Fetch-Elements fest und sendet eine weitere Anforderung.

/// <summary>
/// Returns all records matching the criteria
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance.</param>
/// <param name="fetchXml">The fetchXml Query string</param>
/// <param name="pageSize">The page size to use. Default is 5,000</param>
/// <returns>All the records that match the criteria</returns>
static EntityCollection RetrieveAll(IOrganizationService service, string fetchXml, int pageSize = 5000)
{

    // The records to return
    List<Entity> entities = new();

    XElement fetchNode = XElement.Parse(fetchXml);

    int page = 1; //Start with page 1

    //Set the page
    fetchNode.SetAttributeValue("page", page);

    // Set the page size
    fetchNode.SetAttributeValue("count", pageSize);

    while (true)
    {
        // Get the page
        EntityCollection results = service.RetrieveMultiple(new FetchExpression(fetchNode.ToString()));

        entities.AddRange(results.Entities);

        if (!results.MoreRecords)
        {
            break;
        }

        // Set the fetch paging-cookie attribute with the paging cookie from the previous query
        fetchNode.SetAttributeValue("paging-cookie", results.PagingCookie);

        fetchNode.SetAttributeValue("page", ++page);
    }
    return new EntityCollection(entities);
}

Um FetchXML-Abfragen zu testen, passen Sie das Beispiel in der Schnellstartanleitung an: Führen Sie ein SDK für .NET-Anforderung (C#) mit den folgenden Schritten aus:

  1. Fügen Sie die statische RetrieveAll-Methode zur Program-Klasse hinzu.
  2. Ändern Sie die Main Methode wie im folgenden Code dargestellt:
static void Main(string[] args)
{
    using (ServiceClient serviceClient = new(connectionString))
    {
        if (serviceClient.IsReady)
        {
            //WhoAmIResponse response = 
            //    (WhoAmIResponse)serviceClient.Execute(new WhoAmIRequest());

            //Console.WriteLine("User ID is {0}.", response.UserId);

            string fetchQuery = @"<fetch count='3' page='1'>
                <entity name='contact'>
                    <attribute name='fullname'/>
                    <attribute name='jobtitle'/>
                    <attribute name='annualincome'/>
                    <order descending='true' attribute='fullname'/>
                </entity>
        </fetch>";

            EntityCollection records = RetrieveAll(service: serviceClient,
                        fetchXml: fetchQuery,
                        pageSize: 25);

            Console.WriteLine($"Success: {records.Entities.Count}");
        }
        else
        {
            Console.WriteLine(
                "A web service connection was not established.");
        }
    }

    // Pause the console so it does not close.
    Console.WriteLine("Press the <Enter> key to exit.");
    Console.ReadLine();
}

Anmerkung

Diese Abfrage gibt alle Datensätze zurück, die den Kriterien entsprechen. Stellen Sie sicher, dass Sie Filterelemente einschließen, um die Ergebnisse einzuschränken.

Lesen Sie die folgenden wichtigen Informationen zur Verwendung einer Verbindungszeichenfolge im Anwendungscode.

Wichtig

Microsoft empfiehlt, den sichersten verfügbaren Authentifizierungsflow zu verwenden. Der in diesem Artikel beschriebene Authentifizierungsablauf erfordert ein sehr hohes Maß an Vertrauen in die Anwendung und birgt Risiken, die in anderen Flows nicht vorhanden sind. Sie sollten diesen Flow nur verwenden, wenn andere, sicherere Flows, z. B. verwaltete Identitäten, nicht funktionsfähig sind.

Anordnung und Auslagerung

Wie eine Seite geordnet ist, hat eine große Auswirkung auf die Datenverarbeitung beim Paging. Wenn die Informationen zur Reihenfolge der Ergebnisse nicht eindeutig sind, kann Dataverse seitenweise Daten nicht konsistent oder effizient zurückgeben.

Geben Sie eine Reihenfolge für Ihre Abfrage an. Wenn Sie bei FetchXml Ihrer Abfrage keine Sortierelemente hinzufügen, fügt Dataverse eine Sortierung basierend auf dem Primärschlüssel der Tabelle hinzu. Dies ist bei QueryExpression jedoch nicht der Fall. Wenn Ihre Abfrage distinct-Ergebnisse angibt, werden außerdem keine Primärschlüsselwerte zurückgegeben, weshalb Dataverse diese Standardreihenfolge nicht hinzufügen kann. Sie müssen eine Seitenreihenfolge angeben. Ohne Angabe einer Reihenfolge werden distinct-Abfrageergebnisse möglicherweise in zufälliger Reihenfolge zurückgegeben. OData bietet keine Option zum Zurückgeben eindeutiger Ergebnisse, Sie sollten beim Abruf seitierter Ergebnisse jedoch trotzdem eine Sortierung anwenden.

Die Speicherverwaltung ist dynamisch. Jede Anforderung wird bei Eingang einzeln bewertet. Ein Paging-Cookie übermittelt Dataverse die vorherige Seite. Mit diesen Paging-Cookie-Daten kann Dataverse nach dem letzten Datensatz auf der vorherigen Seite mit dem nächsten beginnen.

Die Speicherverwaltung wird in Zukunft am besten funktionieren. Wenn Sie zurückgehen und eine Seite abrufen, die Sie zuvor abgerufen haben, können die Ergebnisse unterschiedlich sein, da seit dem letzten Abruf der Seite Datensätze hinzugefügt, gelöscht oder geändert werden konnten. Mit anderen Worten: Wenn Ihre Seitengröße 50 beträgt und Sie zurückgehen, erhalten Sie 50 Datensätze, es handelt sich jedoch möglicherweise nicht um dieselben 50 Datensätze. Wenn Sie die Seiten eines Dataset weiter durchgehen, können Sie davon ausgehen, dass alle Datensätze in einer konsistenten Reihenfolge zurückgegeben werden.

Die deterministische Sortierung ist wichtig

Deterministische Reihenfolge bedeutet, dass es eine Möglichkeit gibt, eine Reihenfolge konsistent zu berechnen. Bei einem bestimmten Datensatzsatz werden die Datensätze immer in derselben Reihenfolge zurückgegeben. Wenn Sie eine einheitliche Reihenfolge und ein Paging benötigen, müssen Sie einige eindeutige Werte oder Kombinationen aus Spaltenwerten einschließen und eine Reihenfolge angeben, in der sie ausgewertet werden sollen.

Nichtdeterministisches Beispiel

Schauen wir uns ein Beispiel an, das nichtdeterministisch ist. Dieses Dataset enthält nur Status und Status-Informationen und ist gefiltert, um nur Datensätze in einem offenen Status zurückzugeben. Die Ergebnisse sind nach Status geordnet. Die ersten drei Seiten werden angefordert. Die Ergebnisse sehen folgendermaßen aus:

Bundesstaat Status Seite
Öffnen Aktiv 1 Starten
Öffnen Aktiv 1
Öffnen Aktiv 1 Ende
Öffnen Aktiv
Öffnen Aktiv
Öffnen Inaktiv
Öffnen Inaktiv

Das Auslagerungs-Cookie speichert Informationen über den letzten Datensatz auf der Seite. Wenn die nächste Seite angefordert wird, ist der letzte Datensatz der ersten Seite nicht enthalten. Aufgrund der nichtdeterministischen Daten gibt es jedoch keine Garantie dafür, dass die beiden anderen Datensätze auf der ersten Seite nicht auf der zweiten Seite enthalten sind.

Um eine deterministische Reihenfolge zu erreichen, fügen Sie Reihenfolgen für Spalten hinzu, die eindeutige oder halbeindeutige Werte enthalten.

Deterministisches Beispiel

Diese Abfrage ähnelt der nichtdeterministischen Abfrage, enthält jedoch die Spalte Fall-ID, die eindeutige Werte enthält. Es wird auch nach Status, aber auch nach Fall-ID sortiert. Die Ergebnisse sehen folgendermaßen aus:

Bundesstaat Status Fall-ID Seite
Öffnen Aktiv Case-0010 1 Starten
Öffnen Aktiv Case-0021 1
Öffnen Aktiv Case-0032 1 Ende
Öffnen Aktiv Case-0034
Öffnen Aktiv Case-0070
Öffnen Inaktiv Case-0015
Öffnen Inaktiv Case-0047

Auf der nächsten Seite hat das Cookie Case-0032 als letzten Datensatz auf der ersten Seite gespeichert, sodass Seite zwei mit dem nächsten Datensatz nach diesem Datensatz startet. Die Ergebnisse sehen folgendermaßen aus:

Bundesstaat Status Fall-ID Seite
Öffnen Aktiv Case-0010 1 Starten
Öffnen Aktiv Case-0021 1
Öffnen Aktiv Case-0032 1 Ende
Öffnen Aktiv Case-0034 2 Starten
Öffnen Aktiv Case-0070 2
Öffnen Inaktiv Case-0015 2 Ende
Öffnen Inaktiv Case-0047

Da diese Abfrage eindeutige Spaltenwerte anordnet, ist die Reihenfolge konsistent.

Best Practices für Bestellungen beim Daten-Seitentransfer

Anmerkung

Wenn möglich, sollten Abfragen nach dem Primärschlüssel für die Tabelle sortiert werden, da Dataverse standardmäßig für die Sortierung nach dem Primärschlüssel optimiert ist. Die Sortierung nach nicht eindeutigen oder komplexen Feldern führt zu übermäßigem Overhead und langsameren Abfragen.

Wenn Sie einen begrenzten Datensatz abrufen, der in einer Anwendung angezeigt werden soll, oder wenn Sie mehr als 5000 Datenzeilen (500 bei elastischen Tabellen) zurückgeben müssen, müssen Sie die Ergebnisse paginieren. Die Auswahl, die Sie bei der Bestimmung der Reihenfolge der Ergebnisse treffen, kann bestimmen, ob sich die Zeilen auf jeder von Ihnen abgerufenen Datenseite mit anderen Seiten überschneiden. Ohne die richtige Reihenfolge kann derselbe Datensatz auf mehr als einer Seite erscheinen.

Um zu verhindern, dass derselbe Datensatz auf mehr als einer Seite erscheint, wenden Sie die folgenden Best Practices an:

Am besten fügen Sie eine Spalte mit einem eindeutigen Bezeichner ein. Zum Beispiel:

  • Primärschlüsselsäulen der Tabellen
  • Autonummer-Spalten
  • Benutzer-/Kontakt-IDs

Wenn Sie keine Spalte mit einem eindeutigen Bezeichner einschließen können, schließen Sie mehrere Felder ein, die höchstwahrscheinlich zu eindeutigen Kombinationen führen. Zum Beispiel:

  • Vorname + Nachname + E-Mail-Adresse
  • Vollständiger Name + E-Mail-Adresse
  • E-Mail-Adresse + Firmenname

Anti-Muster für Reihenfolgen bei der Paginierung von Daten

Die folgenden Auswahlmöglichkeiten für die Sortierung sollten Sie vermeiden:

  • Bestellungen ohne eindeutige Bezeichner

  • Sortierungen in berechneten Feldern

  • Sortierungen mit einzelnen oder mehreren Feldern, die wahrscheinlich keine Eindeutigkeit bieten, wie:

    • Status und Zustand
    • Auswahlmöglichkeiten oder Ja/Nein
    • Werte eigenständig benennen. Zum Beispiel name, firstname, lastname
    • Textfelder wie Titel, Beschreibungen und mehrzeiliger Text
    • Nicht eindeutige Nummernfelder

Nächste Schritte,

Erfahren Sie, wie Sie Daten aggregieren können.

Aggregatdaten

  • Last updated on