Linee guida per l'onboarding per i provider di API OneRoster con School Data Sync (SDS)
Introduzione
Microsoft School Data Sync (SDS) è in grado di sincronizzare le informazioni di identità e roster da qualsiasi sistema che implementa lo standard 1EdTech OneRoster API (Application Programming Interfaces) in un flusso di dati in ingresso. Questo documento ha lo scopo di aiutare tutti i nuovi provider di API OneRoster a integrarsi correttamente con SDS. I clienti possono connettersi direttamente al provider usando le API OneRoster 1.1 basate su REST. Il processo di onboarding seguente definisce i passaggi richiesti dal provider di API prima che possano essere aggiunti per consentire ai tenant di selezionare e usare in SDS.
Informazioni su SDS
Per altre informazioni su SDS, visitare il sito del prodotto SDS.
Per informazioni tecniche su SDS, inclusi i video di distribuzione e le indicazioni per l'amministratore, visitare il sito della documentazione di SDS.
Per altre informazioni sull'esperienza del cliente per connettere i dati con l'API OneRoster, vedere Connettere i dati con l'API OneRoster.
Panoramica
Completare il modulo nel modulo di iscrizione ai partner SDS.
Indicare che è necessario assistenza per l'integrazione della sincronizzazione dati dell'istituto di istruzione nel modulo.
La registrazione è necessaria per accedere al modulo: visitare il sito Microsoft Partner Network per altre informazioni. È necessario inviare un modulo separato per l'accesso alle risorse di sviluppo di SDS e Office.
Implementare gli endpoint dell'API OneRoster richiesti da SDS.
SDS usa un filtro sulla proprietà dateLastModified per l'elaborazione di sincronizzazione differenziale/sincronizzazione incrementale ed è necessario per l'integrazione con SDS.
Verificare che SDS funzioni con gli endpoint dell'API OneRoster.
Valutare le API usando la raccolta Postman.
Eseguire il test con la progettazione di SDS in un ambiente sandbox.
Configurare SDS per convalidare la soluzione E2E.
Pilotare la soluzione con due clienti di produzione.
Rendere il connettore disponibile a livello generale in SDS per tutti i tenant EDU Office 365.
Introduzione
Se si stanno sviluppando di recente le API OneRoster, seguire la specifica dell'API OneRoster v1.1 per il roster di base.
È consigliabile la certificazione come provider con 1EdTech, ma non richiederla.
Per altre informazioni sull'elenco predefinito di valori supportati da SDS, vedere Elenco predefinito di valori.
Endpoint API necessari per SDS
| Azione | URL | Proprietà filtro necessarie | Filtro facoltativo/consigliato | Esempi |
|---|---|---|---|---|
| GetAllAcademicSessions | /academicSessions | stato | dateLastModified | /academicSessions?offset=0&limit=5000&filter=status='active'/academicSessions?filter=dateLastModified>'{deltaDateTime}' |
| GetAllOrgs | /orgs | stato | dateLastModified | /orgs?offset=0&limit=5000&filter=status='active'/orgs?filter=dateLastModified>'{deltaDateTime}' |
| GetAllUsers | /Gli utenti | stato | dateLastModified | /users?offset=0&limit=5000&filter=status='active'/users?filter=dateLastModified>'{deltaDateTime}' |
| GetAllClasses | /Classi | stato | dateLastModified | /classes?offset=0&limit=5000&filter=status='active'/classes?filter=dateLastModified>'{deltaDateTime}' |
| GetAllEnrollments | /Iscrizioni | stato | dateLastModified | /enrollments?offset=0&limit=5000&filter=status='active'/enrollments?filter=dateLastModified>'{deltaDateTime}' |
Endpoint API facoltativi per SDS
Nota
Per i dati facoltativi per i dati demografici, le relazioni di contatto degli studenti e i flag utente degli studenti, la possibilità per un cliente di includere o meno questi dati si baserà sulle funzionalità di dati facoltative supportate dal profilo del provider che verrà creato. Seguendo i passaggi di test e verifica annotati, se si sceglie di supportare anche questi dati per i clienti che usano SDS, verrà visualizzato l'interruttore (impostazione predefinita) selezionato Sì per includere dati aggiuntivi. Possono selezionare l'interruttore per disattivare se lo desiderano. Se l'interruttore non è disponibile, visualizzato ma disattivato e non è disponibile per l'interazione, significa che il profilo del provider non supporta attualmente la fornitura di tali dati.
| Azione | URL | Proprietà filtro necessarie | Filtro facoltativo/consigliato | Esempi |
|---|---|---|---|---|
| GetAllCourses | /Corsi | stato | dateLastModified | /courses?offset=0&limit=5000&filter=status='active'/courses?filter=dateLastModified>'{deltaDateTime}' |
| GetAllDemographics | /Demografia | stato | dateLastModified | /demographics?offset=0&limit=5000&filter=status='active'/demographics?filter=dateLastModified>'{deltaDateTime}' |
Relazioni di contatto facoltative tra studenti utente
Consiglio
Poiché SDS non supporta il caricamento laterale della data dei contatti degli studenti tramite CSV se i dati del roster vengono forniti tramite l'API OneRoster, è consigliabile che tutti i provider lavorino per supportare la fornitura di contatti usando l'approccio dell'API OneRoster.
La relazione di contatto con gli studenti può essere specificata per gli utenti degli studenti per migliorare le esperienze di docente per la comunicazione con i genitori e i tutori degli studenti. I contatti sono più utenti forniti con l'endpoint /users e l'associazione a uno studente si trovano nel record utente dello studente in "agenti".
- Per altre informazioni, sui ruoli di relazione di contatto degli studenti supportati da SDS, vedere Elenco predefinito dei valori: Ruoli di relazione di contatto.
- FamilyName, givenName e posta elettronica sono necessari per gli utenti con ruoli di contatto/tutore.
- Aspettatevi che telefono e sms siano in E.164 e + devono essere inclusi. (Esempio: +1234567890).
- Se vengono forniti dati inversi, da un record di controllo della relazione di contatto a uno studente nel campo "agenti" degli utenti di contatto, questi record vengono filtrati.
Flag facoltativi per i dati demografici degli utenti
I flag utente possono essere specificati per consentire agli utenti degli studenti di indicare la loro partecipazione a un programma o a una coorte. I flag utente sono inclusi (se true per l'utente) o non inclusi se non applicabile.
I flag vengono specificati come estensione di metadati per l'utente, in un campo di metadati. L'approccio segue una chiave|Coppia di valori, con la chiave denominata microsoft.userFlags, e deve essere formattata come elenco delimitato da virgole. I flag utente possono essere visualizzati in qualsiasi ordine e non fanno distinzione tra maiuscole e minuscole.
Per altre informazioni, nell'elenco predefinito dei valori dei flag utente supportati da SDS, vedere Elenco predefinito di valori: Flag utente.
Esempio:
{
"user" : {
…
…
"metadata" : {
"microsoft.userFlags" : "freeLunch,homeless,giftedOrTalented“
}
}
Regole di corrispondenza e convalida dei dati
Per altre informazioni sulla corrispondenza dei dati e sulle regole di convalida, vedere Regole e descrizioni di convalida.
Importante
Per 1EdTech è responsabilità del provider imporre la privacy dei dati per i dati disponibili quando viene effettuata una richiesta di dati. School Data Sync effettua una richiesta di dati attivi in base all'ora della richiesta.
Note e suggerimenti utili
- Gli endpoint vengono sempre dopo l'URL https: {server_URL}/ims/esistenti/v1p1.
- Tutti gli endpoint devono supportare il paging, ovvero i parametri limite e offset (ad esempio: limite=10&offset=5000).
- Gli endpoint hanno requisiti per il supporto dei parametri di filtro per consentire il filtro in base allo stato o per abilitare la sincronizzazione differenziale.
- I clienti sanno come abilitare l'opzione "È attivo" o come consentire solo la disponibilità di dati attivi per la connessione che deve essere usata da School Data Sync. Ciò garantisce che vengano forniti solo i dati attivi per l'anno scolastico e la sessione attiva man mano che l'anno scolastico progredisce.
- Per evitare che determinate scuole vengano incluse nei dati forniti dal SIS a SDS, i clienti sanno come configurare quali scuole sono incluse per la connessione o le credenziali usate per collegare SDS al sis.
- SDS applica un filtro alla proprietà dateLastModified per l'elaborazione di sincronizzazione differenziale/sincronizzazione incrementale ed è necessario per l'integrazione con SDS.
- I provider devono scegliere di implementare lo schema di autenticazione OAuth1(a) o OAuth 2.0 (concessione delle credenziali client), oAuth 2.0 preferito.
- Durante lo sviluppo, è possibile verificare gli endpoint con la raccolta Postman.
- Se il protocollo di autenticazione supportato è "OAuth 2" - tipo di concessione delle credenziali client, SDS invierà le credenziali nell'intestazione "Autorizzazione". SDS non supporta l'invio delle credenziali nel corpo della richiesta.
Test delle API OneRoster
Uso della raccolta Postman
Postman è uno strumento noto per eseguire e gestire le API REST. È stata creata la raccolta Postman dell'API OneRoster per richiamare e testare le API OneRoster richieste da SDS. L'esecuzione della raccolta richiama tutte le API richieste da SDS ed esegue test semplici sui dati restituiti.
Testare con SDS Engineering in un ambiente sandbox
Creare un ambiente sandbox per le API OneRoster e condividere le credenziali con il tecnico SDS designato. Insieme, viene eseguito un set più approfondito di test per garantire che l'integrazione riesca.
Configurare per convalidare la soluzione
Quando tutti i test hanno avuto esito positivo, il nome del sistema viene aggiunto all'elenco dei provider OneRoster in SDS. Al momento, tuttavia, è visibile solo per i tenant in anteprima per i profili provider indicati come modalità "InPilot" (non disponibile pubblicamente). Configurare quindi SDS per connettere i dati con l'API OneRoster nel tenant di Microsoft 365 di test per sincronizzare i dati dagli endpoint OneRoster sandbox e assicurarsi che le esecuzioni vengano completate senza errori. Se vengono visualizzati errori o avvisi e si necessita di assistenza dopo l'analisi automatica, contattare il tecnico SDS designato.
Progetto pilota del cliente
Dopo aver completato correttamente i test, è il momento di iniziare a pilotare la soluzione con i clienti. Il nome del sistema è visibile nell'elenco dei provider OneRoster® in SDS per quelli "in anteprima" per visualizzare anche i provider che sono in modalità "InPilot", accettando di pilotare l'integrazione. Il team SDS e il team del provider OneRoster collaborano per identificare i clienti pilota appropriati e pianificare un orario per la distribuzione di SDS. Collaboriamo a stretto contatto con i clienti per garantire che le esecuzioni del flusso in ingresso riescano e convalidiamo i risultati insieme. Eventuali bug finali identificati devono essere risolti prima di rendere la soluzione disponibile pubblicamente a tutti i clienti Office 365 dell'istruzione.
Vai pubblico
Dopo che due clienti hanno completato correttamente le distribuzioni pilota, il sistema partner è disponibile in SDS come sistema di origine del provider OneRoster certificato. SDS visualizza il nome del provider ai tenant quando definiscono la configurazione dei dati di connessione usando l'API OneRoster. Il team SDS documenta il sistema partner nella pagina di panoramica del provider di API OneRoster nei documenti online di SDS.
Il team SDS ha bisogno di:
- Versione minima del software
- Prerequisiti di configurazione
- Come ottenere ID client, segreto client e URL
- Qualsiasi altra istruzione specifica
- Chi contattare per assistenza
Il team SDS può coordinarsi con il team per promuovere l'integrazione in modo più ampio attraverso vari canali di marketing.