本页介绍了如何使用 Classroom API 预览版功能,以及如何指定预览版。
与稳定版 v1 API 相比,使用预览版功能时需要考虑以下两个方面:
- 抢先体验或预览计划中的 API 功能不会在标准客户端库中提供,并且默认情况下可能无法通过 HTTP 访问。
- 在任何给定时间,都可能存在多个预览版 API 状态或版本。
在客户端库中启用预览功能
使用 Classroom API 的常见方式是使用客户端库。客户端库有三种类型:
- 动态生成的客户端库
- Google 提供的静态客户端库
- 您自己的自定义客户端库
建议使用动态生成的或 Google 提供的静态库来使用该 API。如果您需要构建自己的库,请参阅构建客户端库。如何创建自己的库不在本指南的讨论范围内,但您应查看动态库部分,了解预览标签及其在 Discovery 中的作用。
动态库
Python 等语言的库在运行时使用发现服务中的发现文档生成客户端库。
发现文档是用于描述和使用 REST API 的机器可读规范。它用于构建客户端库、IDE 插件以及与 Google API 交互的其他工具。一项服务可能会提供多个发现文档。
您可在以下端点找到 Classroom API 服务的发现文档 (classroom.googleapis.com
):
https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY
使用预览版 API 的重要区别在于指定适当的 label
。对于 Google 课堂公开预览版,该标签为 DEVELOPER_PREVIEW
。
如需生成 Python 库并使用预览方法实例化 Google 课堂服务,您可以使用相应的服务、凭据和标签指定发现网址:
classroom_service_with_preview_features = googleapiclient.discovery.build(
serviceName='classroom',
version='v1',
credentials=credentials,
static_discovery=False,
discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY)'
有关每种语言的详细信息,请参阅单独的 Google API 客户端库文档。
静态库
Java、Node.js、PHP、C# 和 Go 等语言的客户端库必须在源代码的基础上构建。这些库是为您提供的,并且已纳入预览版功能。
对于公开预览版,您可以在其他 Workspace 开发者预览版计划客户端库中找到 Google 课堂客户端库。如需非公开预览版,如果您需要生成的静态库,请与您的 Google 联系人联系。
您可能需要修改典型的依赖项配置以使用这些本地库,而不是导入不具备预览版功能的标准客户端库。
例如,如需使用 Go 客户端库,您需要在 go.mod
文件中使用 replace
指令来需要本地目录中的模块:
module example.com/app
go 1.21.1
require (
golang.org/x/oauth2 v0.12.0
google.golang.org/api v0.139.0 // Classroom library is in here.
)
require (
...
)
// Use a local copy of the Go client library.
replace google.golang.org/api v0.139.0 => ../google-api-go-client
再举一个例子,如果您使用的是 Node.js 和 npm,请将 Node.js 客户端库下载 (googleapis-classroom-1.0.4.tgz
) 作为本地依赖项添加到 package.json
中:
{
"name": "nodejs-classroom-example",
"version": "1.0.0",
...
"dependencies": {
"@google-cloud/local-auth": "^2.1.0",
"googleapis": "^95.0.0",
"classroom-with-preview-features": "file:./googleapis-classroom-1.0.4.tgz"
}
}
然后,在您的应用中,除了常规依赖项之外,还需要 classroom-with-preview-features
模块,并实例化该模块中的 classroom
服务:
const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithPreviewFeatures = require('classroom-with-preview-features');
...
const classroom = classroomWithPreviewFeatures.classroom({
version: 'v1',
auth: auth,
});
...
指定 API 预览版
无论您使用静态库还是动态库,在对具有预览功能的方法进行 API 调用时都必须指定预览版本。
如需了解各种可用的版本及其包含的功能,请参阅 Classroom API 路线图。方法和字段的参考文档还介绍了该方法或字段适用于哪些版本。
您可以通过在请求中设置 PreviewVersion 字段来指定版本。例如,如需使用评分准则 CRUD Preview API 创建评分准则,应在 CREATE 请求中将 previewVersion
设置为 V1_20231110_PREVIEW
:
rubric = service.courses().courseWork().rubrics().create(
courseId=course_id,
courseWorkId=coursework_id,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW",
body=body
).execute()
与预览方法调用关联的资源还包含在调用中作为只读字段使用的 previewVersion
,以帮助您了解自己使用的是哪个版本。例如,上一个 CREATE 调用的响应包含 V1_20231110_PREVIEW
值:
print(json.dumps(rubric, indent=4))
{
"courseId": "123",
"courseWorkId": "456",
"creationTime": "2023-10-23T18:18:29.932Z",
"updateTime": "2023-10-23T18:18:29.932Z",
"id": "789",
"criteria": [...],
# The preview version used in the call that returned this resource.
"previewVersion": "V1_20231110_PREVIEW",
...
}
HTTP 请求
您还可以直接通过 HTTP 使用 Classroom API。
如果您在没有客户端库的情况下发出 HTTP 请求,则仍需启用指定预览版本的预览功能。为此,您需要将带有 X-Goog-Visibilities
标头和前述预览版本的 label
设置为查询参数或 POST 正文字段。对于公开预览版,该标签为 DEVELOPER_PREVIEW
。
例如,以下 curl 请求会使用相应的可见性标签和预览版本对评分准则服务进行 LIST 调用:
curl \
'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID/rubrics?key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
--header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Accept: application/json' \
--compressed
您还可以在请求正文中指定预览版本,例如在发出 POST 请求时:
curl --request PATCH \
'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
--compressed
REST 文档中介绍了每个 HTTP 请求的 API。