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 Google Classroom API. Mục tiêu là hỗ trợ những độc giả chưa quen với thiết kế hướng tài nguyên hoặc API Google Workspace.
Để xem các mẫu mã cụ thể, hãy xem hướng dẫn tương ứng về API, ví dụ: Tạo và quản lý khoá học hoặc Tạo và quản lý bài tập.
Thiết kế hướng đến tài nguyên
Như đã đề cập trong phần Tài nguyên 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 Course Lớp học 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.
Các lệnh gọi Create() luôn yêu cầu thông tin 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 các tài nguyên phụ (đôi khi được gọi là tài nguyên con), bạn cũng phải có mã nhận dạng cho tài nguyên mẹ. Ví dụ: khi tạo CourseWork trong Course, bạn cần có id Course để xác định CourseWork thuộc về Course nào.
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 của lệnh gọi API. Tài nguyên được trả về thường có mọi trường bổ sung do máy chủ tạo, chẳng hạn như id hoặc creationTime của tài nguyên.
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(), chỉ có 2 đ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.- Một danh sách các trường (gọi là
updateMask) để xác định những trường cần cập nhật trên tài nguyên. Đây là trường không bắt buộc trong trường hợp có một bộ trường mặc định hoặc các trường được suy luận.
Các phương thức Patch() trả về toàn bộ phiên bản 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.
Nhận 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 giá trị nhận dạng nào đó. Ví dụ: tìm nạp một Course dựa trên id hoặc alias. Lệnh gọi get() sẽ trả về toàn bộ tài nguyên ngay lập tức.
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 duy nhất mà không cần mã nhận dạng tài nguyên riêng lẻ. Thường thì thao tác list() sẽ lấy tất cả cá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 một Course. Điều này hữu ích cho việc 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 các tài nguyên mà bạn muốn.
Thông thường, 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 duy nhất và bạn có thể định cấu hình các giới hạn thấp hơn bằng cách đưa 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ợ phân trang; mỗi "trang" kết quả được trả về sẽ cung cấp một pageToken. Bạn có thể đưa pageToken vào một 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 một giá trị nhận dạng tài nguyên, chẳng hạn như id, rồi xoá tài nguyên tương ứng. Nếu delete() thành công, một phản hồi trống sẽ được trả về.
Toán tử khác
Bạn không thể thực hiện tất cả các thao tác có thể thực hiện bằng API Lớp học bằng các thao tác tiêu chuẩn nêu trên, chẳng hạn như sửa đổi người được giao 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à riêng biệt và bạn nên tham khảo tài liệu cho từng phương thức.