Pautas de la API de SGA para la integración de complementos de Bloc de notas de clase de OneNote

Artículo
04/13/2017

Se aplica a: blocs de notas empresariales en Office 365

Este documento proporciona las llamadas API necesarias para que OneNote enumere las clases y las tareas, establezca las tareas, descargue las calificaciones y actualice las calificaciones en cualquier SGA.

Todas las solicitudes deben ser autenticadas. Todas las solicitudes deben hacerse a través de HTTPS.

Nota

Se recomienda que cada SGA implemente el flujo de concesión del código de autorización para la implementación de oauth2. Esto evita que el usuario tenga la necesidad de introducir credenciales cada vez que el token de acceso caduque.

Recuperar una lista de clases

Realice una solicitud GET a <Specify URL for retrieving list of classes>.

SGA debe devolver una matriz de clases JSON para el usuario autenticado actualmente.

Cada clase debe tener las siguientes propiedades:

Nombre de la propiedad	Tipo	Descripción
id	cadena	Identificador para la clase, único en la instalación del SGA
name	cadena	Nombre de la clase, legible para personas

Recuperar una lista de los alumnos en una clase

Realice una solicitud GET a <Specify URL for retrieving list of students in a class>.

SGA debe devolver una matriz JSON de alumnos en la clase.

Cada alumno debe tener las siguientes propiedades:

Nombre de la propiedad	Tipo	Descripción
id	cadena	Identificador del alumno, único en la instalación del SGA
name	cadena	Nombre del alumno, legible para personas.
email	cadena	Dirección de correo electrónico de los alumnos

Recuperar una lista de tareas para una clase

Realice una solicitud GET a <Specify URL for retrieving list of assignments for a class>.

SGA debe devolver una matriz JSON de tareas para la clase.

Nombre de la propiedad	Tipo	Descripción
id	cadena	Identificador de la tarea, único en la instalación del SGA
título	cadena	Título de la tarea
description	cadena	Descripción de la tarea
gradetypeid	cadena	Identificador del tipo de calificación, único en la instalación del SGA
dueDate	fecha como cadena (formato: 2016-12-25T00: 00: 00)	Fecha de vencimiento de la tarea. El SGA no almacenará ni usará la porción de tiempo.
url	cadena	URL de la tarea. Disponible solo en las versiones compatibles de SGA.

Nombre de propiedad opcional	Tipo	Descripción
gradetypeid	cadena	Identificador del tipo de calificación, único en la instalación del SGA
min	entero	Puntuación mínima que se puede asignar a un alumno
max	entero	Puntuación máxima que se puede asignar a un alumno
validgradevalues	lista	Valores válidos de calificaciones para esta tarea

Establecer una tarea a una clase

Realice una solicitud POST a <Specify URL for setting an assignment to a class>.

Se requieren las siguientes variables POST de formulario:

Nombre de la propiedad	Tipo	Descripción
título	cadena (longitud máxima: 280)	Título de la tarea
dueDate	fecha como cadena (formato: 2016-12-25T00: 00: 00)	Fecha de vencimiento de la tarea.
description	cadena	Descripción de la tarea

Nombre de propiedad opcional	Tipo	Descripción
gradetypeid	cadena	Identificador del tipo de calificación, único en la instalación del SGA
min	entero	Puntuación mínima que se puede asignar a un alumno
max	entero	Puntuación máxima que se puede asignar a un alumno
validgradevalues	lista	Valores válidos de calificaciones para esta tarea

El SGA devolverá un objeto JSON con una única propiedad de identificación. El valor de esta propiedad será el identificador de la tarea recién establecida.

Recuperar una lista de calificaciones de una tarea

Realice una solicitud GET a <Specify URL for retrieving grades for a given assignment>.

El SGA debe devolver una matriz JSON de alumnos que recibieron la asignación y sus calificaciones/puntuación.

Cada segmento JSON del alumno debe tener las siguientes propiedades:

Nombre de la propiedad	Tipo	Descripción
id	cadena	Identificador del alumno, único en la instalación del SGA
email	cadena	Dirección de correo electrónico de los alumnos
graded	booleano	Indica si el profesor ha proporcionado una nota
obtainedMark	entero	Nota opcional lograda por el alumno (ej. 85)
maxMark	entero	Nota opcional más alta posible (por ejemplo, 100)
feedback	cadena	Comentarios opcionales dados al estudiante (p. ej., "Buen trabajo")
grade	cadena	Calificación opcional dada al alumno (p. ej. "A")

Tenga en cuenta que el SGA puede admitir la clasificación de números distintos de 100. En ese caso (maxMark no es igual a 100), es posible que OneNote necesite convertir la obtainedMark obtenida si no puede mostrarse en la IU de OneNote.

Establecer un calificación para un alumno

Realice una solicitud POST a <Specify URL for setting grade for a given student>.

Se pueden incluir las siguientes variables POST de formulario:

Nombre de la propiedad	Tipo	Descripción
id	cadena	Identificador para el alumno, un guid
source	cadena	Establezca siempre el valor en " onenote"
obtainedMark	entero	Nota lograda por el alumno
maxMark	entero	Nota máxima posible alcanzable
obtainedGrade	cadena	Calificación o nivel alcanzado por el alumno (por ejemplo: "A")
comments	cadena	Comentarios de texto libre para el alumno

Obtener tipos de calificación

Realice una solicitud GET a <Specify URL for getting grade types>.

El SGA debe devolver una matriz JSON de tipos de calificación. Cada tipo de calificación debe tener las siguientes propiedades:

Nombre de la propiedad	Tipo	Descripción
id	cadena	Identificador del tipo de calificación, único en la instalación del SGA
gradeTypeCategory	GradeTypeCategory	Categoría del tipo de calificación, único en la instalación del SGA
max	entero	Máxima puntuación posible
description	cadena	Mostrar la cadena para el tipo de calificación

Obtener el tipo de calificación específico

Realice una solicitud GET a <Specify URL for getting grade type by id>.

El SGA debe devolver un JSON de tipo de calificación único, que tiene las siguientes propiedades:

Nombre de la propiedad	Tipo	Descripción
id	cadena	Identificador del tipo de calificación, único en la instalación del SGA
gradeTypeCategory	GradeTypeCategory	Categoría del tipo de calificación, único en la instalación del SGA
max	entero	Máxima puntuación posible
description	cadena	Mostrar la cadena para el tipo de calificación

API para crear/eliminar clases y eliminar tareas

Estas son opcionales pero muy recomendables para las pruebas de integración. El equipo de Bloc de notas de clase de Microsoft realiza estos puntos de conexión con fines de limpieza.

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

Requisitos previos de entorno de prueba

El entorno de prueba se compone de dos sistemas:

Cuenta empresarial de prueba de Office 365

Puede ser cualquier cuenta empresarial de Office 365 a la que tenga acceso y haya varias cuentas de profesores y alumnos con licencias de Office válidas.

La Demostración de cuenta empresarial de Office 365 está disponible para los asociados. Cuando configure esta cuenta empresarial de demostración, puede elegir una instancia EDU K–12 personalizada que vendrá rellenada previamente con profesores y alumnos y números de referencia de inventario (SKU) de educación.
Entorno de prueba y cuentas del SGA

Tendrá que proporcionar al equipo del bloc de notas de clase la siguiente información:
- URL base de su SGA/SIS que aloja los puntos finales de API.
- Identificador de aplicación (si no admite oauth2): un id. único de aplicación asignado al complemento del bloc de notas de clase que le permite detectarla como una aplicación válida.
- Clave de la aplicación (si no admite oauth2): el secreto de la aplicación para el identificador de aplicación determinado.

Requisitos previos de información de marketing

Imagen de logotipo. No tiene que ser de muy alta resolución. Nuestros logotipos actuales en realidad son de menos de 100 KB de tamaño y hasta 300x300 píxeles máx.
Descripción. La descripción debe ser corta, unas 75 palabras (mejor si alrededor de 50) para el mensaje sobre su oferta
Enlace a su sitio web. Ideado para obtener más información acerca de su oferta.
Logotipo de botón. Debe ser un logotipo de 64x64 píxeles.