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

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.

Note

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.

Voir aussi