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

  • 项目

简介

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

关于 SDS

概述

  1. 填写 SDS 合作伙伴注册表单上的表单。

    1. 指示你将在表单上提供学校数据同步集成帮助。

    2. 需要注册才能访问表单 - 请访问 Microsoft 合作伙伴网络站点 了解详细信息。 必须提交单独的表单才能访问 SDS 和 Office 开发资源。

  2. 实现 SDS 所需的 OneRoster API 终结点。

    SDS 对 dateLastModified 属性使用筛选器进行增量同步/增量同步处理，并且是与 SDS 集成所必需的。

  3. 验证 SDS 是否适用于 OneRoster API 终结点。

    1. 使用 Postman 集合评估 API。

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

    3. 配置 SDS 以验证解决方案 E2E。

  4. 与两个生产客户一起试用解决方案。

  5. 使连接器在所有Office 365 EDU 租户的 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}'

可选用户学生联系人关系

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

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

可选的用户人口统计标志

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

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

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

示例：

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

数据匹配和验证规则

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

重要

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

有用的说明和提示

  • 终结点始终在 https url 之后：{server_URL}/ims/oneroster/v1p1。

  • 所有终结点都必须支持分页，即限制和偏移参数 (例如：limit=10&offset=5000) 。

  • 终结点对筛选器参数支持有要求，允许按状态进行筛选或启用增量同步。

  • 客户知道如何启用“处于活动状态”选项，以及如何仅允许活动数据可用于学校数据同步要使用的连接。这可确保在学年进行时仅提供活动学年和课程的活动数据。

  • 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 租户中使用 OneRoster API 设置数据引入来载入 SDS ，以便从沙盒 OneRoster 终结点同步数据，并确保运行完成且不会出错。 如果在 自我调查后看到任何错误或警告并需要帮助，请联系指定的 SDS 工程师。

客户试点

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

公开

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

SDS 团队需要：

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

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