存取預覽 API

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

使用預先發布版功能的三大注意事項 第 1 版 API 的特色如下：

1. 呼叫的 Google Cloud 專案必須在 Google Workspace 中註冊 開發人員預覽版計畫，並允許在 Google 上架。
2. 搶先體驗或預先發布版程式的 API 功能並未在 標準用戶端程式庫，且可能預設無法透過 HTTP 存取。
3. 隨時都可能有多個 API 狀態 預覽。

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

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

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

使用動態產生或 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。

Google Apps Script

從 Google Apps Script 呼叫預覽 API 是可行的做法。不過 這與一般 Apps Script 使用方式有些許差異

1. 您必須將指令碼設定為使用所需的 Google Cloud 專案 已註冊開發人員預覽版計畫。
2. 進階服務不支援預覽方法，因此您必須 直接傳送要求
3. 您必須提供上述說明的標籤和預覽版本 HTTP 區段。

請參閱相應的快速入門導覽課程，熟悉相關知識。 Apps Script 並取得基本專案設定。接著依照這些 瞭解如何開始呼叫預覽 API：

變更指令碼使用的 Cloud 專案

在「Project Settings」中按一下「Change project」，然後輸入 您在「開發人員」中註冊的任何專案的 Cloud 專案 ID 搶先體驗方案 (預設為 Apps Script 指令碼使用一般專案)。僅限已註冊 專案可以呼叫預覽方法

設定 HTTP 要求

接下來，請為要回呼的任何方法設定 HTTP 要求 編輯者：舉例來說，在快速入門導覽課程中，您可以透過 Classroom 列出課程 服務看起來會像這樣：

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 部分所述。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);
}