Freigeben über

Datenabfrage mit Web-API

  • Artikel

Wenn Sie die Web-API verwenden, um eine Abfrage gegen eine Dataverse-Tabelle zu erstellen, müssen Sie die folgenden Entscheidungen treffen:

Entscheidung Beschreibung
Spalten auswählen Die Daten mit den Spalten, die zurückzugebenden werden sollen
Tabellen verbinden Welche verwandten Tabellen in die Ergebnisse aufgenommen werden sollen
Bestellzeilen Welche Bestellung die Ergebnisse zurückgeben sollen
Filterzeilen Welche Datenzeilen zurückzugebenden werden sollen
Seitenergebnisse Anzahl Datenzeilen für die Rückgabe
Aggregatdaten So gruppieren und aggregieren Sie die zurückgegebenen Daten
Anzahl der Zeilen So werden die Anzahl der Zeilen gezählt

In diesem Artikel geht es um das Abfragen von Daten, die in Tabellen gefunden wurden. Sie können auch Web-API verwenden, um Daten über Tabellendefinitionen oder Entitäts-Metadaten abzufragen. Die Struktur der Daten ist unterschiedlich, sodass viele der hier beschriebenen Funktionen nicht zutreffen. Weitere Informationen: Abfrage von Tabellendefinitionen über die Web-API und Definitionen des Abfrageschemas

Sammlungen von Entitäten

Jede Abfrage beginnt mit einer Sammlung von Entitäten. Entitätssammlungen können sein:

EntitySet-Ressourcenen

Um alle in Ihrer Umgebung verfügbaren EntitySet-Ressourcen zu finden, senden Sie eine GET-Anfrage an das Web-API Servicedokument:

Anforderung:

GET [Organization URI]/api/data/v9.2/
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata",
    "value": [
        {
            "name": "aadusers",
            "kind": "EntitySet",
            "url": "aadusers"
        },
        {
            "name": "accountleadscollection",
            "kind": "EntitySet",
            "url": "accountleadscollection"
        },
        {
            "name": "accounts",
            "kind": "EntitySet",
            "url": "accounts"
        },
      ... <Truncated for brevity>
   [
}

Tipp

Diese Werte sind in der Regel der Pluralname der Tabelle, aber sie können auch anders lauten. Verwenden Sie diese Abfrage, um sicherzustellen, dass Sie den richtigen EntitySet-Ressourcennamen verwenden.

Um Daten aus dem Account EntityType abzurufen, beginnen Sie mit der Ressource accounts EntitySet.

GET [Organization URI]/api/data/v9.2/accounts?$select=name

Gefilterte Sammlungen

Sie können jede Sammlung von Entitäten abfragen, die durch eine Navigationseigenschaft mit Sammlungswert eines angegebenen Datensatzes dargestellt werden.

Wenn Sie Daten aus dem Konto EntityType abrufen möchten, bei dem ein bestimmter Benutzer der OwningUser ist, können Sie die Navigationseigenschaft user_accounts mit dem Sammlungswert aus dem angegebenen Systemuser Datensatz verwenden.

GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name

Um den Namen der Navigationseigenschaft mit dem Wert einer Sammlung zu finden:

OData-Abfrageobtionen

Die folgende Tabelle beschreibt die OData Abfrageoptionen, die die Dataverse Web-API unterstützt.

Option Verwendet um Weitere Informationen
$select Fordern Sie einen bestimmten Satz von Eigenschaften für jede Entität oder jeden komplexen Typ an. Spalten auswählen
$expand Geben Sie die zugehörigen Ressourcen an, die in Übereinstimmung mit den abgerufenen Ressourcen eingeschlossen werden sollen. Tabellen verbinden
$filter Eine Sammlung von Ressourcen filtern. Filterzeilen
$orderby Fordern Sie Ressourcen in einer bestimmten Reihenfolge an. Bestellzeilen
$apply Daten gruppieren und aggregieren. Aggregatdaten
$top Die Anzahl der Elemente in der abgefragten Sammlung, die in das Ergebnis einbezogen werden sollen definieren. Verwenden Sie nicht $top, wenn Sie Seiten mit Daten abrufen. Verwenden Sie die Abfrageoption $top
$count Fordern Sie eine Anzahl der übereinstimmenden Ressourcen an, die in den Ressourcen in der Antwort enthalten sind. Anzahl der Zeilen

Sie können mehrere Optionen auf eine Abfrage anwenden. Trennen Sie Abfrageoptionen vom Ressourcenpfad durch ein Fragezeichen (?). Trennen Sie jede Option nach der ersten mit einem kaufmänischen und (&). Bei Optionsnamen wird zwischen Groß- und Kleinschreibung unterschieden.

Das Dataverse Web-API unterstützt diese OData Abfrageoptionen nicht: $skip, $search, $format.

Verwendung von Parameteraliasen mit Systemabfrageoptionen

Sie können Parameteraliase für $filter- und $orderby-Systemabfrageoptionen verwenden, aber derzeit nicht innerhalb der $expand-Option. Parameter-Aliase lassen es zu, dass Sie denselben Wert mehrfach in einer Anfrage verwenden. Wenn dem Alias kein Wert zugeordnet wurde, wird angenommen, dass er NULL ist.

Ohne Parameteraliase:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null

Mit Parameteraliassen:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=@p1 asc,@p2 desc
&$filter=@p1 ne @p3&@p1=revenue&@p2=name

Sie können auch Parameteraliase verwenden, wenn Sie Funktionen verwenden. Weitere Informationen: Verwenden von Web-API-Funktionen

Spalten auswählen

Wichtig

Wenn Sie Daten abfragen, ist es wichtig, die Menge der zurückgegebenen Daten zu begrenzen, um die Leistung zu optimieren. Nur die Spalten mit den erforderlichen Daten auswählen.

Verwenden Sie die $select Abfrageoption, um auszuwählen, welche Spalten mit Ihrer Abfrage zurückgegeben werden sollen. In OData wird jede Spalte als eine Eigenschaft dargestellt. Wenn Sie keine $select Abfrageoption einfügen, werden alle Eigenschaften zurückgegeben.

Das folgende Beispiel fragt die Eigenschaften name und revenue aus einer Zeile der Ressource accounts EntitySet ab:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)",
    "value": [
        {
            "@odata.etag": "W/\"81052965\"",
            "name": "Litware, Inc. (sample)",
            "revenue": 20000.0000,
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "4624eff7-53d3-ed11-a7c7-000d3a993550"
        }
    ]
}

Die Primärschlüsseleigenschaft wird immer zurückgegeben, sodass Sie sie nicht in Ihre $select aufnehmen müssen. In diesem Beispiel ist accountid der Primärschlüssel.

Andere Eigenschaftswerte können ebenfalls enthalten sein. In diesem Fall ist die _transactioncurrencyid_value Nachschlageeigenschaft für die zugehörige Währung (Transaktionswährung)-Tabelle/Entitätsreferenz enthalten, weil revenue eine Währungseigenschaft ist.

Welche Eigenschaften sind verfügbar?

Alle verfügbaren Eigenschaften für eine Entität finden Sie im $metadata Service Dokument. Weitere Informationen: WEB-API Eigenschaften

Die Typen der Entitäten, die in Dataverse enthalten sind, werden in Web API Entity Type Reference beschrieben.

Tipp

Der einfachste Weg, schnell herauszufinden, welche Eigenschaften verfügbar sind, besteht darin, eine Anfrage mit der $top Abfrageoption mit dem Wert 1 zu senden, ohne $select zu verwenden.

Formatierte Werte

Formatierte Werte sind auf dem Server generierte Zeichenfolgenwerte, die Sie in Ihrer Anwendung verwenden können. Formatierte Werte schließen ein:

  • Die lokalisierten Bezeichnungen für die Spalten „Auswahl“, „Auswahl“, „Ja/Nein“, „Status“ und „Statusgrund“
  • Der primäre Namenswert für Such- und Eigentümereigenschaften
  • Währungswerte mit Währungssymbolen
  • Formatierte Datumswerte in der Zeitzone des Benutzers

Um formatierte Werte in Ihren Ergebnissen zu integrieren, nutzen Sie den Aforderungsheader:

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Formatierte Werte sind eine von mehreren Anmerkungen, die Sie anfordern können. Verwenden Sie Prefer: odata.include-annotations="*", um alle Anmerkungen einzuschließen. Weitere Informationen: Anforderungsanmerkungen

Der formatierte Wert wird mit dem Datensatz mit einer Anmerkung zurückgegeben, die dieser Konvention folgt:

<property name>@OData.Community.Display.V1.FormattedValue

Zum Beispiel:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue,_primarycontactid_value,customertypecode,modifiedon
&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Die folgende Tabelle beschreibt die Werte und formatierten Werte, die für die angeforderten Eigenschaften zurückgegeben werden.

Eigenschaften Wert Formatierter Wert
name Litware, Inc. (sample) Nein
revenue 20000.0000 $20,000.00
_primarycontactid_value 70bf4d48-34cb-ed11-b596-0022481d68cd Susanna Stubberod (sample)
customertypecode 1 Competitor
modifiedon 2023-04-07T21:59:01Z 4/7/2023 2:59 PM
_transactioncurrencyid_value 228f42f8-e646-e111-8eb7-78e7d162ced1 US Dollar
accountid 78914942-34cb-ed11-b596-0022481d68cd Nein

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)",
    "value": [
{
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "revenue@OData.Community.Display.V1.FormattedValue": "$20,000.00",
            "revenue": 20000.0000,
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "Competitor",
            "customertypecode": 1,
            "modifiedon@OData.Community.Display.V1.FormattedValue": "4/7/2023 2:59 PM",
            "modifiedon": "2023-04-07T21:59:01Z",
            "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

Suche Eigenschaftsdaten

Wenn eine Suchfeld-Eigenschaft eine Beziehung mit mehreren Tabellen oder eine polymorphe Beziehung darstellt, müssen Sie spezielle Anmerkungen anfordern, um festzustellen, welche Tabelle die entsprechenden Daten enthält.

Beispielsweise enthalten viele Tabellen Datensätze, die Benutzer oder Teams besitzen können. Eigentumsdaten werden in einer Suchfeld-Spalte mit dem Namen ownerid gespeichert. Diese Spalte ist eine einwertige Navigationseigenschaft in OData. Sie könnten $expand verwenden, um einen Join zu erstellen, um diesen Wert zu erhalten, aber Sie können $select nicht verwenden. Sie können jedoch die entsprechende _ownerid_value Lookup-Eigenschaft mit $select verwenden.

Wenn Sie die Suchfeld-Eigenschaft _ownerid_value mit Ihrer $select einschließen, wird ein GUID-Wert zurückgegeben. Dieser Wert sagt Ihnen nicht, ob der Eigentümer des Datensatzes ein Benutzer oder ein Team ist. Sie müssen Anmerkungen anfordern, um diese Daten zu erhalten.

Um diese Anmerkungen in Ihren Ergebnissen zu integrieren, nutzen Sie den Anforderungsheader:

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

Tipp

Oder Sie können Prefer: odata.include-annotations="*" verwenden, um alle Anmerkungen einzuschließen. Weitere Informationen: Anforderungsanmerkungen

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,_ownerid_value&$top=2
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

Die folgende Antwort gibt zwei verschiedene Kontodatensätze zurück. Eine team steht für den ersten und eine systemuser für den zweiten. Die Anmerkung _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname liefert diese Informationen.

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_ownerid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81550512\"",
            "name": "Adventure Works (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "team",
            "_ownerid_value": "39e0dbe4-131b-e111-ba7e-78e7d1620f5e",
            "accountid": "1adef0b8-54d3-ed11-a7c7-000d3a993550"
        },
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
            "_ownerid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}
  • <lookup property name>@Microsoft.Dynamics.CRM.lookuplogicalname ist der logische Name der Bezugstabelle.
  • <lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty ist der Name der entsprechenden einwertigen Navigationseigenschaft. Sie können $expand mit diesem Wert in einer anderen Anfrage verwenden, um weitere Daten aus dem verknüpften Datensatz abzurufen.

Tabellen verbinden

Um zu steuern, welche Daten aus den Datensätzen der Bezugstabelle zurückgegeben werden, verwenden Sie die Option $expand Abfrage mit Navigationseigenschaften.

  • Sie können bis zu 15 $expand-Optionen in eine Abfrage aufnehmen. Jede $expand-Option erstellt eine Verknüpfung, die die Leistung beeinträchtigen kann.
  • Abfragen, die Navigationseigenschaften mit Sammlungswert erweitern, geben möglicherweise zwischengespeicherte Daten für die Eigenschaften zurück, die die letzten Änderungen nicht widerspiegeln. Es wird empfohlen, eine If-None-Match-Kopfzeile mit Wert null zu verwenden, um Browserzwischenspeichern zu überschrieben. Weitere Informationen hierzu: HTTP-Header.

Die folgende Tabelle beschreibt die Abfrageoptionen, die Sie in bestimmten $expand-Optionen anwenden können:

Option Beschreibung
$select Wählen Sie aus, welche Eigenschaften zurückgegeben werden. Weitere Informationen: Spalten auswählen
$filter Begrenzen Sie für sammlungswertige Navigationseigenschaften die zurückgegebenen Datensätze. Weitere Informationen: Filterzeilen
$orderby Steuern Sie für sammlungswertige Navigationseigenschaften die Reihenfolge zurückgegebener Datensätze. Wird nicht mit verschachteltem $expand unterstützt. Weitere Informationen: Verschachteltes $expand auf sammlungswertigen Navigationseigenschaften
$top Beschränken Sie für sammlungswertige Navigationseigenschaften die Anzahl zurückgegebener Datensätze. Wird nicht mit verschachteltem $expand unterstützt. Weitere Informationen: Verschachteltes $expand auf sammlungswertigen Navigationseigenschaften
$expand Erweitern Sie die Navigationseigenschaften im verknüpften Entitätssatz. Die Verwendung von $expand in einer $expand wird als verschachtelte $expand bezeichnet. Weitere Informationen: Verschachtelte Erweiterung von einwertigen Navigationseigenschaften & Verschachteltes $expand auf sammlungswertigen Navigationseigenschaften

Diese Optionen sind eine Teilmenge der Systemabfrageoptionen, die im Abschnitt 11.2.4.2.1 Optionen erweitern von OData Version 4.0 Part 1: Protocol Plus Errata 02 beschrieben werden. Die Optionen $skip, $count, $search und $levels werden für die Dataverse-Web-API nicht unterstützt.

Verwenden Sie diese Optionen mit $expand, indem Sie sie in Klammern nach dem Namen der Navigationseigenschaft hinzufügen. Trennen Sie jede Option mit einem Semikolon (;).

Beispielsweise in der folgenden Abfrage:

  • Weisen Sie die account.name Eigenschaft neu zu

  • Teilt die AccountTasks sammlungswertigen Navigationseigenschaftsanfrage:

    • Die task.subject-Eigenschaft
    • Wo task.subject die Zeichenfolge „Task“ enthält
    • Sortiert nach task.createdon Datum, absteigend
/accounts?$select=name&$expand=Account_Tasks($select=subject;$filter=contains(subject,'Task');$orderby=createdon desc)

Spalten mit $select begrenzen

Begrenzen Sie die zurückgegebenen Spalten immer mit $select, wenn Sie $expand in einer Anfrage verwenden. Die folgende Abfrage gibt zum Beispiel die Werte contact.fullname und task.subject in den erweiterten Ergebnissen des Typs account zurück:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)
Prefer: odata.maxpagesize=1
If-None-Match: null
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

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

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(fullname),Account_Tasks(subject))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
            },
            "Account_Tasks": [
                {
                    "@odata.etag": "W/\"80649460\"",
                    "subject": "Task 1 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "f68393c1-34cb-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Unterschiede zwischen Navigationseigenschaftstypen

Es ist wichtig, daran zu denken, dass es zwei Typen von Navigationseigenschaften gibt. Weitere Informationen: Web API-Navigationseigenschaften

  • Einzelwertige Navigationseigenschaften entsprechen Suchattributen, die N:1-Beziehungen unterstützen und eine Referenz auf einen anderen Datensatz ermöglichen.

  • Sammlungswertige Navigationseigenschaften entsprechen 1:n- oder n:n-Beziehungen.

Das Erweitern einer sammlungswertigen Navigationseigenschaft kann die Größe der Antwort auf eine Weise vergrößern, die schwer vorhersehbar ist. Es ist wichtig, dass Sie Grenzwerte einschließen, um zu steuern, wie viele Daten zurückgegeben werden. Sie können die Anzahl der Datensätze mit Hilfe der Paginierung begrenzen. Weitere Informationen: Seite Ergebnisse

Es gibt einen signifikanten Unterschied darin, wie Paging auf verschachtelte $expand-Optionen angewendet wird, die auf Navigationseigenschaften mit Sammlungswert angewendet werden. Weitere Informationen: Sammlungswertige Navigationseigenschaften erweitern

Einzelwertige Navigationseigenschaften erweitern

Das folgende Beispiel zeigt, wie Kontaktdatensätze abgerufen werden, einschließlich des primären Kontakts und des Benutzers, der die Datensätze erstellt hat.

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)  
Prefer: odata.maxpagesize=2
If-None-Match: null
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0  
  
{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(contactid,fullname),createdby(fullname))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "fullname": "Susanna Stubberod (sample)"
            },
            "createdby": {
                "fullname": "System Administrator",
                "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
            }
        },
        {
            "@odata.etag": "W/\"80649580\"",
            "name": "Adventure Works (sample)",
            "accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd",
                "fullname": "Nancy Anderson (sample)"
            },
            "createdby": {
                "fullname": "System Administrator",
                "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Die createdby einwertige Navigationseigenschaft gibt eine Instanz des systemuser EntityType zurück. Sowohl systemuserid als auch ownerid-Eigenschaften werden zurückgegeben. Dies liegt daran, dass systemuser vom Principal EntityType erbt und den ownerid Primärschlüssel mit Team-EntityType über diese Vererbung teilt.

Die Benutzer (SystemUser)-Tabelle hat jedoch den Primärschlüssel SystemUserId. Die beiden Eigenschaften systemuserid und ownerid haben denselben Wert. Weitere Informationen: EntityType-Vererbung

Referenzen zurückgeben

Anstatt Daten zurückzugeben, können Sie auch Verweise oder Links zu den zugehörigen Datensätzen zurückgeben, indem Sie die einwertige Navigationseigenschaft mit der /$ref Option erweitern. Das folgende Beispiel gibt JSON-Objekte mit einer @odata.id-Eigenschaft zurück, die eine URL für jeden primären Kontakt enthält.

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid/$ref  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0  
  
{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid,primarycontactid/$ref())",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "@odata.id": "[Organization URI]/api/data/v9.2/contacts(70bf4d48-34cb-ed11-b596-0022481d68cd)"
            }
        },
        {
            "@odata.etag": "W/\"80649580\"",
            "name": "Adventure Works (sample)",
            "_primarycontactid_value": "72bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "@odata.id": "[Organization URI]/api/data/v9.2/contacts(72bf4d48-34cb-ed11-b596-0022481d68cd)"
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid/$ref&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Sie können die /$ref-Option nur mit Einzelwert-Navigationseigenschaften verwenden. Wenn Sie sie mit einer sammlungswertigen Navigationseigenschaft verwenden, erhalten Sie den folgenden Fehler:

{
    "error": {
        "code": "0x80060888",
        "message": "Expand with $ref is only supported on lookup type navigation property."
    }
}

Verschachtelte Erweiterung von einwertigen Navigationseigenschaften

Sie können einwertige Navigationseigenschaften auf mehrere Ebenen erweitern, indem Sie eine $expand-Option in einer anderen $expand-Option verschachteln.

Die folgende Abfrage gibt die Datensätze task zurück und erweitert den zugehörigen Datensatz contact, den Datensatz account, der sich auf den Datensatz contact bezieht, und den Datensatz systemuser, der den Datensatz account erstellt hat:

Anforderung:

GET [Organization URI]/api/data/v9.2/tasks?$select=subject
&$expand=regardingobjectid_contact_task($select=fullname;
 $expand=parentcustomerid_account($select=name;
  $expand=createdby($select=fullname)))  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0 

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#tasks(subject,regardingobjectid_contact_task(fullname,parentcustomerid_account(name,createdby(fullname))))",
    "value": [
        {
            "@odata.etag": "W/\"80730855\"",
            "subject": "Task 1 for Susanna Stubberod",
            "activityid": "e9a8c72c-dbcc-ed11-b597-000d3a993550",
            "regardingobjectid_contact_task": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "parentcustomerid_account": {
                    "name": "Litware, Inc. (sample)",
                    "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
                    "createdby": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            }
        },
        {
            "@odata.etag": "W/\"80730861\"",
            "subject": "Task 2 for Susanna Stubberod",
            "activityid": "c206f534-dbcc-ed11-b597-000d3a993550",
            "regardingobjectid_contact_task": {
                "fullname": "Susanna Stubberod (sample)",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "parentcustomerid_account": {
                    "name": "Litware, Inc. (sample)",
                    "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
                    "createdby": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            }
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/tasks?$select=subject&$expand=regardingobjectid_contact_task($select=fullname;$expand=parentcustomerid_account($select=name;$expand=createdby($select=fullname)))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bC206F534-DBCC-ED11-B597-000D3A993550%257d%2522%2520first%253d%2522%257bE9A8C72C-DBCC-ED11-B597-000D3A993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Sammlungswertige Navigationseigenschaften erweitern

Es gibt einige wichtige Unterschiede in der Antwort, die davon abhängen, ob Sie verschachteltes $expand mit einer Navigationseigenschaft mit Sammlungswert irgendwo in Ihrer Abfrage verwenden.

Verschachteltes $expand Einzelnes $expand
Paging Paging in erweiterten Zeilen. Paging nur auf Ressourcenentitätssatz. <property name>@odata.nextLink-URLs für erweiterte Zeilen enthalten keine Paging-Informationen.
$top oder $orderby unterstützt Nein Ja

Einzelnes $expand auf sammlungswertigen Navigationseigenschaften

Wenn Sie nur die einfache $expand Ebene verwenden, wird kein Paging auf die erweiterten Zeilen angewendet. Wenn Sie den Anforderungsheader Prefer: odata.maxpagesize einschließen, wird Paging nur auf die Entitätssatz-Ressource der Abfrage angewendet.

Jede erweiterte Navigationseigenschaft mit Sammlungswert gibt eine <property>@odata.nextLink-URL zurück, die keine Paging-Informationen enthält. Es ist eine URL, die die gefilterte Sammlung für die Beziehung mit Ihren angehängten Abfrageoptionen darstellt. Sie können diese URL verwenden, um eine separate GET-Anforderung zu senden, und sie gibt dieselben Zeilen zurück, die in Ihrer ursprünglichen Anforderung zurückgegeben wurden. Sie können Paging auf diese Anforderung anwenden.

Da auf die erweiterten Datensätze kein Paging angewendet wird, können bis zu 5000 zugehörige Datensätze für jede erweitere sammlungswertige Navigationseigenschaft zurückgegeben werden. Abhängig von Ihren Daten und der Abfrage kann es sich um eine Menge Daten handeln. Wenn Sie so viele Daten zurückgeben, kann dies die Leistung beeinträchtigen und möglicherweise dazu führen, dass Ihre Anfrage eine Zeitüberschreitung verursacht. Seien Sie vorsichtig mit den Abfragen, die Sie verfassen. Sie können die Optionen $top, $filter und $orderby verwenden, um die Gesamtzahl der zurückgegebenen Datensätze zu steuern.

Das folgende Beispiel enthält eine einfache Erweiterung der Account_Tasks und contact_customer_accounts beim Abrufen von Datensätzen für Konten. Die Abfragekopfzeile Prefer: odata.maxpagesize=1 stellt sicher, dass nur ein Datensatz des Kontos auf der ersten Seite zurückgegeben wird.

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)
Prefer: odata.maxpagesize=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=1
OData-Version: 4.0 

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "Account_Tasks": [
                {
                    "@odata.etag": "W/\"80730894\"",
                    "subject": "Task 1 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
                },
                {
                    "@odata.etag": "W/\"80730903\"",
                    "subject": "Task 2 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "605dbd65-e2cc-ed11-b597-000d3a993550"
                },
                {
                    "@odata.etag": "W/\"80730909\"",
                    "subject": "Task 3 for Litware",
                    "_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "activityid": "a718856c-e2cc-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject",
            "contact_customer_accounts": [
                {
                    "@odata.etag": "W/\"80648695\"",
                    "fullname": "Susanna Stubberod (sample)",
                    "_parentcustomerid_value": "78914942-34cb-ed11-b596-0022481d68cd",
                    "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
                }
            ],
            "contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Vergleichen Sie diese Antwort mit dem folgenden Beispiel, das eine verschachtelte $expand enthält. Scrollen Sie in der Beispielantwort horizontal, um zu sehen, dass nur die URL @odata.nextLink für das Kontoergebnis Paging-Informationen enthält.

Verschachteltes $expand auf sammlungswertigen Navigationseigenschaften

Wenn Sie irgendwo in Ihrer Abfrage ein verschachteltes $expand verwenden und den Prefer: odata.maxpagesize-Anforderungsheader eingeschlossen haben, wird Paging auf jede der erweiterten Sammlungen angewendet.

Jede erweiterte Navigationseigenschaft mit Sammlungswert gibt eine <property>@odata.nextLink-URL zurück, die Paging-Informationen enthält. Sie können diese URL verwenden, um eine separate GET-Anforderung zu senden, und sie gibt den nächsten Satz an Datensätzen zurück, die in Ihrer ursprünglichen Anforderung nicht einbezogen wurden.

Sie können die Optionen $top oder $orderby nicht verwenden, um die Gesamtzahl der Datensätze zu begrenzen, die mit einem verschachtelten $expand zurückgegeben werden. Der folgende Fehler wird zurückgegeben, wenn Sie diese Optionen verwenden:

{
    "error": {
        "code": "0x80060888",
        "message": "Only $select and $filter clause can be provided while doing $expand on many-to-one relationship or nested one-to-many relationship."
    }
}

Das folgende Beispiel basiert auf dem vorherigen Beispiel und verwendet die gleichen Daten. Der einzige Unterschied ist der Zusatz in der URL dieser verschachtelten $expand auf einer einwertigen Navigationseigenschaft, um den besitzenden Benutzer des Kontakts zurückzugeben: ;$expand=owninguser($select=fullname).

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname;
$expand=owninguser($select=fullname))
Prefer: odata.maxpagesize=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=1
OData-Version: 4.0 

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname,owninguser(fullname)))",
    "value": [
        {
            "@odata.etag": "W/\"80649578\"",
            "name": "Litware, Inc. (sample)",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "Account_Tasks": [
                {
                    "subject": "Task 1 for Litware",
                    "activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
                }
            ],
            "Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject,description&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520first%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E",
            "contact_customer_accounts": [
                {
                    "fullname": "Susanna Stubberod (sample)",
                    "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                    "owninguser": {
                        "fullname": "System Administrator",
                        "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                        "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                    }
                }
            ],
            "contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname&$expand=owninguser($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
        }
    ],
    "@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject,description),contact_customer_accounts($select=fullname;$expand=owninguser($select=fullname))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Vergleichen Sie diese Antwort mit dem vorherigen Beispiel, das keine verschachtelte $expand verwendet. In dieser Antwort wird der Prefer: odata.maxpagesize=1-Anforderungsheader auf die task-Datensätze angewendet, die mit Account_Tasks zurückgegeben werden. Statt drei wird nur eine Aufgabe zurückgegeben. Die URL Account_Tasks@odata.nextLink gibt die nächsten beiden Aufgaben zurück. Scrollen Sie in der Beispielantwort horizontal, um zu sehen, dass die URLs Account_Tasks@odata.nextLink, contact_customer_accounts@odata.nextLink und @odata.nextLink Paging-Informationen enthalten.

Bestellzeilen

Geben Sie die $orderby Abfrageoption ein, um die Reihenfolge zu definieren in der Elemente zurückgegeben werden. Verwenden Sie das Suffix asc oder desc, um eine aufsteigende bzw. absteigende Reihenfolge anzugeben. Die Standardeinstellung ist aufsteigend. Das folgende Beispiel ruft die Eigenschaften name und revenue von Konten ab, geordnet nach aufsteigender revenue und absteigender name:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null

Anordnung und Auslagerung

Die Reihenfolge einer Seite macht beim Auslagern von Daten einen großen Unterschied. Wenn die Informationen zur Reihenfolge der Ergebnisse nicht eindeutig sind, kann Dataverse ausgelagerte 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 zum Zurückgeben unterschiedlicher Ergebnisse. Sie sollten beim Abrufen ausgelagerter Ergebnisse jedoch trotzdem eine Reihenfolge anwenden.

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

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:

Bundesstaat Status Seite
Eröffnung Aktiv 1 Start
Eröffnung Aktiv 1
Eröffnung Aktiv 1 Ende
Eröffnung Aktiv
Eröffnung Aktiv
Eröffnung Inaktiv
Eröffnung 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
Eröffnung Aktiv Case-0010 1 Start
Eröffnung Aktiv Case-0021 1
Eröffnung Aktiv Case-0032 1 Ende
Eröffnung Aktiv Case-0034
Eröffnung Aktiv Case-0070
Eröffnung Inaktiv Case-0015
Eröffnung 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
Eröffnung Aktiv Case-0010 1 Start
Eröffnung Aktiv Case-0021 1
Eröffnung Aktiv Case-0032 1 Ende
Eröffnung Aktiv Case-0034 2 Start
Eröffnung Aktiv Case-0070 2
Eröffnung Inaktiv Case-0015 2 Ende
Eröffnung Inaktiv Case-0047

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

Best Practices für Reihenfolgen beim Auslagern von Daten

Hinweis

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 Satz von Daten zur Anzeige in einer Anwendung abrufen oder mehr als 5.000 Datenzeilen zurückgeben müssen, müssen Sie die Ergebnisse auslagern. 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:

  • Spalten für Primärschlüssel der Tabellen
  • 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:

  • Sortierungen 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
    • Namenswerte allein. Zum Beispiel name, firstname, lastname
    • Textfelder wie Titel, Beschreibungen und mehrzeiliger Text
    • Nicht eindeutige Nummernfelder

Filterzeilen

Verwenden Sie die $filter Abfrageoption , um eine Sammlung von Ressourcen zu filtern.

Dataverse wertet jede Ressource in der Sammlung mit dem Ausdruckssatz für $filter aus. Nur Datensätze, bei denen der Ausdruck zu true ausgewertet wird, werden in der Antwort zurückgegeben. Datensätze werden nicht zurückgegeben, wenn der Ausdruck zu false oder null ausgewertet wird oder wenn der Benutzer keinen Lesezugriff auf den Datensatz hat.

Die folgende Tabelle beschreibt die Operatoren und Funktionen, die Sie in $filter-Ausdrücken verwenden können.

Beschreibung Weitere Informationen
Vergleichsoperatoren Verwenden Sie die eq,ne,gt,ge,lt, Und le Operatoren zum Vergleichen einer Eigenschaft und eines Werts. Vergleichsoperatoren
Logische Operatoren Verwenden von and, or, und not, um komplexere Ausdrücke zu erstellen. Logische Operatoren
Gruppierungsoperatoren Verwenden Sie Klammern: (), um den Vorrang für die Auswertung eines komplexen Ausdrucks festzulegen. Gruppierungsoperatoren
OData-Abfragefunktionen verwenden Werten Sie Zeichenfolgenwerte mit contains, endswith und startswith Funktionen aus. OData-Abfragefunktionen verwenden
Dataverse Abfragefunktionen Verwenden Sie mehr als 60 spezialisierte Funktionen, die für Geschäftsanwendungen entwickelt wurden. Dataverse Abfragefunktionen
Lambda-Ausdrücke Erstellen Sie Ausdrücke basierend auf Werten verwandter Sammlungen. Filtern Sie anhand von Werten verwandter Sammlungen

Wenn Sie eine Suchfeld-Eigenschaft in einer $filter verwenden, können Sie auch ein gefiltertes Suchfeld mit der entsprechenden Navigations-Eigenschaft mit Sammlungswert verwenden. Diese beiden Abfragen geben beispielsweise dieselben Ergebnisse zurück:

accounts?$filter=_owninguser_value eq '<systemuserid value>'&$select=name

systemusers(<systemuserid value>)/user_accounts?$select=name

Vergleichsoperatoren

Die folgende Tabelle beschreibt die Operatoren, die Sie verwenden können, um eine Eigenschaft und einen Wert zu vergleichen.

Operator Beschreibung Beispiel
eq Equal $filter=revenue eq 100000
ne Ungleich $filter=revenue ne 100000
gt Größer als $filter=revenue gt 100000
ge Größer als oder gleich $filter=revenue ge 100000
lt Kleiner als $filter=revenue lt 100000
le Kleiner oder gleich $filter=revenue le 100000

Vergleich von Spalten

Sie können Vergleichsoperatoren verwenden, um Eigenschaftswerte in derselben Zeile zu vergleichen. Nur Vergleichsoperatoren können verwendet werden, um Werte in derselben Zeile zu vergleichen, und die Spaltentypen müssen übereinstimmen. Die folgende Abfrage gibt z.B. alle Kontakte zurück, bei denen firstname gleich lastname ist:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$filter=firstname eq lastname

Logische Operatoren

Die folgende Tabelle beschreibt die logischen Operatoren, die Sie verwenden können, um komplexere Ausdrücke zu erstellen.

Operator Beschreibung Beispiel
and Logisch und $filter=revenue lt 100000 and revenue gt 2000
or Logisch oder $filter=contains(name,'(sample)') or contains(name,'test')
not Logische Negation $filter=not contains(name,'sample')

Gruppierungsoperatoren

Verwenden Sie Klammern () mit logischen Operatoren, um den Vorrang bei der Auswertung eines komplexen Ausdrucks festzulegen; zum Beispiel:

$filter=(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Dataverse-Abfragefunktionen

Verwenden Sie mehr als 60 spezialisierte Funktionen, die für Geschäftsanwendungen entwickelt wurden. Diese Funktionen bieten besondere Funktionalitäten, wie in der folgenden Tabelle beschrieben.

Gruppieren Funktionen
Datumsangaben InFiscalPeriod, InFiscalPeriodAndYear, InFiscalYear, InOrAfterFiscalPeriodAndYear, InOrBeforeFiscalPeriodAndYear,
Last7Days, LastFiscalPeriod, LastFiscalYear, LastMonth, LastWeek, LastXDays, LastXFiscalPeriods, LastXFiscalYears,
LastXHours, LastXMonths, LastXWeeks, LastXYears, LastYear, Next7Days, NextFiscalPeriod, NextFiscalYear,
NextMonth, NextWeek, NextXDays, NextXFiscalPeriods, NextXFiscalYears, NextXHours, NextXMonths,
NextXWeeks, NextXYears, NextYear, OlderThanXDays, OlderThanXHours, OlderThanXMinutes, OlderThanXMonths,
OlderThanXWeeks, OlderThanXYears, On, OnOrAfter, OnOrBefore, ThisFiscalPeriod, ThisFiscalYear, ThisMonth, ThisWeek, ThisYear, Today, Tomorrow, Yesterday
ID-Werte EqualBusinessId, EqualUserId, NotEqualBusinessId, NotEqualUserId
Hierarchie Above, AboveOrEqual, EqualUserOrUserHierarchy, EqualUserOrUserHierarchyAndTeams, EqualUserOrUserTeams,
EqualUserTeams, NotUnder, Under, UnderOrEqual
Weitere Informationen: Hierarchische Daten abfragen
Auswahlspalten ContainValues, DoesNotContainValues
Weitere Informationen: Abfrage von Daten über die Auswahl
Zwischen Between, NotBetween
In In, NotIn
Sprache EqualUserLanguage

Hinweis

Die Funktion Enthält ist für die Verwendung mit Spalten gedacht, die über eine Volltextindizierung verfügen. Nur die Tabelle Dynamics 365 KBArticle (Artikel) hat Spalten mit Volltextindizierung. Verwenden Sie stattdessen die Funktion OData contains.

Die Web API Query Function Reference enthält die vollständige Liste. Jeder Artikel enthält ein Syntaxbeispiel, das Sie kopieren können.

Sie müssen den voll qualifizierten Namen der Funktion verwenden und den Service-Namensraum (Microsoft.Dynamics.CRM) an den Namen der Funktion anhängen.

Jede Funktion hat einen PropertyName-Parameter, der die zu bewertende Eigenschaft angibt. Die Funktion kann mehr Parameter haben, z. B. PropertyValue, PropertyValues oder PropertyValue1 und PropertyValue2. Wenn diese Parameter vorhanden sind, müssen Sie einen oder mehrere Werte angeben, um sie mit dem PropertyName -Parameter zu vergleichen.

Das folgende Beispiel zeigt die Verwendung der Between-Funktion für die Suche nach Konten mit 5 bis 2.000 Mitarbeitern.

GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

Filtern Sie mithilfe von Zeichenfolgenwerten

Beachten Sie die folgenden Punkte, wenn Sie nach Zeichenfolgen filtern:

  • Alle Filter für String-Werte sind unabhängig von der Groß-/Kleinschreibung.
  • Sie müssen Sonderzeichen in Filterkriterien URL-kodieren. Weitere Informationen: URL-Codierung von Sonderzeichen
  • Sie können Platzhalterzeichen verwenden, vermeiden Sie jedoch nachgestellte Platzhalterzeichen. Mehr Informationen: Verwenden von Platzhalterzeichen
  • Sie können OData Abfragefunktionen verwenden: contains, startswith, und endswith. Weitere Informationen: OData Abragefunktionen verwenden
  • Sie müssen einfache Anführungszeichen verwalten, wenn Sie Filter verwenden, die eine Reihe von Zeichenfolgen akzeptieren. Weitere Informationen: Verwalten von Einzelangeboten

URL-Codierung von Sonderzeichen

Wenn die Zeichenfolge, die Sie als Wert in einer Filterfunktion verwenden, ein Sonderzeichen enthält, müssen Sie es per URL codieren. Wenn Sie beispielsweise diese Funktion verwenden: contains(name,'+123'), wird es nicht funktionieren, weil + ein Zeichen ist, das nicht in eine URL eingefügt werden kann. Wenn Sie die Zeichenfolge per URL codieren, wird sie zu contains(name,'%2B123') und Sie erhalten Ergebnisse, bei denen der Spaltenwert +123 enthält.

Die folgende Tabelle zeigt die URL-codierten Werte für häufige Sonderzeichen.

Sonder-
zeichen		 URL-codiertes
zeichen
$ %24
& %26
+ %2B
, %2C
/ %2F
: %3A
; %3B
= %3D
? %3F
@ %40

Platzhalterzeichen verwenden

Beim Erstellen von Filtern mit Zeichenfolgen können Sie die folgenden Platzhalterzeichen anwenden:

Zeichen Beschreibung T-SQL Dokumentation und Beispiele
% Stimmt mit einer beliebigen Zeichenfolge aus null oder mehr Zeichen überein. Dieses Platzhalterzeichen kann entweder als Präfix oder als Suffix verwendet werden. Prozentzeichen (Platzhalter – Abzugleichende Zeichen) (Transact-SQL)
_ Verwenden Sie den Unterstrich, um ein beliebiges einzelnes Zeichen in einem Zeichenfolgenvergleichsvorgang abzugleichen, der einen Musterabgleich beinhaltet. _ (Platzhalter – Übereinstimmung mit einem Zeichen) (Transact-SQL)
[] Stimmt mit jedem einzelnen Zeichen innerhalb des angegebenen Bereichs oder Satzes überein, der in Klammern angegeben ist. [ ] (Platzhalter - Übereinstimmende Zeichen) (Transact-SQL)
[^] Stimmt mit jedem einzelnen Zeichen nicht innerhalb des angegebenen Bereichs oder Satzes überein, der in eckigen Klammern angegeben ist. [^] (Platzhalter - Nicht Übereinstimmende Zeichen) (Transact-SQL)

Weitere Informationen: Verwenden Sie Platzhalterzeichen in Bedingungen für Zeichenfolgenwerte

Nachfolgende Platzhalter werden unterstützt

Es ist wichtig, dass Sie keine nachgestellten Platzhalter verwenden, da diese nicht unterstützt werden. Abfragen, die diese Anti-Patterns verwenden, führen zu Leistungsproblemen, da die Abfragen nicht optimiert werden können. Hier finden Sie einige Beispiele für nachgestellte Platzhalter:

startswith(name,'%value')
endswith(name,'value%')

OData-Abfragefunktionen verwenden

Die folgende Tabelle beschreibt die OData-Abfragefunktionen, die Sie zum Filtern von Zeichenfolgen verwenden können:

Funktion Beispiel
contains $filter=contains(name,'(sample)')
endswith $filter=endswith(name,'Inc.')
startswith $filter=startswith(name,'a')

Sie können diese Funktionen mit dem logischen Operator not verwenden, um das Ergebnis zu negieren.

Einzelangebote verwalten

Einige Filter akzeptieren ein Array von Zeichenfolgen, wie z.B. die Funktion In Query. Wenn Sie in diesen Filtern Werte angeben, die einfache Anführungszeichen oder Apostrophe enthalten, wie z.B. O'Brian oder Men's clothes, müssen Sie die Werte in doppelte Anführungszeichen setzen, zum Beispiel:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=Microsoft.Dynamics.CRM.In(PropertyName=@p1,PropertyValues=@p2)
&@p1='lastname'
&@p2=["OBrian","OBryan","O'Brian","O'Bryan"]

Wenn Sie das nicht tun, erhalten Sie die folgende Fehlermeldung: Invalid JSON. A comma character ',' was expected in scope 'Array'. Every two elements in an array and properties of an object must be separated by commas.

Wenn sich der Filter auf einen einzelnen Wert bezieht, ersetzen Sie das einfache Anführungszeichen durch zwei aufeinanderfolgende einfache Anführungszeichen, zum Beispiel:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=lastname eq 'O''Bryan'

Wenn Sie das nicht tun, erhalten Sie eine Fehlermeldung wie diese: There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.

Filter basierend auf zugehörigen Datenwerten

Sie können zurückgegebene Zeilen basierend auf Werten in verknüpften Tabellen filtern. Wie Sie filtern, hängt von der Art der Beziehung ab.

Filtern Sie mithilfe von Eigenschaftswerten der Nachschlagespalte

Sie können auf Grundlage einwertiger Navigationseigenschaftswerte filtern, die die Nachschlagespalten darstellen. Dieses Muster verwenden:

<single-valued navigation property>/<property name>

Das folgende Beispiel gibt Datensätze von Konten basierend auf dem Wert der Spalte primarycontactid/fullname zurück:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/fullname eq 'Susanna Stubberod (sample)'
&$select=name,_primarycontactid_value
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antwort:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_primarycontactid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

Sie können auch Werte weiter oben in der Hierarchie der einwertigen Navigationseigenschaften vergleichen.

Das folgende Beispiel gibt das erste Konto zurück, bei dem der Datensatz des Kontakts die primarycontactid darstellt, wobei 'Systemadministrator' den Datensatz erstellt hat, unter Verwendung der primarycontactid/createdby/fullname in der $filter.

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/createdby/fullname eq 'System Administrator'
&$select=name,_primarycontactid_value
&$expand=primarycontactid(
$select=fullname,_createdby_value;
$expand=createdby($select=fullname))
&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antwort:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_primarycontactid_value,primarycontactid(fullname,_createdby_value,createdby(fullname)))",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "fullname": "Susanna Stubberod (sample)",
                "_createdby_value@OData.Community.Display.V1.FormattedValue": "System Administrator",
                "_createdby_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "createdby": {
                    "fullname": "System Administrator",
                    "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                    "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                }
            }
        }
    ]
}

Filtern Sie anhand von Werten verwandter Sammlungen

Verwenden Sie die Lambda-Operatoren any und all, um Werte in einer Sammlung auszuwerten und die Ergebnisse zu filtern.

  • any: Gibt true zurück, wenn der angewendete Ausdruck für ein beliebiges Mitglied der Sammlung wahr ist; andernfalls gibt er false zurück. Der any-Operator ohne Argument gibt true zurück, wenn die Sammlung nicht leer ist.
  • all: Gibt „Wahr“ zurück, wenn der angewandte Ausdruck für alle Mitglieder der Sammlung wahr ist; andernfalls wird „Falsch“ zurückgegeben.

Die Syntax sieht so aus:

<collection>/[any | all](o:<expression to evaluate>)

In diesem Fall ist o die Variable, die Elemente in der Sammlung darstellt. Die Konvention besteht darin, den ersten Buchstaben des Typs zu verwenden. Verwenden Sie in dem Ausdruck o/<property or collection name>, um auf eine Eigenschaft oder Sammlung eines bestimmten Artikels zu verweisen.

Sie können Bedingungen für mehrere sammlungswertige Navigationseigenschaften und verschachtelte Sammlungen einschließen. Sie können keine Bedingungen in Navigationseigenschaften mit Sammlungswert einfügen, die in ein Suchfeld verschachtelt sind. Zum Beispiel: $filter=primarycontactid/new_contact_account/any(a:a/accountid eq '{GUID}') wird nicht unterstützt.

Weitere Informationen: Lambda-Operatoren unter oData.org verwenden

Beispiele für Lambda-Operatoren

Das folgende Beispiel ruft alle Datensätze von Entitäten ab, die mindestens eine E-Mail mit „sometext“ im Betreff enthalten:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext'))
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Das folgende Beispiel ruft alle Datensätze der Entität „Konto“ ab, bei denen alle zugehörigen Aufgaben abgeschlossen sind:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Tasks/all(t:t/statecode eq 1)
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Das folgende Beispiel ruft alle Datensätze der Kontoentität ab, die mindestens eine E-Mail mit dem Betreff „sometext“ enthalten und deren Statuscode aktiv ist:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext') and 
e/statecode eq 0)
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Das folgende Beispiel erstellt eine verschachtelte Abfrage mit den Operatoren any und all:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=(contact_customer_accounts/any(c:c/jobtitle eq 'jobtitle' and 
c/opportunity_customer_contacts/any(o:o/description ne 'N/A'))) and 
endswith(name,'Inc.')
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Seitenergebnisse

Verwenden Sie die Abfragekopfzeile Prefer: odata.maxpagesize, um die Anzahl der zurückgegebenen Datensätze zu steuern. Wenn Sie keine Zahl angeben, können bis zu 5.000 Datensätze für jede Anfrage zurückgegeben werden. Sie können keine Seitengröße über 5000 anfordern.

Hinweis

Dataverse unterstützt nicht die Abfrageoption $skip, sodass Sie die Kombination aus $top und $skip nicht für das Paging verwenden können. Weitere Informationen: Verwenden der Abfrageoption $top

Im folgenden Beispiel werden die ersten zwei Kontodatensä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. Für jede nachfolgende Anforderung weiterer Seiten sollten Sie denselben odata.maxpagesize Präferenzwert verwenden, der sich in der ursprünglichen retrieve multiple-Anforderung verwendet wurde. 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 wurden die kodierten Informationen als Wert des Parameters $skiptoken im URL-Wert @odata.nextLink festgelegt. Der Server legt diese codierten Informationen fest, um das Paging zu steuern. Sie sollten die kodierten Informationen nicht verändern oder weiter kodieren. Verwenden Sie den angegebenen URL-Wert, um die nächste Seite abzurufen.

Verwenden Sie 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

Aggregatdaten

Wenn Sie die $apply Option verwenden, können Sie Ihre Daten dynamisch sammeln und gruppieren.

Die Aggregatfunktionen werden auf eine Sammlung von 50.000 Datensätzen beschränkt. Weitere Informationen zur Nutzung der Aggregatfunktionalität mit Dataverse finden Sie hier: Daten mithilfe von FetchXml aggregieren.

Weitere Informationen über die OData-Datenaggregation finden Sie hier: OData Erweiterung für Datenaggregation Version 4.0. Beachten Sie, dass Dataverse nur eine Teilmenge dieser Aggregatmethoden unterstützt.

Hinweis

  • groupby mit Datums-/Uhrzeitwerten wird nicht unterstützt.

  • $orderby mit aggregierten Werten wird nicht unterstützt. Dies gibt den Fehler zurück: The query node SingleValueOpenPropertyAccess is not supported.

Im Folgenden finden Sie einige Beispiele:

Diese Beispiele zeigen der Kürze halber nicht die vollständige Anfrage und Antwort.

Liste mit eindeutigen Status in der Abfrage

GET accounts?$apply=groupby((statuscode))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antworttext

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2
        }
    ]
}

Anzahl nach Statuswerten

GET accounts?$apply=groupby((statuscode),aggregate($count as count))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antworttext

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "count@OData.Community.Display.V1.FormattedValue": "8",
            "count": 8
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "count@OData.Community.Display.V1.FormattedValue": "1",
            "count": 1
        }
    ]
}

Summe der aggregierten Einnahmen

GET accounts?$apply=aggregate(revenue with sum as total)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antworttext

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "total@OData.Community.Display.V1.FormattedValue": "$440,000.00",
            "total": 440000.000000000
        }
    ]
}

Durchschnittlicher Umsatz basierend auf dem Status

GET accounts?$apply=groupby((statuscode),aggregate(revenue with average as averagevalue))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antworttext

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "averagevalue@OData.Community.Display.V1.FormattedValue": "$53,750.00",
            "averagevalue": 53750.000000000
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "averagevalue@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "averagevalue": 10000.000000000
        }
    ]
}

Durchschnittlicher Umsatz basierend auf dem Status

GET accounts?$apply=groupby((statuscode),aggregate(revenue with sum as total))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antworttext

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
            "statuscode": 1,
            "total@OData.Community.Display.V1.FormattedValue": "$430,000.00",
            "total": 430000.000000000
        },
        {
            "statuscode@OData.Community.Display.V1.FormattedValue": "Inactive",
            "statuscode": 2,
            "total@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "total": 10000.000000000
        }
    ]
}

Firmenumsatz nach primärem Kontaktnamen

GET accounts?$apply=groupby((primarycontactid/fullname),aggregate(revenue with sum as total))
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antworttext

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "total@OData.Community.Display.V1.FormattedValue": "$10,000.00",
            "total": 10000.000000000,
            "contact_fullname": "Jim Glynn (sample)"
        },
        {
            "total@OData.Community.Display.V1.FormattedValue": "$80,000.00",
            "total": 80000.000000000,
            "contact_fullname": "Maria Campbell (sample)"
        },
      ... <truncated for brevity>
      
    ]
}

Primäre Kontaktnamen für Konten in 'WA'.

GET accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))

Antworttext

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "contact_fullname": "Rene Valdes (sample)"
        },
        {
            "contact_fullname": "Robert Lyon (sample)"
        },
        {
            "contact_fullname": "Scott Konersmann (sample)"
        }
    ]
}

Datum und Uhrzeit für zuletzt erstellten Datensatz

GET accounts?$apply=aggregate(createdon with max as lastCreate)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antworttext

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "lastCreate@OData.Community.Display.V1.FormattedValue": "3/25/2023 10:42 AM",
            "lastCreate": "2023-03-25T17:42:47Z"
        }
    ]
}

Datum und Uhrzeit für zuerst erstellten Datensatz

GET accounts?$apply=aggregate(createdon with min as firstCreate)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antworttext

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts",
    "value": [
        {
            "firstCreate@OData.Community.Display.V1.FormattedValue": "3/25/2023 10:42 AM",
            "firstCreate": "2023-03-25T17:42:46Z"
        }
    ]
}

Anzahl der Zeilen

Verwenden Sie die Abfrageoption $count=true, um eine Zählung der Entitäten, die den Filterkriterien entsprechen, bis zu 5.000, zu erhalten.

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=accountid&$count=true
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(accountid)",
    "@odata.count": 9,
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        },
        ... <Truncated for brevity>
    ]
}

Die -Antwortanmerkung @odata.count enthält die Anzahl der Zeilen bis zu 5.000, die den Filterkriterien entsprechen, ungeachtet einer -Einstellungsbeschränkung.

Hinweis

Wenn Sie innerhalb der letzten 24 Stunden eine Momentaufnahme der Gesamtzahl der Zeilen für eine Tabelle über 5.000 abrufen möchten, verwenden Sie die Funktion RetrieveTotalRecordCount.

Wenn der Zählwert 5.000 ist und Sie wissen möchten, ob die Zählung genau 5.000 oder höher ist, können Sie den folgenden Header hinzufügen:

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.totalrecordcount,Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded"

Diser Header fügt die folgenden Anmerkungen dem Ergebnis hinzu:

  • @Microsoft.Dynamics.CRM.totalrecordcount
  • @Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded

Wenn die Abfrageoption $count=true verwendet wird und mehr als 5.000 Datensätze vorhanden sind, werden die folgenden Werte zurückgegeben:

"@odata.count": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,

Wenn weniger als 5.000 Datensätze vorhanden sind, wird die tatsächliche Anzahl zurückgegeben.

"@odata.count": 58,
"@Microsoft.Dynamics.CRM.totalrecordcount": 58,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,

Wenn Sie die $count=true-Abfrageoption nicht mit aufnehmen, ist der Gesamtwert von @Microsoft.Dynamics.CRM.totalrecordcount -1.

Das folgende Beispiel zeigt, dass es 10 Konten gibt, die auf die $filter passen, aber nur die ersten drei Konten werden zurückgegeben:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name?
&$filter=contains(name,'sample')
&$count=true  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Prefer: odata.maxpagesize=3
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.*"

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.maxpagesize=3
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.*"
  
{  
   "@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(name)",
   "@odata.count":10,
   "@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
   "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,
   "value":[  
      {  
         "@odata.etag":"W/\"502482\"",
         "name":"Fourth Coffee (sample)",
         "accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
      },
      {  
         "@odata.etag":"W/\"502483\"",
         "name":"Litware, Inc. (sample)",
         "accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
      },
      {  
         "@odata.etag":"W/\"502484\"",
         "name":"Adventure Works (sample)",
         "accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
      }
   ],
   "@odata.nextLink":"[Organization URI]/api/data/v9.2/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Um nur eine Zahl zu erhalten, die die Anzahl einer Sammlung darstellt, hängen Sie /$count an, wie im folgenden Beispiel:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts/$count  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: text/plain  
OData-Version: 4.0  
  
10

Siehe auch

Nach Dataverse-Datensätzen suchen
Web API-Abfragedatenbeispiel (C#)
Web API-Abfragedatenbeispiele (clientseitiges JavaScript)
Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen erstellen und Fehlern behandeln