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

此页面由 Cloud Translation API 翻译。

访问预览版 API

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

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

发起调用的 Google Cloud 项目必须在 Google Workspace 中注册开发者预览版计划并允许被 Google 列入。
抢先体验计划或预览版计划中的 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。

Google Apps 脚本

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

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

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

更改脚本使用的 Cloud 项目

在项目设置中，点击更改项目，然后输入您在 Developer 中注册的任何项目的 Cloud 项目 ID 预览计划（默认情况下， Apps 脚本使用通用项目）。仅已注册项目可以调用预览方法。

配置 HTTP 请求

接下来，配置您希望在其中回调的任意方法的 HTTP 请求 编辑者。例如，在快速入门中列出包含 Google 课堂的课程 Service 如下所示：

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 部分中的说明。对评分准则服务将如下所示：

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);
}