访问预览版 API

本页介绍了如何使用 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。