Table of contents
TOC
Collapse the table of content
Expand the table of content
Última actualización: 20/06/2018

Pautas de autenticación

Se recomienda encarecidamente 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.

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

Se aplica a: Bloc 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.

Recuperar una lista de clases

Hacer una GET solicitud al <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 propiedadTipoDescripción
idcadenaIdentificador para la clase, único en la instalación del SGA
nombrecadenaNombre de la clase, legible para personas.

Recuperar una lista de alumnos en una clase

Hacer una GET solicitud al <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 propiedadTipoDescripción
idcadenaIdentificador del alumno, único en la instalación del SGA
nombrecadenaNombre del alumno, legible para personas.
correo electrónicocadenaDirección de correo electrónico del alumno

Recuperar una lista de tareas para una clase

Hacer una GET solicitud al <Specify URL for retrieving list of assignments for a class>

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

Nombre de la propiedadTipoDescripción
idcadenaIdentificador de la tarea, único en la instalación del SGA
títulocadenaTítulo de la tarea
descripcióncadenaDescripción de la tarea
gradetypeidcadenaIdentificador del tipo de calificación, único en la instalación del SGA
dueDatefecha 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.
urlcadenaURL de la tarea. Disponible solo en las versiones compatibles de SGA.
Nombre de propiedad opcionalTipoDescripción
gradetypeidcadenaIdentificador del tipo de calificación, único en la instalación del SGA
minenteropuntuación mínima que se puede asignar a un alumno
maxenteropuntuación máxima que se puede asignar a un alumno
validgradevalueslistavalores válidos de calificaciones para esta tarea

Establecer una tarea para una clase

Hacer una POST solicitud al <Specify URL for setting an assignment to a class>

Se requieren las siguientes variables POST de formulario:

Nombre de la propiedadTipoDescripción
títulocadena (longitud máxima: 280)Título de la tarea
dueDatefecha como cadena (formato: 2016-12-25T00: 00: 00)Fecha de vencimiento de la tarea.
descripcióncadenaDescripción de la tarea
Nombre de propiedad opcionalTipoDescripción
gradetypeidcadenaIdentificador del tipo de calificación, único en la instalación del SGA
minenteropuntuación mínima que se puede asignar a un alumno
maxenteropuntuación máxima que se puede asignar a un alumno
validgradevalueslistavalores 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 para una tarea

Hacer una GET solicitud al <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 propiedadTipoDescripción
idcadenaIdentificador del alumno, único en la instalación del SGA
correo electrónicocadenaDirección de correo electrónico del alumno
gradedbooleanoIndica si el profesor ha proporcionado una nota
obtainedMarkenteroNota opcional lograda por el alumno (ej. 85)
maxMarkenteroNota opcional más alta posible (por ejemplo, 100)
comentarioscadenaComentarios opcionales dados al estudiante (p. ej., "Buen trabajo")
calificacióncadenaCalificació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 una calificación para un alumno

Hacer una POST solicitud al <Specify URL for setting grade for a given student>

Se pueden incluir las siguientes variables POST de formulario.

Nombre de la propiedadTipoDescripción
idcadenaIdentificador para el alumno, un guid
sourcecadenaEstablezca siempre el valor en " onenote"
obtainedMarkenteroNota lograda por el alumno
maxMarkenteroNota máxima posible alcanzable
obtainedGradecadenaCalificación o nivel alcanzado por el alumno (por ejemplo: "A")
comentarioscadenaComentarios de texto libre para el alumno

Obtener tipos de calificación

Hacer una GET solicitud al <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 propiedadTipoDescripción
idcadenaIdentificador del tipo de calificación, único en la instalación del SGA
gradeTypeCategoryGradeTypeCategoryCategoría del tipo de calificación, único en la instalación del SGA
maxenteropuntuación máxima posible
descripcióncadenamuestra la cadena para el tipo de calificación

Obtener un tipo de calificación específico

Hacer una GET solicitud al <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 propiedadTipoDescripción
idcadenaIdentificador del tipo de calificación, único en la instalación del SGA
gradeTypeCategoryGradeTypeCategoryCategoría del tipo de calificación, único en la instalación del SGA
maxenteropuntuación máxima posible
descripcióncadenamuestra 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 ejercicios 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 del entorno de pruebas

Su entorno de prueba estará compuesto por dos sistemas:

Cuenta empresarial de prueba de Office 365

Puede ser cualquier cuenta empresarial de Office 365 al que tenga acceso y hay un par de cuentas de profesores y alumnos con licencias de Office válidas. Hay algo llamado Cliente de Office 365 para demostración, disponible para asociados. Cuando configure este usuario de demostración, puede elegir una instancia EDU K - 12 personalizada que vendrá prellenada con profesores y alumnos y el número 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.
  • ID de la aplicación*: id único de la aplicación asignado al complemento del bloc de notas de clase que le permite detectar como una aplicación válida.
  • Clave de la aplicación*: secreto de la aplicación para la id de la aplicación determinada

*si no admite oauth2

Requisitos previos de información de marketing

Imagen del logotipo

No tiene que ser de muy alta resolución. Nuestros logotipos actuales son, de hecho, de menos de 100k de tamaño y hasta 300x300px como máximo.

Descripción

La descripción debe ser corta, ~ 75 palabras (mejor si alrededor de 50) de mensajes sobre su oferta

Ideado para obtener más información acerca de su oferta

Debe ser un logotipo de 64x64 píxeles

Recursos adicionales

© 2018 Microsoft