LMS-API-Richtlinien für die Add-In-Integration für OneNote-Kursnotizbuch

  • Artikel

Gilt für: Unternehmensnotizbücher auf Office 365

Dieses Dokument enthält die API-Aufrufe, die OneNote benötigt, um Klassen und Aufgaben aufzuzählen, Aufgaben zu setzen, Jahrgangsstufen herunterzuladen und in jedem LMS zu aktualisieren.

Alle Anforderungen sollten authentifiziert werden. Alle Anforderungen sollten über HTTPS erfolgen.

Hinweis

Es wird dringend empfohlen, dass jedes LMS den Autorisierungscode Grant Flow für eine oauth2 Implementierung implementiert. Dadurch wird verhindert, dass der Benutzer bei jedem Ablauf des Zugriffstokens seine Zugangsdaten eingeben muss.

Abrufen einer Liste von Kursen

Stellen Sie eine GET Anforderung an <Specify URL for retrieving list of classes>.

LMS sollte ein JSON-Array von Kursen für den aktuell authentifizierten Benutzer zurückgeben.

Jeder Kurs sollte die folgenden Eigenschaften haben:

Eigenschaftenname Typ Beschreibung
ID Zeichenfolge Eindeutiger Bezeichner für die Klasse auf der LMS-Installation
Name Zeichenfolge Menschlich lesbarer Name des Kurses

Abrufen einer Liste der Kursteilnehmer in einem Kurs

Stellen Sie eine GET Anforderung an <Specify URL for retrieving list of students in a class>.

LMS sollte ein JSON-Array von Kursteilnehmern in dem Kurs zurückgeben.

Jeder Kursteilnehmer sollte die folgenden Eigenschaften haben:

Eigenschaftenname Typ Beschreibung
ID Zeichenfolge Bezeichner für den Schüler, eindeutig auf der LMS-Installation
Name Zeichenfolge Menschlich lesbarer Name des Schülers
E-Mail Zeichenfolge E-Mail-Adresse des Kursteilnehmers

Abrufen einer Liste von Aufgaben für einen Kurs

Stellen Sie eine GET Anforderung an <Specify URL for retrieving list of assignments for a class>.

LMS sollte ein JSON-Array mit Aufgaben für den Kurs zurückgeben.

Eigenschaftenname Typ Beschreibung
ID Zeichenfolge Bezeichner für die Aufgabe, eindeutig auf der LMS-Installation
Titel Zeichenfolge Titel der Aufgabe
Beschreibung Zeichenfolge Beschreibung der Aufgabe
gradetypeid Zeichenfolge Bezeichner für den Jahrgangsstufen-Typ, eindeutig auf der LMS-Installation
dueDate Datum als string (format: 2016-12-25T00:00:00) Fälligkeitsdatum der Aufgabe. LMS speichert oder verwendet den Zeitanteil nicht.
URL Zeichenfolge URL der Aufgabe. Nur in den unterstützten Versionen von LMS verfügbar.


Optionaler Eigenschaftenname Typ Beschreibung
gradetypeid Zeichenfolge Bezeichner für den Jahrgangsstufen-Typ, eindeutig auf der LMS-Installation
min Ganze Zahl Mindestpunktzahl, die einem Kursteilnehmer zugewiesen werden kann
max Ganze Zahl Maximale Punktzahl, die einem Kursteilnehmer zugewiesen werden kann
validgradevalues Liste Gültige Notenwerte für diese Aufgabe

Legen Sie eine Aufgabe für einen Kurs fest

Stellen Sie eine POST Anforderung an <Specify URL for setting an assignment to a class>.

Die folgenden Formular-POSTEN-Variablen werden benötigt:

Eigenschaftenname Typ Beschreibung
Titel string (max. Länge: 280) Titel der Aufgabe
dueDate Datum als string (format: 2016-12-25T00:00:00) Fälligkeitsdatum der Aufgabe
Beschreibung Zeichenfolge Beschreibung der Aufgabe


Optionaler Eigenschaftenname Typ Beschreibung
gradetypeid Zeichenfolge Bezeichner für den Jahrgangsstufen-Typ, eindeutig auf der LMS-Installation
min Ganze Zahl Mindestpunktzahl, die einem Kursteilnehmer zugewiesen werden kann
max Ganze Zahl Maximale Punktzahl, die einem Kursteilnehmer zugewiesen werden kann
validgradevalues Liste Gültige Notenwerte für diese Aufgabe

LMS gibt ein JSON-Objekt mit einer einzigen ID-Eigenschaft zurück. Der Wert dieser Eigenschaft ist der Bezeichner der neu gesetzten Aufgabe.

Abrufen einer Liste von Bewertungen für eine Aufgabe

Stellen Sie eine GET Anforderung an <Specify URL for retrieving grades for a given assignment>.

LMS sollte ein JSON-Array von Kursteilnehmern zurückgeben, die die Aufgabe und ihre Punktzahlen/Noten erhalten haben.

Jedes Kursteilnehmer-Segment von JSON sollte die folgenden Eigenschaften haben:

Eigenschaftenname Typ Beschreibung
ID Zeichenfolge Bezeichner für den Schüler, eindeutig auf der LMS-Installation
E-Mail Zeichenfolge E-Mail-Adresse des Kursteilnehmers
Bewertet boolesch Zeigt an, ob eine Punktzahl von der Lehrkraft angegeben wird
obtainedMark Ganze Zahl Optionale Punktzahl des Schülers (z.B. 85)
maxMark Ganze Zahl Optionale mögliche höchste Punktzahl (z.B. 100)
Feedback Zeichenfolge Optionale Rückmeldung an den Schüler (z.B. "Gute Arbeit")
Ergebnis Zeichenfolge Optionale Note des Schülers (z.B. "A")

Beachten Sie, dass LMS auch die Bewertung aus anderen Höchstpunktzahlen als 100 unterstützen kann. In diesem Fall (maxMark ist ungleich 100) muss OneNote möglicherweise die erhaltene Punktzahl konvertieren, wenn diese nicht in der OneNote-Benutzeroberfläche angezeigt werden kann.

Legen Sie eine Ergebnis für einen Kursteilnehmer fest

Stellen Sie eine POST Anforderung an <Specify URL for setting grade for a given student>.

Die folgende Formular-POSTEN-Variablen können eingebunden werden:

Eigenschaftenname Typ Beschreibung
ID Zeichenfolge Bezeichner für den Schüler, als Leitfaden
Quelle Zeichenfolge Stellen Sie den Wert immer auf " onenote ein"
obtainedMark Ganze Zahl Vom Schüler erreichte Punktzahl
maxMark Ganze Zahl Maximal erreichbare Punktzahl
obtainedGrade Zeichenfolge Vom Schüler erreichte Note oder Stufe (z.B.: "A")
Kommentare Zeichenfolge Freier Text für Feedback für den Kursteilnehmer

Abrufen von Ergebnis-Typen

Stellen Sie eine GET Anforderung an <Specify URL for getting grade types>.

LMS sollte ein JSON-Array von Ergebnistypen zurückgeben. Jeder Ergebnistyp sollte die folgenden Eigenschaften haben:

Eigenschaftenname Typ Beschreibung
ID Zeichenfolge Bezeichner für den Jahrgangsstufen-Typ, eindeutig auf der LMS-Installation
gradeTypeKategorie GradeTypeKategorie Kategorie für den Notentyp, eindeutig auf der LMS-Installation
max Ganze Zahl Maximal mögliche Punktzahl
Beschreibung Zeichenfolge Zeichenfolge für den Ergebnistyp anzeigen

Abrufen bestimmter Ergebnistypen

Stellen Sie eine GET Anforderung an <Specify URL for getting grade type by id>.

LMS sollte einen JSON vom Typ Einzelergebnis mit den folgenden Eigenschaften zurückgeben:

Eigenschaftenname Typ Beschreibung
ID Zeichenfolge Bezeichner für den Jahrgangsstufen-Typ, eindeutig auf der LMS-Installation
gradeTypeKategorie GradeTypeKategorie Kategorie für den Notentyp, eindeutig auf der LMS-Installation
max Ganze Zahl Maximal mögliche Punktzahl
Beschreibung Zeichenfolge Zeichenfolge für den Ergebnistyp anzeigen

Erstellen/Löschen von Klassen und zum Löschen von Aufgaben

Diese sind optional, werden aber für Integrationstests dringend empfohlen. Das Microsoft Kursnotizbuch Team übt diese Endpunkte zur Bereinigung aus.

enum GradeTypeCategory
{
        /// <summary>
        /// no grade type category.
        /// </summary>
        None,

        /// <summary>
        /// Numeric grade type category.
        /// </summary>
        Numeric,

        /// <summary>
        /// Percent grade type category.
        /// </summary>
        Percentage,

        /// <summary>
        /// Letter grade type category.
        /// </summary>
        Letters,
}

Testen der erforderlichen Komponenten der Umgebung

Ihre Testumgebung besteht aus zwei Systemen:

  • Office 365 Test-Mandant

    Dies kann jeder Office 365 Mandant sein, zu dem Sie Zugang haben und es gibt ein paar Lehrer- und Kursteilnehmerkonten mit gültigen Bürolizenzen.

    Die Office 365-Mandanten Demo steht Partnern zur Verfügung. Wenn Sie diesen Demo-Mandanten einrichten, können Sie eine benutzerdefinierte K–12 EDU-Instanz auswählen, die mit Lehrern und Kursteilnehmern und Bildungs-SKUs vorbesetzt ist.

  • LMS-Testumgebung und Konten

    Sie müssen dem Kursnotizbuch-Team folgende Informationen zur Verfügung stellen:

    • Basis-Url Ihres LMS/SIS, das die API-Endpunkte hostet.
    • App-ID (sofern Sie oauth2 nicht unterstützen): Eine eindeutige App-ID, die dem Kurs-Notizbuch Add-In zugewiesen ist, die Ihnen ermöglicht, diese als gültige Anwendung zu erkennen.
    • App-Schlüssel (falls Sie oauth2 nicht unterstützen): der geheime App-Schlüssel für die angegebene App-ID.

Erforderliche Marketing-Informationen

  • Logo-Abbild. Es muss nicht unbedingt eine sehr hohe Auflösung sein. Unsere aktuellen Logos haben tatsächlich weniger als 100 KB an Größe und bis zu maximal 300 x 300 Pixel.

  • Beschreibung. Die Beschreibung sollte kurz sein, ca. 75 Wörter (besser, wenn nur etwa 50) mit Nachrichten über Ihr Angebot.

  • Link zu Ihrer Website. Dazu gedacht, um mehr über Ihr Angebot zu erfahren.

  • Schaltfläche Logo. Es sollte ein Logo von 64 x 64 Pixel sein.

Siehe auch