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.
Sau đây là 2 đ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 phiên bản 1 ổn định:
- Các tính năng API trong chương trình truy cập sớm hoặc chương trình xem trước không xuất hiện trong thư viện ứng dụng tiêu chuẩn 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 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ó ba 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 được tạo động hoặc thư viện tĩnh do Google cung cấp. Xem bài viết tạo thư viện ứng dụng nếu bạn cần xây dựng thư viện của riêng mình. Việc tạo thư viện riêng nằm ngoài phạm vi của hướng dẫn này, nhưng bạn nên xem phần thư viện động để tìm hiểu về các nhãn xem trước và vai trò của các nhãn đó trong mục 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á trong 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. Thư viện 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 các 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 các Tài liệu khám phá dành 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
Một đ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 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 các phương thức xem trước, bạn có thể chỉ định URL của 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ừng tài liệu về thư viện ứng dụng của Google API để 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 sẵn các tính năng của bản xem trước.
Đối với các bản xem trước công khai, bạn có thể tìm thấy thư viện ứng dụng của Lớp học bằng 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 các bản xem trước 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ể cần sửa đổi cấu hình phần phụ thuộc thông thường của mình để 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 thực thể cho dịch vụ classroom qua 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 đề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 đó đều được ghi lại trong Lộ trình API Lớp học. Tài liệu tham khảo cho phương thức và trường cũng mô tả(các) phiên bản phương thức hoặc trường có sẵn.
Việc chỉ định phiên bản được thực hiện bằng cách đặt trường PreviewVersion vào các yêu cầu.
Ví dụ: để tạo tiêu chí chấm điểm bằng API xem trước CRUD tiêu chí chấm điểm, bạn cần đặ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, để giúp bạn hiểu 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 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 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 nêu trên dưới dạng tham số truy vấn hoặc trường nội dung POST. Đố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 một lệnh gọi LIST đến dịch vụ Tiêu chí chấm điểm với 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_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ụ như khi đưa ra yêu cầu POST:
curl --request PATCH \
'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID//rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
--compressed
API cho mỗi yêu cầu HTTP được mô tả trong tài liệu REST.