Datenabfrage mit Web-API

Artikel
05/12/2022
15 Minuten Lesedauer

Hinweis

Unsicher bei Entität vs. Tabelle? Siehe Developers: Understand terminology in Microsoft Dataverse.

Wenn Sie Daten für einen Entitätssatz abrufen möchten, verwenden Sie eine GET-Anforderung. Wenn Sie Daten abrufen, können Sie Abfrageoptionen anwenden, um Kriterien für die gewünschten Entitätsdaten (Tabellen) und für die Entitätseigenschaften (Spalten), die zurückgegeben werden sollen, festzulegen.

Grundlegendes Abfragebeispiel

Dieses Beispiel fragt den Firmen-Entitätssatz ab und verwendet die $select und $top-Systemabfrageoptionen, um die Name-Eigenschaft für ersten drei Firmen zurückzugeben:

Anforderung

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

Response

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)",
   "value":[  
      {  
         "@odata.etag":"W/\"501097\"",
         "name":"Fourth Coffee (sample)",
         "accountid":"89390c24-9c72-e511-80d4-00155d2a68d1"
      },
      {  
         "@odata.etag":"W/\"501098\"",
         "name":"Litware, Inc. (sample)",
         "accountid":"8b390c24-9c72-e511-80d4-00155d2a68d1"
      },
      {  
         "@odata.etag":"W/\"501099\"",
         "name":"Adventure Works (sample)",
         "accountid":"8d390c24-9c72-e511-80d4-00155d2a68d1"
      }
   ]
}

Grenzwerte der Zahl der zurückgegebenen Tabellenzeilen (Entitäten)

Sofern Sie keine kleinere Seitengröße angeben, wird ein Maximum von 5.000 Zeilen pro Anforderung zurückgegeben. Falls mehr Zeilen vorhanden sind, die mit den Filterkriterien der Abfrage übereinstimmen, wird eine @odata.nextLink-Eigenschaft mit den Ergebnissen zurückgegeben. Verwenden Sie den Wert der @odata.nextLink-Eigenschaft mit einer neuen GET-Anforderung, um die nächste Seite mit Zeilen zurückzugeben.

Hinweis

Abfragen zu Entitätsdefinitionen (Tabellendefinitionen) sind nicht eingeschränkt oder ausgelagert. Mehr Informationen:Abfragetabellendefinition mithilfe der Web-API

`$top`-Abfrageoption verwenden

Sie können die Anzahl der zurückgegebenen Ergebnisse einschränken, indem Sie die Systemabfrageoption $top, verwenden. Im folgenden Beispiel werden nur die ersten drei Kontozeilen zurückgegeben.

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

Hinweis

Durch Einschränken der Ergebnisse mit $top wird die Anwendung der odata.maxpagesize-Einstellung verhindert. Sie können die odata.maxpagesize-Einstellung oder $top verwenden, aber nicht beide gleichzeitig. Weitere Informationen zu odata.maxpagesize finden Sie unter Anzahl der Zeilen, die in einer Seite zurückgegeben werden sollen.

Sie sollten außerdem nicht $top mit $count verwenden.

Geben Sie die Anzahl der Zeilen an, die in einer Seite zurückgegeben werden sollen

Verwenden Sie den odata.maxpagesize-Einstellungswert, um die Anzahl der in der Antwort zurückgegebenen Zeilen abzufragen.

Hinweis

Sie können keinen odata.maxpagesize-Einstellungswert verwenden, der größer als 5000 ist.

Das folgende Bespiel fragt den Firmen-Entitätssatz ab und gibt die name-Eigenschaft für die ersten drei Firmen zurück.

Anforderung

GET [Organization URI]/api/data/v9.2/accounts?$select=name HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Prefer: odata.maxpagesize=3

Antwort

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Content-Length: 402  
Preference-Applied: odata.maxpagesize=3  
  
{  
   "@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(name)",
   "value":[  
      {  
         "@odata.etag":"W/\"437194\"",
         "name":"Fourth Coffee (sample)",
         "accountid":"7d51925c-cde2-e411-80db-00155d2a68cb"
      },
      {  
         "@odata.etag":"W/\"437195\"",
         "name":"Litware, Inc. (sample)",
         "accountid":"7f51925c-cde2-e411-80db-00155d2a68cb"
      },
      {  
         "@odata.etag":"W/\"468026\"",
         "name":"Adventure Works (sample)",
         "accountid":"8151925c-cde2-e411-80db-00155d2a68cb"
      }
   ],
   "@odata.nextLink":"[Organization URI]/api/data/v9.2/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b8151925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520first%253d%2522%257b7D51925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20/%3E"
}

Verwenden Sie den Wert der @odata.nextLink-Eigenschaft, um die nächste Datensatzgruppe anzufordern. Sie sollten keine zusätzlichen Systemabfrageoptionen für den Wert ändern oder anfügen. Für jede nachfolgende Anforderung weiterer Seiten sollten Sie denselben odata.maxpagesize-Einstellungswert verwenden, der sich in der ursprünglichen Anforderung verwendet wurde. Zwischenspeichern Sie auch die zurückgegebenen Ergebnisse oder den Wert der @odata.nextLink-Eigenschaft, sodass Sie zu zuvor abgerufenen Seiten zurückkehren können.

Hinweis

Der Wert der @odata.nextLink-Eigenschaft ist URI-codiert. Falls Sie den Wert vor dem Senden URI-codieren, verursachen die XML-Cookieinformationen in der URI einen Fehler.

Verwenden von Systemabfrageoptionen

Jede der Systemabfrageoptionen, die Sie zur URI für den Entitätssatz anfügen, wird mithilfe der Syntax für Abfragezeichenfolgen hinzugefügt. Die erste wird nach [?] angefügt und die nachfolgenden Abfrageoptionen werden mithilfe von [&] getrennt. Alle Abfrageoptionen unterscheiden zwischen Groß-/Kleinschreibung, wie im folgenden Beispiel angezeigt.

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

Anforderungsspezifische Eigenschaften

Verwenden Sie die $select-Systemabfrageoption, um die zurückgegebenen Eigenschaften zu begrenzen, wie im folgenden Beispiel angezeigt.

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

Wichtig

Dies ist eine bewährte Methode für die Leistung. Wenn Eigenschaften nicht mithilfe von $selectangegeben wurden, werden alle Eigenschaften zurückgegeben.

Wenn Sie bestimmte Eigenschaftstypen anfordern, können Sie erwarten, dass zusätzliche Schreibschutzeigenschaften automatisch zurückgegeben werden.

Wenn Sie einen Geldwert anfordern, wird die _transactioncurrencyid_value-Sucheigenschaft zurückgegeben. Diese Eigenschaft enthält nur den GUID-Wert der Transaktionswährung, daher könnten Sie diesen Wert verwenden, um Informationen über die Währung mithilfe von transactioncurrency EntityType abzurufen. Alternativ können Sie durch das Anfordern von Anmerkungen zusätzliche Daten in derselben Anforerung abrufen. Weitere Informationen: Daten zu Sucheigenschaften abrufen

Wenn Sie eine Eigenschaft anfordern, die Teil eines zusammengesetzten Attributs für eine Adresse ist, erhalten Sie auch die zusammengesetzte Eigenschaft. Wenn beispielsweise Ihre Abfrage die address1_line1-Eigenschaft für einen Kontakt anfordert, wird die address1_composite-Eigenschaft ebenfalls zurückgegeben.

Ergebnisse filtern

Verwenden Sie die $filter-Systemabfrageoption, um Kriterien dafür festzulegen, welche Zeilen zurückgegeben werden sollen.

Standardfilteroperatoren

Die Web-API unterstützt die OData-Standardfilteroperatoren, die in der folgenden Tabelle aufgelistet werden.

Operator	Beschreibung	Beispiel
Vergleichsoperatoren
`eq`	Gleich	`$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`
Logische Operatoren
`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')`
Gruppieren von Operatoren
`( )`	Rangfolgengruppierung	`(contains(name,'sample') or contains(name,'test')) and revenue gt 5000`

Hinweis

Dies ist eine Teilmenge von 11.2.5.1.1 Integrierte Filtervorgänge. Arithmetische Operatoren und der Vergleich hat Operator werden von der Web-API nicht unterstützt.

Alle Filterbedingungen für String-Werte sind unabhängig von der Groß-/Kleinschreibung.

Standardabfragenfunktionen

Die Web API unterstützt diese Standardfunktionen der OData-Zeichenkettenabfrage:

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

Hinweis

Dies ist eine Teilmenge von 11.2.5.1.2 Integrierte Abfragefunktionen. Date, Math, Type, Geo und andere String-Funktionen werden nicht in der Web-API unterstützt.

Verwenden Sie Platzhalterzeichen in Bedingungen mit Zeichenfolgenwerte

Sie können Platzhalterzeichen verwenden, wenn Sie Abfragen unter Verwendung dieser standardmäßigen Abfragefunktion für Zeichenfolgenwerte. Weitere Informationen: Verwenden Sie Platzhalterzeichen in Bedingungen für Zeichenfolgenwerte

Microsoft Dataverse-Web-API-Abfragefunktionen

Dataverse enthält einige spezielle Funktionen, die Parameter akzeptieren, Boolesche Werte zurückgeben und als Filterkriterium in einer Abfrage verwendet werden können. Eine Liste dieser Funktionen finden Sie unter Web API Query Function Reference. Im Folgenden finden Sie ein Beispiel für die Suche von Between Function nach Firmen mit einer Mitarbeiterzahl zwischen 5 und 2000.

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

Weitere Informationen: Eine Abfrage mit Funktionen verfassen.

Verwenden von Lambda-Operatoren

Die Web-API ermöglicht Ihnen, zwei Lambda-Operatoren zu verwenden, nämlich any und all, um einen booleschen Ausdruck für eine Sammlung auszuwerten.

`any`-Operator

Der any-Operator gibt true zurück, wenn der übernommene boolesche Ausdruck für ein Mitglied der Sammlung true ist; andernfalls gibt er false zurück. Der any-Operator ohne Argument gibt true zurück, wenn die Sammlung nicht leer ist.

Beispiel

Das folgende Beispiel veranschaulicht, wie Sie alle Firmenentitätsdatensätze, die mindestens eine E-Mail mit „sometext“ im Betreff enthalten, abrufen können.

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(o:contains(o/subject,'sometext')) HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

`all`-Operator

Der all-Operator gibt true zurück, wenn der übernommene boolesche Ausdruck für alle Mitglieder der Sammlung true ist; andernfalls gibt er false zurück.

Beispiel

Das folgende Beispiel veranschaulicht, wie Sie alle Firmenentitätsdatensätze, bei denen alle zugeordneten Aufgaben geschlossen sind, abrufen können.

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Tasks/all(o:o/statecode eq 1) HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Das folgende Beispiel veranschaulicht, wie Sie alle Firmenentitätsdatensätze, die mindestens eine E-Mail mit „sometext“ im Betreff enthalten und deren statecode aktiv ist, abrufen können.

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

Das folgende Beispiel zeigt Ihnen, wie Sie außerdem eine geschachtelte Abfrage mit any- und all-Operatoren erstellen können.

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,'{0}') HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Filtern von übergeordneten Zeilen (Datensätzen) auf Grundlage der Werte von untergeordneten Datensätzen

Das folgende Beispiel veranschaulicht, wie Sie den /any-Operator verwenden können, um alle Kontodatensätze abzurufen, die Folgendes aufweisen:

Jedes verknüpfte Budget der Verkaufschancendatensätze größer oder gleich 300 und
die Verkaufschancendatensätze haben keine Beschreibung oder
Die Beschreibung der Verkaufschancen-Datensätze enthält den Begriff "bad".

Anforderung

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=not opportunity_customer_accounts/any(o:o/description eq null and 
o/budgetamount le 300 or 
contains(o/description, 'bad')) and 
opportunity_customer_accounts/any() and 
endswith(name,'{0}') HTTP/1.1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Navigationseigenschaften ermöglichen den Zugriff auf Daten zur aktuellen Entität. Einzelwertige Navigationseigenschaften entsprechen Suchattributen, die N:1-Beziehungen unterstützen und eine Referenz auf eine andere Entität ermöglichen. Weitere Informationen: Navigationseigenschaften.

Sie können Ihre Entitätssatzdatensätze auf Grundlage einwertiger Navigationseigenschaftswerte filtern. Zum Beispiel können Sie untergeordnete Firmen für die angegebene Firma abrufen.

Beispiel:

Abrufen aller passenden Firmen für eine angegebene Kontaktkennung

Anforderung

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=primarycontactid/contactid eq a0dbf27c-8efb-e511-80d2-00155db07c77 HTTP/1.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)",
"value":[  
        {  
            "@odata.etag":"W/\"513479\"",
            "name":"Adventure Works (sample)",
            "accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
        },
        {  
            "@odata.etag":"W/\"514057\"",
            "name":"Blue Yonder Airlines (sample)",
            "accountid":"3edbf27c-8efb-e511-80d2-00155db07c77"
        }
    ]
}

Rufen Sie untergeordnete Konten für die angegebene Konto-ID ab

Anforderung

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=parentaccountid/accountid eq 3adbf27c-8efb-e511-80d2-00155db07c77  
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)",
"value":[  
        {  
            "@odata.etag":"W/\"514058\"",
            "name":"Sample Child Account 1",
            "accountid":"915e89f5-29fc-e511-80d2-00155db07c77"
        },
        {  
            "@odata.etag":"W/\"514061\"",
            "name":"Sample Child Account 2",
            "accountid":"03312500-2afc-e511-80d2-00155db07c77"
        }
    ]
}

Hinweis

Es ist möglich, mit $filter innerhalb von $expand Ergebnisse nach Bezugsdatensätzen in einem Abrufvorgang zu filtern. Sie können eine durch Semikolon getrennte Liste von Systemabfrageoptionen verwenden, die in Klammern hinter dem Namen der collection-valued navigation property eingeschlossen ist. Die in $expand unterstützten Abfrageoptionen sind $select, $filter, $top und $orderby. Weitere Informationen: Optionen zur Anwendung auf erweiterte Tabellen.

Die beiden Optionen zum Filtern von Ergebnissen basierend auf Werten von Navigationseigenschaften mit Collection-Werten sind:

Eine Abfrage mit Lambda-Operatoren erstellen

Mit Lambda-Operatoren können Sie Filter auf Werte von Sammlungseigenschaften für eine Link-Entität anwenden. Das folgende Beispiel ruft die Datensätze des Entitätstyps systemuser ab, die mit den Entitätstypen team und teammembership verknüpft sind, d. h. es ruft die Datensätze systemuser ab, die gleichzeitig Administratoren eines Teams namens „CITTEST“ sind.

GET [Organization URI]/api/data/v9.2/systemusers?$filter=(teammembership_association/any(t:t/name eq 'CITTEST'))
&$select=fullname,businessunitid,title,address1_telephone1,systemuserid
&$orderby=fullname
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Weitere Informationen: Lambda-Operatoren verwenden.

Lesen Sie über Sie die Ergebnisse nach, indem Sie einzelne Entitäten auf Grundlage der Werte in der Sammlung mit mehreren Vorgänge filtern

Um die gleichen Ergebnisse wie im obigen Beispiel zu erhalten, können Sie Datensätze von zwei Entitätstypen abrufen und dann iterativ die Werte in der Sammlung einer Entität mit dem Wert in der anderen Entität abgleichen und so Entitäten basierend auf den Werten in der Sammlung filtern.

Folgen Sie den Schritten im folgenden Beispiel, um zu verstehen, wie wir Ergebnisse mit der Iterationsmethode filtern können:

Erhalten Sie eine eindeutige Liste der team._administratorid_value Werte.
- GET [OrganizationURI]/api/data/v9.2/teams?$select=_administratorid_value&$filter=_administrator_value ne null
- Schleife dann durch die zurückgegebenen Werte, um Duplikate zu entfernen und eine eindeutige Liste zu erhalten. d.h. Erstellen Sie ein neues Array, durchlaufen Sie die Abfrageergebnisse für jede Prüfung, um zu sehen, ob sie sich bereits im neuen Array befinden, wenn nicht, fügen Sie sie hinzu. Dies sollte Ihnen eine Liste von verschiedenen systemuserid-Werten liefern.
- Die Art und Weise, wie Sie dies in JavaScript vs. C# tun würden, wäre anders, aber im Wesentlichen sollten Sie in der Lage sein, die gleichen Ergebnisse zu erzielen.
Abfrage systemuser mit ContainValues Query Function zum Vergleich der systemuserid-Werte mit der in Schritt 1 erfassten Liste.

Einfache Anführungszeichen in Zeichenfolgenfilterwerten verwalten

Beim Angeben von Vergleichswerten in Filtern, die ein Array von Zeichenfolgenwerten akzeptieren, z. B. In Query Function, die einfache Anführungszeichen (Apostroph) enthalten, z. B. O'Brian oderMen's clothes müssen die Werte in doppelte Anführungszeichen gesetzt werden. 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"]

Andernfalls erhalten Sie denfolgenden Fehler: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 der Filter für einen einzelnen Wert gilt, 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'

Andernfalls erhalten Sie einen Fehler wie den folgenden: There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.

Reihenfolge von Ergebnissen

Geben Sie die Reihenfolge an, in der Elemente unter Verwendung Systemabfrageoption $orderby zurückgegeben werden. Verwenden Sie das asc- oder desc-Suffix, um eine jeweils aufsteigende oder absteigende Reihenfolge anzugeben. Die Standardeinstellung ist aufsteigend, wenn das Suffix nicht angewendet wird. Das folgende Beispiel zeigt das Abrufen der Namens- und Umsatzeigenschaften von Firmen, sortiert nach aufsteigendem Umsatz und absteigendem Namen.

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

Gesamt- und Gruppierungsergebnisse

Wenn Sie $apply verwenden, können Sie Ihre Daten dynamisch sammeln und gruppieren. Mögliche Anwendungsfälle mit $apply:

Anwendungsfall	Beispiel
Liste mit eindeutigen Status in der Abfrage	`accounts?$apply=groupby((statuscode))`
Gesamtsumme des Schätzwerts	`opportunities?$apply=aggregate(estimatedvalue with sum as total)`
Durchschnittliche Größe des Geschäftsabschlusses auf Grundlage des Schätzwert und des Status	`opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)`
Summe der Schätzwerte basierend auf dem Status	`opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))`
Verkaufschancengesamtumsatz nach Firmenname	`opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))`
Primäre Kontaktnamen für Konten in 'WA'.	`accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))`
Datum und Uhrzeit für zuletzt erstellten Datensatz	`accounts?$apply=aggregate(createdon with max as lastCreate)`
Datum und Uhrzeit für zuerst erstellten Datensatz	`accounts?$apply=aggregate(createdon with min as firstCreate)`

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: Verwenden Sie FetchXML, um eine Abfrage zu erstellen.

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

Verwendung von Parameteraliasen mit Systemabfrageoptionen

Sie können Parameteraliase für $filter- und $orderby-Systemabfrageoptionen verwenden. Parameteraliase erlauben die mehrmalige Verwendung des gleichen Werts in einer Anforderung. Wenn dem Alias kein Wert zugeordnet wurde, wird angenommen, dass er NULL ist.

Ohne Parameteraliasse:

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

Ruft eine Anzahl von Zeilen ab

Verwenden Sie die Systemabfrageoption $count mit dem Wert true, um eine Anzahl von Entitäten einzuschließen, die die Filterkriterien bis 5000 entsprechen.

Hinweis

Der Zählwert stellt nicht die Gesamtzahl der Zeilen im System dar. Es ist begrenzt durch die maximale Anzahl von Zeilen, die zurückgegeben werden können. Weitere Informationen: Limits für die Anzahl der zurückgegebenen Zeilen

Wenn Sie die Gesamtzahl der Zeilen für eine Tabelle über 5000 hinaus abrufen wollen, verwenden Sie die RetrieveTotalRecordCount Function.

Die Eigenschaft @odata.count der Antwort enthält die Anzahl der Zeilen, die den Filterkriterien entsprechen, unabhängig von einer odata.maxpagesize-Einschränkung.

Hinweis

Sie sollten nicht $top mit $count verwenden.

Das folgende Beispiel zeigt, dass zehn Firmen vorhanden sind, die den Kriterien übereinstimmen, wo der Name „Beispiel” enthält, aber nur die ersten drei Firmen zurückgegeben werden.

Anforderung

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

Antwort

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.maxpagesize=3  
  
{  
   "@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(name)",
   "@odata.count":10,
   "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"
}

Wenn Sie keine Daten bis auf die Anzahl zurückgeben möchten, können Sie $count auf eine beliebige Sammlung anwenden, um nur den Wert abzurufen.

Anforderung

GET [Organization URI]/api/data/v9.2/accounts/$count HTTP/1.1  
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

Formatierte Werte einschließen

Wenn Sie mit den Ergebnissen formatierte Werte für Eigenschaften abrufen möchten, verwenden Sie die Einstellung odata.include-annotations mit dem Wert OData.Community.Display.V1.FormattedValue. Die Antwort schließt diese Werte mit Eigenschaften ein, die mit der nächsten Namenskonvention übereinstimmen:

<propertyname>@OData.Community.Display.V1.FormattedValue

Das folgende Bespiel fragt den Firmenentitätssatz ab und gibt den ersten Datensatz zurück, einschließlich Eigenschaften, die formatierte Werte unterstützen.

Anforderung

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

Response

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,donotpostalmail,accountratingcode,numberofemployees,revenue)",
   "value":[  
      {  
         "@odata.etag":"W/\"502170\"",
         "name":"Fourth Coffee (sample)",
         "donotpostalmail@OData.Community.Display.V1.FormattedValue":"Allow",
         "donotpostalmail":false,
         "accountratingcode@OData.Community.Display.V1.FormattedValue":"Default Value",
         "accountratingcode":1,
         "numberofemployees@OData.Community.Display.V1.FormattedValue":"9,500",
         "numberofemployees":9500,
         "revenue@OData.Community.Display.V1.FormattedValue":"$100,000.00",
         "revenue":100000,
         "accountid":"89390c24-9c72-e511-80d4-00155d2a68d1",
         "transactioncurrencyid_value":"50b6dd7b-f16d-e511-80d0-00155db07cb1"
      }
   ]
}

Verwenden Sie die $expand-Systemabfrageoption in den Navigationseigenschaften, um zu steuern, welche Daten von den verbundenen Entitäten zurückgegeben werden. Weitere Informationen: Abrufen von verknüpften Tabellen mit einer Abfrage.

Daten zu Sucheigenschaften abrufen

Wenn die Abfrage Sucheigenschaften enthält, können Sie Anmerkungen anfordern, die zusätzliche Informationen zu den Daten dieser Eigenschaften bieten. Meistens können die gleichen Daten mit Kenntnissen der einzelbewerteten Navigationseigenschaften und der Daten, die in den verknüpften Entitäten enthalten sind, abgeleitet werden. Wenn die Eigenschaft jedoch ein Suchattribut darstellt, das auf mehr als einen Entitätstyp verweisen kann, können Ihnen diese Informationen mitteilen, auf welchen Entitätstyp die Sucheigenschaft verweist. Weitere Informationen: Sucheigenschaften

Es gibt zwei zusätzliche Anmerkungstypen für diese Eigenschaften.

Annotation	Beschreibung
Microsoft.Dynamics.CRM.associatednavigationproperty	Der Name der einzelbewerteten Navigationseigenschaft, der den Verweis auf die Entität einschließt.
Microsoft.Dynamics.CRM.lookuplogicalname	Der logische Name der Entität, auf die die Suche verweist.

Diese Eigenschaften können auch formatierte Werte enthalten, wie in Formatierte Werte einschließen beschrieben. Genau wie formatierte Werte können Sie die anderen Anmerkungen mithilfe der odata.include-annotations-Einstellung zurückgeben, die auf den bestimmten gewünschten Anmerkungstyp festgelegt ist, oder Sie können den Wert auf "*" festlegen und alle drei zurückgeben. Das folgende Beispiel zeigt die Anforderung und Antwort zum Abrufen von Informationen über die _customerid_value-Sucheigenschaft der Vorfall-Entität mit eingeschlossenen Anmerkungen.

Anfordern

GET [Organization URI]/api/data/v9.2/incidents(39dd0b31-ed8b-e511-80d2-00155d2a68d4)?$select=title,_customerid_value
&$expand=customerid_contact($select=fullname) HTTP/1.1  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Prefer: odata.include-annotations="*"

Response

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.include-annotations="*"  
  
{  
    "@odata.context":"[Organization URI]/api/data/v9.2/$metadata#incidents(title,_customerid_value,customerid_contact(fullname))/$entity",
    "@odata.etag":"W/\"504696\"",
    "_customerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty":"customerid_contact",
    "_customerid_value@Microsoft.Dynamics.CRM.lookuplogicalname":"contact",
    "_customerid_value@OData.Community.Display.V1.FormattedValue":"Susanna Stubberod (sample)",
    "_customerid_value":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4",
    "incidentid":"39dd0b31-ed8b-e511-80d2-00155d2a68d4",
    "customerid_contact":{  
        "@odata.etag":"W/\"503587\"",
        "fullname":"Susanna Stubberod (sample)",
        "contactid":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4"
    }
}

Synchronisieren von Daten mit externen Systemen mithilfe der Änderungsnachverfolgung

Mit der Änderungsnachverfolgungsfunktion können die Daten effizient synchronisiert werden, indem festgestellt wird, welche Daten geändert wurden, nachdem die Daten ursprünglich extrahiert oder zuletzt synchronisiert wurden. Änderungen, die in den Entitäten vorgenommen werden, können mithilfe von Web-API-Anforderungen nachverfolgt werden, indem odata.track-changes als Einstellungskopfzeile hinzugefügt wird. Die Einstellungskopfzeile odata.track-changes fordert an, dass ein Deltalink zurückgegeben wird, der später verwendet werden kann, um Entitätsänderungen abzurufen.

Weitere Informationen: Verwenden der Änderungsnachverfolgung zum Synchronisieren von Daten mit externen Systemen.

Spaltenvergleich mit der Web API

Das folgende Beispiel zeigt, wie Spalten mit der Web-API verglichen werden:

https://<environment-root>/contacts?$select=firstname&$filter=firstname eq lastname

Weitere Informationen: Spaltenvergleich in Abfragen verwenden

Siehe auch

Tabellendaten mit der Dataverse Suche durchsuchen
Arbeiten mit der Suchelementeinschränkung der Schnellsuche
Web API-Abfragedatenbeispiel (C#)
Web API-Abfragedatenbeispiele (clientseitiges JavaScript)
Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen verfassen und Fehler beheben
Erstellen einer Tabelle mit Hilfe der Web-API
Abrufen von Änderungen für eine Tabelle über Web-API
Tabellen aktualisieren und löschen mithilfe der Web-API
Tabellen zuordnen und Zuordnungen aufheben mithilfe der Web-API
Nutzen von Web-API-Funktionen
Nutzen von Web-API-Aktionen
Ausführen von Batchbetrieben mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit Web API
Bedingte Vorgänge mithilfe der Web-API ausführen

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).

Datenabfrage mit Web-API

Grundlegendes Abfragebeispiel

Grenzwerte der Zahl der zurückgegebenen Tabellenzeilen (Entitäten)

`$top`-Abfrageoption verwenden

Geben Sie die Anzahl der Zeilen an, die in einer Seite zurückgegeben werden sollen

Verwenden von Systemabfrageoptionen

Anforderungsspezifische Eigenschaften

Ergebnisse filtern

Standardfilteroperatoren

Standardabfragenfunktionen

Verwenden Sie Platzhalterzeichen in Bedingungen mit Zeichenfolgenwerte

Microsoft Dataverse-Web-API-Abfragefunktionen

Verwenden von Lambda-Operatoren

`any`-Operator

`all`-Operator

Filtern von übergeordneten Zeilen (Datensätzen) auf Grundlage der Werte von untergeordneten Datensätzen

Filterung von Zeilen (Datensätzen) auf Grundlage einer einzelbewerteten Navigationseigenschaft

Filtern von Ergebnissen basierend auf Werten von sammlungsbewerteten Navigationseigenschaften

Einfache Anführungszeichen in Zeichenfolgenfilterwerten verwalten

Reihenfolge von Ergebnissen

Gesamt- und Gruppierungsergebnisse

Verwendung von Parameteraliasen mit Systemabfrageoptionen

Ruft eine Anzahl von Zeilen ab

Formatierte Werte einschließen

Daten zu Sucheigenschaften abrufen

Synchronisieren von Daten mit externen Systemen mithilfe der Änderungsnachverfolgung

Spaltenvergleich mit der Web API

Siehe auch

Feedback

Datenabfrage mit Web-API

Ist diese Seite hilfreich?

Grundlegendes Abfragebeispiel

Grenzwerte der Zahl der zurückgegebenen Tabellenzeilen (Entitäten)

$top-Abfrageoption verwenden

Geben Sie die Anzahl der Zeilen an, die in einer Seite zurückgegeben werden sollen

Verwenden von Systemabfrageoptionen

Anforderungsspezifische Eigenschaften

Ergebnisse filtern

Standardfilteroperatoren

Standardabfragenfunktionen

Verwenden Sie Platzhalterzeichen in Bedingungen mit Zeichenfolgenwerte

Microsoft Dataverse-Web-API-Abfragefunktionen

Verwenden von Lambda-Operatoren

any-Operator

all-Operator

Filtern von übergeordneten Zeilen (Datensätzen) auf Grundlage der Werte von untergeordneten Datensätzen

Filterung von Zeilen (Datensätzen) auf Grundlage einer einzelbewerteten Navigationseigenschaft

Filtern von Ergebnissen basierend auf Werten von sammlungsbewerteten Navigationseigenschaften

Einfache Anführungszeichen in Zeichenfolgenfilterwerten verwalten

Reihenfolge von Ergebnissen

Gesamt- und Gruppierungsergebnisse

Verwendung von Parameteraliasen mit Systemabfrageoptionen

Ruft eine Anzahl von Zeilen ab

Formatierte Werte einschließen

Abrufen von verknüpften Tabellen mit einer Abfrage

Daten zu Sucheigenschaften abrufen

Synchronisieren von Daten mit externen Systemen mithilfe der Änderungsnachverfolgung

Spaltenvergleich mit der Web API

Siehe auch

Feedback

`$top`-Abfrageoption verwenden

`any`-Operator

`all`-Operator