本頁面說明如何存取 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 說明文件。