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 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 Google Cloud gọi phải được đăng ký tham gia Chương trình xem 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 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 lựa chọn phổ biến để sử dụng API Lớp học là thông qua 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 động để sử dụng API. 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 trong 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 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ố 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 bản sao 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 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)'
Hãy xem tài liệu về thư viện ứng dụng của từng API của 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 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 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 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 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
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 cho các phương thức và trường cũng mô tả(các) phiên bản có phương thức hoặc trường đó.
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 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ưới dạng trường chỉ có thể đọc để giúp bạn hiểu phiên bản bạn đang sử 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 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 thực hiện 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 các API xem trước:
Thay đổi dự án trên Google Cloud mà tập lệnh sử dụng
Trong phần 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 trên Google Cloud của dự án mà bạn đã đăng ký tham gia Chương trình xem 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ỉ 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 phần bắt đầu nhanh, 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 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, 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);
}