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

此页面由 Cloud Translation API 翻译。

访问预览版 API

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

与稳定版 v1 API 相比，使用预览版功能时有以下三个注意事项：

发起调用的 Google Cloud 项目必须已注册 Google Workspace 开发者预览版计划，并允许 Google 列出。
抢先体验或预览版计划中的 API 功能未在标准客户端库中公开，并且默认情况下可能无法通过 HTTP 访问。
在任何给定时间，预览版中都可能有多个 API 状态或版本。

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

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

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

建议您使用动态生成的库或 Google 提供的静态库来使用此 API。如果您需要构建自己的库，请参阅构建客户端库。本指南不涉及创建自定义库，但您应查看动态库部分，了解预览标签及其在发现广告中的用途。

动态库

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

发现文档是用于描述和使用 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 调用时，都必须指定预览版。

Google 课堂 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。

Google Apps 脚本

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

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

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

更改脚本使用的 Cloud 项目

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

配置 HTTP 请求

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

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 Script 中直接向 Google API 发出 HTTP 调用，您需要手动添加适当的范围。

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

更新后的 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);
}