Abfrageoptionen in der Learn365-API: Übersicht und Nutzung

Einführung

Bei der Verwendung von API-Endpunkten wird eine API-Anfrage an einen Server (Ressource) gesendet. Nach der Verarbeitung sendet der Server eine Antwort an den Client (Learn365) zurück, die die abgerufenen Informationen oder das Ergebnis der ausgeführten Funktion enthält. Anzahl und Reihenfolge der Daten, die in der Antwort an Learn365 zurückgegeben werden, können in Swagger über eine Reihe von Abfragezeichenfolgenparametern gesteuert werden: die Systemabfrageoptionen.

Dieser Artikel beschreibt die Systemabfrageoptionen der Learn365-API und zeigt, wie diese verwendet werden können.

Abfrageoptionen

Überblick

API-Anfragen können verwendet werden, um Kurse und Schulungspläne sowie zugehörige Materialien zu verwalten, Statistiken über Benutzer und Schulungen abzurufen, Benutzer hinzuzufügen und zu entfernen, sie zu registrieren und Registrierungen aufzuheben und vieles mehr.

Abhängig von der im Mandanten gespeicherten Datenmenge können bestimmte API-Anfragen Ihren Mandanten stark belasten, wodurch die Berichterstellung, die Seitenladezeit oder das Laden insgesamt verlangsamt werden können. All dies lässt sich durch eine Steuerung der zurückgegebenen Antwortdaten vermeiden, was mithilfe von Systemabfrageoptionsparametern geschieht. 

Systemabfrageoptionen sind Abfragezeichenfolgenparameter, die die Menge und Reihenfolge der für die durch die URL identifizierte Ressource zurückgegebenen Daten steuern. Den Namen aller Systemabfrageoptionen wird ein Dollarzeichen ($) vorangestellt. Folgende Systemabfrageoptionen sind vorhanden:

• $expand
• $filter
• $select
• $orderby
• $top
• $skip
• $count

Für die Abfrageoptionsparameter können die Standarddaten der Werte folgende Typen haben:

• guid - die eindeutige id, die dem freigegebenen Parameter zugeordnet ist.
• string – jede endliche Abfolge von Zeichen (Buchstaben, Ziffern, Symbole, Interpunktionszeichen usw.).
• integer – Ganzzahl.
• boolean – Variable mit dem Wert „true“ oder „false“.

$expand

Mit der Systemabfrageoption $expand können Clients zusammengehörende Einträge mit einer einzigen URL zurückgeben – die zugehörigen Ressourcen oder Medienstreams werden inline zusammen mit den abgerufenen Ressourcen eingebunden.

Entitäten, die in dieser Weise erweitert werden können, sind im Abschnitt Model der Eigenschaft unter dem Block Responses oder unter Models am Ende der Abschnittsliste der Learn365-API einsehbar.

Sie können eine Eigenschaft erweitern, die in einer anderen Eigenschaft verschachtelt ist. Abfrageoptionen können auf eine erweiterte Navigationseigenschaft angewendet werden, indem eine in Klammern eingeschlossene, durch Semikola getrennte Liste von Abfrageoptionen an den Namen der Navigationseigenschaft angehängt wird. Zulässige Systemabfrageoptionen sind $filter, $select, $orderby, $skip, $top, $count, $search und $expand. Details zur Filterspezifikation finden Sie hier.

Beispiele

Ein Beispiel für eine Eigenschaft, die für die Abfrageoption $expand des Abschnitts Courses verwendet werden kann, ist: Quizzes.

In diesem speziellen Fall erhalten Sie in der Antwort Daten zu jedem Quiz, das im jeweiligen Kurs des Mandanten enthalten ist. Sie können die Ergebnisse im JSON-Dateiformat auf Ihren Computer herunterladen.

Ein Beispiel für eine Anfrage mit einer Eigenschaft, die in einer anderen Eigenschaft verschachtelt ist, wäre etwa die GET-Anfrage /odata/v2/Courses aus dem Abschnitt Courses: Erweitern Sie die Eigenschaft Course unter Model > erweitern Sie die Eigenschaft Quizzesproperty inside the Course property > Sharing. In diesem Fall lautet der Wert von $expand folglich: Quizzes($expand=Sharing)

In diesem konkreten Fall erhalten Sie in der Antwort die Daten zu den Freigabeeinstellungen des jeweiligen Quiz jedes Kurses im Mandanten. Sie können die Ergebnisse im JSON-Dateiformat auf Ihren Computer herunterladen.

$filter

Mit der Systemabfrageoption $filter können Benutzer eine Sammlung von Ressourcen filtern, die von einer Anfrage-URL adressiert werden, und eine Antwort zurückerhalten, die nur die Elemente enthält, die die Bedingung erfüllen. Sie können auch nach einer Eigenschaft filtern, die in einer anderen Eigenschaft verschachtelt ist. Details zur Filterspezifikation finden Sie hier.

Eine Anzahl nicht auswählbarer und nicht filterbarer API-Eigenschaften, die nicht mit $filter verwendet werden können, finden Sie hier.

Beispiele

Ein Beispiel für einen verschachtelten $filter ist etwa die GET-Anfrage /odata/v2/Courses aus dem Abschnitt Courses : Dabei wird $filter auf 'IsPublished eq true' festgelegt, wobei IsPublished den Parameter angibt, nach dem gefiltert werden soll, eq ein Gleichheitsoperator ist und true ein Filterwert ist. 

In diesem Fall enthält die Antwort nur die Daten zu den veröffentlichten Kursen des Mandanten.

Es ist auch möglich, nach erweiterten Eigenschaften zu filtern, die aus dem Bereich Model des betreffenden Abschnitts abgerufen wurden. Geben Sie zuerst mit $expand an, auf welchen Teil von Model der Filter angewendet werden soll, und legen Sie dann mit $filter den Filterparameter fest.

Im Beispiel nehmen wir die GET-Anfrage /odata/v2/Enrollments aus dem Abschnitt Enrollments und setzen Course für $expand, um der Antwort Daten zu Kursen und Schulungsplänen hinzuzufügen. Dann setzen wir den Filterparameter für $filter auf Course/CourseType eq 'TrainingPlan', wobei CourseType den Parameter angibt, nach dem gefiltert wird, eq ein Gleichheitsoperator ist und 'TrainingPlan' ein Filterwert ist. Die Ergebnisse in der Antwort werden nach dem Schulungstyp gefiltert, sodass nur die Schulungspläne aus allen Kurskatalogen des Mandanten angezeigt werden.

$select

Mit der Option $select können Sie die exakten Eigenschaften (d. h. die jeweilige Entität oder den jeweiligen komplexen Typ) angeben, die Sie in die Antwort einschließen möchten.

Die Abfrageoption $select wird oft in Verbindung mit der $expand-Systemabfrageoption verwendet, um den Umfang des zurückzugebenden Ressourcengraphen zu definieren ($expand) und dann eine Teilmenge von Eigenschaften für die jeweilige Ressource im Graphen anzugeben ($select).

Details zur Filterspezifikation finden Sie hier.

Eine Anzahl nicht auswählbarer und nicht filterbarer API-Eigenschaften, die nicht für $select verwendet werden können, finden Sie hier.

Beispiel

Wenn Sie beispielsweise 'Title' für die $select-Abfrage für die GET-Anfrage /odata/v2/Competencies (skills) aus dem Abschnitt Competencies (skills) verwenden, enthält die Antwort nur die Ergebnisse, die diesem Parameter entsprechen – nämlich die Titel der Qualifikationen des gesamten Tenants. 

Ein Beispiel für eine Kombination von $select und $expand könnte die folgende Anfrage sein: Angenommen, Sie verwenden Title für $select in der GET-Anfrage /odata/v2/Competencies (skills) aus dem Abschnitt Competencies (skills) und setzen Course für $expand. 

In diesem Fall enthält die Antwort den Titel der Qualifikation und Daten zu den Kursen, für die diese Qualifikation zuerkannt wird.

$orderby

Mit der Systemabfrageoption $orderby können Clients Ressourcen in einer bestimmten Reihenfolge abrufen. Details zur Filterspezifikation finden Sie hier.

Zusammengehörige Entitäten können sortiert werden, wenn $orderby innerhalb der $expand-Klausel angegeben wird.

Beispiele

Beispielsweise erhalten Sie, wenn Sie RegistrationDate desc für $orderby in der GET-Anfrage /odata/v2/Enrollments aus dem Abschnitt Enrollments verwenden, eine Antwort, in der alle Kurse aus dem Tenant absteigend nach dem Registrierungsdatum sortiert sind. 

Ein Beispiel für eine Kombination aus $orderby und $expand könnte dieselbe GET-Anfrage /odata/v2/Enrollments sein: Course für $expand und Course/WBE desc für $orderby. In diesem Fall enthält der Antworttext Kurse, die absteigend nach der Anzahl der zuerkannten WBEs sortiert sind.

Ferner wird $count oft innerhalb eines $orderby-Ausdrucks verwendet, um die zurückgegebenen Elemente nach der genauen Anzahl zusammengehörender Entitäten oder Elemente innerhalb einer Eigenschaft mit Sammlungswerten zu sortieren.

Verwenden wir sowohl $count als auch $orderby für die GET-Anfrage /odata/v2/Registrierungen aus dem Abschnitt Registrierungen: Legen Sie RegistrationDate desc für $orderby fest und wählen Sie true für $count. 

In den Ergebnissen zeigt uns die Antwort nicht nur die Schulungen, geordnet nach der absteigenden Anzahl der gewährten WBEs, sondern auch die Anzahl der Kurse und Tarife mit WBEs wird gezählt und am Anfang der Antwort angezeigt.

$top

Mit der Systemabfrageoption $top können Clients eine Antwort abrufen, die nur die ersten n Ergebnisse enthält. Geben Sie für das Feld eine ganze Zahl an, um die entsprechende Anzahl von Rückgabewerten in der Antwort zu erhalten. 

Ferner ist $top besonders praktisch, wenn es mit der $orderby-Option verwendet wird.

Details zur Filterspezifikation finden Sie hier.

Beispiele

Zum Beispiel können wir $top für die GET-Anfrage /odata/v2/CourseCatalogs aus dem Abschnitt CourseCatalogs auf 15 festlegen. In diesem Fall zeigt uns die Anfrage die ersten 15 Kurskataloge des Tenants.

Ein Beispiel für eine Kombination von $top und $orderby könnte die GET-Anfrage /odata/v2/Enrollments aus dem Abschnitt Enrollments sein: Titel für $orderby und 10 für $top. In diesem Fall gibt der Antworttext die ersten 10 Kurskataloge des Mandanten an, sortiert nach dem Titel.

Ein Client kann eine bestimmte Seite mit Elementen abrufen, indem er $top und $skip kombiniert.

$skip

Mit der Abfrageoption $skip können Clients eine Antwort abrufen, bei der die ersten x Ergebnisse übersprungen werden. Tragen Sie eine ganze Zahl in das Feld ein. Sie erhalten dann eine Antwort, in der die entsprechende Anzahl der ersten Rückgabewerte übersprungen ist. 

Details zur Filterspezifikation finden Sie hier.

Beispiele

Beispielsweise können wir $skip für die GET-Anfrage /odata/v2/CourseCatalogs aus dem Abschnitt CourseCatalogs auf 20 festlegen. In diesem Fall zeigt die Anfrage Kurskataloge aus dem Mandanten an, wobei die ersten 20 Ergebnisse übersprungen wurden.

$skip ist besonders praktisch, wenn es mit $orderby und/oder in Kombination mit der Option $top verwendet wird.

Wenn beispielsweise $orderby auf „Course/WBE desc“, $top auf 15 und $skip auf 20 festgelegt wird, enthält die Antwort die 15 wichtigsten Kurse, absteigend sortiert nach den zuerkannten WBEs, wobei die ersten 20 Ergebnisse übersprungen werden. 

$count

Mit der Systemabfrageoption $count können Clients die Anzahl der übereinstimmenden Ressourcen anfordern, die zusammen mit den Ressourcen in der Antwort enthalten ist. Die Abfrageoption $count hat einen booleschen Wert von „true“ oder „false“.

Die Antwort wird als „count. [Anzahl der passenden Ergebnisse] dargestellt. Beispiel:

 "@odata.count": 50

Details zur Filterspezifikation finden Sie hier.

Any und all

Wenn Sie expand für Eigenschaften verwenden, die keinen Einzelwert, sondern eine Sammlung zurückgeben, sollten die Operatoren any/all zum Filtern von Sammlungsfeldern verwendet werden. Beiden ist ein Navigationspfad voranzustellen, durch den eine Sammlung identifiziert wird. 

• Der any-Operator wendet einen booleschen Ausdruck auf jedes Element einer Sammlung an und gibt dann „true“ zurück, wenn und nur wenn der Ausdruck für ein beliebiges Element der Sammlung wahr ist; andernfalls wird „false“ zurückgegeben.  Dies impliziert auch, dass der any-Operator für eine leere Sammlung immer „false“ ist. Der any Operator kann ohne einen Argumentausdruck verwendet werden.
• Der all-Operator wendet einen booleschen Ausdruck auf jedes Element einer Sammlung an und gibt „true“ zurück, wenn der Ausdruck für alle Elemente der Sammlung wahr ist; andernfalls wird „false“ zurückgegeben. Dies impliziert auch, dass der all-Operator für eine leere Sammlung immer „true“ ist. Der all-Operator kann nicht ohne einen Argumentausdruck verwendet werden.

Ausführliche Informationen finden Sie hier.

Nutzung von Abfrageoptionen

Rufen Sie Swagger auf und lassen Sie sich autorisieren. Dann scrollen Sie nach unten zum Block Learn365 API und suchen dort nach dem betreffenden Abschnitt und der Methode.

Wir zeigen die Verwendung von Abfrageoptionen am Beispiel einer API-Anfrage aus dem Abschnitt Registrierungen .

Wir verwenden die GET-Anfrage /odata/v2/Enrollments mit der Beschreibung Returns the list of current user's active Enrollments , die die Liste der aktiven Registrierungen des aktuellen Benutzers zurückgibt.

Um fortzufahren, wählen Sie die Option Try it out aus, geben die Abfrageparameter ein und wählen die Schaltfläche Execute , um die Anfrage auszuführen. Ffcr unser Beispiel legen wir diese Parameter so fest, dass wir Daten (einschliedflich Benutzer-ID, Registrierungsdatum und Registrierungsstatus) zu den 15 aktivsten Kursen erhalten (wobei die ersten 20 0Ergebnisse fcbersprungen werden) und diese Kurse nach dem Registrierungsdatum der Benutzer absteigend sortiert werden.

Scrollen Sie zum Block Responses, um die Ergebnisse einzusehen:

• Die Zahl 2xx (beispielsweise „200“) unter Code zeigt an, dass die Anfrage korrekt funktioniert hat.
• Das Feld Response body zeigt die Daten entsprechend den festgelegten Eigenschaften an. Sie können die Suche über Strg+F aufrufen, um die relevanten Daten zu finden.