Seitenergebnisse mit OData

Verwenden Sie die OData-Paginierung mit dem Anforderungsheader Prefer: odata.maxpagesize, um die Anzahl der Datensätze zu steuern, die von der Microsoft Dataverse Web-API zurückgegeben werden. Wenn Sie keine Zahl angeben, gibt jede Anforderung möglicherweise bis zu 5.000 Tabellenzeilen zurück. Für Standard- und elastische Tabellen können Sie eine maximale Seitengröße bis zu 5.000 angeben. Der Dienst ignoriert Anforderungen für maximale Seitengröße, die größer als 5.000 sind, sowohl für Standardtabellen als auch für elastische Tabellen.

Im folgenden Beispiel werden die ersten zwei Kontaktdatensätze abgerufen.

Anforderung:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2

Antwort:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
    "value": [
        {
            "@odata.etag": "W/\"72201545\"",
            "fullname": "Yvonne McKay (sample)",
            "contactid": "49b0be2e-d01c-ed11-b83e-000d3a572421"
        },
        {
            "@odata.etag": "W/\"80648695\"",
            "fullname": "Susanna Stubberod (sample)",
            "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Wenn mehr Datensätze als angefordert vorhanden sind, stellt die Annotation @odata.nextLink eine URL bereit, die Sie mit GET verwenden können, um die nächste Datenseite zurückzugeben, wie im folgenden Beispiel gezeigt:

Anforderung:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2

Antwort:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
    "value": [
        {
            "@odata.etag": "W/\"80648710\"",
            "fullname": "Nancy Anderson (sample)",
            "contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd"
        },
        {
            "@odata.etag": "W/\"80648724\"",
            "fullname": "Maria Campbell (sample)",
            "contactid": "74bf4d48-34cb-ed11-b596-0022481d68cd"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%223%22%20pagingcookie=%22%253ccookie%2520page%253d%25222%2522%253e%253ccontactid%2520last%253d%2522%257bF2318099-171F-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257bBB55F942-161F-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Sie sollten die zurückgegebenen Ergebnisse oder den @odata.nextLink-URL-Wert zwischenspeichern und ihn verwenden, um zu vorherigen Seiten zurückzukehren.

Ändern Sie den URL-Wert @odata.nextLink nicht und fügen Sie ihm keine Abfrageoptionen hinzu. Verwenden Sie für jede nachfolgende Anforderung für weitere Seiten den gleichen odata.maxpagesize Einstellungswert, der in der ursprünglichen Anforderung verwendet wird. Sie können so lange durch die Daten blättern, bis keine @odata.nextLink Anmerkung in den Ergebnissen enthalten ist.

In den früheren Beispielen enthält der Wert des $skiptoken Parameters im @odata.nextLink URL-Wert codierte Informationen. Der Server legt diese codierten Informationen fest, um das Paging zu steuern. Ändern Sie die codierten Informationen nicht, oder codieren Sie sie weiter. Verwenden Sie den angegebenen URL-Wert, um die nächste Seite abzurufen.

Verwenden Sie beim Paging von Datensätzen nicht die Abfrageoption "$top".

Verwenden Sie die Abfrageoption $top, um die Anzahl der zurückgegebenen Ergebnisse zu begrenzen. Verwenden Sie nicht $top mit dem Anfrage-Header Prefer: odata.maxpagesize. Wenn Sie beide angeben, wird $top ignoriert.

Das folgende Beispiel gibt nur die ersten drei Kontozeilen zurück:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=3

Anordnung und Auslagerung

Wie eine Seite angeordnet ist, macht beim Paginieren von Daten einen großen Unterschied. Wenn die Informationen darüber, wie die Ergebnisse geordnet sind, mehrdeutig 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 Auslagerungsreihenfolge angeben. Ohne Angabe einer Reihenfolge werden distinct-Abfrageergebnisse möglicherweise in zufälliger Reihenfolge zurückgegeben. OData bietet keine Option, um eindeutige Ergebnisse zurückzugeben, aber Sie sollten dennoch eine Reihenfolge anwenden, wenn Sie paginierte Ergebnisse abrufen.

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

Die Auslagerung funktioniert zukünftig am besten. 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:

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:

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:

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

Best Practices für Reihenfolgen beim Auslagern von Daten

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üsselspalten der Tabelle
• AutoWert-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 beim Auslagern von Daten

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

• Bestellungen ohne eindeutige Bezeichner

• Befehle für berechnete Felder

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

  • Status und Zustand
  • Auswahlmöglichkeiten oder Ja/Nein
  • Werte selbst 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.