有关使用 Microsoft Learn 目录 API 的最佳做法
本文介绍使用 Learn 目录 API 的最佳做法。
了解服务条款
虽然 Learn 目录 API 已公开发布且可供使用，但用户受 Microsoft API 使用条款的约束。 在使用 Learn 目录 API 之前以及在任何生产环境中包括输出之前，先阅读并了解 API 使用条款。
了解 Learn 目录 API 的限制
请参阅 Learn 目录 API 功能概述 一文中的限制。
了解 Learn 内容模型
为了有效地使用 Learn 目录 API 响应，请务必了解 Microsoft Learn 中可用的内容类型及其彼此之间的关系。 有关详细信息，请查看 Learn 内容模型文章。
特别是：
- UID 代表唯一 ID，对于每个内容对象都是唯一的。 如果 UID 发生更改，即使标题或其他元数据保持不变，内容将被视为新对象。
- 模块是 Learn 训练目录中的核心对象。 他们都能够独立运作，从某种意义上说，它们能够在内部全面讲授某个场景或概念，无需先修模块。 对于一些人来说，这就是它，它们不是学习路径的一部分。 对于其他人，它们被捆绑在一个或多个学习路径中，以便于帮助用户构建更高级的概念。 模块不必是学习路径的一部分，也可以是一个或多个模块的一部分。
- 单元不编写为独立内容。 它们旨在按模块的特定顺序执行。 因此，我们包括模块详细信息页和第一个单元的链接，以便用户可以从那里开始并继续浏览内容。
了解“学习”中的本地化工作原理以及如何在 API 输出中反映本地化内容
Microsoft Learn 支持网站上的 65 多个区域设置，大部分内容都转换为这些区域设置。 我们旨在将内容提供在产品教学所用的所有语言中，但并非所有地区的用户体验都有可用的本地化内容。
当区域记录没有可用的关联翻译时，网站上的内容和 API 响应会切换为默认的英语。 在 API 输出中，回退发生时，在其他区域设置响应中看到英语元数据。 但是，内容的 URL 仍然指向用户的语言区域设置，即使主要内容可能会回退，这是为了让用户仍然能够以该区域设置浏览网站（显示已翻译的页眉/页脚，以及任何其他有可用翻译的链接）。
将更新发布到英语内容时，我们的本地化管道将尽快更新本地化版本 - 通常在原始更改后的几天内完成。
可以在 Microsoft Learn 网站的页脚中查看支持区域设置的完整列表（选择您正在浏览的语言）。 可以使用 locale 筛选器通过 Learn 目录 API 查询其中每个区域设置。
我们的训练内容完成记录与区域设置无关，这意味着，我们不会将内容的本地化版本区分为用户训练完成记录中的单独对象。 无论用户使用何种语言完成培训，他们都会获得整个项目的学分，我们不会存储所用语言的记录。 这种不受区域限制的完成方式意味着，如果在学习体验中实施 Learn 目录 API，则需要考虑这一点。如果将内容对象以独立的对象形式加载，还需要实现一种等价机制，以确保无论用户使用哪种语言完成训练，他们在其他语言中都能得到认可，而无需重新进行该培训。
了解内容版本控制在 Learn 中的工作原理及其在 API 输出中的反映方式
值得注意的是，内容一直都在更新。 我们每天发布两次可用更新。 它们可能是次要的，例如次要文本更改或主要修订，例如主要修订、添加或删除。 一般来说，内容组合作为一个巨大的高度治理的开源项目进行管理，其中包含成千上万的参与者，因此，更改一直发生。 如果在生产系统中使用 Learn 目录 API，则应注意这一点，并让系统能够处理它。
添加新内容对象时，它们会在响应中显示为新对象（由 UID 标识）。 修改内容后，可以根据其last_modified值进行判断。 删除内容后，将从响应中删除内容对象。 尽管 API 响应中更新的内容有时稍有延迟，但当用户关注内容的 URL 时，他们始终会看到最新的信息。 删除时，旧 URL 将重定向到新内容或体验，或重定向到下一个最佳选项。
目前没有对last_modified日期之后的内容版本进行引用。
定期刷新数据
如果您使用 Learn 目录 API 中的目录信息来支持业务流程，或向客户显示，作为网站体验的一部分，请确保每天至少刷新一次这些内容。
值得注意的是，内容一直都在更新。 我们每天发布两次可用更新。 它们可能是次要的，例如次要文本更改或主要修订，例如主要修订、添加或删除。 一般来说，内容组合作为一个巨大的高度治理的开源项目进行管理，其中包含成千上万的参与者，因此，更改一直发生。 如果在生产系统中使用 Learn 目录 API，则应注意这一点，并让系统能够处理它。
审查开发人员文档中的建议
Learn 目录 API 开发人员文档 包含作为响应的一部分提供的数据的完整列表，以及建议如何使用每个字段来支持出色的学习体验。
了解查询逻辑
有许多筛选器可用于预筛选响应，以便仅获取要查找的内容，并且可以处理较小的文件大小。 可以在 Learn 目录 API 开发人员参考文章中看到查询筛选器的完整列表。 值得注意的是，你需要正确形成查询，如果在请求中使用多个查询参数，将使用 AND 运算符评估查询。
后续步骤
请查阅以下文章以获取有关 Learn 目录 API 支持的更多信息：