Trang này mô tả thông tin tổng quan cấp cao về cách hoạt động của các yêu cầu trong API Google Lớp học. Mục tiêu là hỗ trợ những độc giả chưa quen thuộc với thiết kế hướng tài nguyên hoặc API Google Workspace.
Đối với mã mẫu cụ thể, hãy xem các hướng dẫn về API tương ứng, ví dụ: Tạo và quản lý khoá học hoặc Tạo và quản lý tài liệu môn học.
Thiết kế dựa trên tài nguyên
Như đã đề cập trong phần Cấu trúc API, API Lớp học tuân theo các mẫu thiết kế hướng đến tài nguyên. Hầu hết các tài nguyên đều có các phương thức cho các thao tác tiêu chuẩn như tạo, đọc, cập nhật và xoá các thực thể của tài nguyên.
Ví dụ: bạn có thể create(), patch(), get(), list() và delete() một lớp học Course bằng API.
Tạo
Để tạo một tài nguyên mới, chẳng hạn như Course, hãy gọi phương thức create() cho tài nguyên tương ứng.
Lệnh gọi Create() luôn yêu cầu thông tin chi tiết ban đầu, quan trọng của tài nguyên tương ứng làm dữ liệu đầu vào. Ví dụ: để tạo Course, hãy gọi phương thức create() trên tài nguyên Course và chỉ định name và description trong yêu cầu, cùng với thông tin không bắt buộc như room.
Đối với tài nguyên phụ (đôi khi gọi là tài nguyên con), bạn cũng phải cung cấp giá trị nhận dạng cho tài nguyên mẹ. Ví dụ: khi tạo CourseWork trong Course, bạn cần có Course id để thiết lập Course mà CourseWork thuộc về.
Các phương thức Create() trả về một thực thể của tài nguyên mới tạo trong phản hồi lệnh gọi API. Tài nguyên được trả về thường có bất kỳ trường bổ sung nào do máy chủ tạo, chẳng hạn như tài nguyên id hoặc creationTime.
Bản vá
Để sửa đổi tài nguyên hiện có, hãy gọi phương thức patch() (đôi khi được gọi là update()) trên tài nguyên tương ứng. Phương thức patch() gần giống với create(), với hai điểm khác biệt chính; khi gọi phương thức patch(), bạn phải chỉ định:
idcủa tài nguyên cần sửa đổi.- Danh sách các trường, được gọi là
updateMask, để xác định những trường nào trên tài nguyên cần cập nhật. Đây là tính năng không bắt buộc trong trường hợp có một nhóm trường mặc định hoặc các trường được suy luận.
Các phương thức Patch() trả về phiên bản đầy đủ của tài nguyên đã cập nhật trong phản hồi lệnh gọi API, với tất cả các thay đổi đã hoàn tất.
Lấy và liệt kê
Có hai phương thức để truy xuất tài nguyên: get() và list().
Phương thức get() truy xuất một tài nguyên cụ thể theo một số giá trị nhận dạng. Ví dụ: tìm nạp Course dựa trên id hoặc alias. Lệnh gọi get() sẽ trực tiếp trả về toàn bộ tài nguyên.
Phương thức list() truy xuất nhiều tài nguyên cùng loại trong một yêu cầu mà không cần có giá trị nhận dạng tài nguyên riêng lẻ. Thông thường, thao tác list() sẽ lấy tất cả tài nguyên phụ của một số tài nguyên mẹ, ví dụ: truy xuất tất cả CourseWork trong Course. Điều này rất hữu ích để giảm thiểu các yêu cầu so với việc thực hiện nhiều lệnh gọi get() và đặc biệt có giá trị khi bạn không biết id của tài nguyên mà bạn muốn.
Nhìn chung, các phương thức list() có một số lượng tài nguyên tối đa có thể được trả về trong một lệnh gọi. Ngoài ra, bạn có thể định cấu hình các giới hạn dưới bằng cách thêm giá trị pageSize vào lệnh gọi. Trong trường hợp có nhiều tài nguyên hơn giới hạn, phương thức list() sẽ hỗ trợ tính năng phân trang; mỗi "trang" kết quả được trả về sẽ cung cấp một pageToken mà có thể được đưa vào lệnh gọi list() tiếp theo để tìm nạp lô tài nguyên tiếp theo.
Xoá
Phương thức delete() chấp nhận giá trị nhận dạng tài nguyên, chẳng hạn như id, và xoá tài nguyên tương ứng. Nếu delete() thành công, hệ thống sẽ trả về một phản hồi trống.
Toán tử khác
Không phải thao tác nào cũng có thể thực hiện được bằng API Lớp học thông qua các thao tác tiêu chuẩn nêu trên, ví dụ: sửa đổi người được chỉ định của tài nguyên CourseWork. Trong những trường hợp này, các phương thức tuỳ chỉnh sẽ có sẵn, chẳng hạn như phương thức modifyAssignees. Hành vi của các phương thức này là tuỳ chỉnh và bạn nên tham khảo tài liệu riêng cho từng phương thức.