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 các tính năng xem trước của API Lớp học và chỉ định các phiên bản xem trước.

Có 3 điều 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 gọi trên Google Cloud phải được đăng ký tham gia Chương trình dùng thử cho nhà phát triển của Google Workspace và được Google cho phép đăng lên danh sách.
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 thư viện ứng dụng khách chuẩn và có thể không truy cập được theo mặc định qua HTTP.
Tại bất kỳ thời điểm nào, 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 cách phổ biến để sử dụng API Lớp học là dùng 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 thư viện tĩnh do Google cung cấp hoặc được tạo một cách linh động để sử 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 xem trước trong chiến dịch Khám phá.

Thư viện động

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

Tài liệu khám phá là một thông số kỹ thuật mà máy có thể đọc được để mô tả và sử dụng các API REST. Công cụ này dùng để xây dựng 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 API xem trước là chỉ định label thích hợp. Đối với bản xem trước công khai trên Lớp học, nhãn đó là DEVELOPER_PREVIEW.

Để tạo thư viện Python và tạo thực thể cho 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 của tài liệu Khám phá bằng dịch vụ, thông tin xác thực 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)'

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

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 xem trước 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 trong Chương trình xem trước dành 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 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 chuẩn (không 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 lệnh 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 tệp 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, 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 bản sao 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 động, bạn đều phải chỉ định phiên bản xem trước khi thực hiện lệnh gọi API đến các phương thức có khả năng xem trước.

Các phiên bản hiện có và tính năng của các phiên bản đó được ghi lại trong Bản đồ đường đi của API Lớp học. Tài liệu tham khảo về các phương thức và trường cũng mô tả(các) phiên bản của phương thức hoặc trường đó.

Bạn có thể chỉ định một phiên bản bằng cách đặt trường PreviewVersion trong yêu cầu. Ví dụ: để tạo một tiêu chí chấm điểm bằng API xem trước CRUD của tiêu chí chấm điểm, 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 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ạng trường chỉ đọc, để giúp bạn biết mình đang sử dụng phiên bản nào. 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 tạo 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 để chỉ định phiên bản xem trước. Bạn có thể thực hiện việc này bằng cách đặt label với tiêu đề X-Goog-Visibilities và phiên bản xem trước được đề cập ở 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 xem trước 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 với nhãn chế độ 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 tạo 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 mỗi yêu cầu HTTP được mô tả trong tài liệu về 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 vài đ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 Google Cloud nào mà bạn đã đăng ký trong Chương trình xem trước 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 cần gửi 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ước đó.

Hãy xem phầ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 API xem trước:

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

Trong phần Cài đặt dự án, hãy nhấp vào Thay đổi dự án rồi nhập mã dự án trên Google Cloud của bất kỳ dự án nào bạn đã đăng ký tham gia Chương trình dùng thử 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ỉ các 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 tính năng bắt đầu nhanh, hãy liệt kê các khoá học có dịch vụ Lớp học 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 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 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 phần Project Settings (Cài đặt dự án), hãy bật tuỳ chọn Show "appsscript.json" manifest file in editor (Hiển thị tệp kê khai "appsscript.json" trong trình chỉnh sửa). Quay lại Trình chỉnh sửa, hãy thêm oauthScopes vào tệp appscript.json cho bất kỳ phạm vi nào bạn cần. Phạm vi của một phương thức nhất định được liệt kê trong trang tham khảo. 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ể có dạ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

Quay lại tập lệnh của bạn, 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 đó. Lệnh gọi LIST mẫu đế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);
}