Compartir a través de

Guía de incorporación para proveedores de API de OneRoster con School Data Sync (SDS)

  • Artículo

Introducción

Microsoft School Data Sync (SDS) puede sincronizar la información de identidad y lista de cualquier sistema que implemente el estándar 1EdTech OneRoster API (Interfaces de programación de aplicaciones) en un flujo de datos de entrada. Este documento está diseñado para ayudar a los nuevos proveedores de API de OneRoster a integrarse correctamente con SDS. Los clientes pueden conectarse directamente a su proveedor mediante las API de OneRoster 1.1 basadas en REST. El siguiente proceso de incorporación define los pasos necesarios para que el proveedor de API pueda agregarlos para que los inquilinos puedan seleccionarlos y usarlos en SDS.

Acerca de SDS

Información general

  1. Complete el formulario en el formulario de registro de asociados de SDS.

    1. Indique que le gustaría recibir asistencia de integración de School Data Sync en el formulario.

    2. El registro es necesario para acceder al formulario: visite el sitio de Microsoft Partner Network para obtener más información. Debe enviar un formulario independiente para el acceso a los recursos de desarrollo de SDS y Office.

  2. Implemente los puntos de conexión de api de OneRoster requeridos por SDS.

    SDS usa un filtro en la propiedad dateLastModified para el procesamiento de sincronización diferencial o sincronización incremental y es necesario para la integración con SDS.

  3. Compruebe que SDS funciona con los puntos de conexión de la API de OneRoster.

    1. Evalúe las API mediante la colección Postman.

    2. Pruebe con la ingeniería de SDS en un entorno de espacio aislado.

    3. Configure SDS para validar la solución E2E.

  4. Pilote la solución con dos clientes de producción.

  5. Haga que el conector esté disponible con carácter general en SDS para todos los inquilinos Office 365 EDU.

Introducción

Puntos de conexión de API necesarios para SDS

Acción URL Propiedades de filtro necesarias Filtro opcional o recomendado Ejemplos
GetAllAcademicSessions /academicSessions status dateLastModified /academicSessions?offset=0&limit=5000&filter=status='active'/academicSessions?filter=dateLastModified>'{deltaDateTime}'
GetAllOrgs /orgs status dateLastModified /orgs?offset=0&limit=5000&filter=status='active'/orgs?filter=dateLastModified>'{deltaDateTime}'
GetAllUsers /Usuarios status dateLastModified /users?offset=0&limit=5000&filter=status='active'/users?filter=dateLastModified>'{deltaDateTime}'
GetAllClasses /Clases status dateLastModified /classes?offset=0&limit=5000&filter=status='active'/classes?filter=dateLastModified>'{deltaDateTime}'
GetAllEnrollments /Inscripciones status dateLastModified /enrollments?offset=0&limit=5000&filter=status='active'/enrollments?filter=dateLastModified>'{deltaDateTime}'

Puntos de conexión de API opcionales para SDS

Nota:

En el caso de los datos opcionales de datos demográficos, las relaciones de contacto de los alumnos y las marcas de usuario de los alumnos, la capacidad de un cliente para incluir estos datos o no se basará en las funcionalidades de datos opcionales admitidas del perfil de proveedor que vamos a crear. Siguiendo los pasos de prueba y comprobación indicados, si decide admitir también estos datos para los clientes que usan SDS, verán el botón de alternancia (valor predeterminado) seleccionado Activado para incluir datos adicionales. Pueden seleccionar el botón de alternancia para desactivar si lo desean. Si el botón de alternancia no está disponible, se muestra pero está desactivado y no está disponible para la interacción, esto significa que el perfil de proveedor no admite actualmente proporcionar esos datos.

Acción URL Propiedades de filtro necesarias Filtro opcional o recomendado Ejemplos
GetAllCourses /Cursos status dateLastModified /courses?offset=0&limit=5000&filter=status='active'/courses?filter=dateLastModified>'{deltaDateTime}'
GetAllDemographics /Demografía status dateLastModified /demographics?offset=0&limit=5000&filter=status='active'/demographics?filter=dateLastModified>'{deltaDateTime}'

Relaciones de contacto opcionales de alumnos de usuario

Sugerencia

Dado que SDS no admite la carga lateral de la fecha de contactos de los alumnos a través de CSV si se proporcionan sus datos de lista a través de la API de OneRoster, se recomienda que todos los proveedores trabajen para proporcionar contactos mediante el enfoque de la API de OneRoster.

La relación de contacto con los alumnos se puede especificar para que los usuarios de los alumnos mejoren las experiencias del educador para comunicarse con los padres y tutores de los estudiantes. Los contactos son más usuarios que se proporcionan con el punto de conexión /users y la asociación a un alumno se encuentran en el registro de usuario del alumno en "agentes".

  • Para obtener más información, sobre los roles de relación de contacto de alumno admitidos admitidos por SDS, consulte Lista predeterminada de valores: Roles de relación de contacto.
  • familyName, givenName y correo electrónico son necesarios para los usuarios que tienen roles de contacto o tutor.
  • Espere que el teléfono y los sms estén en E.164 y + deben estar incluidos. (Ejemplo: +1234567890).
  • Si se proporcionan datos inversos, desde un registro de tutor de relación de contacto hasta un alumno en el campo "agentes" de usuarios de contacto, estos registros se filtran.

Marcas demográficas de usuario opcionales

Las marcas de usuario se pueden especificar para que los usuarios estudiantes indiquen su participación en un programa o cohorte. Las marcas de usuario se incluyen (cuando es true para el usuario) o no se incluyen si no son aplicables.

Las marcas se especifican como una extensión de metadatos para el usuario, en un campo de metadatos. El enfoque sigue una clave|Par de valores, con la clave denominada microsoft.userFlags, y debe tener formato de lista delimitada por comas. Las marcas de usuario pueden aparecer en cualquier orden y no distinguen mayúsculas de minúsculas.

Para obtener más información, en la lista predeterminada de valores de marca de usuario compatibles con SDS, consulte Lista predeterminada de valores: Marcas de usuario.

Ejemplo:

{ 
  "user" : { 
   … 
   … 
    "metadata" : { 
     "microsoft.userFlags" : "freeLunch,homeless,giftedOrTalented“ 
    } 
}

Reglas de coincidencia y validación de datos

Para obtener más información sobre las reglas de validación y coincidencia de datos, vea Reglas y descripciones de validación.

Importante

Por 1EdTech es responsabilidad del proveedor exigir la privacidad de los datos disponibles cuando se realiza una solicitud de datos. School Data Sync realiza una solicitud de datos activos en función de la hora de la solicitud.

Notas y sugerencias útiles

  • Los puntos de conexión siempre vienen después de la dirección URL https: {server_URL}/ims/oneroster/v1p1.
  • Todos los puntos de conexión deben admitir la paginación, es decir, los parámetros de límite y desplazamiento (por ejemplo, limit=10&offset=5000).
  • Los puntos de conexión tienen requisitos sobre la compatibilidad con parámetros de filtro para permitir el filtrado por estado o para habilitar la sincronización diferencial.
  • Los clientes saben cómo habilitar la opción "Está activo" o cómo permitir que solo los datos activos estén disponibles para la conexión que va a usar School Data Sync. Esto garantiza que solo se proporcionen datos activos para el año escolar y la sesión activos a medida que avanza el año escolar.
  • Para evitar que ciertas escuelas se incluyan en los datos que se proporcionan desde el SIS a SDS, los clientes saben cómo configurar qué escuelas se incluyen para la conexión o las credenciales que se usan para vincular SDS a su SIS.
  • SDS aplica un filtro en la propiedad dateLastModified para el procesamiento de sincronización diferencial o sincronización incremental y es necesario para la integración con SDS.
  • Los proveedores deben elegir implementar el esquema de autenticación OAuth1(a) o OAuth 2.0 (concesión de credenciales de cliente), OAuth 2.0 preferido.
  • Durante el desarrollo, puede comprobar los puntos de conexión con nuestra colección Postman.
  • Si el protocolo de autenticación admitido es "OAuth 2": tipo de concesión de credenciales de cliente, SDS enviaría las credenciales en el encabezado "Autorización". SDS no admite el envío de las credenciales en el cuerpo de la solicitud.

Prueba de las API de OneRoster

Uso de la colección Postman

Postman es una herramienta conocida para ejecutar y administrar las API REST. Hemos creado la colección Postman de api de OneRoster para invocar y probar las API de OneRoster necesarias para SDS. La ejecución de la colección invoca todas las API necesarias para SDS y ejecuta pruebas sencillas en los datos devueltos.

Prueba con ingeniería de SDS en un entorno de espacio aislado

Cree un entorno de espacio aislado para las API de OneRoster y comparta las credenciales con el ingeniero de SDS designado. Juntos, ejecutamos un conjunto más profundo de pruebas para garantizar que la integración sea correcta.

Configuración para validar la solución

Cuando todas las pruebas se realizaron correctamente, el nombre del sistema se agrega a la lista de proveedores de OneRoster en SDS. Sin embargo, en este momento, solo es visible para los inquilinos piloto para los perfiles de proveedores que se indican como modo "InPilot" (no disponible públicamente). A continuación, configure SDS para conectar datos con OneRoster API en el inquilino de Microsoft 365 de prueba para sincronizar los datos de los puntos de conexión de OneRoster de espacio aislado y asegurarse de que las ejecuciones se completen sin errores. Si ve errores o advertencias y necesita ayuda después de su auto-investigación, póngase en contacto con el ingeniero de SDS designado.

Piloto del cliente

Una vez que las pruebas se hayan completado correctamente, es el momento de empezar a pilotar la solución con los clientes. El nombre del sistema está visible en la lista de proveedores de OneRoster® en SDS para aquellos "pilotos" para ver también los proveedores que son el modo "InPilot", aceptando pilotar la integración. El equipo de SDS y el equipo del proveedor de OneRoster trabajan juntos para identificar a los clientes piloto adecuados y programar una hora para implementar SDS. Colaboramos estrechamente con los clientes para garantizar que el flujo de entrada se ejecuta correctamente y validar los resultados juntos. Los errores finales identificados deben abordarse antes de que la solución esté disponible públicamente para todos los clientes de educación Office 365.

Ir público

Una vez que dos clientes han completado correctamente sus implementaciones piloto, el sistema asociado está disponible en SDS como un sistema de origen certificado del proveedor de OneRoster. SDS muestra el nombre del proveedor a los inquilinos al definir su configuración de datos de conexión mediante la API de OneRoster. El equipo de SDS documenta el sistema asociado en nuestra página de información general del proveedor de API de OneRoster en nuestros documentos en línea de SDS.

El equipo de SDS necesita:

  • Versión mínima del software
  • Requisitos previos de configuración
  • Obtención del identificador de cliente, el secreto de cliente y las direcciones URL
  • Cualquier otra instrucción específica
  • Quién debe ponerse en contacto para obtener ayuda

El equipo de SDS puede coordinarse con su equipo para promover la integración de forma más amplia a través de diversos canales de marketing.