使用 Microsoft Learn 组织报告服务的最佳做法
本文介绍使用 Learn 组织报告服务的最佳做法。
了解 Microsoft Learn 数据访问和共享协议
使用此数据共享服务即表示你确认并接受 Microsoft Learn 数据访问和共享协议，同意 Microsoft 就使用组织的租户 ID 登录的 Learn 用户与组织共享 Learn 数据。 在使用 Microsoft Learn 组织报告服务并将输出包含在任何生产环境中之前，请阅读并理解本协议。
规划用于可视化此服务中提供的数据的报告解决方案
Microsoft Learn 组织报告服务向组织提供原始完成数据，默认情况下没有任何仪表板。 可以获取数据并将其导出为 CSV 以快速查看数据，但需要将数据联接在一起才能产生影响。
我们提供了适用于 SQL DB 存储的 Learn 组织报告 Power BI 模板，其中包含许多标准数据可视化效果，但你也可以使用所选的任何报告解决方案。 提前规划要使用的内容，以便在设置过程中将其连接到数据存储。
了解 Learn 内容模型
为了有效地使用 Microsoft Learn 组织报告服务响应，请务必了解 Microsoft Learn 中可用的内容类型及其彼此之间的关系。 有关详细信息，请查看 Learn 内容类型一文。
值得注意的是：
- UID 代表“唯一 ID”，对于每个内容对象都是唯一的。 如果 UID 发生更改，即使标题或其他元数据保持不变，内容也会被视为新对象。
- 模块是 Learn 训练目录中的核心对象。 这些模块都能够独立存在，从某种意义上说，它们在其中端到端地教授方案或概念，并且不需要学习先决条件模块。 对于某些模块，就是这样，它们不是学习路径的一部分。 对于其他模块，它们会被捆绑在一个或多个学习路径中，引导用户生成更高级的概念。 模块不一定是某一个学习路径的一部分，它也可以是一个或多个学习路径的一部分。
- 单元不作为独立的内容写入。 它们旨在以特定的顺序用于模块。 出于此原因，我们会包括指向模块详细信息页和第一个单元的链接，使用户可从该位置开始，继续浏览内容。
了解 Learn 中的本地化工作原理以及本地化内容如何反映在组织报告输出中
Microsoft Learn 支持网站上超过 65 种区域设置，并且大部分内容已翻译为这些区域设置。 我们的目标是使内容以内容中教授的产品可用的所有语言提供，但并非所有区域设置体验都有翻译内容可用。
当区域设置记录没有可用的关联翻译时，网站上的内容和 API 响应将“回退”为默认的英语。 对于 API 输出，当发生回退时，你将在其他区域设置响应中看到英语元数据。 但即使主要内容可能会回退，内容的 URL 仍将指向该区域设置，原因是使用户仍能够在该区域设置中导航网站（这将显示翻译的页眉/页脚，以及任何其他有可用翻译的链接）。
将更新发布到英语内容时，本地化管道会尽快更新本地化版本 - 通常是在原始更改后的几天内。 可以通过站点页脚查看受支持区域设置的完整列表（选择指向正在查看站点的语言的链接）。
我们的培训内容完成记录与区域设置无关，这意味着我们不会在用户培训完成记录中将内容的本地化版本区分为单独的对象。 无论用户使用哪种语言完成培训，他们都将获得整个对象的学分，我们不会存储对完成培训的语言的引用。 这意味着，如果在学习体验中实现 Learn 组织报告服务数据，则需要将其考虑在内，并且，如果将内容对象作为单独的对象加载，请在它们之间实现等效性，以便无论用户使用哪种语言完成培训，他们都将获得其他语言的学分，而不必重新参加培训。
了解内容版本控制在 Learn 中的工作原理以及它如何反映在组织报告输出中
值得注意的是，内容一直都在更新。 我们通常每天发布两次更新。 它们可能是次要更新（例如次要文本更改），也可能是主要更新，例如主要修订、新增或删除。 通常，内容组合作为一个涵盖数千个参与者的高度治理的大型开源项目进行管理，因此，更改会一直发生。 如果在生产系统中使用 Learn 组织报告服务数据，则应注意这一点，并让系统具备处理能力。
添加新内容对象时，它们将在响应中显示为新对象（由 UID 标识）。 内容被修改时，可以根据其 last_modified 值进行判断。 内容被删除时，将从响应中移除该内容。 尽管在 API 响应中内容更新会稍有延迟，但当用户根据 URL 访问内容时，他们始终会看到最新信息。 在删除的情况下，旧 URL 将重定向到新内容或体验。
目前在 last_modified 日期之后，没有对内容版本的引用。
了解组织报告服务的限制
请参阅 Learn 组织报告服务功能概述一文中的限制。
定期刷新数据
如果使用 Learn 组织报告服务数据中的目录信息来支持业务流程，或作为网站体验的一部分向客户显示，请确保每天至少刷新一次内容。
值得注意的是，内容一直都在更新。 我们通常每天发布两次更新。 它们可能是次要更新（例如次要文本更改），也可能是主要更新，例如主要修订、新增或删除。 通常，内容组合作为一个涵盖数千个参与者的高度治理的大型开源项目进行管理，因此，更改会一直发生。 如果在生产系统中使用组织报告服务数据，则应注意这一点，并让系统能够处理这些数据。
确保定期刷新加入的 Microsoft Entra 信息
为了知道每条完成记录引用的人员，需要将组织报告数据集数据加入 Microsoft Entra 信息，以便名字与完成记录显示在一起。 如果未刷新加入 Microsoft Entra 的数据，则完成记录可能包含过时的人员数据，或者缺少与其关联的 PII 数据。
参考开发人员文档
Learn 组织报告服务开发人员文档包含作为响应的一部分提供的数据的完整列表，以及有关如何建议使用每个字段来支持出色学习体验的建议。
后续步骤
有关使用 Learn 组织报告服务为你提供支持的详细信息，请查看以下文章：