Instructions concernant l'API LMS pour l'intégration du complément bloc-notes OneNote pour la classe

Article
04/13/2017

S’applique aux : Blocs-notes d’entreprise sur Office 365

Ce document présente les appels API qui permettent à OneNote d'énumérer les classes et les devoirs, de définir les devoirs, de télécharger les notes et de les mettre à jour au sein de n'importe quel LMS.

Toutes les demandes doivent être authentifiées. Toutes les demandes doivent être effectuées via HTTPS.

Notes

Il est recommandé que chaque LMS implémente flux d'octroi de code d'autorisation pour implémenter oauth2. Cela empêche l’utilisateur d'avoir besoin d’entrer les informations d’identification chaque fois qu’un jeton d’accès arrive à expiration.

Récupérer une liste de classes

Effectuer une demande GET à <Specify URL for retrieving list of classes>.

Le LMS doit renvoyer un tableau JSON des classes pour l'utilisateur actuellement authentifié.

Chaque classe doit avoir les propriétés suivantes :

Nom de la propriété	Type	Description
id	chaîne	Identifiant unique de la classe pour l'installation du LMS
nom	chaîne	Nom de la classe visuellement contrôlable

Récupérer la liste des participants dans une classe

Effectuer une demande GET à <Specify URL for retrieving list of students in a class>.

Le LMS doit renvoyer un tableau JSON des étudiants de la classe.

Chaque étudiant doit avoir les propriétés suivantes :

Nom de la propriété	Type	Description
id	chaîne	Identifiant unique de l'étudiant pour l'installation du LMS
nom	chaîne	Nom de l'étudiant visuellement contrôlable
email	chaîne	Adresse de messagerie de l’étudiant

Récupérer la liste des activités pour une classe

Effectuer une demande GET à <Specify URL for retrieving list of assignments for a class>.

Le LMS doit renvoyer un tableau JSON des affectations de la classe.

Nom de la propriété	Type	Description
id	chaîne	Identifiant unique du devoir pour l'installation du LMS
title	chaîne	Titre de l'activité

description	chaîne	Description de l'activité
gradetypeid	chaîne	Identifiant unique du type de note pour l'installation du LMS
dueDate	date sous forme de chaîne (format : 2016-12-25T00:00:00)	Date d'échéance de l'activité. Le LMS ne stockera pas et n'utilisera la partie « heure ».
url	chaîne	URL du devoir. Disponible uniquement pour les versions de LMS prises en charge.

Nom de propriété facultatif	Type	Description
gradetypeid	chaîne	Identifiant unique du type de note pour l'installation du LMS
min	entier	Score minimal pouvant être attribué à un étudiant
max	entier	Score maximal pouvant être attribué à un étudiant
validgradevalues	list	Valeurs valides pour les notes de cette activité

Définir une activité à une classe

Effectuer une demande POST à <Specify URL for setting an assignment to a class>.

Les variables de formulaire POST suivantes sont obligatoires :

Nom de la propriété	Type	Description
title	chaîne (longueur maximale : 280)	Titre de l'activité

dueDate	date sous forme de chaîne (format : 2016-12-25T00:00:00)	Date d'échéance du devoir
description	chaîne	Description de l'activité

Nom de propriété facultatif	Type	Description
gradetypeid	chaîne	Identifiant unique du type de note pour l'installation du LMS
min	entier	Score minimal pouvant être attribué à un étudiant
max	entier	Score maximal pouvant être attribué à un étudiant
validgradevalues	list	Valeurs valides pour les notes de cette activité

Le LMS renvoie un objet JSON avec une seule propriété d'identification. La valeur de cette propriété constituera l'identificateur pour la nouvelle activité.

Récupérer une liste de notes pour une activité

Effectuer une demande GET à <Specify URL for retrieving grades for a given assignment>.

Le LMS doit renvoyer un tableau JSON des étudiants auxquels l'activité a été assignée, ainsi que leurs notes/scores.

Les segments JSON propres à chaque étudiant doivent contenir les propriétés suivantes :

Nom de la propriété	Type	Description
id	chaîne	Identifiant unique de l'étudiant pour l'installation du LMS
email	chaîne	Adresse de messagerie de l’étudiant
graded	booléen	Indique si une note a été fournie par l'enseignant
obtainedMark	entier	Note obtenue par l'étudiant (par ex. 85) (facultatif)
maxMark	entier	Note maximale possible (par exemple 100) (facultatif)
feedback	chaîne	Commentaires fournis à l'étudiant (par ex. "Bon travail") (facultatif)
grade	chaîne	Note fournie à l'étudiant (par ex. "A") (facultatif)

Notez que le LMS peut prendre en charge la notation par des chiffres autres que 100. Dans ce cas (si la note maximale n'est pas égale à 100), il est possible que OneNote doive convertir la note obtenue si celle-ci ne peut être affichée dans l'interface utilisateur de OneNote.

Définir une note pour un étudiant

Effectuer une demande POST à <Specify URL for setting grade for a given student>.

Les variables de formulaire POST suivantes peuvent être incluses :

Nom de la propriété	Type	Description
id	chaîne	Identifiant de l'étudiant, un GUID
source	chaîne	Définissez toujours cette valeur à " onenote"
obtainedMark	entier	Note obtenue par l'étudiant
maxMark	entier	Note maximale pouvant être obtenue
obtainedGrade	chaîne	Note ou niveau obtenu par l'étudiant (ex. : "A")
comments	chaîne	Commentaire textuel libre fourni à l'étudiant

Get grade types

Effectuer une demande GET à <Specify URL for getting grade types>.

Le LMS doit renvoyer un tableau JSON des types de notes. Chaque type de note doit avoir les propriétés suivantes :

Nom de la propriété	Type	Description
id	chaîne	Identifiant unique du type de note pour l'installation du LMS
gradeTypeCategory	GradeTypeCategory	Catégorie unique du type de note pour l'installation du LMS
max	entier	Score maximum possible
description	chaîne	Chaîne affichée pour le type de note

Obtenir le type de catégorie spécifique

Effectuer une demande GET à <Specify URL for getting grade type by id>.

Le LMS doit renvoyer un JSON pour un seul type de note, doté des propriétés suivantes :

Nom de la propriété	Type	Description
id	chaîne	Identifiant unique du type de note pour l'installation du LMS
gradeTypeCategory	GradeTypeCategory	Catégorie unique du type de note pour l'installation du LMS
max	entier	Score maximum possible
description	chaîne	Chaîne affichée pour le type de note

Créer/supprimer des classes et supprimer des activités

Ces possibilités sont facultatives, mais elles sont fortement recommandées pour permettre les tests d'intégration. L'équipe Bloc-notes Microsoft pour la classe utilise ces points de terminaison à des fins de nettoyage.

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,
}

Conditions préalables pour l'environnement de test

Votre environnement de test se compose de deux systèmes :

Client test Office 365

Il peut s'agir de n'importe quel client Office 365 auquel vous avez accès et pour lequel il existe un certain nombre de comptes enseignant et étudiant disposant de licences Office valides.

Le Client de démonstration Office 365 est disponible pour les partenaires. Lors de l'installation de ce client de démonstration, vous pouvez choisir une instance K–12 EDU personnalisée. Elle sera pré-remplie avec des enseignants, des étudiants et des SKU éducation.
Environnement et comptes de test du LMS

Vous devez fournir les informations suivantes à l'équipe Bloc-notes pour la classe :
- URL de base de votre LMS/SIS qui héberge les points de terminaison de l'API.
- ID de l’application (si vous ne prennez pas en charge oauth2) : un ID d’application unique affecté au complément bloc-notes pour la classe qui vous permet de la détecter comme application valide.
- Clé d’application (si vous ne prennez pas en charge oauth2) : le secret d’application pour l’ID d’application donné.

Conditions préalables pour les informations de marketing

Image du logo. La résolution n'a pas besoin d'être très élevée. Nos logos en cours ont en fait moins de 100 ko en taille et jusqu'à 300x300 pixels.
Description. La description doit être courte : un message d'environ 75 mots (50 serait mieux) portant sur votre offre.
Lien vers votre site web. Permet d'en savoir plus sur votre offre.
Logo du bouton. Doit être un logo de 64x64 pixels.