OData-Systemabfrageoptionen mithilfe des OData-Endpunkts
Veröffentlicht: November 2016
Gilt für: Dynamics CRM 2015
Sie können genauere Ergebnisse für Ihre Abfrage erhalten, indem Sie Systemabfrageoptionen verwenden. Die folgende Tabelle führt die im OData-Protokoll definierten Optionen für die Abfragenzeichenfolge auf, die im OData Endpunkt für Microsoft Dynamics CRM 2015 und Microsoft Dynamics CRM Online 2015-Update implementiert werden.
Option |
Beschreibung |
|---|---|
$expand |
Weist an, dass verwandte Datensätze im Datensatz oder der Sammlung, die abgerufen wird, abgerufen werden. |
$filter |
Legt einen Ausdruck oder eine Funktion fest, die als wahr für einen Datensatz auswerten muss, damit ein Datensatz in der Sammlung zurückgegeben wird. |
$orderby |
Legt fest, welche Werte verwendet werden, um eine Sammlung von Datensätzen zu ordnen. |
$select |
Gibt eine Teilmenge von Eigenschaften an, die zurückgegeben werden sollen. |
$skip |
Legt die Anzahl von Datensätzen fest, die ausgelassen werden können, bevor Datensätze in einer Sammlung abgerufen werden. |
$top |
Legt die maximale Anzahl der Datensätze fest, die zurückgegeben werden sollen. |
$expand
Weist an, dass verwandte Datensätze im Datensatz oder der Sammlung, die abgerufen wird, abgerufen werden.
Wenn Sie verwandte Datensätze abrufen möchten, suchen Sie den Namen der Entitätsbeziehung, die diese Beziehung definiert. Möglicherweise müssen Sie die in der Anwendung die Entitätsbeziehungsinformationen anzeigen, um die Beziehung oder die konzeptionelle Schemadefinitionssprache (CSDL) für den Organisationsdatendienst richtig zu identifizieren.
Um beispielsweise Verkaufschancendatensätze abzurufen, die mit Firmen zusammenhängen, verwenden Sie die Entitätsbeziehung opportunity_customer_accounts. Die Abfrage /AccountSet?$expand=opportunity_customer_accounts gibt die Verkaufschancendatensätze und die Firmendatensätze zurück.
Wenn Sie die zurückgegebenen Spalten begrenzen, müssen Sie auch den Namen der Navigationseigenschaft in die Query einbeziehen. Beispielsweise gibt die Abfrage /AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts nur den Firmennamen und die erweiterten Verkaufschancendatensätze zurück.
Microsoft Dynamics CRM 2015 und Microsoft Dynamics CRM Online 2015-Update unterstützt nicht das Abfragen einer Beziehungseigenschaft auf mehreren Ebenen. Beispielsweise funktioniert diese Abfrage nicht, die Informationen über den besitzenden Benutzer von Verkaufschancen, die mit Firmen zusammenhängen, abrufen soll: /AccountSet?$expand=opportunity_customer_accounts/opportunity_owning_user.
Standardmäßig können Sie bis zu sechs Beziehungen definieren, die erweitert werden sollen. Diese Abfrage, bei der sowohl die Verkaufschancen und der Systembenutzer, der die Firma besitzt, eingeblendet werden, funktioniert /AccountSet?$select=Name,opportunity_customer_accounts,user_accounts&$expand=opportunity_customer_accounts,user_accounts.
Hinweis
Die Anzahl der verwandten Datensätze, die zurückgegeben werden, hängt von derselben Begrenzung der Anzahl der zurückgegebenen Datensätze ab. Weitere Informationen finden Sie unter Beschränkungen der Zahl der zurückgegebenen Datensätze. Sie können die Anzahl der Beziehungen, die erweitert werden sollen, erhöhen, indem Sie den Einstellungswert ServerSettingsMaxExpandCount ändern.
Weitere Informationen:OData: Option für die Filtersystemabfrage ($expand)
$filter
Legt einen Ausdruck oder eine Funktion fest, die als true auswerten muss, damit ein Datensatz in der Sammlung zurückgegeben wird.
Wenn Sie weitere Gruppen von Daten mithilfe des Links next abrufen, sollten Sie den Abfrageoptionswert $filter nicht ändern, da dies zu unvorhersehbaren Ergebnissen führt.
Der OData-Spezifikation für die Filter-System-Abfrageoption beschreibt die verwendeten Operatoren, um einen Ausdruck zu erstellen, um den Filter auszuwerten.Microsoft Dynamics 365 verwendet alle logische Operatoren und eine Teilmenge für die verfügbaren Funktionen, unterstützt jedoch nicht die Verwendung von arithmetischen Operatoren Filter können gruppierte Bedingungen verwenden, die in Klammern angegeben wurden. Vergleiche von Zeitwerten müssen das folgende Format verwenden: datetime’<time value>’, beispielsweise datetime'2010-07-15' oder datetime'2010-07-15T16:19:54Z'.
Die folgende Tabelle führt die Operatoren auf, die von Microsoft Dynamics 365 unterstützt werden.
Operator |
Beschreibung |
Beispiel |
|---|---|---|
eq |
Gleich |
/AccountSet?$filter=Address1_City eq 'Redmond' |
ne |
Ungleich |
/AccountSet?$filter=Address1_City ne null |
gt |
Größer als |
/AccountSet?$filter=CreditLimit/Value gt 1000 |
ge |
Größer als oder gleich |
/AccountSet?&$filter=CreditLimit/Value ge 1000 |
Lt |
Kleiner als |
/AccountSet?$filter=CreditLimit/Value lt 1000 |
le |
Kleiner oder gleich |
/AccountSet?$filter=CreditLimit/Value le 1000 |
and |
Logisch und |
/AccountSet?$filter=CreditLimit/Value ge 1000 and Address1_StateOrProvince eq 'TX' |
or |
Logisch oder |
/AccountSet?$filter=AccountCategoryCode/Value eq 2 or AccountRatingCode/Value eq 1 |
not |
Logische Negation |
/AccountSet?$filter=(AccountCategoryCode/Value ne null) and not (AccountCategoryCode/Value eq 1) |
Sie können die Abfrageoption $filter verwenden, um den Wert eines EntityReference-Attributs zu filtern. Wenn Sie beispielsweise den Wert Id für einen SystemUser-Datensatz haben, können Sie eine Liste aller Firmendatensätze abrufen, denen ein Benutzer zugewiesen ist, indem Sie den folgenden Filter verwenden:
/AccountSet?$filter=OwnerId/Id eq (guid'" + SystemUserId + "')
Die folgende Tabelle führt die Funktionen auf, die von Microsoft Dynamics 365 unterstützt werden.
Funktion |
Beispiel |
|---|---|
startswith |
/AccountSet?$filter=startswith(Name, 'a') |
substringof |
/AccountSet?$filter=substringof('store',Name) |
endswith |
/AccountSet?$filter=endswith(Name, '(sample)') |
Weitere Informationen:OData: Option für die Filtersystemabfrage ($filter)
$orderby
Legt fest, welche Werte verwendet werden, um eine Sammlung von Datensätzen zu ordnen. Die Reihenfolge ist standardmäßig aufsteigend. Verwenden Sie desc, um die Reihenfolge umzukehren, oder asc um den Standard explizit festzulegen.
Wenn Sie weitere Gruppen von Daten mithilfe des Links next abrufen, sollten Sie den Abfrageoptionswert $orderby nicht ändern, da dies zu unvorhersehbaren Ergebnissen führt.
Hinweis
Sie können bis zu 12 Spalten mithilfe von $orderby auswählen.
Wenn Sie nach komplexen Typen sortieren, wie beispielsweise EntityReference oder OptionSetValue, sollte nur der Attributname angegeben werden. Um beispielsweise nach dem primären Kontakt einer Firma zu sortieren, verwenden Sie die Abfrage $orderby=PrimaryContactId. Das Angeben von $orderby=PrimaryContactId/Name gibt Ihnen einen ungültigen Anforderungsfehler HTTP (HTTP Fehlercode 400) zurück.
Im folgenden Bespiel werden Firmendatensätze nach Land/Region in aufsteigender Reihenfolge und nach Standort in absteigender Reihenfolge aufgeführt:
/AccountSet?$select=Address1_Country,Address1_City,Name&$orderby=Address1_Country,Address1_City desc&$filter=(Address1_Country ne null) and (Address1_City ne null)
Weitere Informationen:OData: Option für die Filtersystemabfrage ($orderby)
$select
Gibt eine Teilmenge von Eigenschaften an, die zurückgegeben werden sollen, sowie die Reihenfolge, in der die Datenspalten angeordnet werden. Standardmäßig werden alle Spalten, die $select=* entsprechen, zurückgegeben.
Wenn Sie $expand verwenden, um verknüpfte Daten einzufügen und $select verwenden, um die zurückgegebenen Spalten zu begrenzen, müssen Sie auch den Namen der Navigationseigenschaft in die Abfrage einbeziehen. Beispielsweise gibt die folgende Abfrage /AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts nur den Firmennamen und die erweiterten Verkaufschancendatensätze zurück.
Hinweis
Es gibt eine maximale Pfadlänge von 2048 Zeichen für POST- und GET-Anforderungen in Internet Explorer. Sie können diesen Grenzwert einfach erreichen, falls Sie jedes Attribut in der Firmenentität in die Option $select einschließen. Weitere Informationen finden Sie unter Microsoft KB 208427.
Weitere Informationen:OData: Option für die Filtersystemabfrage ($select)
$skip
Legt die Anzahl von Datensätzen fest, die ausgelassen werden müssen, bevor Datensätze in einer Sammlung abgerufen werden.
Wenn Sie weitere Gruppen von Daten mithilfe des Links next abrufen, sollten Sie den Abfrageoptionswert $skip nicht ändern, da dies zu unvorhersehbaren Ergebnissen führt.
Weitere Informationen:OData: Option für die Filtersystemabfrage ($skip)
$top
Legt eine maximale Anzahl von Datensätzen fest, die zurückgegeben werden sollen.
Wenn Sie weitere Gruppen von Daten mithilfe des Links next abrufen, sollten Sie den Abfrageoptionswert $top nicht ändern, da dies zu unvorhersehbaren Ergebnissen führt.
Weitere Informationen:OData: Option für die Filtersystemabfrage ($top)
Nicht unterstützte Systemabfrageoptionen
Microsoft Dynamics CRM 2015 und Microsoft Dynamics CRM Online 2015-Update unterstützt nicht mithilfe der folgenden Systemabfrageoptionen:
$inlinecount
$count
$format
Siehe auch
Abfrage von Microsoft Dynamics CRM 2015-Daten mit dem OData-Endpunkt
OData: URI-Konventionen
© 2017 Microsoft. Alle Rechte vorbehalten. Copyright