Google Classroom 外掛程式現已全面開放開發人員使用！詳情請參閱外掛程式說明文件。

本頁面由 Cloud Translation API 翻譯而成。

存取預覽 API

本頁面說明如何存取 Classroom API 的預先發布版功能，以及如何指定預先發布版。

與穩定版 v1 API 相比，使用預先發布版功能時，有三個需要考量的事項：

呼叫的 Google Cloud 專案必須註冊 Google Workspace 開發人員預覽計畫，並列入 Google 的許可清單。
搶先體驗或搶先體驗方案中的 API 功能不會在標準用戶端程式庫中公開，且可能無法透過 HTTP 預設存取。
在預覽期間，可能會有多個 API 狀態或版本。

在用戶端程式庫中啟用預先發布版功能

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

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

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

動態程式庫

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。在 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 等語言的用戶端程式庫必須從原始碼建構。這些程式庫已提供給您，並已整合預先發布版功能。

如需查看 Classroom 用戶端程式庫的公開預覽版，請參閱其他 Workspace 開發人員預覽版計畫用戶端程式庫。如需私人預覽功能，如果您需要產生靜態程式庫，請洽詢您的 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，請將 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 要求會向 Rubrics 服務發出 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 用法有些不同。

您必須設定指令碼，以便使用您在開發人員預覽計畫中註冊的 Google Cloud 專案。
進階服務不支援預覽方法，因此您必須直接使用 HTTP 提出要求。
您必須提供標籤和預覽版本，如上文HTTP 專節所述。

請參閱對應的快速入門導覽課程，熟悉 Apps 指令碼並完成基本專案設定。接著，請按照下列操作說明開始呼叫預覽版 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 部分所述，新增適當的標籤和預覽版本。以下是對 Rubrics 服務發出的 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);
}