Add-on Google Classroom kini tersedia secara umum untuk developer. Lihat dokumentasi add-on untuk informasi selengkapnya.

Halaman ini diterjemahkan oleh Cloud Translation API.

Berinteraksi dengan lampiran

Halaman ini membahas detail penerapan untuk membuat lampiran, tindakan yang direkomendasikan saat pengguna membuka lampiran, dan cara menangani kiriman siswa. Perhatikan bahwa Anda mungkin perlu memberikan parameter terkait lampiran saat membuat permintaan ini.

Membuat lampiran

Buat lampiran dengan mengirimkan permintaan CREATE ke endpoint courses.*.addOnAttachments.create yang sesuai. Permintaan Anda harus menyertakan instance AddOnAttachment dalam isi permintaan.

Kolom berikut wajib diisi saat membuat lampiran:

title: nama string lampiran.
teacherViewUri: URI untuk Tampilan Pengajar lampiran.
studentViewUri: URI untuk Tampilan Siswa lampiran.
studentWorkReviewUri: URI bagi pengajar untuk melihat tugas siswa pada lampiran. Kolom ini hanya diperlukan untuk lampiran jenis aktivitas.

Anda dapat menyertakan beberapa kolom opsional berikut:

dueDate dan dueTime jika menentukan kapan lampiran harus diserahkan.
maxPoints: tingkat maksimum untuk lampiran. Harus berupa nilai non-nol jika Anda ingin mendukung pengiriman balik nilai. Hanya berlaku untuk lampiran jenis aktivitas.

Lihat referensi sumber AddOnAttachment untuk mengetahui detail selengkapnya tentang kolom ini.

Memvalidasi kredensial dan peran pengguna

iframe Tampilan Siswa, iframe Peninjauan Tugas Siswa, dan iframe Tampilan Pengajar semuanya dimaksudkan untuk menyajikan konten kepada pengguna, bukan mengubah tugas Classroom. Pertimbangkan untuk melakukan hal berikut saat salah satu tampilan ini terbuka:

Dapatkan kredensial OAuth untuk pengguna.
Buat permintaan courseWork.getAddOnContext, courseWorkMaterials.getAddOnContext, atau announcements.getAddOnContext berdasarkan itemType untuk memvalidasi peran pengguna.
Periksa respons untuk melihat apakah TeacherContext atau StudentContext ada. Hanya satu yang dapat ditampilkan, sesuai dengan peran pengguna dalam kursus.
Jika pengguna saat ini adalah siswa dan itemType adalah courseWork, catat submissionId dari respons dengan tugas siswa. submissionIds cocok di seluruh iframe add-on, dan diperlukan untuk meneruskan kembali nilai dan untuk menampilkan tugas siswa kepada pengajar di alat penilaian.
Jika attachmentId sudah diketahui oleh add-on, tampilkan UI lampiran yang sesuai.
Jika tidak, lampiran ini pasti telah disalin dari item atau kursus stream lain. Lihat panduan Menangani konten yang disalin untuk mendapatkan rekomendasi tentang skenario ini.

Detail kiriman siswa

Alur kerja pengiriman umum mengikuti langkah-langkah berikut:

Siswa meluncurkan studentViewUri untuk menyelesaikan aktivitas.
Add-on mengambil submissionId dari metode getAddOnContext menggunakan kredensial siswa.
submissionId dan attachmentId disimpan oleh developer add-on sebagai ID unik tugas siswa. Jika guru menyalin tugas di Classroom, Anda dapat menggunakan kunci komposit dari kedua parameter ini untuk menampilkan lampiran baru di tugas yang disalin. Lihat halaman kami tentang konten yang disalin untuk mengetahui detail selengkapnya.
Pengajar yang tertarik untuk meninjau tugas siswa meluncurkan studentWorkReviewUri. Permintaan mencakup parameter kueri berikut: courseId, itemId, itemType, attachmentId, dan submissionId.
Developer add-on menggunakan empat ID ini untuk mengambil tugas siswa. Gunakan endpoint courses.courseWork.addOnAttachments.studentSubmissions untuk mengambil atau mengubah informasi tentang kiriman siswa.

Mendeteksi status pengiriman

Kirim permintaan GET ke endpoint courses.courseWork.addOnAttachments.studentSubmissions untuk mendapatkan detail tentang submissionId tertentu. Anda menerima objek AddOnAttachmentStudentSubmission, yang berisi nilai kiriman (pointsEarned) dan status saat ini (postSubmissionState). Status kiriman dapat berupa salah satu nilai berikut:

NEW, jika siswa belum pernah mengakses kiriman.
CREATED, jika siswa telah membuat kiriman tetapi belum mengirimkannya.
TURNED_IN, jika siswa telah mengirimkan tugasnya kepada pengajar.
RETURNED, jika pengajar telah mengembalikan tugas kiriman kepada siswa.
RECLAIMED_BY_STUDENT, jika siswa "belum mengirimkan" tugasnya.

Gunakan endpoint ini untuk mendeteksi status tugas siswa di add-on Anda. Kemudian, Anda dapat menyesuaikan tampilan atau opsi yang diberikan kepada siswa, bergantung pada status yang ditampilkan. Hal ini dapat mencakup fitur seperti:

Menampilkan status penyerahan tugas dalam add-on Anda. Hal ini dapat membantu siswa menghindari potensi kebingungan dan memastikan mereka tidak salah gagal menyerahkan tugas.
Membatasi hak istimewa pengeditan kiriman. Jika tugas memiliki status CREATED atau RECLAIMED_BY_STUDENT, siswa mungkin diizinkan untuk mengedit tugas yang dikirimkan. Jika tugas memiliki status TURNED_IN atau RETURNED, siswa mungkin tidak diizinkan mengedit kiriman mereka.

Nilai dan beberapa lampiran

Hanya satu lampiran add-on yang dapat digunakan untuk menetapkan nilai bagi satu tugas. Jika pengajar membuat lebih dari satu lampiran jenis aktivitas yang memberikan nilai maxPoints, hanya lampiran pertama yang dapat menetapkan nilai tugas. Biarkan nilai maxPoints tidak ditetapkan atau tetapkan ke nol untuk menonaktifkan pengiriman kembali nilai untuk lampiran.

Menetapkan nilai kiriman

Anda dapat mengubah kiriman siswa dengan mengirim permintaan PATCH ke endpoint courses.courseWork.addOnAttachments.studentSubmissions. Isi permintaan harus menyertakan instance AddOnAttachmentStudentSubmission dengan nilai yang diubah. Tetapkan kolom pointsEarned untuk mengubah nilai kiriman. Nilai yang diteruskan dalam pointsEarned menjadi nilai draf yang dapat dilihat oleh pengajar di UI Classroom. Pengajar dapat mengubah draf nilai sebelum mengembalikan tugas kepada siswa. Lihat Ringkasan penilaian di UI Classroom untuk mengetahui detail tentang cara nilai ditampilkan kepada pengajar.

Perhatikan bahwa Anda dapat menetapkan nilai dengan pointsEarned hanya jika hal berikut benar:

Lampiran harus memiliki nilai maxPoints positif.
Add-on harus menjadi kreator asli lampiran.

Perhatikan juga bahwa Anda dapat mengubah nilai maxPoints dari AddOnAttachment yang sudah dibuat dengan mengirimkan permintaan PATCH ke endpoint addOnAttachments.

Kapan harus memberikan nilai

Anda memiliki beberapa pilihan terkait kapan nilai diteruskan kembali ke Google Classroom. Perbedaan pentingnya adalah apakah Anda memilih untuk menyimpan kredensial pengajar, karena hanya pengajar yang dapat mengubah nilai.

Ada dua momen add-on saat Anda dapat meneruskan nilai ke Google Classroom: saat siswa menyelesaikan tugasnya atau saat pengajar membuka tugas siswa di iframe Peninjauan Tugas Siswa.

Jika Anda ingin menetapkan nilai saat siswa menyelesaikan tugas, Anda harus menyimpan kredensial offline pengajar, lalu mengambil dan menggunakannya untuk mengubah nilai saat siswa menyelesaikan tugas. Metode ini memberikan beberapa potensi manfaat:

Memberikan update nilai yang lancar. Pengajar tidak perlu melakukan tindakan khusus apa pun agar nilai muncul di UI Classroom.
Memberikan insight real-time tentang progres kelas dalam menyelesaikan tugas. Dengan menetapkan nilai saat siswa menyelesaikan lampiran, pengajar dapat memahami pemahaman siswa tanpa membuka setiap kiriman.

Perhatikan bahwa pendekatan ini juga memungkinkan pendekatan asinkron untuk sinkronisasi nilai. Anda dapat melakukan polling secara berkala pada endpoint AddOnAttachmentStudentSubmission untuk mendeteksi kapan siswa telah mengirimkan tugasnya. Setelah dikirimkan, tetapkan nilai kiriman menggunakan kredensial yang disimpan.

Jika Anda tidak ingin memuat kredensial pengajar selama sesi siswa, Anda dapat menggunakan kredensial pengajar aktif saat mereka memuat kiriman siswa di iframe Peninjauan Tugas Siswa. Namun, hal ini mungkin tidak memberikan pengalaman pengguna yang lancar karena nilai di UI Classroom tidak diupdate secara real time dan pengajar harus membuka setiap iframe Peninjauan Hasil Kerja Siswa dari kiriman.

Mendeteksi perubahan nilai tugas

Pengajar dapat mengedit setelan penilaian di Classroom setelah tugas dibuat. Pengeditan tersebut dapat mencakup:

Mengubah nilai poin yang ditetapkan.
Mengubah nilai maxPoints tugas.
Mengubah apakah tugas harus diberi nilai atau tidak.

Untuk melihat setelan penilaian tugas saat ini, sebaiknya Anda mengirim permintaan GET ke endpoint courses.courseWork. Respons mencakup nilai maxPoints saat ini. Tugas yang belum dinilai memiliki nilai null atau nol maxPoints.

Jika Anda telah mengirimkan nilai kembali ke Classroom, gunakan endpoint courses.courseWork.addOnAttachments.studentSubmissions untuk mengambil atau mengubah nilai untuk lampiran add-on. Nilai tingkat ditetapkan menggunakan kolom pointsEarned. Pertimbangkan untuk memeriksa dan, jika perlu, memperbarui nilai ini jika produk Anda memungkinkan pengajar mengedit skor siswa untuk aktivitas tertentu.