Google 课堂插件现已面向开发者正式推出！如需了解详情，请参阅插件文档。

此页面由 Cloud Translation API 翻译。

访问预览版 API

本页介绍了如何访问 Classroom API 预览版功能以及如何指定预览版。

与稳定的 v1 API 相比，使用预览版功能时需要考虑以下三个方面：

调用 Google Cloud 项目必须已加入 Google Workspace Developer Preview Program，并且已获得 Google 的许可。
抢先体验计划或预览版计划中的 API 功能不会显示在标准客户端库中，并且默认情况下可能无法通过 HTTP 访问。
在任何给定时间，可能都有多个 API 状态或版本处于预览状态。

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

使用客户端库是使用 Classroom API 的常见选择。客户端库有三种类型：

动态生成的客户端库
Google 提供的静态客户端库
您自己的自定义客户端库

建议使用动态生成的库或 Google 提供的静态库来使用该 API。如果您需要构建自己的库，请参阅构建客户端库。创建自己的库不在本指南的讨论范围内，但您应查看动态库部分，了解预览标签及其在 Discovery 中的作用。

动态库

Python 等语言的库会在运行时使用来自 Discovery 服务的发现文档生成客户端库。

发现文档是用于描述和使用 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。对于 Classroom 公开预览版，相应标签为 DEVELOPER_PREVIEW。

如需生成 Python 库并使用预览版方法实例化 Classroom 服务，您可以指定包含相应服务、凭据和标签的 Discovery 网址：

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 开发者预览版计划客户端库中找到 Classroom 客户端库。对于私密预览版，如果您需要生成静态库，请与您的 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 字段来指定版本。例如，如需使用 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 请求会向 Rubrics 服务发出 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

每项 HTTP 请求的 API 都在 REST 文档中进行了说明。

Google Apps 脚本

可以从 Google Apps 脚本调用预览版 API。不过，与典型的 Apps 脚本用法相比，存在一些差异。

您必须将脚本配置为使用您注册开发者预览版计划时所用的 Google Cloud 项目。
高级服务不支持预览方法，因此您需要直接使用 HTTP 发出请求。
您必须提供标签和预览版，如上文的 HTTP 部分中所述。

请参阅相应的快速入门，熟悉 Apps 脚本并设置基本项目。然后，按照以下说明开始调用预览版 API：

更改脚本使用的 Cloud 项目

在项目设置中，点击更改项目，然后输入您加入开发者预览计划的项目的 Cloud 项目 ID（默认情况下，Apps 脚本使用通用项目）。只有已加入该计划的项目才能调用预览版方法。

配置 HTTP 请求

接下来，在编辑器中配置您想要回调的方法的 HTTP 请求。例如，在快速入门中，列出 Classroom 服务中的课程如下所示：

function listCourses() {
  try {
    const response = Classroom.Courses.list();
    const courses = response.courses;
    if (!courses || courses.length === 0) {
      console.log('No courses found.');
      return;
    }
    for (const course of courses) {
      console.log('%s (%s)', course.name, course.id);
    }
  } catch (err) {
    // TODO: Developer to handle.
    console.log(err.message);
  }
}

直接使用 HTTP 的等效操作是：

function listCourses() {
  const response = UrlFetchApp.fetch(
        'https://classroom.googleapis.com/v1/courses', {
        method: 'GET',
        headers: {'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()},
        contentType: 'application/json',
      });
  const data = JSON.parse(response.getContentText());
  if (data.error) {
    // TODO: Developer to handle.
    console.log(err.message);
    return;
  }
  if (!data.courses || !data.courses.length) {
    console.log('No courses found.');
    return;
  }
  for (const course of data.courses) {
    console.log('%s (%s)', course.name, course.id);
  }
}

使用高级服务时，系统会推断所需的 OAuth 范围，但要在 Apps 脚本中直接对 Google API 进行 HTTP 调用，您需要手动添加相应的范围。

在项目设置中，启用在编辑器中显示“appsscript.json”清单文件。返回编辑器，根据需要将 oauthScopes 添加到 appscript.json 文件中。给定方法的范围列在参考页面中。例如，请参阅 courses.courseWork.rubrics list 方法页面。

更新后的 appscript.json 文件可能如下所示：

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/classroom.coursework.students",
    "https://www.googleapis.com/auth/classroom.courses",
    "https://www.googleapis.com/auth/spreadsheets.readonly",
    "https://www.googleapis.com/auth/spreadsheets"
  ]
}

提供标签和预览版本

返回到脚本中，确保您已添加适当的标签和预览版，如上文的 HTTP 部分中所述。对 Rubrics 服务的 LIST 调用示例如下所示：

function listRubrics() {
  const courseId = COURSE_ID;
  const courseWorkId = COURSE_WORK_ID;
  const response = UrlFetchApp.fetch(
         `https://classroom.googleapis.com/v1/courses/${courseId}/courseWork/${courseWorkId}/rubrics?previewVersion=V1_20231110_PREVIEW`, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer ' + ScriptApp.getOAuthToken(),
          'X-Goog-Visibilities': 'DEVELOPER_PREVIEW'
        },
        contentType: 'application/json',
        muteHttpExceptions: true
      });
  const data = JSON.parse(response.getContentText());
  console.log(data)
  if (data.error) {
    // TODO: Developer to handle.
    console.log(error.message);
    return;
  }
  if (!data.rubrics || !data.rubrics.length) {
    console.log('No rubrics for this coursework!');
    return;
  }
  console.log(data.rubrics);
}