Hiện tại, các nhà phát triển đã có thể sử dụng rộng rãi tiện ích bổ sung của Google Lớp học! Vui lòng xem tài liệu về tiện ích bổ sung để biết thêm thông tin.

Trang này được dịch bởi Cloud Translation API.

Truy cập API xem trước

Trang này mô tả cách bạn có thể truy cập vào các tính năng dùng thử của Classroom API và chỉ định phiên bản dùng thử.

Có 3 điểm cần cân nhắc khi sử dụng các tính năng xem trước so với API v1 ổn định:

Dự án Google Cloud gọi phải được đăng ký trong Chương trình dùng thử trước dành cho nhà phát triển của Google Workspace và được Google đưa vào danh sách cho phép.
Các tính năng API trong chương trình tiếp cận sớm hoặc chương trình dùng thử không được hiển thị trong các thư viện ứng dụng chuẩn và theo mặc định, có thể không truy cập được qua HTTP.
Tại một thời điểm bất kỳ, có thể có nhiều trạng thái hoặc phiên bản API ở chế độ xem trước.

Bật các tính năng xem trước trong thư viện ứng dụng

Một lựa chọn phổ biến để sử dụng Classroom API là thông qua một thư viện ứng dụng. Có 3 loại thư viện ứng dụng:

Thư viện ứng dụng được tạo động
Thư viện ứng dụng tĩnh do Google cung cấp
Thư viện ứng dụng tuỳ chỉnh của riêng bạn

Bạn nên sử dụng các thư viện tĩnh do Google cung cấp hoặc được tạo động để dùng API này. Hãy xem phần tạo thư viện ứng dụng nếu bạn cần tạo thư viện của riêng mình. Việc tạo thư viện của riêng bạn nằm ngoài phạm vi của hướng dẫn này, nhưng bạn nên xem lại phần thư viện động để tìm hiểu về nhãn xem trước và vai trò của nhãn trong Khám phá.

Thư viện động

Các thư viện bằng những ngôn ngữ như Python sẽ tạo thư viện ứng dụng trong thời gian chạy bằng cách sử dụng Tài liệu khám phá từ Dịch vụ khám phá.

Tài liệu khám phá là một quy cách mà máy có thể đọc được để mô tả và sử dụng các API REST. Công cụ này được dùng để tạo thư viện ứng dụng, trình bổ trợ IDE và các công cụ khác tương tác với API của Google. Một dịch vụ có thể cung cấp nhiều tài liệu khám phá.

Bạn có thể tìm thấy Tài liệu khám phá cho dịch vụ API Lớp học (classroom.googleapis.com) tại điểm cuối sau:

https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY

Điểm khác biệt quan trọng khi làm việc với các API xem trước là chỉ định label thích hợp. Đối với bản dùng thử công khai của Lớp học, nhãn này là DEVELOPER_PREVIEW.

Để tạo thư viện Python và khởi tạo dịch vụ Lớp học bằng các phương thức xem trước, bạn có thể chỉ định URL Khám phá bằng dịch vụ, thông tin đăng nhập và nhãn thích hợp:

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)'

Hãy xem tài liệu về thư viện ứng dụng API của Google cho từng ngôn ngữ để biết thông tin chi tiết.

Thư viện tĩnh

Bạn phải tạo thư viện ứng dụng bằng các ngôn ngữ như Java, Node.js, PHP, C# và Go từ nguồn. Các thư viện này được cung cấp cho bạn và đã tích hợp các tính năng xem trước.

Đối với bản dùng thử công khai, bạn có thể tìm thấy các thư viện ứng dụng Lớp học cùng với các thư viện ứng dụng khác của Chương trình dùng thử cho nhà phát triển Workspace. Đối với bản xem trước riêng tư, hãy liên hệ với đầu mối liên hệ của bạn tại Google nếu bạn cần tạo thư viện tĩnh.

Bạn có thể cần sửa đổi cấu hình phần phụ thuộc thông thường để sử dụng các thư viện cục bộ này thay vì nhập các thư viện ứng dụng tiêu chuẩn không có các tính năng xem trước.

Ví dụ: để sử dụng thư viện ứng dụng Go, bạn cần sử dụng chỉ thị replace trong tệp go.mod để yêu cầu một mô-đun từ thư mục cục bộ:

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

Một ví dụ khác: nếu bạn đang sử dụng Node.js và npm, hãy thêm bản tải xuống thư viện ứng dụng Node.js (googleapis-classroom-1.0.4.tgz) làm phần phụ thuộc cục bộ trong 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"
  }
}

Sau đó, trong ứng dụng của bạn, hãy yêu cầu mô-đun classroom-with-preview-features ngoài các phần phụ thuộc thông thường và tạo thực thể dịch vụ classroom từ mô-đun đó:

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,
});

...

Chỉ định phiên bản API xem trước

Bất kể bạn sử dụng thư viện tĩnh hay thư viện động, bạn đều phải chỉ định phiên bản xem trước khi thực hiện các lệnh gọi API đến các phương thức có chức năng xem trước.

Các phiên bản hiện có và các tính năng mà chúng bao gồm được ghi lại trong Lộ trình phát triển API Lớp học. Tài liệu tham khảo cho các phương thức và trường cũng mô tả(các) phiên bản mà phương thức hoặc trường có sẵn.

Bạn có thể chỉ định phiên bản bằng cách đặt trường PreviewVersion trong các yêu cầu. Ví dụ: để tạo một tiêu chí chấm điểm bằng Rubrics CRUD preview API, bạn sẽ đặt previewVersion thành V1_20231110_PREVIEW trong yêu cầu CREATE:

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()

Các tài nguyên liên kết với một lệnh gọi phương thức xem trước cũng chứa previewVersion được dùng trong lệnh gọi dưới dạng một trường chỉ đọc, để giúp bạn hiểu rõ phiên bản mà bạn đang dùng. Ví dụ: phản hồi từ lệnh gọi CREATE trước đó chứa giá trị 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",
  ...
}

Yêu cầu HTTP

Bạn cũng có thể sử dụng trực tiếp API Lớp học bằng HTTP.

Nếu thực hiện các yêu cầu HTTP mà không có thư viện ứng dụng, bạn vẫn cần bật các tính năng xem trước và chỉ định phiên bản xem trước. Việc này được thực hiện bằng cách đặt label bằng tiêu đề X-Goog-Visibilities và phiên bản xem trước nêu trên làm tham số truy vấn hoặc trường nội dung POST (xem tài liệu tham khảo API riêng lẻ thích hợp). Đối với bản dùng thử công khai, nhãn là DEVELOPER_PREVIEW.

Ví dụ: yêu cầu curl sau đây thực hiện lệnh gọi LIST đến dịch vụ Rubrics (Phiếu chấm điểm) bằng nhãn hiển thị và phiên bản xem trước thích hợp:

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

Bạn cũng có thể chỉ định phiên bản xem trước trong nội dung yêu cầu, ví dụ: khi đưa ra yêu cầu 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

API cho từng yêu cầu HTTP được mô tả trong tài liệu REST.

Google Apps Script

Bạn có thể gọi các API xem trước từ Google Apps Script. Tuy nhiên, có một số điểm khác biệt so với cách sử dụng Apps Script thông thường.

Bạn phải định cấu hình tập lệnh để sử dụng bất kỳ dự án nào trên Google Cloud mà bạn đã đăng ký trong Chương trình dùng thử dành cho nhà phát triển.
Dịch vụ nâng cao không hỗ trợ các phương thức xem trước, vì vậy, bạn sẽ cần đưa ra yêu cầu trực tiếp bằng HTTP.
Bạn phải cung cấp nhãn và phiên bản xem trước, như mô tả trong phần HTTP ở trên.

Hãy xem hướng dẫn bắt đầu nhanh tương ứng để làm quen với Apps Script và thiết lập một dự án cơ bản. Sau đó, hãy làm theo các hướng dẫn sau để bắt đầu gọi các API xem trước:

Thay đổi dự án trên Cloud mà tập lệnh sử dụng

Trong Project Settings (Cài đặt dự án), hãy nhấp vào Change project (Thay đổi dự án) rồi nhập mã dự án Cloud của dự án mà bạn đã đăng ký tham gia Chương trình dùng thử trước dành cho nhà phát triển (theo mặc định, các tập lệnh Apps Script sử dụng một dự án chung). Chỉ những dự án đã đăng ký mới có thể gọi các phương thức xem trước.

Định cấu hình yêu cầu HTTP

Tiếp theo, hãy định cấu hình yêu cầu HTTP của bất kỳ phương thức nào mà bạn muốn gọi lại trong Trình chỉnh sửa. Ví dụ: trong quickstart, việc liệt kê các khoá học bằng dịch vụ Lớp học sẽ có dạng như sau:

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);
  }
}

Thao tác tương đương khi sử dụng trực tiếp HTTP là:

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);
  }
}

Khi sử dụng Dịch vụ nâng cao, các phạm vi OAuth bắt buộc sẽ được suy luận, nhưng để thực hiện các lệnh gọi HTTP trực tiếp đến các API của Google trong Apps Script, bạn cần thêm các phạm vi thích hợp theo cách thủ công.

Trong Project Settings (Cài đặt dự án), hãy bật Show "appsscript.json" manifest file in editor (Hiện tệp kê khai "appsscript.json" trong trình chỉnh sửa). Trong Editor, hãy thêm oauthScopes vào tệp appscript.json cho bất kỳ phạm vi nào bạn cần. Các phạm vi cho một phương thức nhất định được liệt kê trong trang tham chiếu. Ví dụ: hãy xem trang phương thức danh sách courses.courseWork.rubrics.

Tệp appscript.json mới cập nhật có thể trông như sau:

{
  "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"
  ]
}

Cung cấp nhãn và phiên bản xem trước

Trong tập lệnh, hãy đảm bảo bạn đã thêm nhãn và phiên bản xem trước thích hợp như mô tả trong phần HTTP trước đó. Ví dụ về lệnh gọi LIST đến dịch vụ Rubrics sẽ có dạng như sau:

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);
}