Skip to main content

即将发布的 REST 规范

Note

本文档采用 AI 辅助机器翻译。译文仅供参考，不保证准确性；此内容的英文版为官方权威版本。

Grades Journey v2 可以通过 REST API 配置成绩簿数据。虽然这些API与核心Learn API不同，成绩 Journey v2 API的认证遵循与核心Learn REST API相同的OAuth2认证流程。这需要在 Anthology Developer Portal 上设置一个 REST API 应用。

创建评分方案

Web 服务端点

https://{{hostname}}/learn/api/v2/cc/gradejourney/gradeSchemasAPI

示例 JSON 正体

[
   {
       "title": "Pass-Fail-Custom-Schema",
       "symbols": "P=80:F=0",
       "optionalData": "sisSchemaID=PF"
   }
]

评分方案元素定义

元素名称

描述

必需

类型与最大尺寸

称谓

评分方案标题。

是

字符串（333个字符）

符号

列表中的符号，带有可选的下界。

是

String（2000号）

optionalData

键值对中每组对之间用冒号分隔，键值之间用等号分隔。例如：key1=value1：key2=value2

否

String（2000号）

示例回应

[ 
   { 
       "courseId": "", 
       "name": "Pass-Fail-Custom-Schema", 
       "status": "OK", 
       "message": "Grade schema successfully created" 
   }
]

创建可评分项目和成绩栏

Web 服务端点

https://{{hostname}}/learn/api/v2/cc/gradejourney/gradableItemsAPI

示例 JSON 正体

[
   {
       "courseId": "course1",
       "name": "Final Grade",
       "itemType": "MANUAL_COLUMN",
       "instructions": ""
       "anonymous": false,
       "group": false,
       "contentAreaName": "Assignments",
       "available": true,
       "attempts": 1,
       "tracked": false,
       "startDate":
       "endDate":
       "dueDate": "",
       "points": 100,
       "gradeSchema": "Pass-Fail-Custom-Schema",
       "sequenceNum": 1,
       "extract": true,
       "mapping": "",
       "optionalData": "SIS_ID=FG123456",
   }
]

可评分项目与成绩列元素定义

元素名称

描述

必需

类型与最大尺寸

courseId

批处理 UID 确定该可评分题目或成绩栏适用于的课程。

是

字符串（256个字符）

name

可评分物品的标题。

是

字符串（333个字符）

item类型

要制作的可分级物品类型。

可能的值：*作业，*测试，调查，有讨论区，维基，博客，期刊，SELF_AND_PEER_TEST，*MANUAL_COLUMN，*WEIGHTED_COLUMN，TOTAL_COLUMN

*Ultra和Original课程。其他所有课程仅限原创课程。

是

字符串（333个字符）

说明

评分项目说明。

否

String（2000号）

匿名

如果属实，作业或测试将启用匿名评分功能。

对于 Ultra 课程的匿名评分，需要为作业设置截止日期。

否

布尔值（默认 false）

群

如果属实，作业将被创建为作业类型组提交。

否

布尔值（默认 false）

内容区域名称

可评分物品的位置会被创建。

可以在Ultra课程中使用，配置子文件夹并将内容放入子文件夹。该值的格式为“parent@>@child”，其中“parent”是顶层（父）文件夹的名称，“child”是子文件夹的名称。如果子文件夹已经存在，作业会被添加到现有子文件夹中。如果子文件夹不存在，则会在父文件夹中创建。

否

字符串（255字符）

可用

判断该物品是否对学生可见。

否

布尔值（默认 false）

颜色

原始课程中可评分题目的颜色链接。颜色名称或六边形数值。

仅限原创课程。

否

String（10个角色）

尝试

测试或作业允许的尝试次数。

否

智力（无限默认 –1）

跟踪

确定可评分物品是否启用统计追踪。不适用于成绩栏。

仅限原创课程。

否

布尔值（默认 false）

startDate

日期显示。

否

日期

结束日期

显示至今。

否

日期

dueDate

可分级项目的到期日期。

否

日期

点

满分。

否

浮点数（默认100.0）

gradeschema

按Learn中存在的成绩模式名称。请注意，该模式可能是通过成绩导出或Blackboard Learn提供的网络服务创建的

否

字符串（333个字符）

序列数字

内容区域序列显示订单号。

仅限原创课程。

否

智力

提取

真/假—如果为真，该列将从提取工具中提取。仅当成绩旅程在出局设置页面启用了配置时才适用。

否

字符串（333个字符）

映射

对于加权列，指定映射。默认是无映射，这需要在 Learn 中手动完成映射。这将是可评分的物品名称/百分比对，中间用逗号分隔，百分比总和为100。示例：作业1=30，测试1=30，测试2=40。

对于总计列，只需指定应包含在总计中的列。例如，作业1、考试1、作业2、期末成绩

否

字符串（333个字符）

optionalData

键值对中每组对之间用冒号分隔，键值之间用等号分隔。例如：key1=value1：key2=value2

否

String（2000号）

示例回应

 [
   {
       "status": "OK",
       "message": "Gradecolumn successfully created",
       "courseId": "course1",
       "name": "Final Grade"
   }
]

删除成绩栏

Web 服务端点

https://{{hostname}}//learn/api/v2/cc/gradejourney/gradeColumnDeleteAPI

示例 JSON 正体

[
   {
       "courseId": "course1",
       "name": "Final Grade"
   }
]

成绩列删除元素定义

元素名称

描述

必需

类型与最大尺寸

courseId

课程批处理 UID。

是

字符串（333个字符）

name

要删除的列名。

是

字符串（333个字符）

示例回应

[
   {
       "status": "OK",
       "message": "Grade column successfully deleted",
       "courseId": "TG-TEST-ORIG",
       "name": "Delete Column"
   }
]

设定外部成绩

（仅限原创课程）

Web 服务端点

https://{{hostname}}/learn/api/v2/cc/gradejourney/externalGradeColumnAPI

示例 JSON 正体

[
   {
       "courseId": "course1",
       "name": "Final Grade"
   }
]

外部成绩柱元素定义

元素名称

描述

必需

类型与最大尺寸

courseId

课程批处理 UID。

是

字符串（333个字符）

name

拟设定的柱子名称为外部成绩。

是

字符串（333个字符）

示例回应

 [
   {
       "status": "OK",
       "message": "External grade column successfully updated",
       "courseId": "course1",
       "name": "Final Grade"
   }
]

创建注册元数据

Web 服务端点

https://{{hostname}}/learn/api/v2/cc/gradejourney/userMetadataAPI

示例 JSON 正体

[
   {
       "courseId": "course1",
       "userId": "student1",
       "optionalData": "EnrollType=LetterGrade"
   },
   {
       "courseId": "course1",
       "userId": "student2",
       "optionalData": "EnrollType=Audit"
   }
]

注册元数据元素定义

元素名称

描述

必需

类型与最大尺寸

courseId

课程批处理 UID。

是

字符串（333个字符）

用户ID

用户批处理 UID。

是

字符串（333个字符）

optionalData

键值对中每组对之间用冒号分隔，键值之间用等号分隔。例如：key1=value1：key2=value2

否

String（2000号）

示例回应

 [
   {
       "status": "OK",
       "message": "User metadata successfully created",
       "courseId": "course01",
       "name": "student01"
   },
   {
       "status": "OK",
       "message": "User metadata successfully created",
       "courseId": "course02",
       "name": "student02"
   }
]

更新成绩值

Web 服务端点

https://{{hostname}}/learn/api/v2/cc/gradejourney/gradeValueAPI

示例 JSON 正体

[ 
   { 
       "courseId": "course001", 
       "userId": "user1", 
       "name": "FINAL GRADE", 
       "value": "B" 
   } 
]

成绩值更新元素定义

元素名称

描述

必需

类型与最大尺寸

courseId

课程批处理 UID。

是

字符串（333个字符）

用户ID

用户批处理 UID。

是

字符串（333个字符）

name

要更新的列值。

是

字符串（333个字符）

价值

更新到的成绩值。

是

字符串（333个字符）

示例回应

[
   {
       "status": "OK",
       "message": "Grade value successfully added",
       "courseId": "course1",
       "name": "Final Grade"
   }
]