如何使用 OneRoster® 1.1 API (经典) 部署学校数据同步

重要

到 2024 年底，学校数据同步 (经典) 体验将替换为 新的学校数据同步体验 。 我们建议你开始计划下一年回到学校的新体验 的过渡 。

OneRoster® 是一种行业标准格式，用于交换学生信息系统 (SIS) 数据。 通过 OneRoster® REST API，我们可以通过 SDS (经典) 服务将对象从提供 OneRoster® API 的 SIS 同步到 Microsoft 365。 使用此同步方法，可以使用 SIS 提供的基于 REST 的 OneRoster 1.1 API 直接连接到 SIS，并直接同步数据，而不是使用 CSV 文件。 使用 OneRoster® API 引入突出显示的数据类别，它使你能够点亮核心 SDS (经典) 预配功能。 它还允许你增强 Microsoft 365 (Microsoft 365) 所列产品和功能的体验。

若要使用 OneRoster® Sync 方法设置 SDS (经典) ，请按照本文中详述的说明进行操作。

先决条件

在使用 OneRoster® Sync 方法开始与 SDS (经典) 同步之前，请阅读 SDS (经典) 概述 ，并确保满足以下先决条件：

• 教育版租户Office 365
• 全局管理员权限

注意

通过 SDS (经典) 提供的数据可由第三方应用程序提供商通过其应用访问，因此应仅同步要提供给这些第三方的数据。

观看部署视频

另请参阅以下视频，了解用户标识匹配。

• 视频：如何匹配同步的源和目标属性

由学校数据同步访问的数据 (经典)

重要

通过连接学校数据同步 (经典) 提供机构数据，你确认你有权与 Microsoft 共享此数据，并承诺遵守组织的数据治理标准。

学术会议

操作	URL	所需的筛选器属性	示例
getAllAcademicSessions	/academicSessions	schoolYear， status	/academicSessions？filter=schoolYear='2019' AND status='active'
getAcademicSession	/academicSessions/{academicSession_id}

用户

操作	URL	所需的筛选器属性	示例
getAllUsers	/用户	status、dateLastModified	/users？filter=status='active' AND dateLastModified'2018-01-25T03>：22：03.297Z'
getUser	/users/{user_id}

学校

操作	URL	所需的筛选器属性	示例
getAllSchools	/学校	status、dateLastModified	/users？filter=status='active' AND dateLastModified'2018-01-25T03>：22：03.297Z'
getSchool	/schools/{school_id}
getClassesForSchool	/schools/{school_id}/classes	status、dateLastModified	/schools/{school_id}/classes？filter=dateLastModified'2018-01-25T03>：22：07.209Z'
getStudentsForSchool	/schools/{school_id}/students	status、dateLastModified	/schools/{school_id}/students？filter=dateLastModified'2018-01-25T03>：22：07.209Z'
getTeachersForSchool	/schools/{school_id}/teachers	status、dateLastModified	/schools/{school_id}/teachers？filter=dateLastModified'2018-01-25T03>：22：07.209Z'
getEnrollmentsForSchool	/schools/{school_id}/enrollments	status， dateLastModified， role	/schools/{school_id}/enrollments？filter=role='student'/schools/{school_id}/enrollments？filter=dateLastModified'2018-01-25T03>：22：28.204Z' AND role='teacher'

课程

操作	URL	所需的筛选器属性	示例
getClass	/classes/{class_id}

入学 人数

操作	URL	所需的筛选器属性	示例
getEnrollment	/enrollments/{enrollment_id}

学生

操作	URL	所需的筛选器属性	示例
getStudent	/students/{student_id}

教师

操作	URL	所需的筛选器属性	示例
getTeacher	/teachers/{teacher_id}

条款

操作	URL	所需的筛选器属性	示例
getTerm	/terms/{term_id}

关于 Microsoft Entra Connect 部署警告

如果要为租户配置 SDS (经典) ，该租户通过 Microsoft Entra Connect 从本地 Active Directory 同步，你可能会注意到，错误连接中显示的断开连接器数有所增加。 这是 Microsoft 365 组无法同步回 Microsoft Entra Connect Metaverse 和本地 Active directory 的结果。 这些警告不会对当前的 Microsoft Entra Connect 部署产生任何负面影响，并且仅提供有关生成的同步失败的信息性说明。 在 SDS (经典) 中启用同步后，Microsoft Entra Connect 中应会出现这些警告。 为通过 SDS (经典) 同步的每个类创建一个 Microsoft 365 组。

使用 OneRoster API 同步方法同步 SIS 数据

设置 SIS/SMS 访问后，请在 SDS (经典) 中创建同步配置文件以同步信息。

SDS 访问和首次登录

若要访问 SDS 管理员门户启动专用 Web 浏览器，请导航到 sds.microsoft.com，然后使用 Microsoft 365 全局管理员帐户登录。

创建同步配置文件并同步 SIS 数据

1. 登录后，在左侧导航栏中选择“ +添加配置文件” 以创建同步配置文件。

   

2. 在 “选择连接类型 ”页上，选择“OneRoster API”，然后从 “选择提供程序” 下拉菜单中选择 SIS 集成提供程序。 完成后，选择“ 开始”。

   

   • 命名此配置文件 - 输入同步配置文件的名称。 此名称用于标识 SDS (经典) 仪表板中的同步配置文件，在配置文件设置完成后无法更改。
   • 选择同步方法 - 在显示的可用同步方法之间进行选择。 如果使用 OneRoster 进行同步，请选择“通过 API 同步方法连接”，然后选择“OneRoster 1.1 API”作为服务选择。

3. 在 “同步选项” 页上，选择相应的选项以创建新用户或同步现有用户。 然后根据需要在页面上完成选择。

   注意

   如果运行用于创建新用户的选项并希望采用 V2.1 CSV，我们发布了一个工具，可帮助你准备支持 V2.1 CSV 格式，作为回到学校过渡的一部分。 在创建用户之前，请参阅更新定位点 ID。

   

   • 现有用户 - 如果已在 Microsoft 365 租户中为 OneRoster 中包含的每个学生和教师创建了用户帐户，请选择此选项。
   • 新用户 - 如果希望 SDS (经典) 为 OneRoster 中包含的每个学生和教师创建用户帐户，请选择此选项。
   • Web 访问 URL - 这是 SIS/SMS 的基本 OneRoster API URL，可通过 Internet 访问。
   • 客户端 ID - 用于连接到 SIS/SMS OneRoster API
   • 客户端密码 - 用于连接到 SIS/SMS OneRoster API。
   • 选择要同步的学校 - 此选项允许选择要从 OneRoster 同步的学校。
   • 学校属性 - 选择要包含的学校属性。
   • 节属性 - 选择要包含的分区属性。
   • 筛选非活动属性 - 选中此框仅同步活动记录。
   • 团队创建选项 – 选中此框可确保 SDS (经典) 为每个同步的课堂创建 Microsoft 365 组和课堂团队。 如果未选中该框，则 SDS (经典) 将仅创建Microsoft 365 组。
   • 替换不支持的字符 - 选中此框将自动将不支持的字符替换为支持的字符。
   • 分区组显示名称的同步选项 - 选中此框将允许教师在第一次同步后控制分区显示名称，并防止 SDS 覆盖教师所做的分区显示名称更改。
   • 延迟学生访问 - 启用此选项后，可以设置学生查看其课程的未来日期。 禁用此选项可允许学生立即查看其课程。
   • 何时应停止同步此配置文件？ - 你通常需要在学年结束时执行此操作。 停止同步此配置文件后，可以选择停用与此配置文件关联的类。

   注意

   目前，具有混合格式的单个租户 (即，将 V1 和 V2 同步配置文件主动运行且两者都设置为“同步到见解”) 将不起作用。

   注意

   正在等待 SIMS 和 Infinite Campus 提供程序支持同步到见解。

4. 在 “教师选项” 页上，选择适当的标识匹配选项，确认已选择教师属性，然后选择“ 下一步”。

   

   • 主键 (目标目录) - 这是Microsoft Entra ID中用于 SDS 标识匹配的用户属性。 观看标识匹配视频，详细了解如何选择适当的目标目录属性，以及如何为教师正确配置标识匹配设置。
   • 域 (可选) - 这是一个可选域值，可添加到所选源目录属性以完成教师标识匹配。 如果需要匹配 UserPrincipalName 或 Mail 属性，则必须在字符串中包含域。 源属性必须已包含域，或者可以使用此下拉菜单将相应的域追加到源属性。
   • 主键 (源目录) - 这是 OneRoster 中用于 SDS 标识匹配的教师属性。 观看标识匹配视频，详细了解如何选择适当的源目录属性，以及如何为教师正确配置标识匹配设置。

5. 在“ 学生选项” 页上，选择适当的标识匹配选项，确认已选择学生属性，然后选择“ 下一步”。

   

   • 主键 (源目录) - 这是 OneRoster 中用于 SDS 标识匹配的学生属性。 观看标识匹配视频，详细了解如何选择适当的源目录属性，以及如何为教师正确配置标识匹配设置。
   • 主键 (目标目录) - 这是用于 SDS 标识匹配的Microsoft Entra ID中的用户属性。 观看标识匹配视频，了解有关如何选择适当的目标目录属性以及为学生正确配置标识匹配设置的其他信息。
   • 域 (可选) - 这是一个可选域值，可添加到所选源目录属性以完成学生标识匹配。 如果需要匹配 UserPrincipalName 或 Mail 属性，则必须在字符串中包含域。 源属性必须已包含域，或者可以使用下拉菜单将相应的域追加到源属性。

6. 在“ 审阅 ”页上，确保已做出适当的选择。 如果满意，请选择“ 创建配置文件”。

   

OneRoster API 的筛选状态

• 学生和注册 - SDS 根据学校关联和状态同步某些学生。

  • 已同步
    • 活动
  • 未同步
    • 要删除

• 教师 - SDS 根据学校关联和状态同步某些学生。

  • 已同步
    • 活动
  • 未同步
    • 要删除

• 课堂 - SDS 根据学校关联和教职员工类型同步某些课程。

  • 已同步
    • 活动
  • 未同步
    • 要删除

• 学校 - SDS 根据学校关联和教职员工类型同步某些学校。

  • 已同步
    • 活动
  • 未同步
    • 要删除

  

视频：OneRoster API 部署

视频：如何匹配同步的源和目标属性

有关同步逻辑匹配成功和失败的各种示例，watch标识匹配视频：