Cara kerja permintaan

Halaman ini menjelaskan ringkasan tingkat tinggi 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 tugas kelas.

Desain berorientasi resource

Seperti yang disebutkan dalam referensi 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 dan penting dari resource terkait 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, id Course 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 dibuat server, seperti id atau creationTime resource.

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 pada resource yang akan diperbarui. Kolom ini bersifat opsional jika ada kumpulan kolom default atau kolom disimpulkan.

Tips: Anda mungkin melihat metode update() bersama dengan metode patch(). Meskipun keduanya memodifikasi resource, keduanya berbeda dalam perilaku. Update() sepenuhnya menggantikan resource dengan yang baru, sedangkan patch() hanya memperbarui kolom tertentu. Misalnya, courses.update() menggantikan seluruh Course yang ada, sedangkan courses.patch() menggunakan fieldMask yang disebutkan di atas untuk mengubah hanya kolom tertentu dalam Course. Untuk mempermudah, 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 telah selesai.

Mendapatkan dan mencantumkan

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() mengembalikan resource lengkap secara langsung.

Metode list() mengambil beberapa resource dengan jenis yang sama dalam satu permintaan, tanpa memerlukan ID resource individual. Operasi list() sering kali mendapatkan semua sub-resource 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 jumlah maksimum resource yang dapat ditampilkan dalam satu panggilan, dan batas bawah 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 batch 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 tugas resource CourseWork. Dalam kasus ini, metode kustom tersedia, seperti metode modifyAssignees. Perilaku metode ini bersifat khusus dan Anda harus membaca dokumentasinya satu per satu.