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