访问预览版 API

本页面介绍了如何使用 Classroom API 预览版功能和指定预览版本。

与稳定版相比，使用预览版功能时的两个注意事项 v1 API 具有如下特点：

抢先体验计划或预览版计划中的 API 功能不会在标准客户端库，默认情况下可能无法通过 HTTP 访问。
在任意给定时间，预览。

在客户端库中启用预览功能

使用 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 等语言的客户端库。这些库是为您提供的，并且具有预览版功能已经纳入。

对于公开预览版，Google 课堂客户端库可以 Workspace 开发者预览版计划客户端库。对于非公开预览版如果您需要生成的静态库，请与您的 Google 联系人联系。

您可能需要修改典型的依赖项配置才能使用这些与导入标准客户端库相比提供预览版功能

例如，若要使用 Go 客户端库，您需要使用 replace 指令添加到 go.mod 文件中，以需要本地目录中的模块：

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 字段来指定版本。例如，要使用 Rubrics CRUD 预览 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 请求，您仍然需要启用预览功能指定一个预览版本。方法是设置一个 label 具有 X-Goog-Visibilities 标头和上述预览版，作为查询参数或 POST 正文字段（请参阅相应的 API 参考文档）。对于公开预览版，此标签是 DEVELOPER_PREVIEW。

例如，以下 curl 请求对评分准则服务进行 LIST 调用具有适当的可见性标签和预览版本：

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_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_WORK_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]"}' \
  --compressed

REST 文档中介绍了每个 HTTP 请求的 API。