使用学校数据同步 (SDS) 的 OneRoster API 提供程序的载入指南

项目
10/15/2024

简介

Microsoft 学校数据同步 (SDS) 可以在入站数据流中同步任何实现 1EdTech OneRoster API (应用程序编程接口) 标准的系统的标识和名单信息。本文档旨在帮助 OneRoster API 的任何新提供程序成功与 SDS 集成。客户可以使用基于 REST 的 OneRoster 1.1 API 直接连接到其提供商。以下载入过程定义了 API 提供程序在添加供租户在 SDS 中选择和使用之前所需的步骤。

关于 SDS

若要了解有关 SDS 的详细信息，请转到 SDS 产品网站。
有关 SDS 的技术信息（包括部署视频和管理指南），请转到 SDS 文档站点。
有关使用 OneRoster API 连接数据的客户体验的详细信息，请转到使用 OneRoster API 连接数据。

概述

填写 SDS 合作伙伴注册表单上的表单。
1. 指示你将在表单上提供学校数据同步集成帮助。
2. 需要注册才能访问表单 - 请访问 Microsoft合作伙伴网络站点了解详细信息。必须提交单独的表单才能访问 SDS 和 Office 开发资源。
实现 SDS 所需的 OneRoster API 终结点。

SDS 对 dateLastModified 属性使用筛选器进行增量同步/增量同步处理，并且是与 SDS 集成所必需的。
验证 SDS 是否适用于 OneRoster API 终结点。
1. 使用 Postman 集合评估 API。
2. 针对沙盒环境使用 SDS 工程进行测试。
3. 配置 SDS 以验证解决方案 E2E。
与两个生产客户一起试用解决方案。
使连接器在所有Office 365 EDU 租户的 SDS 中正式发布。

开始使用

如果是新开发的 OneRoster API，请按照 OneRoster API v1.1 规范进行核心名单编制。
我们建议作为 1EdTech 提供商进行认证，但不需要认证。 
有关 SDS 支持的默认值列表的详细信息，请参阅默认值列表。

SDS 所需的 API 终结点

操作	URL	所需的筛选器属性	可选/建议的筛选器	示例
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	/用户	status	dateLastModified	/users？offset=0&limit=5000&filter=status='active'/users？filter=dateLastModified>'{deltaDateTime}'
GetAllClasses	/类	status	dateLastModified	/classes？offset=0&limit=5000&filter=status='active'/classes？filter=dateLastModified>'{deltaDateTime}'
GetAllEnrollments	/入学人数	status	dateLastModified	/enrollments？offset=0&limit=5000&filter=status='active'/enrollments？filter=dateLastModified>'{deltaDateTime}'

SDS 的可选 API 终结点

注意

对于人口统计数据、学生联系人关系和学生用户标志的可选数据部分，客户是否包含此数据的能力将基于我们将创建的提供商配置文件中支持的可选数据功能。按照所述的测试和验证步骤，如果选择同时为使用 SDS 的客户支持此数据，他们将看到切换 (默认) 选择“ 打开 ”以包含其他数据。他们可以根据需要选择关闭开关。如果切换开关不可用、显示但处于关闭状态且不可用于交互，则表示提供程序配置文件当前不支持提供该数据。

操作	URL	所需的筛选器属性	可选/建议的筛选器	示例
GetAllCourses	/课程	status	dateLastModified	/courses？offset=0&limit=5000&filter=status='active'/courses？filter=dateLastModified>'{deltaDateTime}'
GetAllDemographics	/人口	status	dateLastModified	/demographics？offset=0&limit=5000&filter=status='active'/demographics？filter=dateLastModified>'{deltaDateTime}'

可选用户学生联系人关系

提示

如果学生名单数据是通过 OneRoster API 提供的，则 SDS 不支持通过 CSV 旁加载学生联系人日期，因此我们建议所有提供商都努力支持使用 OneRoster API 方法提供联系人。

可以为学生用户指定学生联系关系，以增强教师与学生家长和监护人沟通的体验。联系人是随 /users 终结点一起提供的更多用户，与学生的关联位于“代理”下的学生用户记录中。

有关详细信息，请参阅 SDS 支持的学生联系人关系角色的默认值列表：联系人关系角色。
具有联系人/监护人角色的用户需要 familyName、givenName 和电子邮件。
应将电话和短信包含在 E.164 中，并且必须包含 + 。 (示例：+1234567890) 。
如果提供了反向数据，则从联系人用户“代理”字段中的联系人关系监护人记录到学生，这些记录将被筛选掉。

可选的用户人口统计标志

可以为学生用户指定用户标志，以指示他们参与计划或队列。如果用户) 为 true，则包含用户标志 (;如果不适用，则不包含用户标志。

标志在元数据字段中指定为用户的元数据扩展。方法遵循密钥 |值对，键名为 microsoft.userFlags，并且必须格式化为逗号分隔列表。用户标志可以按任何顺序显示，并且不区分大小写。

有关详细信息，有关 SDS 支持的用户标志值的默认列表，请参阅值的默认列表：用户标志。

示例：

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

数据匹配和验证规则

有关数据匹配和验证规则的详细信息，请参阅验证规则和说明。

重要

根据 1EdTech，提供商有责任在发出数据请求时对可用的数据强制实施数据隐私。学校数据同步根据请求的时间发出活动数据请求。

有用的说明和提示

终结点始终在 https url 之后：{server_URL}/ims/oneroster/v1p1。
所有终结点都必须支持分页，即限制和偏移参数 (例如：limit=10&offset=5000) 。
终结点对筛选器参数支持有要求，允许按状态进行筛选或启用增量同步。
客户知道如何启用“处于活动状态”选项，以及如何仅允许活动数据可用于学校数据同步要使用的连接。这可确保在学年进行时仅提供活动学年和课程的活动数据。
为了防止某些学校包含在从 SIS 提供给 SDS 的数据中，客户知道如何为用于将 SDS 链接到其 SIS 的连接/凭据配置包含哪些学校。
SDS 对 dateLastModified 属性应用筛选器进行增量同步/增量同步处理，并且是与 SDS 集成所必需的。
提供程序必须选择实现 OAuth1 () 或 OAuth 2.0 (客户端凭据授予) 身份验证方案（首选 OAuth 2.0）。
在开发期间，可以使用 Postman 集合验证终结点。
如果支持的身份验证协议为“OAuth 2” - 客户端凭据授予类型，则 SDS 将在“授权”标头中发送凭据。 SDS 不支持在请求正文中发送凭据。

测试 OneRoster API

使用 Postman 集合

Postman 是用于运行和管理 REST API 的已知工具。我们创建了 OneRoster API Postman 集合来调用和测试 SDS 所需的 OneRoster API。运行集合会调用 SDS 所需的所有 API，并针对返回的数据运行简单的测试。

使用 SDS 工程针对沙盒环境进行测试

为 OneRoster API 创建沙盒环境，并与指定的 SDS 工程师共享凭据。我们共同运行一组更深入的测试，以确保集成成功。

配置以验证解决方案

当所有测试都成功后，系统的名称将添加到 SDS 中的 OneRoster 提供程序列表中。但是，目前，它仅对为提供程序配置文件外部测试的租户可见（表示为“InPilot”模式）， () 不公开可用。接下来，在测试Microsoft 365 租户中将 SDS 配置为使用 OneRoster API 连接数据，以同步沙盒 OneRoster 终结点中的数据，并确保运行完成且不会出现错误。如果在自我调查后看到任何错误或警告并需要帮助，请联系指定的 SDS 工程师。

客户试点

测试成功完成后，可以开始与客户一起试用解决方案。系统名称显示在 SDS 中的 OneRoster® 提供程序列表中，供那些“外部测试版”的提供商查看为“InPilot”模式的提供商，同意试点集成。 SDS 团队和 OneRoster 提供商团队共同确定适当的试点客户，并安排时间部署 SDS。我们与客户密切合作，确保入站流运行成功，并一起验证结果。在向所有Office 365教育客户公开解决方案之前，将解决确定的任何最终 bug。

公开

两个客户成功完成其试点部署后，合作伙伴系统将在 SDS 中作为经过认证的 OneRoster 提供商源系统提供。当租户使用 OneRoster API 定义其连接数据配置时，SDS 向租户显示提供程序的名称。 SDS 团队在 SDS 联机文档中的 OneRoster API 提供程序概述页上记录合作伙伴系统。

SDS 团队需要：

软件的最低版本
配置先决条件
如何获取客户端 ID、客户端密码和 URL
任何其他特定说明
要联系谁寻求帮助

SDS 团队可能会与你的团队协调，通过各种营销渠道更广泛地促进集成。

通过