Inserimento dati con l'API OneRoster

  • Articolo

L'API OneRoster (Application Programming Interfaces) è un formato standard del settore, da 1EdTech (in precedenza IMS Global), per lo scambio di dati SIS (Student Information System) o SMS (Student Management Systems). Usando questo metodo di sincronizzazione, è possibile connettersi direttamente al SIS/SMS usando le API OneRoster 1.1 basate su REST sviluppate dal provider SIS/SMS. Il supporto dell'API consente di sincronizzare i dati direttamente invece di usare file CSV (valori delimitati da virgole).

Dati a cui si accede dalla sincronizzazione dati dell'istituto di istruzione

Importante

Connettendo e rendendo disponibili i dati dell'istituto con School Data Sync, si riconosce di essere autorizzati a condividere questi dati con Microsoft e a rispettare gli standard di governance dei dati dell'organizzazione.

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

Configurare SDS per Microsoft 365 Education tenant

  • Microsoft 365 Education tenant
  • Sono necessarie autorizzazioni di amministratore globale

Accesso SDS e accesso alla prima volta

Per accedere al portale di Amministrazione SDS avviare il Web browser, passare a sds.microsoft.com e quindi accedere usando l'account microsoft 365 Global Amministrazione.

  1. Seleziona Inizia.

    Screenshot che mostra il messaggio di benvenuto.

  2. Selezionare Continua.

    Screenshot che mostra la panoramica di SDS.

    Attendere alcuni istanti per il provisioning dei servizi nel tenant prima del passaggio successivo.

    Screenshot che mostra in sospeso durante l'attesa del completamento del provisioning del servizio.

  3. Selezionare Crea nuovo flusso in ingresso. Selezionare Avanti per continuare.

    Screenshot che mostra la richiesta di creare un nuovo flusso in ingresso.

  4. Scegliere l'origine dati. Per l'API OneRoster selezionare l'opzione Connetti ai dati personali.

  5. Selezionare il formato. Per l'API OneRoster selezionare l'API di opzione. Selezionare Avanti per continuare.

    Screenshot della selezione dell'API.

    Screenshot che mostra la richiesta di processo per ottenere l'elenco dei provider DI API.

  6. È necessario selezionare il provider SIS/SMS dall'elenco dei provider. Dopo aver selezionato, selezionare Avanti per continuare.

    Screenshot che mostra l'elenco dei provider API per la selezione.

    Nota

    Se il provider SIS/SMS non è incluso nell'elenco, vedere Panoramica del provider OneRoster per istruzioni su come partecipare a test pilota o informazioni da inviare al provider per consentire loro di partecipare come provider OneRoster.

  7. Per abilitare la connessione al SIS/SMS, è necessario specificare le credenziali di connessione.

    • URL di accesso Web: URL in cui l'API OneRoster è accessibile per SIS/SMS

    • ID client usato per connettersi all'API OneRoster SIS/SMS

    • Segreto client usato per connettersi all'API OneRoster SIS/SMS

    • URL del token di accesso, se l'API OneRoster SIS/SMS è configurata per l'autenticazione tramite OAuth2, sarà anche necessario fornire l'endpoint URL del token di accesso che verrà usato per la connessione. L'endpoint è diverso dall'URL di accesso Web.

    • Selezionare Avanti per continuare.

    Screenshot che mostra le richieste di credenziali DELL'API.

  8. Successivamente, la connessione al SIS/SMS viene testata in base alle informazioni immesse nell'ultima schermata.

    Screenshot che mostra la convalida delle credenziali DELL'API.

    • Se non si verificano problemi, si riceve una notifica e si può selezionare Avanti per continuare.

    • Se non è possibile stabilire una connessione, si riceve una notifica e si sarà in grado di selezionare Indietro per esaminare e aggiornare le informazioni fornite.

    Screenshot che mostra la convalida corretta delle credenziali DELL'API.

  9. Scegli l'anno accademico corrente e fornisci un nome descrittivo, ad esempio 2023 o 2022 - 2023. (I caratteri devono essere utf8 o verranno rimossi automaticamente).

    Importante

    L'anno accademico viene usato per associare i dati in ingresso per facilitare la compilazione di dati cronologici anno per anno. L'approccio è allineato a un anno accademico rispetto all'anno di calendario. Se l'anno accademico si estende su un anno di calendario, ad esempio, inizia il 15/8/2022 e termina il 15/6/2023, il valore dell'anno accademico da selezionare è l'anno finale, 2023. Per altre informazioni, vedere Gestione dell'anno accademico

    Immettere le date per l'inizio e la fine dell'anno accademico.

    In base alle funzionalità di dati facoltative supportate dal provider, viene visualizzato l'interruttore attivato (impostazione predefinita) per includere altri dati. Se lo si desidera, è possibile selezionare l'interruttore da disattivare. Se l'interruttore è disattivato e non è disponibile per l'attivazione, significa che il profilo del provider non supporta attualmente la fornitura dei dati facoltativi. Per altre informazioni se il provider supporta l'invio di dati facoltativi, vedere Panoramica del provider di API OneRoster.

    Immettere la data in cui SDS deve interrompere la sincronizzazione dei dati in base all'anno accademico definito per questa origine. È più comune interrompere la sincronizzazione dei dati alla data di fine dell'anno accademico appena immessa.

    Selezionare Avanti per continuare.

    Screenshot che richiede l'anno accademico e interrompe la data di sincronizzazione.

  10. Selezionare le opzioni della regola di identità utente. Effettuare le selezioni sia per i ruoli del personale che per quello degli studenti.

    Nota

    La corrispondenza utente viene eseguita con il flusso in ingresso e non scrive né aggiorna gli oggetti utente in Microsoft Entra ID. La corrispondenza viene eseguita e archiviata nel data lake Education. Per altre informazioni, vedere Microsoft 365 Manage Users on the writing of the match link forward with the outbound flow (Gestione utenti di Microsoft 365 sulla scrittura del collegamento di corrispondenza in avanti con il flusso in uscita).

    • Attributo dall'origine: attributo utente basato sui dati provenienti dal SIS/SMS.
      • Le opzioni di origine disponibili sono Username e Email.
    • Attributo a cui corrispondere: proprietà utente in Microsoft Entra ID a cui corrispondere.
      • Le opzioni di corrispondenza Microsoft Entra ID disponibili sono UserPrincipalName e Mail.
    • (FACOLTATIVO) Se i dati utente non includono il valore @domain , selezionare un dominio dall'elenco.

    Avviso

    La selezione di un dominio è facoltativa e deve essere usata solo se i dati in ingresso in base all'attributo selezionato dall'origine non includono il valore @domain . SDS non controlla e accoda se il valore è mancante in un record. SDS accoderà la selezione del dominio a tutti i record che potrebbero causare @domain@domain e non trovare corrispondenze in tali istanze per il mapping utente esistente con gli utenti in Microsoft Entra ID.

    Attenzione

    Se gli utenti SIS/SMS, ad esempio gli utenti del gruppo di ruoli del personale, possono essere associati a @domain1 o @domain2 o @domain3 è necessario includere un @domain nei dati di origine, in base all'attributo selezionato dalla selezione dell'origine (ad esempio: prefix@domain). Questa operazione è necessaria affinché l'attributo corrisponda a: UserPrincipalName o Mail per trovare il Microsoft Entra utente corretto con cui trovare la corrispondenza.

    La specifica dell'API OneRoster v1.1 consente di passare solo un ruolo per utente. Se associato a più organizzazioni, può passare solo lo stesso ruolo per un utente a più organizzazioni. Poiché un ruolo per organizzazione, i record vengono contrassegnati come isPrimary 'True'.

    Importante

    Quando si configura il flusso Gestione utenti di Microsoft 365, queste regole vengono usate se l'opzione è attivata in Crea utenti senza corrispondenza, per definire il costrutto per la proprietà UserPrincipalName Microsoft Entra.

    Dopo aver soddisfatto le selezioni, selezionare Avanti per continuare.

    Screenshot che mostra i prompt delle regole di identità utente.]

  11. Esaminare le informazioni presentate in Rivedi e crea. Se tutto è corretto, selezionare il pulsante Avanti . In caso contrario, è possibile tornare indietro per correggere.

    Screenshot di Rivedi e crea.]

    Screenshot dell'elaborazione dopo aver selezionato create.]

  12. Il flusso di dati in ingresso è stato creato e la prima esecuzione è in sospeso, selezionare Il pulsante Fine . Ricontrollare per visualizzare lo stato della prima esecuzione.

    Screenshot che indica che il flusso in ingresso è stato creato.]

    Screenshot che mostra l'azione Dashboard home e Gestisci dati.

    Consiglio

    È possibile configurare la configurazione gestisci dati immediatamente dopo aver definito la configurazione dei dati connect, durante la prima esecuzione attiva o dopo il completamento della prima esecuzione.

  13. Per controllare lo stato dell'esecuzione, tornare alla pagina Home del dashboard.

    Se non si verificano problemi con i dati, il dashboard Home indica "Nessun errore o avviso dei dati trovati" e "Non sono stati rilevati errori o avvisi relativi ai dati durante l'ultima esecuzione. Continuate il grande lavoro!

    In caso di problemi con i dati, il dashboard Home informa che "Sono stati rilevati alcuni problemi con i dati" e invita a analizzare l'integrità della sincronizzazione.