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: eindeutige ID, die mit dem betreffenden Parameter verknüpft ist
• string: jede endliche Abfolge von Zeichen (Buchstaben, Ziffern, Symbole, Interpunktionszeichen usw.)
• integer: Ganzzahl
• boolean: Variable mit dem Wert „true“ (wahr) oder „false“ (falsch)

 

$expand

Mit der Systemabfrageoption $expand können Clients zusammengehörende Einträge mit einer einzigen URL zurückgeben. Die zusammengehörenden Ressourcen oder Medienströme werden je nach 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 Quizzes innerhalb der Eigenschaft Course > 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 eine verschachtelte $filter-Abfrage 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 den Wert angibt, nach dem gefiltert wird.

 

 

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 verwenden wir die GET-Anfrage /odata/v2/Enrollments aus dem Abschnitt Enrollments und legen Course für $expand fest, um Daten zu Kursen und Schulungsplänen in der Antwort hinzuzufügen. Dann legen wir als Filterparameter für $filter Course/CourseType eq 'TrainingPlan' fest, wobei CourseType den Parameter zum Filtern angibt, eq ein Gleichheitsoperator ist und 'TrainingPlan' als Filterwert bestimmt wird. 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 Systemabfrageoption $expand 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 mit $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, wird die Antwort nur die Ergebnisse enthalten, die mit diesem Parameter übereinstimmen (nämlich die Titel der Qualifikationen des gesamten Mandanten).

 

 

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

 

 

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 Mandanten absteigend nach dem Registrierungsdatum sortiert sind.

 

 

Als Beispiel für eine Kombination von $orderby und $expand könnte die gleiche GET-Anfrage /odata/v2/Enrollments fungieren: Course für $expand und Course/CEU 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.

Wir können sowohl $count als auch $orderby für die GET-Anfrage /odata/v2/Enrollments aus dem Abschnitt Enrollments verwenden: 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 in absteigender Reihenfolge der zuerkannten WBEs an, sondern es wird auch die Anzahl der Kurse und Schulungspläne mit WBEs 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 Option $orderby 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 CourseCatalogs Abschnitt 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: Geben Sie Title für $orderby und 10 für $top an. 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 Systemabfrageoption $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 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 der Option $orderby und/oder in Kombination mit der Option $top verwendet wird.

Wenn beispielsweise $orderby auf „Course/CEU“, $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 wurden.

 

 

$count

Mit der Systemabfrageoption $count können Clients die Anzahl passender Ressourcen abfragen, die in den Ressourcen in der Antwort enthalten sind. Die Abfrageoption $count hat einen booleschen Wert („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, dann können 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 (und nur dann) „true“ zurück, 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 werden die Verwendung von Abfrageoptionen am Beispiel einer API-Anfrage aus dem Abschnitt Enrollments zeigen.

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

 

 

Zum Fortfahren 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. Für unser Beispiel legen wir die Parameter so fest, dass wir Daten (und zwar konkret die Benutzer-ID, das Registrierungsdatum und den Registrierungsstatus) zu den 15 aktivsten Kursen erhalten (wobei die ersten 20 Ergebnisse übersprungen werden) und diese Kurse nach dem Registrierungsdatum der Benutzer absteigend sortiert werden.

 

 

Scrollen Sie zum Block Reponses, um die Ergebnisse einzusehen:

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