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

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

存取預覽 API

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

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

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

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

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

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

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

動態程式庫

語言等語言的程式庫會使用探索服務中的探索文件，在執行階段產生用戶端程式庫。

探索文件是一種機器可讀取的規格，用於說明及使用 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 服務執行個體化，您可以使用適當的服務、憑證和標籤來指定 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 用戶端程式庫說明文件。

靜態資料庫

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，請在 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 欄位。舉例來說，如要使用 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 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);
}