Udemy Business API 最佳实践

本指南用作有关使用 Udemy Business API 支持集成构建的最佳实践参考。我们建议您遵循本指南中的提示，以确保最终学习者获得最佳体验。

Udemy 的销售和解决方案工程团队可以解答构建过程中出现的任何问题。如果您有任何问题，请随时联系 Udemy business 的业务联系人安排会议。 

访问 Udemy 的完整 API 文档。

本文档的上次更新时间为 2023 年 5 月 31 日。

Screen_Shot_2023-01-27_at_7.57.39_AM.png

目录：

  1. 一般 API 信息
  1. 课程列表 API
  1. 学习路径 API
  1. 报告 API
  1. 即将推出的内容
  2. 反馈？

    1. 一般 API 信息

身份验证和 SSO

请注意，Udemy Business 中的身份验证和用户管理独立于您的学习管理系统 (LMS) 和学习体验平台 (LXP) 系统处理。当学习者通过 LMS/LXP 系统访问 Udemy Business 课程时，这些用户还必须拥有 Udemy Business 的许可证，才能在 Udemy Business 内完成课程。Udemy Business 通过多种机制支持用户管理：标准用户名/密码、电子邮件域访问和单点登录。

错误处理 + 速率限制

429 错误

  • 所有 Udemy API 都有速率限制；当超过速率限制时，系统将通过 Retry-After 标头返回 429 错误响应。您应该实施重试逻辑，以在发出其他请求之前等待 Retry-After 标头中的秒数。 
  • 注意：Udemy 速率限制可能会发生变化。重试逻辑应基于 429 响应中的值而不是任何硬编码速率限制来实现。

50X 错误

  • 对于任何 502/503 错误，也应实现重试逻辑。如果在访问课程列表端点时收到任何 50X 错误，请尝试减小 page_size 参数值以防止进一步错误。
  • 我们还建议实现面向客户的机制，以重新同步课程目录和刷新报告数据。

    2. 课程列表 API 

工作原理

Udemy Business 课程列表 API 使您能够将与 Udemy 课程相关联的所有课程和课程元数据获取到您的系统中。在那里，您可以从第三方平台（如 LMS、LXP 或其他系统）搜索、发现和访问您的 Udemy Business 课程。除了关键课程信息（如标题、描述、缩略图等），课程集成还包括一个深度链接 URL，它会自动将学习者从 LMS/LXP 重定向回您的 Udemy Business 实例，学习者将在 Udemy Business 中完成课程。 

集成不支持在第三方系统中嵌入或完成 Udemy Business 课程这一功能。这样可避免需要在其他系统中重新托管内容，也确保提供最佳的学习者体验，因为课程设计为在 Udemy 内部使用，还包括对学习者工具、讲师问答等内容的访问。 

Udemy Business 支持将课程自动注册作为 API 配置的可选设置。对于集成推荐此设置，当自动注册处于活动状态时，如果学习者单击 LMS/LXP 系统中的课程链接，他们将自动注册。 

访问 Udemy 与第三方系统中的课程 

一些 LMS/LXP 系统支持限制 LMS/LXP 内哪些用户可访问哪些课程这一功能。除了公开自定义课程和学习路径外，Udemy Business 内的所有用户都可以从 Udemy Business 内访问和注册整个公共课程目录。虽然这对我们的客户来说不是问题，但需要注意的是，您的 LMS/LXP 系统和 Udemy Business 之间的功能可能略有不同。

课程刷新频率

由于课程目录可能会更改，我们建议每天执行目录刷新。此操作应会自动进行，无需最终用户手动执行任何步骤。我们建议在非高峰时间进行刷新（UTC 凌晨 3 点最为理想）。

推荐的课程数据

虽然我们提供了通过 API 返回的大量课程元数据，但我们建议至少使用以下数据点以获得最佳用户体验：

API 字段

建议

title

description

primary_category

primary_subcategory

使用这些字段匹配用户的搜索词

images[]

图像 URL，用于向用户提供课程的图像

url

mobile_native_deeplink

分别在 Udemy Business Web 应用和移动应用上指向客户环境中的课程的深度链接

locale

Udemy Business 目录有几种不同语言的课程，您的系统识别和筛选这些语言的能力至关重要

estimated_content_length

数分钟内提供，非常适合为用户显示，可用于通知报告/用户游戏化

level

课程级别（初级、中级、专家） 

 

高效的 API 调用

根据客户的语言集合，我们的 Udemy Business 系列可以提供 6,000 至 23,000 门课程。最大页面大小为 100，需要 60 到 230 次 API 返回才能获得所有这些课程。 从长远来看，设置您的系统以成功地管理该过程将带来重大好处。如果您希望获得有关此过程的个性化咨询，请联系您的 Udemy 解决方案工程师。

页面大小

同步 API 调用

  • 我们建议利用同步请求来高效地检索课程目录。
  • 当您的软件处理课程页面时，序列中的一页可能会因各种原因而失败。重要的是要知道哪些页面已失败，并在此过程中包括重试机制。 
  • 同步 API 调用和队列数据结构对于这类进程非常有用，因为它可以对后续页面排序并重试错过的调用。异步 API 调用可能会使 API 在一段时间内调用过多，从而使得难以跟踪序列中的哪些页面可能已失败。我们建议先成功完成每个课程页面，然后再继续下一个课程。

课程分类

查看当前课程分类列表。这包括可以通过 API 映射到您的系统中的类别和子类别列表。请注意，此分类并未针对所有语言进行标准化，并且此分类可能会随着时间的推移而更改。

语言代码

Udemy Business 中的语言列表和相关代码如下所示。当您从 Udemy 下载课程列表时，您会看到一个区域设置字段，其中前两个小写字母对应于整个课程的语言，后两个字母对应于可用于原文字幕、翻译字幕等的其他区域。例如，en_GB 代表英国英语，而 en_US 代表美国英语。

阿拉伯语 - ar

印度尼西亚语 - id

英语 - en

法语 - fr

德语 - de

印地语 - hi

意大利语 - it

日语* - ja

朝鲜语* - ko

普通话 - zh

波兰语 - pl

葡萄牙语 - pt

俄语 - ru

西班牙语 - es

土耳其语 - tr

独特的课程目录 

Udemy Business 课程目录对每个 Udemy Business 客户来说都是独一无二的。不同的语言包、自定义课程和从 udemy.com 导入的课程将包含在每个客户的集合中，并包含在课程 API 响应中。因此，您需要为每个 Udemy Business 客户组织维护一个独特的课程目录。

新课程和已淘汰的课程

  • 课程目录随时可能更改 - 可能会添加新课程，也可能会淘汰课程。 
  • 如果您使用课程目录获取所有课程并将其加载到您自己的内部数据库中，那么当课程列表输出中不再显示淘汰的课程时，请务必删除或标记这些课程。
  • 一旦某课程遭淘汰，课程列表 API 将不再返回该课程，用户将不再有权在 Udemy 注册该课程。当某课程在 Udemy Business 系列中淘汰时，在淘汰时已注册该课程的任何学习者将继续拥有访问权限。如果学习者取消注册淘汰的课程，他们将无法再访问该课程。此外，任何新学习者都无法访问或注册该课程。 

课程列表 API 中未包含的内容

请注意，Udemy Business 课程目录 API 不包括对有关课程的所有信息的访问。一些值得注意的、目前尚不可用的内容包括：

  • 课程嵌入或托管
    • 您不能在 Udemy Business 之外直接嵌入或托管 Udemy Business 内容。您必须将用户从 LMS/LXP 重定向回 Udemy Business 才能使用内容。
  • 课程评分
    • 这些不包括在课程 API 端点中。请注意，许多 LMS/LXP 系统都包括自己的课程评分系统，您的学习者仍然可以独立使用该系统。
  • 课程评论
  • 注册信息
  • 搜索和发现功能
    • Udemy Business 通过自己的方式来呈现搜索结果和推荐课程，其考虑热门课程、最受好评的课程等。此功能不会“发送”给第三方工具。Udemy Business 无法控制第三方工具如何呈现结果或建议课程。
  • 学习路径和 Udemy Pro 路径
    • 这些是与课程分开的对象，不包含在课程目录同步中。我们有一个单独的学习路径 API 端点，您必须利用它来导入 Udemy Business 学习路径和 Udemy Pro 路径。
  • 讲座级别的数据
    • Udemy Business 的 API 可以通过我们的 API 发送完整的课程和完整的学习路径。我们无法发送部分课程，如个别课程章节、讲座或测验。
    • 如果您正在寻找使用部分课程创建自定义学习路径或学习计划的能力，我们建议在 Udemy Business 中构建学习路径，然后使用我们的学习路径 API 端点将学习路径导入您的 LMS/LXP。 
  • UB Pro 实验、评估、工作区
    • 实验、评估和工作区无法集成到第三方系统中，必须直接从 Udemy Business 启动。 
  • 您不能通过 API 将课程批量上传到 Udemy。我们的 API 用于从 Udemy 中提取课程信息。

    3. 学习路径  API

概述

与 Udemy 的课程列表 API 端点类似，Udemy Business 还提供了学习路径 API 端点，因此您可以在第三方平台（如 LMS、LXP 或其他系统）中搜索、发现和访问您的 Udemy Business 学习路径。 

学习路径是一系列课程、个别讲座、自定义内容和链接的集合，它们组合在一起，向学习者展示学习某一特定知识主题的设计路线。

从学习路径返回的信息在许多方面与通过课程列表 API 端点返回的内容类似，但请谨记，学习路径被视为与课程不同的对象，并且必须以这种方式处理。

虽然使用学习路径 API 开发连接器对于与 Udemy Business 集成的核心用例来说并不是绝对必要的，然而在考虑开发来最大限度提高集成的长期好处时，它是一个很好的附加功能。

    4. 报告 API

概述

Udemy Business 报告 API 使您能够跟踪学习者如何参与内容。例如，您可以查看、跟踪和了解谁正在完成哪些课程、频率、跟踪优秀学习者、吸引正苦苦挣扎的学习者等等。这些洞察分析对于实现更广泛的学习和发展目标非常有帮助。从 Udemy Business 导出的报告洞察分析有助于在 LMS/LXP 中查看，并与其他外部系统中现有的数据和报告功能相结合或增强。

可通过两种机制从 Udemy 获取报告数据：xAPI 和 REST 报告 API。有关差异的更多信息，请访问 xAPI 的优点。 

报告 xAPI

  • Udemy 将近乎实时地向指定的端点发送进度 + 完成事件。这样做可不再重复轮询 Udemy 的 API。
  • 如果您的平台具有 xAPI 功能，则推荐使用 xAPI，因为越来越多的学习系统继续采用此标准。
  • 请注意，报告 xAPI 当前包含的数据元素没有 RESTful API 那么多。 
    • 例如，学习者在课程中花费的时间不会作为 xAPI 语句的一部分发送。

报告 RESTful API

必须定期调用此 API，数据将从报告 REST API 端点拉入 LMS/LXP。它不是实时的，需要定期拉取才能获得新记录。

建议的端点

完成和进度数据的用户课程活动。使用from_date 和 to_date 将结果限制为给定的日期段。

报告 API 刷新频率

  • 每 4 小时
    • 注意：我们的 REST API 数据每天更新 3 次。 
    • 每 4 小时允许 Udemy 在未来执行更频繁的更新，而不需要集成更改。

报告数据

数据元素

详细资料

course_id

课程的唯一标识符 

user_email

用户的唯一标识符 

completion_ratio

用户已完成的课程百分比。

请注意，此百分比可能会随着课程的变化而变化。
例如， 100% 完成 + 1 个新讲座可能更改为 80%

num_video_consumed_minutes

非常适合内部 LMS 指标，可跟踪用户参与度总学习分钟数/学分

course_first_completion_date

用于跟踪用户是否在任何时间完成了课程。

course_completion_date

用于跟踪最新完成情况。
如果用户已取消注册课程，则此项可以为空

user_external_id

用作用户唯一的外部 ID。（仅当电子邮件不是有效的唯一 ID 时）

lms_user_id

用作 LMS 唯一的外部 ID（仅当电子邮件不是有效的唯一 ID 时）

 

进度和完成

  • 您的集成应该包含进度和完成事件。
    • 这应该发生在所有已使用的 Udemy Business 课程中，包括已淘汰课程和未从您的平台启动的课程。

报告 API 和 xAPI 中未包含的内容

  • Udemy Business Pro 报告
    • 目前，用户实验活动报告和用户评估活动报告只能通过 Udemy 管理员设置直接下载。
  • 学习路径报告
    • 这不是通过 API 提供的，目前只能通过 Udemy 管理员设置直接下载。

    5. 即将推出的内容

Udemy 正努力不断改进我们的 API 和技术堆栈。 

  • GraphQL - Udemy 工程团队计划更新我们的课程目录 API，以利用 GraphQL 架构。阅读有关 GraphQL 概念的更多信息。这将支持查询我们的课程目录 API，它们仅返回该特定调用所需的数据，还有其他好处。Udemy 的 GraphQL API 计划于 2023 年第三季度公开发布。

  • 搜索 API - Udemy 拥有来自用户的丰富知识，可以搜索我们的超过 20 万门课程的目录，并推荐适合他们的课程。我们的搜索功能可以协助您的搜索和建议需求。搜索功能定于 2023 年第 3 季度发布。

    6. 反馈？

对此文档有任何反馈或希望查看其他信息？请将您的反馈提交至 partnerships@udemy.com，我们期待着您的来信。

相关文章

联系我们