Berinteraksi dengan lampiran

Halaman ini membahas detail penerapan untuk membuat lampiran dan menangani tugas yang dikirimkan siswa. Perhatikan bahwa Anda mungkin perlu memberikan 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 untuk pengajar agar dapat melihat tugas siswa di lampiran. Kolom ini hanya wajib diisi untuk lampiran jenis aktivitas.

Sebaiknya sertakan beberapa kolom opsional berikut:

• dueDate dan dueTime jika menentukan kapan lampiran harus dikirim.
• maxPoints: nilai maksimum untuk lampiran. Harus berupa nilai non-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:

1. Siswa meluncurkan studentViewUri untuk menyelesaikan aktivitas.
2. Add-on ini mengambil submissionId dari metode getAddOnContext menggunakan kredensial siswa.
3. submissionId dan attachmentId 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.
4. Pengajar yang tertarik untuk meninjau tugas siswa akan meluncurkan studentWorkReviewUri. Permintaan tersebut mencakup parameter kueri berikut: courseId, itemId, itemType, attachmentId, dan submissionId.
5. 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.

Penting: Saat mengeluarkan permintaan PATCH, jangan lupa untuk juga memberikan updateMask. Nilai updateMask harus berupa daftar nama kolom yang dipisahkan koma yang akan diubah.

Mendeteksi status pengiriman

Buat 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 tugas yang dikirimkan.
• CREATED, jika siswa telah membuat tugas tetapi belum mengirimkannya.
• TURNED_IN, jika siswa telah mengirimkan tugasnya kepada pengajar.
• RETURNED, jika pengajar telah mengembalikan tugas kepada siswa.
• RECLAIMED_BY_STUDENT, jika siswa telah "membatalkan pengiriman" tugasnya.

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

• Menampilkan status penyerahan tugas dalam add-on Anda. Hal ini dapat membantu siswa menghindari potensi kebingungan dan memastikan mereka tidak gagal menyerahkan tugas.
• Membatasi hak istimewa edit pengiriman. 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 untuk mengedit kiriman mereka.

Nilai dan beberapa lampiran

Poin Penting: Pertimbangkan untuk memberi pengajar opsi guna mengaktifkan atau menonaktifkan passback nilai saat membuat 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 yang dapat menetapkan nilai tugas. Biarkan nilai maxPoints tidak ditetapkan atau tetapkan ke nol untuk menonaktifkan passback nilai untuk lampiran.

Menetapkan nilai kiriman

Anda dapat mengubah pengiriman 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 terlihat oleh pengajar di UI Classroom. Pengajar dapat mengubah nilai draf sebelum mengembalikan tugas kepada siswa. Lihat Ringkasan penilaian di UI Classroom untuk mengetahui detail tentang cara nilai ditampilkan kepada pengajar.

Peringatan: Pembaruan nilai di UI Google Classroom tidak terjadi secara real time. Mungkin ada penundaan hingga 30 detik antara saat nilai berhasil diterima dan ditampilkan di Classroom.

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

• Lampiran harus memiliki nilai maxPoints positif.
• Add-on harus merupakan kreator 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 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 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 pembaruan nilai yang lancar. Pengajar tidak perlu melakukan tindakan khusus apa pun untuk membuat nilai diisi di UI Classroom.
• Memberikan insight real-time tentang perkembangan kelas melalui tugas. Dengan menetapkan nilai saat siswa menyelesaikan lampiran, pengajar dapat mengetahui 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 mereka. Setelah dikirimkan, tetapkan nilai kiriman menggunakan kredensial yang disimpan.

Jika 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 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

Poin Penting: Pertimbangkan untuk memeriksa setelan penilaian tugas saat ini sebelum menetapkan nilai tugas.

setelan nilai dapat diedit di Classroom setelah tugas dibuat. Pengeditan 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.