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

Ba điều cần cân nhắc khi sử dụng tính năng xem trước so với phiên bản ổn định API phiên bản 1 bao gồm:

Bạn phải đăng ký gói Google Workspace trong dự án gọi điện trên Google Cloud Chương trình dùng thử cho nhà phát triển và cho phép được Google liệt kê.
Các tính năng API trong chương trình tiếp cận sớm hoặc chương trình xem trước không được cung cấp trong và có thể không truy cập được theo mặc định 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 trong bản xem trước.

Bật 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ó 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

Việc sử dụng thư viện tĩnh do Google cung cấp hoặc được tạo một cách linh động bạn nên sử dụng API này. Xem bài viết xây dựng thư viện ứng dụng nếu bạn cần tạo thư viện của riêng bạn. Việc tạo thư viện của riêng bạn nằm ngoài phạm vi của chính sách này mà bạn nên xem xét phần thư viện động để tìm hiểu về bản xem trước nhãn và vai trò của chúng 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 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 thông số mà máy có thể đọc được để mô tả và sử dụng API REST. Thư viện 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á.

Tài liệu khám phá cho dịch vụ API Lớp học (classroom.googleapis.com) có thể được tìm thấy 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 các bản xem trước công khai của 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 xem trước, bạn có thể chỉ định Discovery URL bằng dịch vụ thích hợp, thông tin đăng nhập và nhãn:

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 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à có các tính năng xem trước đã được tích hợp.

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

Bạn có thể phải sửa đổi cấu hình của các phần phụ thuộc thông thường để sử dụng thay vì nhập thư viện ứng dụng tiêu chuẩn, vì việc này 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 replace trong tệp go.mod để yêu cầu một mô-đun từ mộ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 ứng dụng Node.js bản tải xuống thư viện (googleapis-classroom-1.0.4.tgz) dưới dạng 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, 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ể cho 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ể sử dụng thư viện tĩnh hay động, bạn 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 khác nhau hiện có và tính năng trong các phiên bản đó đều được ghi lại trong Lộ trình của API Lớp học. Tài liệu tham khảo về các phương thức và các 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 một phiên bản bằng cách đặt trường PreviewVersion trong yêu cầu. Ví dụ: để tạo tiêu chí chấm điểm bằng API xem trước của Tiêu chí chấm điểm CRUD, bạn sẽ đặt previewVersion đến V1_20231110_PREVIEW trong yêu cầu TẠO:

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 cuộc gọi dưới dạng trường chỉ đọc để giúp bạn hiểu phiên bản bạn đang sử dụng. Ví dụ: phản hồi trong nút CREATE trước đó lệnh gọi 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 qua 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 tính năng xem trước chỉ định một phiên bản xem trước. Bạn có thể thực hiện việc này bằng cách đặt một label có tiêu đề X-Goog-Visibilities và phiên bản xem trước nói trên dưới dạng tham số truy vấn hoặc trường nội dung POST (xem API riêng lẻ thích hợp tài liệu tham khảo). Đố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ụ Tiêu chí chấm điểm có 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 phần 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 REST.

Google Apps Script

Có thể gọi API xem trước từ Google Apps Script. Tuy nhiên, có một số một số 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 của mình để dùng bất kỳ dự án nào trên Google Cloud mà bạn đã đăng ký tham gia Chương trình Bản dùng thử 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 thực hiện gửi trực tiếp các yêu cầu bằng HTTP.
Bạn phải cung cấp nhãn và phiên bản xem trước, như được mô tả trong phần trước Phần HTTP.

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

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

Trong Cài đặt dự án, nhấp vào Thay đổi dự án và nhập Mã dự án trên đám mây của bất kỳ dự án nào bạn đã đăng ký trong tài khoản Nhà phát triển Chương trình dùng thử (theo mặc định, Tập lệnh Apps Script sử dụng một dự án chung). Chỉ đã đăng ký có thể gọi 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 Người chỉnh sửa. Ví dụ: trong phần bắt đầu nhanh, liệt kê các khoá học thông qua Lớp học dịch vụ 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 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, hệ thống sẽ dự đoán phạm vi OAuth bắt buộc, nhưng thực hiện lệnh gọi HTTP trực tiếp đến API của Google trong Apps Script, bạn cần thêm phạm vi thích hợp theo cách thủ công.

Trong phần Cài đặt dự án, hãy bật tuỳ chọn Hiện "appsscript.json" tệp kê khai trong trình chỉnh sửa. Quay lại Editor (Trình chỉnh sửa), 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ụ: xem phương thức danh sách courses.courseWork.rubrics .

Tệp appscript.json được 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, đảm bảo bạn đã thêm nhãn và bản xem trước thích hợp phiên bản như được mô tả trong phần HTTP trước đó. Ví dụ về lệnh gọi LIST đến dịch vụ Tiêu chí chấm điểm sẽ trông giố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);
}