存取預覽 API

本頁面將說明如何使用 Classroom API 預先發布版功能，以及指定預覽版本。

使用預先發布版功能時，兩方面的注意事項會進行比較第 1 版 API 的特色如下：

搶先體驗或預先發布版程式的 API 功能並未在標準用戶端程式庫，且可能預設無法透過 HTTP 存取。
隨時都可能有多個 API 狀態預覽。

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

Classroom API 經常是透過用戶端程式庫使用。有用戶端程式庫有三種類型

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

使用動態產生或 Google 提供的靜態資料庫我們會建議他們如何使用 API如需瞭解如何建構用戶端程式庫，請參閱建構用戶端程式庫自行建立程式庫建立自己的程式庫並不在這個範圍內指南，但建議您參閱「動態程式庫」一節來瞭解預覽標籤及其在探索工具中的角色

動態程式庫

使用 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 程式庫並使用預覽方法時，您可以使用適合的服務指定 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 用戶端程式庫說明文件，瞭解各個 API 詳情語言。

靜態程式庫

必須建構 Java、Node.js、PHP、C# 和 Go 等程式語言的用戶端程式庫我們為您提供這些程式庫，且提供預先發布版功能。

如果是公開預覽，則可透過另一種方式找到 Classroom 用戶端程式庫 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 欄位。舉例來說，如要使用評分量表 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 主體欄位 (請參閱參考文件)。在公開預覽中，標籤為 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。