Table of contents
TOC
Inhaltsverzeichnis reduzieren
Inhaltsverzeichnis erweitern
Zuletzt aktualisiert: 20.06.2018

Authentifizierungsrichtlinien

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.

API-Richtlinien für die Add-in-Integration für OneNote-Kursnotizbuch

Gilt für: Enterprise-Notizbü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 Anfragen sollten über HTTPS erfolgen.

Liste der Klassen abrufen

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

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

Jede Klasse sollte die folgenden Eigenschaften haben:

EigenschaftennameTypBeschreibung
idstringEindeutiger Bezeichner für die Klasse auf der LMS-Installation
namestringMenschlich lesbarer Name der Klasse

Abrufen einer Liste von Schülern einer Klasse

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

LMS sollte ein JSON-Array von Schülern in der Klasse zurückgeben.

Jeder Schüler sollte die folgenden Eigenschaften haben:

EigenschaftennameTypBeschreibung
idstringBezeichner für den Schüler, eindeutig auf der LMS-Installation
namestringMenschlich lesbarer Name des Schülers
emailstringE-Mail-Adresse des Schülers

Eine Aufgabenliste zu einer Klasse abrufen

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

LMS sollte ein JSON-Array mit Aufgaben für die Klasse zurückgeben.

EigenschaftennameTypBeschreibung
idstringBezeichner für die Aufgabe, eindeutig auf der LMS-Installation
titlestringTitel der Aufgabe
descriptionstringBeschreibung der Aufgabe
gradetypeidstringBezeichner für den Jahrgangsstufen-Typ, eindeutig auf der LMS-Installation
dueDateDatum als string (format: 2016-12-25T00:00:00)Fälligkeitsdatum der Aufgabe. LMS speichert oder verwendet den Zeitanteil nicht.
urlstringURL der Aufgabe. Nur in den unterstützten Versionen von LMS verfügbar.
Optionaler EigenschaftennameTypBeschreibung
gradetypeidstringBezeichner für den Jahrgangsstufen-Typ, eindeutig auf der LMS-Installation
minintegerMindestpunktzahl, die einem Schüler zugeordnet werden kann
maxintegermaximale Punktzahl, die einem Schüler zugewiesen werden kann
validgradevalueslistgültige Notenwerte für diese Aufgabe

Einer Klasse eine Aufgabe stellen

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

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

EigenschaftennameTypBeschreibung
Titelstring (max. Länge: 280)Titel der Aufgabe
dueDateDatum als string (format: 2016-12-25T00:00:00)Fälligkeitsdatum der Aufgabe
BeschreibungstringBeschreibung der Aufgabe
Optionaler EigenschaftennameTypBeschreibung
gradetypeidstringBezeichner für den Jahrgangsstufen-Typ, eindeutig auf der LMS-Installation
minintegerMindestpunktzahl, die einem Schüler zugeordnet werden kann
maxintegermaximale Punktzahl, die einem Schüler zugeordnet werden kann
validgradevalueslistgü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.

Liste der Noten für eine Aufgabe abrufen

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

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

Jedes Schüler-Segment von JSON sollte die folgenden Eigenschaften haben:

EigenschaftennameTypBeschreibung
idstringBezeichner für den Schüler, eindeutig auf der LMS-Installation
E-MailstringE-Mail-Adresse des Schülers
bewertedBooleanZeigt an, ob eine Punktzahl von der Lehrkraft angegeben wird
obtainedMarkintegerOptionale Punktzahl des Schülers (z.B. 85)
maxMarkintegerOptionale mögliche höchste Punktzahl (z.B. 100)
RückmeldungstringOptionale Rückmeldung an den Schüler (z.B. "Gute Arbeit")
gradestringOptionale 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.

Eine Note für einen Schüler einstellen

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

Die folgende Formular-POST-Variablen können eingebunden werden.

EigenschaftennameTypBeschreibung
idstringBezeichner für den Schüler, als Leitfaden
sourcestringStellen Sie den Wert immer auf " onenote ein"
obtainedMarkintegerVom Schüler erreichte Punktzahl
maxMarkintegerMaximal erreichbare Punktzahl
obtainedGradestringVom Schüler erreichte Note oder Stufe (z.B.: "A")
commentsstringFreitext-Feedback für den Schüler

Notentypen erhalten

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

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

EigenschaftennameTypBeschreibung
idstringBezeichner für den Jahrgangsstufen-Typ, eindeutig auf der LMS-Installation
gradeTypeKategorieGradeTypeKategorieKategorie für den Notentyp, eindeutig auf der LMS-Installation
maxintegermaximal mögliche Punktzahl
BeschreibungstringZeichenfolge für den Notentyp anzeigen

speziellen Notentyp erhalten

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

LMS sollte einen JSON vom Typ Einzelnote zurückgeben, der die folgenden Eigenschaften hat:

EigenschaftennameTypBeschreibung
idstringBezeichner für den Jahrgangsstufen-Typ, eindeutig auf der LMS-Installation
gradeTypeKategorieGradeTypeKategorieKategorie für den Notentyp, eindeutig auf der LMS-Installation
maxintegermaximal mögliche Punktzahl
BeschreibungstringZeichenfolge für den Notentyp anzeigen

APIs zum Anlegen/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 diesen Endpunkt 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,
}

Testumgebung Voraussetzungen

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 Schülerkonten mit gültigen Bürolizenzen. Es gibt einen Demo Office 365 Mandant, verfügbar für Partner. Wenn Sie diesen Demo-Mandanten einrichten, können Sie eine benutzerdefinierte K - 12 EDU-Instanz auswählen, die mit Lehrern und Schülern 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* - eindeutige App-ID, die dem Kursnotizbuch-Add-In zugeordnet ist und die es Ihnen ermöglicht, diese als gültige Anwendung zu erkennen.
  • App-Taste* - App-Geheimnis für die angegebene App-ID

*wenn Sie oauth2 nicht unterstützen

Marketing Information Voraussetzungen

Logo Bild

Es muss nicht unbedingt eine sehr hohe Auflösung sein. Unsere aktuellen Logos sind in der Tat weniger als 100k und bis zu 300x300px groß.

Beschreibung

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

Möchten Sie mehr über Ihr Angebot erfahren?

Es sollte ein 64x64 Pixel Logo sein

Zusätzliche Ressourcen

© 2018 Microsoft