存取預覽 API

本頁面說明如何存取 Classroom API 預覽功能及指定預覽版本。

與穩定版 v1 API 相比，使用預覽功能時的兩大考量包括：

搶先體驗或預覽程式中的 API 功能不會顯示在標準用戶端程式庫中，而且根據預設可能無法透過 HTTP 存取。
在任何時間點，可能會有多個 API 狀態 (或預先發布版)。

啟用用戶端程式庫的預覽功能

使用 Classroom API 的常見做法是透過用戶端程式庫。用戶端程式庫分為三種類型：

動態產生的用戶端程式庫
Google 提供的靜態用戶端程式庫
您的自訂用戶端程式庫

建議您使用動態產生或 Google 提供的靜態程式庫。如需自行建構程式庫，請參閱建構用戶端程式庫一文。建立自己的程式庫並不在本指南的範圍內，但建議您參閱動態程式庫一節，瞭解預覽標籤及其在「探索」中的角色。

動態程式庫

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 服務例項化，您可以使用適當的服務、憑證和標籤來指定探索網址：

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，請在 package.json 中新增 Node.js 用戶端程式庫下載 (googleapis-classroom-1.0.4.tgz) 做為本機依附元件：

{
  "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 預覽 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

如需每個 HTTP 要求的 API 說明，請參閱 REST 說明文件。