应用程序开发人员手册

上次更新日期： 2024年1月24日

注意:

Adobe Learning Manager V1 API 现已弃用。 V1 API 将自 2021 年 2 月 28 日起停用。我们建议您使用 V2 API 与 Adobe Learning Manager 交互。

概述

Adobe Learning Manager 是一款基于云端、以学习者为中心的自助式学习管理解决方案。客户可以使用 Adobe Learning Manager API 以编程方式访问 Adobe Learning Manager 资源，以将之与其他企业应用程序集成。Adobe 合作伙伴也可以使用 API，扩展 Adobe Learning Manager 的功能或将之与其他应用程序或服务进行集成，从而提高其价值。

使用场景

开发人员使用 Adobe Learning Manager API 可以构建独立的应用程序，从而扩展 Adobe Learning Manager 的功能，或者可将 Adobe Learning Manager 与其他企业应用程序工作流程进行集成。您可以使用您选择的任何技术来开发 Web 应用程序、桌面客户端或移动应用程序。作为开发人员，您可以通过 Adobe Learning Manager 访问应用程序数据。您开发的应用程序将于 Adobe Learning Manager 平台外部进行部署，随着应用程序的发展，您可以完全控制软件开发生命周期。通常应用程序由客户公司进行开发，以便与其 Adobe Learning Manager 帐户结合使用，因此对于特定客户公司来说是隐私应用程序。此外，Adobe 合作伙伴可以使用 Adobe Learning Manager API 构建通用应用程序，这些应用程序可供大量 Adobe Learning Manager 客户使用。

Adobe Learning Manager API

Adobe Learning Manager API 基于 REST 原则，并通过 HTTP 将 Adobe Learning Manager 对象模型的关键要素显示给应用程序开发人员。开发人员在了解 API 端点的详细信息和 HTTP 方法前，可以先熟悉各种 Adobe Learning Manager 对象、其属性和内部关系。深入了解模型之后，大致了解 API 请求和响应的结构，以及 API 之间通用的一些常用编程术语也同样很有帮助。

有关各种 API 端点和方法的详细信息，请参阅 Adobe Learning Manager API 文档。

API 身份验证

在编写向 Adobe Learning Manager 调用 API 的应用程序时，您必须使用集成管理应用程序进行注册。

Adobe Learning Manager API 使用 OAuth 2.0 框架对客户端应用程序进行身份验证和授权。

步骤

1. 设置应用程序

您可以使用客户端 ID 和客户端密钥来设置应用程序，以使用正确的端点。注册应用程序后，便可获取 clientId 和 clientSecret。应在浏览器中使用 Get URL，因为它会使用预配置的帐户（如 SSO、Adobe ID 等）对 Adobe Learning Manager 用户进行身份验证。

GET https://learningmanager.adobe.com/oauth/o/authorize?client_id=<输入 clientId>&redirect_uri=<输入要重定向到的 URL>&state=<任意字符串数据>&scope=<一个或多个逗号分隔的作用域>&response_type=CODE。

身份验证成功后，浏览器将重定向到上述 URL 中提到的 redirect_uri。参数代码随重定向 URI 一起追加。

2. 从代码中获取刷新令牌

POST https://learningmanager.adobe.com/oauth/token Content-Type: application/x-www-form-urlencoded

发布请求正文：

client_id:<输入您的客户 ID>& 
client_secret:<输入您的客户密码>& 
code:<第 1 步中的代码>

3.通过刷新令牌获取访问令牌

获取访问令牌的 URL：

POST https://learningmanager.adobe.com/oauth/token/refresh Content-Type: application/x-www-form-urlencoded

发布请求正文：

client_id:<输入您的客户 ID>& 
client_secret:<输入您的客户密码>& 
refresh_token:<刷新令牌>

用于验证访问令牌详细信息的 URL

GET https://learningmanager.adobe.com/oauth/token/check?access_token=<access_token>

用于验证访问令牌详细信息的 URL

首次登录无头 LMS 应用程序时会保留 refresh_token。之后，refresh_token 用于为其客户端应用程序生成 access_token 以实现 API 调用。同样，内容播放使用 Oauth 端点生成 Cookie 以管理播放，其中涉及多个内容文件以及这些文件使用 Cookie 调用的 API 调用。 Oauth 生成的 Cookie 与 access_token 的 Cookie 有效期相同，为七天。生成 Cookie 后，无法清除它，这与典型的 Web 应用程序注销不同。 Oauth Cookie 和 Web 应用程序 Cookie 是两种不同的 Cookie，彼此互不相关。

因此，为了清除 Cookie，我们引入了一个新的端点，它可以撤消 refresh_token、Cookie 以及 Cookie 和刷新令牌。

详情

端点

查询参数

请求正文

POST oauth/o/revoke

cookie=true|false

表示需要撤销 Cookie

refresh_token=true|false

表示刷新

撤消 refresh_token 或（refresh_token 和 Cookie）所需的正文

{

“client_id”: <>,

“client_secret”: <>,

“refresh_token”: <>

}

仅撤销 Oauth Cookie 所需的正文

{

“access_token”: <>

}

使用限制

访问令牌的有效期为七天。一天后，您必须使用刷新令牌生成新的访问令牌。如果在现有访问令牌仍然有效的情况下用刷新令牌生成了新的访问令牌，则现有令牌将失效。

下面将介绍 Adobe Learning Manager API 中的一些常用术语，供您参考。

“Includes”

开发人员可以访问单个 API 对象模型，也可以访问与该模型关联的多个模型。如需访问后续相关模型，您需要了解每个模型与其他模型之间的关系。 “Includes”参数允许开发人员访问相关模型。您可以使用逗号分隔符来访问多个模型。有关“Includes”的示例用法和更多详细信息，请参阅本页中的示例 API 模型部分。

API 请求

可以通过发出 HTTP 请求来实现 API 请求。开发人员可以根据端点和方法的不同，选择不同的 HTTP 动词，如 GET、PUT、POST、DELETE、PATCH 等。对于某些请求，可以传递查询参数。在请求特定数据模型时，用户还可以按 JSON API 规范中所述请求相关模型。示例模型用法中介绍了典型 API 请求的结构。

API 响应

当客户端发出 API 请求时，将根据 JSON API 规范获取 SON 文档。响应还包含 HTTP 状态码，开发人员可以对其进行验证，以便在自己的应用程序逻辑中执行相应的后续步骤。示例模型用法中介绍了典型 API 响应的结构。

错误

当 API 请求失败时，会得到错误响应。响应中返回的 HTTP 状态码表示错误的性质。错误代码以 API 引用中每个模型的数字显示。 200、204、400 和 404 是 API 中表示 HTTP 访问问题的一些常见错误。

字段

API 对象的属性及其关系统称为“字段”。有关更多信息，请参阅 JSON API。在进行 API 调用时，可以将“字段”用作参数，以从模型中获取一个或多个特定属性。如果没有“字段”参数，API 调用将从模型中获取所有可用属性。例如，在以下 API 调用中，fields[skill]=name 将单独获取技能模型的名称属性。

https://learningmanager.adobe.com/learningmanagerapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name

分页

有时，API 请求会导致在响应中返回一长串对象。在这种情况下，分页属性使开发人员能够按多个页面依次获取结果，其中每个页面包含一系列记录。例如，Adobe Learning Manager 中的分页属性可以让您设置页面中显示的最大记录数。此外，您还可以定义要在页面上显示的记录的范围值。

排序

API 模型中允许排序。根据模型，选择对结果进行排序的类型。可以按升序或降序进行排序。例如，如果指定 sort=name，则按名称升序排序。如果指定 sort=-name，则按名称降序排序。有关更多信息，请参阅 JSON API 规范。

API 使用说明

让我们考虑这样一种情况：开发人员希望获得技能名称、分配给技能级别的最高分数以及学习者针对该技能所获得的分数。

Adobe Learning Manager API 中 userSkill 模型由 id、type、dateAchieved、dateCreated、pointsEarned 等默认属性组成。因此，当开发人员使用 GET 方法获取 userSkill 模型的详细信息时，当前与默认属性相关的数据会显示在响应输出中。

但是，在这种情况下，开发人员希望获得用户的技能名称和技能级别的分数。 Adobe Learning Manager API 可以让您使用关系字段和“include”参数来访问这些相关信息。userSkill 的关联模型可在“关系”标签中获取。您可以通过调用这些模型以及 userSkill 来获取每个关联模型的详细信息。如需获取此信息，请对每个关联模型使用“include”参数和点（句点）分隔值。您可以使用逗号作为分隔符来请求另一个模型，如 user include=skillLevel.skill,course

API 调用

https://learningmanager.adobe.com/learningmanagerapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name&fields[skillLevel]=maxCredits&fields[userSkill]=pointsEarned

例如，userId 可以是 746783，userSkills id 为 746783_4426_1。

API 调用的响应

{ 
   &quot;links&quot;: {&quot;self&quot;: &quot;https://learningmanager.adobe.com/learningmanagerapi/v2/users/746783/userSkills/746783_4426_1?include=skillLevel.skill&fields[userSkill]=pointsEarned&fields[skillLevel]=maxCredits&fields[skill]=name&quot;}, 
   &quot;data&quot;:    { 
      &quot;id&quot;: &quot;746783_4426_1&quot;, 
      &quot;type&quot;: &quot;userSkill&quot;, 
      &quot;attributes&quot;: {&quot;pointsEarned&quot;: 5}, 
      &quot;links&quot;: {&quot;self&quot;: &quot;https://learningmanager.adobe.com/learningmanagerapi/v2/users/746783/userSkills/746783_4426_1&quot;} 
   }, 
   &quot;included&quot;:    [ 
            { 
         &quot;id&quot;: &quot;4426&quot;, 
         &quot;type&quot;: &quot;skill&quot;, 
         &quot;attributes&quot;: {&quot;name&quot;: &quot;Java&quot;}, 
         &quot;links&quot;: {&quot;self&quot;: &quot;https://learningmanager.adobe.com/learningmanagerapi/v2/skills/4426&quot;} 
      }, 
            { 
         &quot;id&quot;: &quot;4426_1&quot;, 
         &quot;type&quot;: &quot;skillLevel&quot;, 
         &quot;attributes&quot;: {&quot;maxCredits&quot;: 10} 
      } 
   ] 
}

Adobe Learning Manager 模型

Adobe Learning Manager API 允许开发人员以 RESTful 资源的形式访问 Adobe Learning Manager 对象。每个 API 端点都表示一个资源，通常为一个徽章之类的对象实例，或此类对象的集合。随后，开发人员可以使用 HTTP 动词，例如 PUT、GET、POST 和 DELETE 在这些对象（集合）上执行 CRUD 操作。

下图表示 V1 API 中 Adobe Learning Manager 对象模型的各个元素。

序列号	Adobe Learning Manager 对象	描述
1.	用户	用户是 Adobe Learning Manager 中的关键模型。用户通常是使用学习对象的企业内部或外部学习者。但是，除学习者之外，他们可能还扮演一些其他角色，如作者和经理。用户 ID、类型、电子邮件是一些内联属性。
2.	课程	课程是 Adobe Learning Manager 支持的学习对象之一，由一个或多个模块组成。
3.	模块	模块是在 Adobe Learning Manager 中创建学习对象时所用的构造块。模块可以分为四种不同类型，如教室、虚拟教室、活动和自学模块。使用此模块模型可获取帐户中所有模块的详细信息。
4.	认证	向成功完成课程的学习者授予认证。使用认证前，您须在应用程序中完成相应课程。
5.	学习计划	学习计划是专门设计的课程，旨在满足用户的特定学习需求。一般而言，学习计划用于推动完成横跨各个课程的学习目标。
6.	徽章	徽章是学习者在课程学习过程中达到特定的阶段性目标时获得的一种成就标志。
7.	技能	技能模型由级别和学分组成。学习者可以在完成相关课程后获得技能。
8.	认证注册	此模型提供用户注册单个认证的详细信息。
9.	课程注册	此模型提供用户注册单个课程的详细信息。
10.	课程实例	一个课程可以关联一或多个实例。您可以获取课程实例
11.	课程技能	课程技能模型会列明通过完成课程获得单个技能的进度。
12.	课程模块	课程模块模型会指明课程中会如何纳入某个模块。例如，模块是用于预先测试还是用于内容。
13.	学习计划实例	学习计划可以包含多个具有学习计划相似属性的实例，或自定义实例。
14.	工作辅助	工作辅助是可供学习者访问的学习内容，不设任何注册或完成标准。您可以提取更新日期、状态、ID 信息及其相关模型，如工作辅助版本、作者和技能级别。
15.	工作辅助版本	根据内容修订次数和上传数量，工作辅助可关联一或多个版本。此模型提供单个工作辅助版本的详细信息。
16.	学习计划实例注册	学习计划由一或多个实例组成。学习者可以自行注册或由管理员分配学习计划实例。此模型提供用户注册单个学习计划实例的详细信息。
17.	模块版本	模块可具有一或多个版本，具体视修订内容的上传次数而定。使用此模型可获取任一模块版本的特定信息。
18.	技能级别	技能级别由一或多门课程组成，学完这些课程后即可获得对应级别和相关学分。
19.	userBadge	UserBadge 将单个徽章与单个用户相关联。它包含一些详细信息，如徽章获取时间、assertionUrl 等。
20.	用户技能	用户技能表明单个用户达成的单项技能级别。

以下是 V2 API 中 Adobe Learning Manager 类图的各个元素。

Adobe Learning Manager 对象	描述
帐户	封装 Adobe Learning Manager 客户的详细信息。
徽章	徽章是学习者在课程进展过程中达到特定的阶段性目标时获得的一种成就标志。
目录	目录是学习对象的集合。
用户	用户是 Adobe Learning Manager 中的关键模型。用户通常是使用学习对象的企业内部或外部学习者。但是，除学习者之外，他们可能还扮演一些其他角色，如作者和经理。用户 ID、类型、电子邮件是一些内联属性。
资源	此模型用于对模块试图封装的每个内容资源进行建模。 loResource 中封装的所有资源在学习目标方面都是等效的，但在交付类型或内容区域设置方面则彼此不同。
userNotification	此模型包含与学习者相关的通知信息。
userSkill	UserSkill 表示一个用户达成的单项技能级别。
userBadge	UserBadge 将单个徽章与单个用户相关联。它包含一些详细信息，如徽章获取时间、assertionUrl 等。
技能	技能模型由级别和学分组成。学习者可以在完成相关课程后获得技能。
skillLevel	技能级别由一门或多门即将使用的课程组成，以获得对应级别和相关学分。
learningObject	学习对象是一个抽象概念，指的是用户可以注册和学习的各种对象。 Adobe Learning Manager 目前有四种学习对象：课程、认证、学习计划和工作辅助。
learningObjectInstance	学习对象的特定实例。
learningObjectResource	这相当于模块概念模块。一门课程由一个或多个模块组成。在 Adobe Learning Manager 中，系统会以多种等效方式提供模块。因此，loResource 实际上封装了所有这些等效资源。
loResourceGrade	这封装了用户在其注册的学习对象背景中使用特定资源的结果。其中包含一些信息，如用户在资源中所花时间、用户完成的进度百分比、通过/失败状态以及用户在任何相关测验中获得的分数。
日历	日历对象是用户可以注册的近期教室或虚拟教室课程的列表。
l1FeedbackInfo	L1 Feedback 封装了学习者针对与学习对象相关的反馈问题提供的答案。通常，如果配置为收集学习者的此类反馈，则系统会在用户完成学习对象后收集此信息。
注册	该抽象概念封装了与某事务相关的详细信息，该事务表示将特定用户分配给特定的学习对象实例。

应用程序开发过程

先决条件

作为开发人员，您必须在 Adobe Learning Manager 上创建试用帐户，以便拥有该帐户中所有角色的访问权限。若要编写应用程序，开发人员还需要创建一些用户帐户和课程，并为帐户设置合理的状态，以确保正在开发的应用程序能够访问部分示例数据。

创建客户端 ID 和密钥

在“集成管理员”登录页面中，单击左侧窗格的“应用程序”。
单击页面右上角的“注册”，以注册您的应用程序详细信息。此时会显示注册页面。

注册新申请人

必须填写此页面中的所有字段。

应用程序名称：输入应用程序名称。不一定要使用相同的应用程序名称，可以是任何有效名称。

URL：如果您知道托管应用程序的确切 URL，可以提及它。如果不知道，则可以提及公司 URL。此字段中必须包含有效的 URL 名称。

重定向域：在完成 OAuth 身份验证后，您希望 Adobe Learning Manager 应用程序重定向至哪款应用程序？请在此输入其域名。此处可提及多个 URL，但必须使用有效的 URL，如 http://google.com、http://yahoo.com 等。

描述：输入应用程序的简要介绍。

作用域：从四个可用选项中选择一个来定义应用程序的作用域。根据您在此处提到的选择，Adobe Learning Manager API 端点可供您的应用程序访问。例如，如果您选择“学习者”角色读取权限，那么您的应用程序可以以只读形式访问所有 Adobe Learning Manager 学习者 API 端点。

仅针对本帐户？
是 - 如果选择“是”，则其他帐户管理员无法看到该应用程序。
否 - 如果选择“否”，则其他帐户管理员也可以访问该应用程序，但他们需要使用应用程序 ID 来访问。应用程序 ID 会在 Adobe Learning Manager 应用程序编辑模式下生成并显示。

注意:

如果您在注册应用程序时选择“管理员”角色读写权限作为作用域，并在授权 API 时选择“管理员”角色读取权限，由于应用程序注册范围取代授权工作流程，所以您仍然对应用程序拥有写入权限。
在注册页中填写详细信息后，单击右上角的“注册”。

应用程序开发和测试

开发人员可以使用 Adobe Learning Manager API 构建任何应用程序。开发人员必须确保其帐户由一些有效用户和课程组成。他们可以创建一些虚拟用户和课程，并在试用帐户中模拟相关活动，以便测试应用程序的功能。

应用程序部署

我们建议生产帐户的 Adobe Learning Manager 管理员或集成管理员负责将应用程序提供给其企业内用户。在应用程序经过测试并被认为可以用于生产后，请将该生产帐户告知管理员。理想情况下，管理员希望在生产帐户中为应用程序生成新的客户端 ID 和客户端密钥，并执行必要的步骤，以安全方式将它们纳入应用程序中。部署应用程序的实际过程因企业而异，您所在企业的 Adobe Learning Manager 管理员必须获得企业内 IT/IS 部门的支持才能完成部署。

外部应用程序审批

单击“应用程序”页面右上角的“审批”，即可添加外部应用程序。提供外部应用程序 ID，然后单击“保存”。

常见问题解答

1. Adobe Learning Manager 是否集成了电子商务？

Adobe Learning Manager 已与 Adobe Commerce 集成。

更快、更轻松地获得帮助

新用户？