Halaman ini membahas detail penerapan untuk membuat lampiran dan menangani tugas yang dikirimkan siswa. Perhatikan bahwa Anda mungkin perlu menyediakan parameter terkait lampiran saat membuat permintaan ini.
Membuat lampiran
Buat lampiran dengan mengeluarkan 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 di lampiran. Kolom ini hanya wajib diisi untuk lampiran jenis aktivitas.
Anda mungkin ingin menyertakan beberapa kolom opsional berikut:
dueDate
dandueTime
jika menentukan waktu pengiriman lampiran.maxPoints
: nilai maksimum untuk lampiran. Harus berupa nilai selain nol jika Anda ingin mendukung passback nilai. Hanya berlaku untuk lampiran jenis aktivitas.
Lihat referensi resource AddOnAttachment
untuk mengetahui detail selengkapnya tentang kolom ini.
Detail kiriman siswa
Alur kerja pengiriman umum mengikuti langkah-langkah berikut:
- Siswa meluncurkan
studentViewUri
untuk menyelesaikan aktivitas. - Add-on ini mengambil
submissionId
dari metodegetAddOnContext
menggunakan kredensial siswa. submissionId
danattachmentId
disimpan oleh developer add-on sebagai ID unik tugas siswa. Jika pengajar menyalin tugas di Classroom, Anda dapat menggunakan kunci gabungan dari kedua parameter ini untuk menampilkan lampiran baru dalam tugas yang disalin. Lihat halaman tentang konten salinan untuk mengetahui detail selengkapnya.- Seorang pengajar yang tertarik untuk meninjau tugas siswa akan meluncurkan
studentWorkReviewUri
. Permintaan tersebut mencakup parameter kueri berikut:courseId
,itemId
,itemType
,attachmentId
, dansubmissionId
. - 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
Kirimkan permintaan GET
ke
endpoint courses.courseWork.addOnAttachments.studentSubmissions
untuk mendapatkan
detail tentang submissionId
tertentu. Anda akan menerima objek AddOnAttachmentStudentSubmission
, yang berisi nilai kiriman (pointsEarned
) dan status saat ini (postSubmissionState
). Status pengiriman dapat berupa salah satu dari nilai berikut:
NEW
, jika siswa belum pernah mengakses kiriman.CREATED
, jika siswa telah membuat tugas tetapi belum mengirimkannya.TURNED_IN
, jika siswa telah mengirimkan tugasnya kepada pengajar.RETURNED
, jika pengajar telah mengembalikan tugas yang dikirimkan kepada siswa.RECLAIMED_BY_STUDENT
, jika siswa telah "membatalkan pengiriman" 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 kesimpangsiuran dan memastikan mereka tidak gagal menyerahkan tugas.
- Membatasi hak istimewa edit kiriman. Jika tugas memiliki status
CREATED
atauRECLAIMED_BY_STUDENT
, siswa mungkin diizinkan untuk mengedit tugas yang dikirimkan. Jika tugas berstatusTURNED_IN
atauRETURNED
, siswa mungkin tidak diizinkan untuk mengedit kirimannya.
Nilai dan beberapa lampiran
Hanya satu lampiran add-on yang dapat digunakan untuk menetapkan nilai untuk satu
tugas. Jika pengajar membuat lebih dari satu lampiran jenis aktivitas yang
memberikan nilai maxPoints
, hanya lampiran pertama tersebut yang dapat menetapkan
nilai tugas. Biarkan nilai maxPoints
tidak disetel atau setel ke nol untuk
menonaktifkan passback 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 di pointsEarned
menjadi draf nilai 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.
Perlu diketahui bahwa Anda dapat menetapkan nilai dengan pointsEarned
hanya jika hal berikut
benar:
- Lampiran harus memiliki nilai
maxPoints
positif. - Add-on harus merupakan pembuat asli lampiran.
Perhatikan juga bahwa Anda dapat mengubah nilai maxPoints
AddOnAttachment
yang sudah dibuat
dengan mengeluarkan permintaan PATCH
ke endpoint addOnAttachments
.
Kapan harus menetapkan nilai
Anda memiliki beberapa pilihan saat nilai dikembalikan 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 yang memungkinkan Anda meneruskan nilai ke Google Classroom: saat siswa menyelesaikan tugasnya atau saat pengajar membuka tugas siswa di iframe Ulasan Tugas Siswa.
Jika 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:
- Berikan pembaruan nilai yang lancar. Pengajar tidak perlu melakukan tindakan khusus untuk membuat nilai diisi di UI Classroom.
- Memberikan insight real-time tentang perkembangan kelas melalui tugas. Dengan menetapkan nilai sebagai siswa menyelesaikan lampiran, pengajar dapat merasakan pemahaman siswa tanpa membuka setiap kiriman.
Perhatikan bahwa pendekatan ini juga memungkinkan pendekatan asinkron untuk sinkronisasi
nilai. Anda dapat melakukan polling pada endpoint AddOnAttachmentStudentSubmission
secara berkala untuk mendeteksi kapan siswa telah mengirimkan tugas. Setelah
dikirimkan, tetapkan nilai kiriman menggunakan kredensial yang tersimpan.
Jika tidak ingin memuat kredensial pengajar selama sesi siswa, Anda dapat menggunakan kredensial pengajar aktif saat mereka memuat kiriman siswa di iframe Ulasan Tugas Siswa. Namun, hal ini mungkin tidak memberikan pengalaman pengguna yang sangat lancar karena nilai di UI Classroom tidak diperbarui secara real time dan pengajar akan diminta untuk membuka setiap frame Ulasan Tugas Siswa dari kiriman.
Deteksi perubahan dalam nilai tugas
setelan nilai dapat diedit di Classroom setelah tugas dibuat. Hasil edit tersebut dapat mencakup:
- Mengubah nilai poin yang ditetapkan.
- Mengubah nilai
maxPoints
tugas. - Mengubah apakah tugas harus dinilai sama sekali.
Untuk melihat setelan penilaian tugas saat ini, sebaiknya kirim
permintaan GET
ke endpoint courses.courseWork
. Responsnya mencakup
nilai maxPoints
saat ini. Tugas yang tidak dinilai memiliki nilai maxPoints
null atau
nol.
Jika Anda telah meneruskan nilai kembali ke Classroom, gunakan
endpoint courses.courseWork.addOnAttachments.studentSubmissions
untuk mengambil atau
mengubah nilai untuk lampiran add-on. Nilai nilai ditetapkan menggunakan
kolom pointsEarned
. Pertimbangkan untuk memeriksa dan, jika perlu, perbarui nilai ini
jika produk Anda memungkinkan pengajar mengedit skor siswa untuk aktivitas
tertentu.