在 SDS 中同步家长和监护人联系人

项目
06/29/2024

概述

学校数据同步 (SDS) 支持引入各种数据元素，主要目的是预配Microsoft 365 个对象和实体，以及启用和扩充 Insights。 SDS 中支持同步的数据元素之一是父数据和守护者数据。本文档介绍父级和监护人同步过程，以及将此数据集同步到 Microsoft 365 的各种用例和注意事项。

为什么学校会引入家长和监护人的联系数据？

家长应用 为教师提供他们通过 SDS 管理和同步的每个课堂团队的所有家长和监护人联系人的列表。家长应用允许教师在 Teams 中直接与学校存档的任何家长和监护人联系人联系并进行通信。
当在 Teams 中启用作业中的每周监护人电子邮件摘要 时，“作业”应用每周向家长和监护人发送电子邮件，其中包含前一周作业的摘要视图，以及每个班级下一周的作业。
第三方应用集成：父级和监护人联系人数据可通过 MS Graph 上的 relatedContacts API 提供给第三方应用程序。通过 Graph 提供数据允许组织为父级和监护人联系人数据构建和提供自己的体验和用例。

注意

如果你的机构当前未使用 SDS，或者有办法向 SDS 提供家长和联系人数据，则管理员可以使教师能够使用 Teams 中的家长应用直接添加和更新家长信息。有关管理步骤的其他详细信息，请参阅在 Teams 中为 EDU 设置父连接。

支持哪些家长和监护人数据？

SDS 支持引入有关家长和监护人的基本联系信息，包括：

名
姓
电子邮件地址
电话号码
ID
相关联系人的角色
相关学生 ID

数据存储在 Entra ID 中的位置和方式？

SDS 将引入到 Substrate 的父级和监护人数据写入每个学生用户对象的隐藏数据存储中。
此基本联系人数据不是作为 Exchange Online 中的标准邮件联系人编写的。此选项旨在防止租户中的所有用户在引入数据时看到所有父级及其相关联系信息。
数据仅提供给 Microsoft 365 中的 Teams，适用于前面指出的前两个方案，并且还通过 MS Graph 上的相关Contacts API 提供给第三方应用程序。 API 需要管理员授予的仅限应用的权限，这意味着租户中的最终用户不允许查询 MS Graph 来查看或访问任何父级和监护人的联系人数据，从而保护家长和监护人的隐私。

如何同步家长和监护人数据？

在 SDS 中同步父级和监护人数据非常简单。本部分介绍如何根据起点和使用的同步方法同步家长和监护人：

SDS v1 CSV 文件

如果使用 SDS v1 CSV 格式将数据同步到 SDS，则应包含两个额外的 csv 文件， user.csv 和 guardianrelationship.csv。

SDS v2.1 CSV 文件

如果使用 SDS v2.1 CSV 格式将数据同步到 SDS，则应包含另一个 csv 文件 ，relationships.csv。

relationships.csv 中的 userSourcedId 对应于 users.csv中相关学生的 sourcedId 值。 relationshipUserSourcedId 属性对应于 users.csv 文件中的相关父级。
如果包含家长和监护人的电话号码，则应引入 E164 格式的数据，不带任何括号或空格，包括字符串前面的加号。 E164 格式可确保当应用引入并包含基于短信的通信方案时，父应用支持电话号码。

OneRoster API

我们已将常规 OneRoster API 支持指南传达给所有当前提供商。你可以通过以下方式提供帮助：跟进并请求提供商提供将联系人数据作为其数据集成的一部分的支持。与提供商共享 OneRoster API 提供程序的载入指南一文，以便他们可以更新支持，并与 SDS 部署工程团队合作来验证支持并更新其配置文件。
若要通过 OneRoster API 进行引入，请根据提供程序支持的可选数据功能，会看到“ 打开 (默认) ”切换为 “包括联系人 数据”。
- 如果切换开关为 “关闭 ”且无法打开，则表示提供程序的配置文件当前不支持提供可选数据。
- 提供程序添加支持后，可以编辑配置以选择切换为 “开” 以包括后续运行中的数据。

使用 Student 用户对象发送联系人数据

若要使用学生用户对象向前写入联系人数据，需要确保 “管理数据”配置将 “学生联系人关联 ”切换为“ 打开 ”，以在后续运行中包含数据。

父和监护人角色

SDS 支持家长和监护人的各种角色，如下所示。 Parents 应用仅支持 家长和监护人 的角色。如果在 SDS 中引入具有其他角色的任何用户，则他们在 Parents 应用中不可用。如果你打算让此人出现在 Parents 应用中并可供使用，请不要使用以下角色之一：

Relative
助手
医生
其他

状态 - 活动与非活动

当 SDS 将每个家长和监护人添加到每个学生用户的隐藏基底数据存储的相关联系人集合时，每个家长和监护人都标记为活动。如果在下次同步时要导入的数据中删除父级或监护人，则它们将被标记为非活动状态。可以在 SDS 中每个学生的“人员”页中查看此状态。只有处于活动状态的家长和监护人才会在家长应用中显示为可用。如果在后续同步中停止发送数据，SDS 不会自动删除父级和监护人记录。有关如何删除父级的详细信息，请参阅下一部分。

删除父级

SDS 在引入每个学生的用户对象上，将所有家长和监护人添加到相关联系人集合。删除学生的用户对象后，随着时间推移，SDS 存储的所有相应联系人也是如此。如果需要在不删除学生的用户对象的情况下删除相关联系人，则 SDS 团队已发布 PowerShell 脚本来帮助完成此过程。如果需要有关运行 PowerShell 脚本的帮助，可以通过联系我们的支持团队 https://aka.ms/sdssupport。从 Substrate 成功删除联系人后，请务必从所有后续上传中删除同一父级或监护人，以避免将它们添加回目录中。

删除父级和监护人数据

父级和卫报数据存储在 Azure 基板存储中。此位置难以访问，需要应用程序权限，并且也受到限制，因此无法删除单个条目。若要删除已同步到学生的单个家长或监护人，必须删除所有记录，然后阅读要与学生关联的记录。

这些步骤可帮助你运行以下脚本并删除父级和卫报数据。

O365-EDU-Tools/SDS Scripts/Reset-Guardians.ps1 at master ·OfficeDev/O365-EDU-Tools (github.com)

重要

此脚本使用 Microsoft.Graph PowerShell 模块。它不会在 PowerShell ISE 中运行。

创建证书

若要运行脚本，需要首先使用 entra ID Microsoft 创建一个应用程序，并提供用于访问信息的证书。在本文中查找有关创建自签名公共证书以对应用程序进行身份验证的步骤、命令和自签名证书详细信息。

在管理员模式下打开 PowerShell。
导航到你正在处理的位置。在此示例中，它是 C：\TEMP\Reset_Guardians_Script。
打开以下页面，了解创建命令的步骤。输入第一个命令，并记住更改证书名称。建议使用 “复制 ”按钮来更轻松地执行完整命令。
在此示例中，我们将证书名称设置为 parentResetScript。
在运行命令之前更改文件夹位置。
在此示例中，我们使用当前所在的同一文件夹。

创建应用程序

应用程序是我们确定脚本的权限和访问权限的方式。

导航到 Microsoft Entra ID 管理中心，然后导航到 标识 |应用程序 |应用注册。
选择“ 新建注册 ”以开始创建过程。
输入应用程序的名称。在此示例中，它是 父重置应用程序。 我们不需要在此页上填写任何其他设置。
复制并保存 应用程序 (客户端) ID。它用于稍后运行脚本。
在“管理”下选择 “API 权限”。
选择“添加权限”。
选择 Microsoft Graph。
选择“应用程序权限”。
搜索并选择 用户。ReadWrite.All 和 EDURoster.ReadWrite.All 并在选中两者后选择底部的 “添加权限 ”。
选择“ 授予管理员同意 (租户名称) 并确认”。
导航到左侧“管理”下的“证书 & 机密”。
选择“ 证书 ”选项卡，然后选择 “上传证书”。
导航到在第一阶段创建的证书。
选择“添加”。
最后，复制指纹。

运行 Reset_Guardians.ps1 脚本

若要运行脚本，需要租户 ID 和可在以下位置找到的脚本： O365-EDU-Tools/SDS Scripts/Reset-Guardians.ps1 master ·OfficeDev/O365-EDU-Tools (github.com)

若要查找租户 ID，请转到“Microsoft Entra ID”中的“ 概述 ”选项卡。
打开 GitHub 存储库并下载脚本。在此示例中，它将下载到包含证书的同一文件夹。
可以通过多种方式运行此脚本。如果使用记事本等文本编辑器打开脚本，可以看到可以使用的不同方法。在此示例中，我们将对所有学生运行它。

若要运行脚本，可以复制最后一个示例，并将字段替换为新的应用程序信息和租户 ID。

\Reset-Guardians.ps1 -clientId "{Application (client) ID}" -certificateThumbprint "{Certificate Thumbprint}" -tenantId "{Tenant ID}" ## Replace the field including the { }