Conseils d’intégration pour les fournisseurs d’API OneRoster avec School Data Sync (SDS)
Introduction
Synchronisation des données scolaires Microsoft (SDS) peut synchroniser les informations d’identité et de liste de n’importe quel système qui implémente la norme API OneRoster 1EdTech (Interfaces de programmation d’application) dans un flux de données entrant. Ce document est destiné à aider tous les nouveaux fournisseurs d’API OneRoster à s’intégrer correctement à SDS. Le processus d’intégration suivant définit les étapes requises par le fournisseur d’API avant qu’elles puissent être ajoutées pour que les locataires puissent sélectionner et utiliser dans SDS.
À propos de SDS
Si vous souhaitez en savoir plus sur SDS, accédez au site du produit SDS.
Pour obtenir des informations techniques sur SDS, notamment des vidéos de déploiement et des conseils d’administration, accédez au site de documentation SDS.
Pour plus d’informations sur l’utilisation de SDS avec l’API® OneRoster, accédez à Ingestion de données avec l’API OneRoster.
Vue d’ensemble
Remplissez le formulaire sur le formulaire d’inscription du partenaire SDS.
Indiquez que vous souhaitez l’aide sur l’intégration de La synchronisation des données scolaires sur le formulaire.
L’inscription est nécessaire pour accéder au formulaire . Pour plus d’informations, visitez le site Microsoft Partner Network . Vous devez envoyer un formulaire distinct pour accéder aux ressources de développement SDS et Office.
Implémentez les points de terminaison de l’API OneRoster requis par SDS.
SDS utilise un filtre sur la propriété dateLastModified pour le traitement de synchronisation différentielle/de synchronisation incrémentielle et est requis pour l’intégration à SDS.
Vérifiez que SDS fonctionne avec vos points de terminaison d’API OneRoster.
Évaluez vos API à l’aide de la collection Postman.
Testez avec l’ingénierie SDS sur un environnement de bac à sable.
Configurez SDS pour valider la solution E2E.
Pilotez la solution avec deux clients de production.
Rendez votre connecteur généralement disponible dans SDS pour tous les locataires Office 365 EDU.
Prise en main
Si vous venez de développer les API OneRoster, suivez la spécification de l’API OneRoster v1.1 pour la liste de base.
Exemple d’implémentation dans ASP.NET MVC à l’aide de C#.
Nous suggérons une certification en tant que fournisseur avec IMS Global, mais ne l’exigez pas.
Pour plus d’informations sur la liste par défaut des valeurs prises en charge par SDS, consultez Liste de valeurs par défaut.
Points de terminaison d’API requis pour SDS
| Action | URL | Propriétés de filtre requises | Filtre facultatif/recommandé | Exemples |
|---|---|---|---|---|
| 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 | /Utilisateurs | status | Datelastmodified | /users ?offset=0&limit=5000&filter=status='active'/users ?filter=dateLastModified>'{deltaDateTime}' |
| GetAllClasses | /Classes | status | Datelastmodified | /classes ?offset=0&limit=5000&filter=status='active'/classes ?filter=dateLastModified>'{deltaDateTime}' |
| GetAllEnrollments | /Inscriptions | status | Datelastmodified | /enrollments ?offset=0&limit=5000&filter=status='active'/enrollments ?filter=dateLastModified>'{deltaDateTime}' |
Points de terminaison d’API facultatifs pour SDS
Remarque
Pour les données facultatives pour les données démographiques, les relations avec les contacts étudiants et les indicateurs d’utilisateur étudiant, la possibilité pour un client d’inclure ces données ou non sera basée sur les fonctionnalités de données facultatives prises en charge à partir de votre profil de fournisseur que nous allons créer. En suivant les étapes de test et de vérification indiquées, si vous choisissez également de prendre en charge ces données pour vos clients qui utilisent SDS, ils verront le bouton bascule (par défaut) sélectionné Sur pour inclure des données supplémentaires. Ils peuvent sélectionner le bouton bascule à désactiver s’ils le souhaitent. Si le bouton bascule n’est pas disponible, s’il est affiché mais désactivé et n’est pas disponible pour l’interaction, cela signifie que votre profil de fournisseur ne prend actuellement pas en charge la fourniture de ces données.
| Action | URL | Propriétés de filtre requises | Filtre facultatif/recommandé | Exemples |
|---|---|---|---|---|
| GetAllCourses | /Cours | status | Datelastmodified | /courses ?offset=0&limit=5000&filter=status='active'/courses ?filter=dateLastModified>'{deltaDateTime}' |
| GetAllDemographics | /Démographie | status | Datelastmodified | /demographics ?offset=0&limit=5000&filter=status='active'/demographics ?filter=dateLastModified>'{deltaDateTime}' |
Relations de contact utilisateur étudiant facultatives
La relation de contact étudiant peut être spécifiée pour les utilisateurs étudiants afin d’améliorer les expériences des enseignants pour la communication avec les parents et tuteurs des étudiants. Les contacts sont davantage d’utilisateurs fournis avec /users et l’association à un étudiant se trouvent dans l’enregistrement utilisateur de l’étudiant sous « agents ».
- Pour plus d’informations, sur les rôles de relation de contact étudiant pris en charge par SDS, consultez Liste de valeurs par défaut : Rôles de relation de contact.
- familyName, givenName et email sont requis pour les utilisateurs qui ont des rôles de contact/tuteur.
- Le téléphone et les sms doivent être inclus dans E.164 et +. (Exemple : +1234567890).
- Si des données inversées sont fournies, d’un enregistrement tuteur de relation de contact à l’étudiant dans le champ « agents » des utilisateurs de contact, ces enregistrements sont filtrés.
Indicateurs démographiques utilisateur facultatifs
Les indicateurs utilisateur peuvent être spécifiés pour permettre aux utilisateurs étudiants d’indiquer leur participation à un programme ou à une cohorte. Les indicateurs utilisateur sont inclus (lorsqu’ils sont true pour l’utilisateur), ou non inclus si cela n’est pas applicable.
Les indicateurs sont spécifiés en tant qu’extension de métadonnées pour l’utilisateur, dans un champ de métadonnées, à la suite d’une clé |Paire valeur, avec la clé nommée microsoft.userFlags et doit être mise en forme en tant que liste délimitée par des virgules. Les indicateurs utilisateur peuvent apparaître dans n’importe quel ordre et ne respectent pas la casse.
Pour plus d’informations, dans la liste par défaut des valeurs d’indicateur utilisateur prises en charge par SDS, consultez Liste de valeurs par défaut : Indicateurs utilisateur.
Exemple :
{
"user" : {
…
…
"metadata" : {
"microsoft.userFlags" : "freeLunch,homeless,giftedOrTalented“
}
}
Règles de validation et de correspondance des données
Pour plus d’informations sur les règles de correspondance et de validation des données, consultez Règles et descriptions de validation.
Importante
Selon 1EdTech, il incombe au fournisseur d’appliquer la confidentialité des données pour les données disponibles lorsqu’une demande de données est effectuée. School Data Sync effectue une demande de données actives en fonction de l’heure de la demande.
Notes et conseils utiles
Les points de terminaison viennent toujours après l’URL https : {server_URL}/ims/oneroster/v1p1.
Tous les points de terminaison doivent prendre en charge la pagination, c’est-à-dire les paramètres de limite et de décalage (par exemple, limit=10&offset=5000).
Les points de terminaison ont des exigences en matière de prise en charge des paramètres de filtre pour autoriser le filtrage par status ou pour activer la synchronisation delta.
Les clients savent comment activer l’option « Est actif » ou comment autoriser uniquement la disponibilité des données actives pour la connexion qui doit être utilisée par School Data Sync. Cela garantit que seules les données actives de l’année scolaire et de la session actives sont fournies au fur et à mesure que l’année scolaire progresse.
SDS applique un filtre sur la propriété dateLastModified pour le traitement de synchronisation delta/synchronisation incrémentielle et est requis pour l’intégration à SDS.
Les fournisseurs doivent choisir d’implémenter le schéma d’authentification OAuth1(a) ou OAuth 2.0 (octroi d’informations d’identification du client), OAuth 2.0 préféré.
Pendant le développement, vous pouvez vérifier vos points de terminaison avec notre collection Postman.
Si le protocole d’authentification pris en charge est « OAuth 2 » - type d’octroi des informations d’identification du client, SDS envoie les informations d’identification dans l’en-tête « Authorization ». SDS ne prend pas en charge l’envoi des informations d’identification dans le corps de la demande.
Test de vos API OneRoster
Utilisation de la collection Postman
Postman est un outil bien connu pour exécuter et gérer des API REST. Nous avons créé la collection Postman de l’API OneRoster pour appeler et tester les API OneRoster requises par SDS. L’exécution de la collection appelle toutes les API requises par SDS et exécute des tests simples sur les données retournées.
Tester avec l’ingénierie SDS sur un environnement de bac à sable
Créez un environnement de bac à sable pour vos API OneRoster et partagez les informations d’identification avec votre ingénieur SDS désigné. Ensemble, nous exécutons un ensemble plus approfondi de tests pour garantir la réussite de l’intégration.
Configurer pour valider la solution
Lorsque tous les tests ont réussi, le nom de votre système est ajouté à la liste des fournisseurs OneRoster dans SDS, mais visible uniquement pour les locataires testés pour les profils de fournisseurs indiqués comme étant en mode « InPilot » (non disponible publiquement). Ensuite, vous allez intégrer SDS en configurant l’ingestion des données avec l’API OneRoster dans votre locataire Microsoft 365 de test pour synchroniser les données de vos points de terminaison OneRoster de bac à sable et vous assurer que les exécutions se terminent sans erreur. Si vous voyez des erreurs ou des avertissements et que vous avez besoin d’aide après votre auto-investigation, contactez votre ingénieur SDS désigné.
Pilote client
Une fois les tests terminés, il est temps de commencer à tester la solution avec les clients. Le nom de votre système sera visible dans la liste des fournisseurs OneRoster® dans SDS pour ceux qui ont été « testés » pour voir également les fournisseurs qui sont en mode « InPilot », après avoir accepté de piloter l’intégration. L’équipe SDS et l’équipe du fournisseur OneRoster collaboreront pour identifier les clients pilotes appropriés et planifier le déploiement de SDS. Nous allons collaborer étroitement avec les clients pour nous assurer que les exécutions de flux entrants sont réussies et valider les résultats ensemble. Tous les bogues finaux identifiés doivent être résolus avant de rendre la solution accessible publiquement à tous les clients Office 365 éducation.
Rendre public
Une fois que deux clients ont réussi leurs déploiements pilotes, le système partenaire est disponible dans SDS en tant que système source de fournisseur OneRoster certifié. SDS affiche le nom du fournisseur aux locataires lorsqu’ils configurent l’ingestion des données avec l’API OneRoster. L’équipe SDS documentera également le système partenaire sur notre page de vue d’ensemble du fournisseur d’API OneRoster dans nos documents en ligne SDS.
L’équipe SDS aura besoin des éléments suivants :
- Version minimale du logiciel
- Configuration requise
- Comment obtenir l’ID client, la clé secrète client et la ou les URL
- Toute autre instruction spécifique
- Personne à contacter pour obtenir de l’aide
L’équipe SDS se coordonnera également avec votre équipe pour promouvoir l’intégration plus largement par le biais de différents canaux marketing.