Datenerfassung mit der OneRoster-API

  • Artikel

OneRoster API (Application Programming Interfaces) ist ein Branchenstandardformat von 1EdTech (früher IMS Global), für den Austausch von Student Information System (SIS) / Student Management Systems (SMS)-Daten. Mit dieser Synchronisierungsmethode können Sie mithilfe der REST-basierten OneRoster 1.1-APIs, die von Ihrem SIS/SMS-Anbieter entwickelt wurden, eine direkte Verbindung mit Ihrem SIS/SMS herstellen. Die API-Unterstützung ermöglicht es Ihnen, Daten direkt zu synchronisieren, anstatt CSV-Dateien (Comma Separated Value) zu verwenden.

Daten, auf die von School Data Sync zugegriffen wird

Wichtig

Durch das Verbinden und Bereitstellen von Daten von Institutionen mit School Data Sync bestätigen Sie, dass Sie berechtigt sind, diese Daten mit Microsoft zu teilen, und verpflichten sich, die Data Governance-Standards Ihrer organization einzuhalten.

Aktion URL Erforderliche Filtereigenschaften Optionaler/empfohlener Filter Beispiele
GetAllAcademicSessions /academicSessions status dateLastModified /academicSessions?offset=0&limit=5000&filter=status='active'/academicSessions?filter=dateLastModified>'{deltaDateTime}'

Einrichten von SDS für Microsoft 365 Education Mandant

  • Microsoft 365 Education Mandant
  • Globale Administratorberechtigungen erforderlich

SDS-Zugriff und erstmalige Anmeldung

Um auf das SDS Admin Portal zuzugreifen, starten Sie Ihren Webbrowser, navigieren Sie zu sds.microsoft.com, und melden Sie sich dann mit Ihrem Microsoft 365 Global Admin-Konto an.

  1. Wählen Sie Erste Schritte aus.

    Screenshot: Willkommensnachricht

  2. Wählen Sie Weiter.

    Screenshot: Übersicht über SDS

    Lassen Sie vor dem nächsten Schritt einige Momente für die Bereitstellung von Diensten im Mandanten ein.

    Screenshot: Ausstehend beim Warten auf den Abschluss der Dienstbereitstellung

  3. Wählen Sie Neuen eingehenden Flow erstellen aus. Wählen Sie Weiter aus, um fortzufahren.

    Screenshot: Aufforderung zum Erstellen eines neuen eingehenden Flows

  4. Wählen Sie Ihre Datenquelle aus. Wählen Sie für die OneRoster-API die Option Verbindung mit meinen Daten herstellen aus.

  5. Wählen Sie das Format aus. Wählen Sie für die OneRoster-API die Option API aus. Wählen Sie Weiter aus, um fortzufahren.

    Screenshot der Auswahl der API.

    Screenshot: Prozessanforderung zum Abrufen einer Liste von API-Anbietern

  6. Sie müssen Ihren SIS/SMS-Anbieter aus der Anbieterliste auswählen. Nachdem Sie ausgewählt haben, wählen Sie Weiter aus, um den Vorgang fortzusetzen.

    Screenshot: Liste der API-Anbieter zur Auswahl.

    Hinweis

    Wenn Ihr SIS/SMS-Anbieter nicht in der Liste enthalten ist, finden Sie unter OneRoster Provider Overview (OneRoster-Anbieterübersicht ) Anweisungen zur Teilnahme an Pilottests oder Informationen, die sie an Ihren Anbieter senden müssen, damit dieser als OneRoster-Anbieter hinzugefügt wird.

  7. Um die Verbindung mit Ihrem SIS/SMS zu aktivieren, müssen Sie die Anmeldeinformationen für die Verbindung angeben.

    • Webzugriffs-URL: URL, auf die Ihre OneRoster-API für Ihr SIS/SMS zugegriffen werden kann

    • Client-ID, die zum Herstellen einer Verbindung mit Ihrer SIS-/SMS-OneRoster-API verwendet wird

    • Geheimer Clientschlüssel, der zum Herstellen einer Verbindung mit Ihrer SIS/SMS OneRoster-API verwendet wird

    • Zugriffstoken-URL: Wenn Ihre SIS-/SMS-OneRoster-API für die Authentifizierung mit OAuth2 konfiguriert ist, müssen Sie auch den Endpunkt der Zugriffstoken-URL angeben, der für die Verbindung verwendet wird. Der Endpunkt unterscheidet sich von der Webzugriffs-URL.

    • Wählen Sie Weiter aus, um fortzufahren.

    Screenshot: Aufforderungen zur Eingabe von API-Anmeldeinformationen

  8. Als Nächstes testen wir die Verbindung mit Ihrem SIS / SMS basierend auf den auf dem letzten Bildschirm eingegebenen Informationen.

    Screenshot: Überprüfung der API-Anmeldeinformationen

    • Wenn keine Probleme auftreten, werden Sie benachrichtigt und können Weiter auswählen, um fortzufahren.

    • Wenn wir keine Verbindung herstellen können, werden Sie benachrichtigt und können Zurück auswählen, um die bereitgestellten Informationen zu überprüfen und zu aktualisieren.

    Screenshot: Erfolgreiche Überprüfung der API-Anmeldeinformationen

  9. Wählen Sie Ihr aktuelles Studienjahr aus, und geben Sie einen Anzeigenamen an, z. B. 2023 oder 2022 – 2023. (Zeichen müssen utf8 sein oder werden automatisch entfernt.)

    Wichtig

    Das Akademische Jahr wird verwendet, um eingehende Daten zuzuordnen, um historische Daten von Jahr zu Jahr zu erstellen. Der Ansatz ist auf ein Akademisches Jahr im Vergleich zum Kalenderjahr ausgerichtet. Wenn Ihr Akademisches Jahr sich über ein Kalenderjahr erstreckt, z. B. am 15.08.2022 beginnt und am 15.06.2023 endet, ist der auszuwählende Wert für das akademische Jahr das Endjahr 2023. Weitere Informationen finden Sie unter Behandlung von Studienjahren.

    Geben Sie die Datumsangaben für den Beginn und das Ende Ihres Studienjahres ein.

    Basierend auf den unterstützten optionalen Datenfunktionen Ihres Anbieters wird die Umschaltfläche Ein (Standard) ausgewählt, um weitere Daten einzuschließen. Sie können die Umschaltfläche auswählen, um sie bei Bedarf zu deaktivieren. Wenn die Umschaltfläche deaktiviert ist und nicht aktiviert werden kann, bedeutet dies, dass das Profil des Anbieters die Bereitstellung der optionalen Daten derzeit nicht unterstützt. Weitere Informationen, wenn Ihr Anbieter das Senden optionaler Daten unterstützt, finden Sie unter Übersicht über OneRoster-API-Anbieter.

    Geben Sie das Datum ein, an dem SDS die Synchronisierung von Daten basierend auf dem definierten akademischen Jahr für diese Quelle beenden soll. Am häufigsten wird die Synchronisierung von Daten am soeben eingegebenen Enddatum des Akademischen Jahres beendet.

    Wählen Sie Weiter aus, um fortzufahren.

    Screenshot mit der Aufforderung zur Angabe des Studienjahres und des Synchronisierungsstoppdatums.

  10. Wählen Sie die Optionen für benutzeridentitätsregel aus. Treffen Sie Ihre Auswahl sowohl für Mitarbeiter- als auch für Studentenrollen.

    Hinweis

    Der Benutzerabgleich wird mit dem eingehenden Flow durchgeführt und schreibt oder aktualisiert die Benutzerobjekte nicht in Microsoft Entra ID. Der Abgleich wird durchgeführt und im Education Data Lake gespeichert. Weitere Informationen finden Sie unter Microsoft 365 Manage Users on the writing of the match link forward with the outbound flow.For more information, see Microsoft 365 Manage Users on the writing of the match link forward with the outbound flow.

    • Attribut aus Quelle: Benutzerattribute basierend auf Daten, die von Ihrem SIS/SMS stammen.
      • Verfügbare Quelloptionen sind Benutzername und Email.
    • Attribut, das mit übereinstimmen soll: Benutzereigenschaft in Microsoft Entra ID, mit der eine Übereinstimmung gefunden werden soll.
      • Verfügbare Microsoft Entra ID Übereinstimmungsoptionen sind UserPrincipalName und Mail.
    • (OPTIONAL) Wenn Ihre Benutzerdaten den @domain Wert nicht enthalten, wählen Sie eine Domäne aus der Liste aus.

    Warnung

    Die Auswahl einer Domäne ist optional und sollte nur verwendet werden, wenn die eingehenden Daten, die auf dem ausgewählten Attribut aus der Quelle basieren, nicht den @domain Wert enthalten. SDS überprüft und fügt nicht an, wenn der Wert in einem Datensatz fehlt. SDS fügt die Domänenauswahl an alle Datensätze an, die zu @domain@domain führen und keine Übereinstimmungen in diesen Instanzen für vorhandene Benutzerzuordnungen mit Benutzern in Microsoft Entra ID finden können.

    Achtung

    Wenn die SIS-/SMS-Benutzer, z. B. Benutzer in der Rollengruppe "Mitarbeiter", @domain1 oder @domain2 oder @domain3 muss ein @domain in den Quelldaten enthalten sein, basierend auf der ausgewählten Auswahl "Attribut aus Quelle " (Beispiel: prefix@domain). Dies ist erforderlich, damit Ihr Attribut mitUserPrincipalName oder Mail übereinstimmt, um den richtigen Microsoft Entra Benutzer zu finden, mit dem er übereinstimmen soll.

    Die OneRoster-API v1.1-Spezifikation ermöglicht nur das Übergeben einer Rolle pro Benutzer. Wenn sie mehreren Organisationen zugeordnet ist, kann sie dieselbe Rolle für einen Benutzer nur an mehrere Organisationen übergeben. Da eine Rolle pro organization werden Datensätze als isPrimary "True" markiert.

    Wichtig

    Beim Konfigurieren des Microsoft 365-Flows "Benutzer verwalten" werden diese Regeln verwendet, wenn die Option "Nicht übereinstimmende Benutzer erstellen" aktiviert ist, um das Konstrukt für die Microsoft Entra UserPrincipalName-Eigenschaft zu definieren.

    Nachdem Sie mit Ihrer Auswahl zufrieden sind, wählen Sie Weiter aus, um fortzufahren.

    Screenshot: Eingabeaufforderungen für Benutzeridentitätsregeln.]

  11. Überprüfen Sie die informationen unter Überprüfen und erstellen. Wenn alles richtig aussieht, wählen Sie die Schaltfläche Weiter aus. Wenn dies nicht der Fall ist, können Sie zurück zur Richtigen navigieren.

    Screenshot: Überprüfen und erstellen.]

    Screenshot der Verarbeitung nach dem Auswählen von

  12. Ihr eingehender Datenfluss wurde erstellt, und die erste Ausführung steht aus. Wählen Sie die Schaltfläche Fertig aus. Sehen Sie sich die status Ihrer ersten Ausführung an.

    Screenshot: Der eingehende Flow wurde erstellt.]

    Screenshot: Startdashboard und Aktion

    Tipp

    Sie können die Konfiguration Daten verwalten sofort nach dem Definieren Ihrer Connect-Datenkonfiguration, während der ersten aktiven Ausführung oder später nach Abschluss der ersten Ausführung einrichten.

  13. Um die status der Ausführung zu überprüfen, navigieren Sie zurück zur Seite Start Dashboard.

    Wenn keine Probleme mit Ihren Daten vorliegen, wird im home-Dashboard "Keine Datenfehler oder Warnungen gefunden" und "Während der letzten Ausführung sind keine Datenfehler oder -warnungen aufgetreten. Halten Sie die großartige Arbeit weiter!"

    Wenn Probleme mit Ihren Daten gefunden werden, informiert das Home-Dashboard darüber, dass "wir einige Probleme mit Ihren Daten gefunden haben" und empfiehlt Ihnen, die Synchronisierungsintegrität zu untersuchen.