Freigeben über

Onboardingleitfaden für OneRoster-API-Anbieter mit School Data Sync (SDS)

  • Artikel

Einführung

Microsoft School Data Sync (SDS) können Identitäts- und Listeninformationen von jedem System synchronisieren, das den 1EdTech OneRoster-API-Standard (Application Programming Interfaces) in einem eingehenden Datenstrom implementiert. Dieses Dokument soll allen neuen Anbietern von OneRoster-APIs helfen, eine erfolgreiche Integration in SDS zu ermöglichen. Kunden können mithilfe der REST-basierten OneRoster 1.1-APIs eine direkte Verbindung mit ihrem Anbieter herstellen. Der folgende Onboardingprozess definiert die Schritte, die vom API-Anbieter erforderlich sind, bevor sie mandanten zur Auswahl und Verwendung in SDS hinzugefügt werden können.

Informationen zu SDS

Übersicht

  1. Füllen Sie das Formular im SDS-Partner-Registrierungsformular aus.

    1. Geben Sie an, dass Sie die Integration von School Data Sync auf dem Formular unterstützen würden.

    2. Für den Zugriff auf das Formular ist eine Registrierung erforderlich. Weitere Informationen finden Sie auf der Microsoft Partner Network-Website . Sie müssen ein separates Formular für den Zugriff auf SDS- und Office-Entwicklungsressourcen übermitteln.

  2. Implementieren Sie die für SDS erforderlichen OneRoster-API-Endpunkte.

    SDS verwendet einen Filter für die dateLastModified-Eigenschaft für die Deltasynchronisierung/inkrementelle Synchronisierungsverarbeitung und ist für die Integration in SDS erforderlich.

  3. Überprüfen Sie, ob SDS mit Ihren OneRoster-API-Endpunkten funktioniert.

    1. Bewerten Sie Ihre APIs mithilfe der Postman-Sammlung.

    2. Testen sie mit SDS-Engineering in einer Sandboxumgebung.

    3. Konfigurieren Sie SDS, um die Lösung E2E zu überprüfen.

  4. Testen Sie die Lösung mit zwei Produktionskunden.

  5. Machen Sie Ihren Connector in SDS für alle Office 365 EDU-Mandanten allgemein verfügbar.

Erste Schritte

Erforderliche API-Endpunkte für SDS

Aktion URL Erforderliche Filtereigenschaften Optionaler/empfohlener Filter Beispiele
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 /Benutzer status dateLastModified /users?offset=0&limit=5000&filter=status='active'/users?filter=dateLastModified>'{deltaDateTime}'
GetAllClasses /Klassen status dateLastModified /classes?offset=0&limit=5000&filter=status='active'/classes?filter=dateLastModified>'{deltaDateTime}'
GetAllEnrollments /Eintragungen status dateLastModified /enrollments?offset=0&limit=5000&filter=status='active'/enrollments?filter=dateLastModified>'{deltaDateTime}'

Optionale API-Endpunkte für SDS

Hinweis

Für die optionalen Datenteile für demografische Daten, Kontaktbeziehungen von Schülern und Studentenbenutzerflags basiert die Möglichkeit eines Kunden, diese Daten einzufügen oder nicht, auf den unterstützten optionalen Datenfunktionen aus Ihrem Anbieterprofil, die wir erstellen. Wenn Sie diese Daten auch für Ihre Kunden unterstützen, die SDS verwenden, wird nach den beschriebenen Test- und Überprüfungsschritten die Option Ein (Standard) angezeigt, um zusätzliche Daten einzuschließen. Sie können die Umschaltfläche auswählen, um sie bei Bedarf zu deaktivieren. Wenn der Umschalter nicht verfügbar, aber deaktiviert und nicht für die Interaktion verfügbar ist, bedeutet dies, dass Ihr Anbieterprofil die Bereitstellung dieser Daten derzeit nicht unterstützt.

Aktion URL Erforderliche Filtereigenschaften Optionaler/empfohlener Filter Beispiele
GetAllCourses /Kurse status dateLastModified /courses?offset=0&limit=5000&filter=status='active'/courses?filter=dateLastModified>'{deltaDateTime}'
GetAllDemographics /Demographien status dateLastModified /demographics?offset=0&limit=5000&filter=status='active'/demographics?filter=dateLastModified>'{deltaDateTime}'

Optionale Kontaktbeziehungen zwischen Kursteilnehmern

Tipp

Da SDS das Querladen von Kontaktdaten von Kursteilnehmern über CSV nicht unterstützt, wenn deren Listendaten über die OneRoster-API bereitgestellt werden, empfehlen wir allen Anbietern, die Bereitstellung von Kontakten mithilfe des OneRoster-API-Ansatzes zu unterstützen.

Die Kontaktbeziehung zwischen Schülern und Studenten kann für Schüler*innen angegeben werden, um die Erfahrungen von Lehrkräften für die Kommunikation mit Eltern und Erziehungsberechtigten zu verbessern. Kontakte sind mehr Benutzer, die mit dem /users-Endpunkt bereitgestellt werden, und die Zuordnung zu einem Kursteilnehmer finden Sie im Benutzerdatensatz des Kursteilnehmers unter "Agents".

  • Weitere Informationen zu den unterstützten Kontaktbeziehungsrollen, die von SDS unterstützt werden, finden Sie unter Standardliste der Werte: Rollen für Kontaktbeziehung.
  • familyName, givenName und email sind für Benutzer mit Kontakt-/Erziehungsberechtigtenrollen erforderlich.
  • Erwarten Sie, dass Telefon und SMS in E.164 und + enthalten sein müssen. (Beispiel: +1234567890).
  • Wenn umgekehrte Daten bereitgestellt werden, von einem Kontaktbeziehungs-Erziehungsberechtigten-Datensatz bis zum Kursteilnehmer im Feld "Agents" der Kontaktbenutzer, werden diese Datensätze herausgefiltert.

Optionale demografische Benutzerflags

Benutzerflags können für Schüler*innen angegeben werden, um ihre Teilnahme an einem Programm oder einer Kohorte anzugeben. Benutzerflags sind enthalten (wenn für den Benutzer true) oder nicht enthalten, falls nicht zutreffend.

Flags werden als Metadatenerweiterung für den Benutzer in einem Metadatenfeld angegeben. Der Ansatz folgt einem Schlüssel|Wertpaar mit dem Schlüssel microsoft.userFlags und muss als durch Trennzeichen getrennte Liste formatiert werden. Benutzerflags können in beliebiger Reihenfolge angezeigt werden, wobei die Groß-/Kleinschreibung nicht beachtet wird.

Weitere Informationen finden Sie in der Standardliste der von SDS unterstützten Benutzerflagswerte unter Standardliste von Werten: Benutzerflags.

Beispiel:

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

Datenabgleichs- und Validierungsregeln

Weitere Informationen zu Datenabgleichs- und Validierungsregeln finden Sie unter Validierungsregeln und -beschreibungen.

Wichtig

Gemäß 1EdTech ist der Anbieter dafür verantwortlich, den Datenschutz dafür zu erzwingen, welche Daten bei einer Datenanforderung verfügbar sind. School Data Sync stellt eine Anforderung für aktive Daten basierend auf dem Zeitpunkt der Anforderung.

Hilfreiche Hinweise und Tipps

  • Die Endpunkte folgen immer hinter der https-URL: {server_URL}/ims/oneroster/v1p1.
  • Alle Endpunkte müssen Paging unterstützen, d.b. Limit- und Offsetparameter (z. B. limit=10&offset=5000).
  • Endpunkte haben Anforderungen an die Unterstützung von Filterparametern, um das Filtern nach status zu ermöglichen oder die Deltasynchronisierung zu aktivieren.
  • Kunden wissen, wie sie die Option "Is Active" aktivieren oder zulassen, dass nur aktive Daten für die Verbindung verfügbar sind, die von School Data Sync verwendet werden soll. Dadurch wird sichergestellt, dass im Laufe des Schuljahres nur aktive Daten für das aktive Schuljahr und die sitzung bereitgestellt werden.
  • Um zu verhindern, dass bestimmte Schulen in die Daten einbezogen werden, die vom SIS an SDS bereitgestellt werden, wissen kunden, wie sie konfigurieren können, welche Schulen für die Verbindung bzw. die Anmeldeinformationen verwendet werden, um SDS mit ihrem SIS zu verknüpfen.
  • SDS wendet einen Filter für die dateLastModified-Eigenschaft für die Deltasynchronisierung/inkrementelle Synchronisierungsverarbeitung an und ist für die Integration in SDS erforderlich.
  • Anbieter müssen entweder das Authentifizierungsschema OAuth1(a) oder OAuth 2.0 (Gewährung von Clientanmeldeinformationen) implementieren, OAuth 2.0 bevorzugt.
  • Während der Entwicklung können Sie Ihre Endpunkte mit unserer Postman-Sammlung überprüfen.
  • Wenn das unterstützte Authentifizierungsprotokoll "OAuth 2" ist – Typ der Gewährung von Clientanmeldeinformationen, würde SDS die Anmeldeinformationen im "Authorization"-Header senden. SDS unterstützt das Senden der Anmeldeinformationen im Anforderungstext nicht.

Testen Ihrer OneRoster-APIs

Verwenden der Postman-Sammlung

Postman ist ein bekanntes Tool zum Ausführen und Verwalten von REST-APIs. Wir haben die Postman-Sammlung der OneRoster-API erstellt, um die für SDS erforderlichen OneRoster-APIs aufzurufen und zu testen. Beim Ausführen der Sammlung werden alle für SDS erforderlichen APIs aufgerufen und einfache Tests für die zurückgegebenen Daten ausgeführt.

Testen mit SDS Engineering in einer Sandboxumgebung

Erstellen Sie eine Sandboxumgebung für Ihre OneRoster-APIs, und geben Sie die Anmeldeinformationen für Ihren designierten SDS-Techniker weiter. Zusammen führen wir eine reihe tiefergehende Tests durch, um sicherzustellen, dass die Integration erfolgreich ist.

Konfigurieren zum Überprüfen der Lösung

Wenn alle Tests erfolgreich waren, wird der Name Ihres Systems der Liste der OneRoster-Anbieter in SDS hinzugefügt. Derzeit ist es jedoch nur für Mandanten sichtbar, die für Anbieterprofile als "InPilot"-Modus bezeichnet werden (nicht öffentlich verfügbar). Konfigurieren Sie als Nächstes SDS zum Verbinden von Daten mit der OneRoster-API in Ihrem Microsoft 365-Testmandanten, um Daten aus Ihren OneRoster-Sandbox-Endpunkten zu synchronisieren und sicherzustellen, dass die Ausführung fehlerfrei abgeschlossen wird. Wenn Fehler oder Warnungen angezeigt werden und Sie nach ihrer Selbstuntersuchung Hilfe benötigen, wenden Sie sich an ihren zuständigen SDS-Techniker.

Kundenpilot

Nachdem die Tests erfolgreich abgeschlossen wurden, ist es an der Zeit, mit der Pilotphase der Lösung mit Kunden zu beginnen. Der Name Ihres Systems ist in der Liste der OneRoster-Anbieter® in SDS für diejenigen sichtbar, die "flighted" sind, um auch Anbieter anzuzeigen, die sich im InPilot-Modus befinden, und sich damit einverstanden erklären, die Integration zu pilotieren. Das SDS-Team und das OneRoster-Anbieterteam arbeiten zusammen, um die entsprechenden Pilotkunden zu identifizieren und eine Zeit für die Bereitstellung von SDS zu planen. Wir arbeiten eng mit Kunden zusammen, um sicherzustellen, dass die eingehenden Datenflussausführungen erfolgreich sind, und überprüfen die Ergebnisse gemeinsam. Alle abschließend identifizierten Fehler müssen behoben werden, bevor die Lösung allen Office 365 Education-Kunden öffentlich zur Verfügung gestellt wird.

Öffentlichen

Nachdem zwei Kunden ihre Pilotbereitstellungen erfolgreich abgeschlossen haben, steht das Partnersystem in SDS als zertifiziertes OneRoster-Anbieterquellsystem zur Verfügung. SDS zeigt mandanten den Namen des Anbieters an, wenn diese ihre Konfiguration der Verbindungsdaten mithilfe der OneRoster-API definieren. Das SDS-Team dokumentiert das Partnersystem auf unserer Übersichtsseite des OneRoster-API-Anbieters in unseren SDS-Onlinedokumenten.

Das SDS-Team benötigt Folgendes:

  • Mindestversion der Software
  • Konfigurationsvoraussetzungen
  • Abrufen der Client-ID, des geheimen Clientschlüssels und der URLs
  • Alle anderen spezifischen Anweisungen
  • An wen Sie sich wenden können, um Hilfe zu benötigen

Das SDS-Team kann sich mit Ihrem Team abstimmen, um die Integration über verschiedene Marketingkanäle breiter zu fördern.