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 implementasi untuk membuat lampiran dan mengerjakan tugas yang dikirimkan siswa. Perhatikan bahwa Anda mungkin perlu memberikan parameter terkait lampiran saat membuat permintaan ini.

Membuat lampiran

Buat lampiran dengan mengajukan permintaan CREATE ke Endpoint courses.*.addOnAttachments.create. 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 lampiran tersebut. Kolom ini hanya wajib diisi untuk lampiran jenis aktivitas.

Anda mungkin ingin menyertakan beberapa kolom opsional berikut:

dueDate dan dueTime jika menentukan waktu pengiriman lampiran.
maxPoints: nilai maksimum untuk lampiran. Harus berupa nilai bukan nol jika Anda ingin mendukung passback nilai. Berlaku untuk lampiran jenis aktivitas saja.

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 mengambil submissionId dari metode getAddOnContext menggunakan kredensial siswa.
submissionId dan attachmentId disimpan oleh add-on developer sebagai ID unik untuk tugas siswa. Jika pengajar menyalin tugas di Classroom, Anda dapat menggunakan kunci gabungan dari kedua parameter ini untuk menampilkan lampiran baru dalam salinan tugas. Lihat halaman tentang konten salinan untuk mengetahui detail selengkapnya.
Seorang pengajar yang tertarik meninjau tugas siswa akan meluncurkan studentWorkReviewUri. Permintaan tersebut 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 tugas yang dikirimkan siswa.

Mendeteksi status pengiriman

Kirimkan permintaan GET ke Endpoint courses.courseWork.addOnAttachments.studentSubmissions untuk mendapatkan detail tentang submissionId spesifik. Anda 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 "membatalkan pengiriman" pekerjaan mereka.

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

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

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 menyetel nilai tugas. Jangan tetapkan nilai maxPoints 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. Permintaan body harus menyertakan instance AddOnAttachmentStudentSubmission dengan nilai yang dimodifikasi. 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 nilai disajikan kepada guru.

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 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. Tujuan perbedaan pentingnya adalah apakah Anda memilih untuk menyimpan kredensial guru, sebagai hanya pengajar yang dapat mengubah nilai.

Ada dua momen tambahan saat Anda bisa lulus nilai Google Classroom: saat siswa menyelesaikan tugasnya atau ketika pengajar membuka tugas siswa dalam iframe Ulasan 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 tugasnya. Metode ini memberikan beberapa potensi manfaat:

Berikan pembaruan nilai yang lancar. Pengajar tidak perlu melakukan yang dapat menyebabkan nilai diisi di UI Classroom.
Memberikan insight real-time tentang perkembangan kelas melalui tugas. Dengan menetapkan nilai seiring siswa menyelesaikan lampiran, pengajar dapat memahami tugas siswanya tanpa membuka setiap kiriman.

Perhatikan bahwa pendekatan ini juga memungkinkan pendekatan asinkron untuk menilai sinkronisasi. Anda mungkin akan melakukan polling untuk AddOnAttachmentStudentSubmission secara berkala endpoint untuk mendeteksi kapan siswa telah mengirimkan tugas. Ketika sudah dikirimkan, atur nilai kiriman menggunakan kredensial yang disimpan.

Jika Anda tidak ingin memuat kredensial pengajar selama sesi siswa, Anda dapat menggunakan kredensial pengajar yang aktif saat mereka memuat kiriman dalam iframe Ulasan Tugas Siswa. Namun, hal ini mungkin tidak memberikan pengalaman pengguna yang sangat lancar sebagai nilai di UI Classroom tidak memperbarui secara langsung dan guru harus membuka setiap iframe Ulasan Tugas Siswa kiriman.

Deteksi perubahan dalam nilai tugas

pengajar dapat mengedit setelan nilai di Classroom setelah tugas dibuat. Pengeditan tersebut mungkin termasuk:

Mengubah nilai poin yang ditetapkan.
Mengubah nilai maxPoints tugas.
Mengubah apakah tugas harus dinilai sama sekali.

Untuk melihat setelan penilaian tugas saat ini, sebaiknya kirimkan permintaan GET ke endpoint courses.courseWork. Responsnya mencakup nilai maxPoints saat ini. Tugas yang tidak dinilai memiliki nilai nol atau nol Nilai maxPoints.

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 disetel menggunakan atribut Kolom pointsEarned. Pertimbangkan untuk memeriksa dan, jika perlu, perbarui nilai ini jika produk Anda memungkinkan pengajar mengedit skor siswa untuk aktivitas Anda.