Cara kerja permintaan

Halaman ini menjelaskan ringkasan umum tentang cara kerja permintaan di Google Classroom API. Tujuannya adalah untuk membantu pembaca yang belum memahami desain berorientasi resource atau Google Workspace API.

Untuk contoh kode tertentu, lihat panduan API yang sesuai, misalnya Membuat & mengelola kursus atau Membuat & mengelola materi kursus.

Desain yang berorientasi pada resource

Seperti yang disebutkan dalam struktur API, Classroom API mengikuti pola desain berorientasi resource. Sebagian besar resource memiliki metode untuk operasi standar seperti membuat, membaca, memperbarui, dan menghapus instance resource.

Misalnya, Anda dapat create(), patch(), get(), list(), dan delete() Course Classroom menggunakan API.

Buat

Untuk membuat resource baru, seperti Course, panggil metode create() untuk resource yang sesuai.

Panggilan Create() selalu memerlukan detail awal yang penting dari resource yang sesuai sebagai input. Misalnya, untuk membuat Course, panggil metode create() pada resource Course dan tentukan name dan description dalam permintaan, beserta informasi opsional seperti room.

Untuk sub-resource (terkadang disebut resource turunan), ID untuk resource induk juga diperlukan. Misalnya, saat membuat CourseWork dalam Course, Course id diperlukan untuk menentukan Course tempat CourseWork berada.

Metode Create() menampilkan instance resource yang baru dibuat dalam respons panggilan API. Resource yang ditampilkan biasanya memiliki kolom tambahan yang dihasilkan server, seperti resource id atau creationTime.

Patch

Untuk mengubah resource yang ada, panggil metode patch() (yang terkadang disebut update()) pada resource yang sesuai. Metode patch() hampir identik dengan create(), dengan dua perbedaan utama; saat memanggil metode patch(), Anda harus menentukan:

1. id resource yang akan diubah.
2. Daftar kolom, yang disebut updateMask, untuk menentukan kolom mana di resource yang akan diperbarui. Hal ini bersifat opsional jika ada kumpulan kolom default atau kolom disimpulkan.

Tips: Anda mungkin melihat metode update() bersama metode patch(). Meskipun keduanya mengubah resource, keduanya memiliki perilaku yang berbeda. Update() sepenuhnya mengganti resource dengan resource baru, sedangkan patch() hanya memperbarui kolom tertentu. Misalnya, courses.update() mengganti seluruh Course yang ada, sedangkan courses.patch() menggunakan fieldMask yang disebutkan di atas untuk hanya mengubah kolom tertentu di Course. Untuk memudahkan, Google Classroom API hampir secara eksklusif menggunakan patch(), dan sebaiknya Anda menggunakan metode tersebut secara umum.

Metode Patch() menampilkan instance lengkap resource yang diperbarui dalam respons panggilan API, dengan semua perubahan selesai.

Mendapatkan dan membuat daftar

Ada dua metode untuk mengambil resource: get() dan list().

Metode get() mengambil resource tertentu berdasarkan beberapa ID. Misalnya, mengambil Course berdasarkan id atau alias. Panggilan get() akan menampilkan resource lengkap secara langsung.

Metode list() mengambil beberapa resource dari jenis yang sama dalam satu permintaan, tanpa memerlukan ID resource satu per satu. Sering kali, operasi list() mendapatkan semua subresource dari beberapa resource induk, misalnya, mengambil semua CourseWork dalam Course. Hal ini berguna untuk meminimalkan permintaan, dibandingkan dengan melakukan beberapa panggilan get(), dan sangat berharga jika Anda tidak mengetahui id resource yang Anda inginkan.

Umumnya, metode list() memiliki beberapa jumlah maksimum resource yang dapat ditampilkan dalam satu panggilan, dan batas yang lebih rendah dapat dikonfigurasi dengan menyertakan nilai pageSize dengan panggilan. Jika ada lebih banyak resource daripada batas, metode list() mendukung penomoran halaman; setiap "halaman" hasil yang ditampilkan memberikan pageToken, yang dapat disertakan dalam panggilan list() berikutnya untuk mengambil kumpulan resource berikutnya.

Hapus

Metode delete() menerima ID resource, seperti id, dan menghapus resource yang sesuai. Jika delete() berhasil, respons kosong akan ditampilkan.

Operasi lainnya

Tidak semua operasi yang dapat dilakukan dengan Classroom API dapat dicapai dengan operasi standar yang disebutkan di atas, misalnya, mengubah penerima resource CourseWork. Dalam hal ini, metode kustom tersedia, seperti metode modifyAssignees. Perilaku metode ini dibuat khusus dan Anda harus membaca dokumentasi untuk masing-masing metode.