Nilai lampiran dan passback nilai

Ini adalah panduan keenam dalam rangkaian panduan add-on Classroom.

Dalam panduan ini, Anda akan mengubah contoh dari langkah panduan sebelumnya untuk menghasilkan lampiran jenis aktivitas yang dinilai. Anda juga dapat meneruskan nilai kembali ke Google Classroom secara terprogram, yang akan muncul di buku nilai pengajar sebagai nilai draf.

Panduan ini sedikit berbeda dengan panduan lainnya dalam seri ini karena ada dua kemungkinan pendekatan untuk meneruskan nilai kembali ke Classroom. Keduanya memiliki dampak yang berbeda pada pengalaman developer dan pengguna; pertimbangkan keduanya saat Anda mendesain add-on Classroom. Baca halaman panduan Berinteraksi dengan lampiran untuk diskusi tambahan tentang opsi penerapan.

Perhatikan bahwa fitur penilaian di API bersifat opsional. Atribut ini dapat digunakan dengan lampiran jenis aktivitas apa pun.

Selama panduan ini, Anda akan menyelesaikan hal berikut:

  • Ubah permintaan pembuatan lampiran sebelumnya ke Classroom API untuk juga menetapkan denominator nilai lampiran.
  • Beri skor tugas siswa secara terprogram dan tetapkan pembilang nilai lampiran.
  • Terapkan dua pendekatan untuk meneruskan nilai tugas ke Classroom menggunakan kredensial pengajar yang login atau offline.

Setelah selesai, nilai akan muncul di buku nilai Classroom setelah perilaku passback dipicu. Waktu yang tepat ketika hal ini terjadi bergantung pada pendekatan implementasi.

Untuk tujuan contoh ini, gunakan kembali aktivitas dari panduan sebelumnya, yang menampilkan gambar tempat terkenal kepada siswa dan diminta untuk memasukkan namanya. Beri nilai penuh untuk lampiran jika siswa memasukkan nama yang benar, nol jika tidak.

Memahami fitur penilaian API add-on Classroom

Add-on Anda dapat menetapkan numerator nilai dan penyebut nilai untuk lampiran. Nilai ini masing-masing ditetapkan menggunakan nilai pointsEarned dan maxPoints di API. Kartu lampiran di UI Classroom menampilkan nilai maxPoints saat telah ditetapkan.

Contoh beberapa lampiran dengan maxPoints pada satu tugas

Gambar 1. UI pembuatan tugas dengan tiga kartu lampiran add-on yang telah menetapkan maxPoints.

API add-on Classroom memungkinkan Anda mengonfigurasi setelan dan menetapkan skor yang diperoleh untuk nilai lampiran. Nilai ini tidak sama dengan nilai tugas. Namun, setelan nilai tugas mengikuti setelan nilai lampiran dari lampiran yang memiliki label Sinkronisasi nilai di kartu lampirannya. Saat lampiran "Sinkronisasi nilai" menetapkan pointsEarned untuk pengiriman siswa, lampiran tersebut juga menetapkan draf nilai siswa untuk tugas tersebut.

Biasanya, lampiran pertama yang ditambahkan ke tugas yang menetapkan maxPoints akan menerima label "Sinkronisasi nilai". Lihat contoh UI pembuatan tugas yang ditampilkan dalam Gambar 1 untuk contoh label "Sinkronisasi nilai". Perhatikan bahwa kartu "Lampiran 1" memiliki label "Sinkronisasi nilai" dan nilai tugas di kotak merah telah diperbarui menjadi 50 poin. Perhatikan juga bahwa meskipun Gambar 1 menampilkan tiga kartu lampiran, hanya satu kartu yang memiliki label "Sinkronisasi nilai". Ini adalah batasan utama dari penerapan saat ini: hanya satu lampiran yang dapat memiliki label "Sinkronisasi nilai".

Jika ada beberapa lampiran yang telah menetapkan maxPoints, menghapus lampiran dengan "Sinkronisasi nilai" tidak mengaktifkan "Sinkronisasi nilai" di salah satu lampiran yang tersisa. Menambahkan lampiran lain yang menetapkan maxPoints akan mengaktifkan Sinkronisasi Nilai pada lampiran baru, dan nilai tugas maksimum akan disesuaikan agar cocok. Tidak ada mekanisme untuk melihat secara terprogram lampiran mana yang memiliki label "Sinkronisasi nilai" atau untuk melihat jumlah lampiran yang dimiliki tugas tertentu.

Menetapkan nilai maksimum lampiran

Bagian ini menjelaskan cara menetapkan penyebut untuk nilai lampiran; yaitu, skor maksimum yang dapat dicapai semua siswa untuk pengiriman mereka. Untuk melakukannya, setel nilai maxPoints lampiran.

Hanya modifikasi kecil pada penerapan yang ada yang diperlukan untuk mengaktifkan fitur penilaian. Saat membuat lampiran, tambahkan nilai maxPoints di objek AddOnAttachment yang sama yang berisi studentWorkReviewUri, teacherViewUri, dan kolom lampiran lainnya.

Perhatikan bahwa skor maksimum default untuk tugas baru adalah 100. Sebaiknya tetapkan maxPoints ke nilai selain 100 agar Anda dapat memverifikasi bahwa nilai ditetapkan dengan benar. Tetapkan maxPoints ke 50 sebagai demonstrasi:

Python

Tambahkan kolom maxPoints saat membuat objek attachment, tepat sebelum mengeluarkan permintaan CREATE ke endpoint courses.courseWork.addOnAttachments. Anda dapat menemukannya di file webapp/attachment_routes.py jika mengikuti contoh yang kami berikan.

attachment = {
    # Specifies the route for a teacher user.
    "teacherViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True),
    },
    # Specifies the route for a student user.
    "studentViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True)
    },
    # Specifies the route for a teacher user when the attachment is
    # loaded in the Classroom grading view.
    "studentWorkReviewUri": {
        "uri":
            flask.url_for(
                "view_submission", _scheme='https', _external=True)
    },
    # Sets the maximum points that a student can earn for this activity.
    # This is the denominator in a fractional representation of a grade.
    "maxPoints": 50,
    # The title of the attachment.
    "title": f"Attachment {attachment_count}",
}

Untuk tujuan demonstrasi ini, Anda juga menyimpan nilai maxPoints di database Lampiran lokal; hal ini menghemat Anda dari keharusan melakukan panggilan API tambahan nanti saat menilai kiriman siswa. Namun, perlu diketahui bahwa pengajar dapat mengubah setelan nilai tugas secara terpisah dari add-on Anda. Kirim permintaan GET ke endpoint courses.courseWork untuk melihat nilai maxPoints tingkat tugas. Saat melakukannya, teruskan itemId di kolom CourseWork.id.

Sekarang perbarui model database Anda agar juga menyimpan nilai maxPoints lampiran. Sebaiknya gunakan nilai maxPoints dari respons CREATE:

Python

Pertama, tambahkan kolom max_points ke tabel Attachment. Anda dapat menemukannya dalam file webapp/models.py jika mengikuti contoh yang kami berikan.

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

Kembali ke permintaan courses.courseWork.addOnAttachments CREATE. Simpan nilai maxPoints yang ditampilkan dalam respons.

new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    # Store the maxPoints value returned in the response.
    max_points=int(resp.get("maxPoints")))
db.session.add(new_attachment)
db.session.commit()

Lampiran kini memiliki nilai maksimum. Anda sekarang dapat menguji perilaku ini; tambahkan lampiran ke tugas baru, dan amati bahwa kartu lampiran menampilkan label "Sinkronisasi nilai" dan nilai "Poin" tugas berubah.

Menetapkan nilai kiriman siswa di Classroom

Bagian ini menjelaskan cara menetapkan penyebut untuk nilai lampiran; yaitu, skor setiap siswa untuk lampiran. Untuk melakukannya, tetapkan nilai pointsEarned kiriman siswa.

Sekarang Anda memiliki keputusan penting yang harus dibuat: bagaimana add-on Anda harus mengeluarkan permintaan untuk menetapkan pointsEarned?

Masalahnya adalah, menyetel pointsEarned memerlukan cakupan OAuth teacher. Anda tidak boleh memberikan cakupan teacher kepada pengguna siswa; hal ini dapat menyebabkan perilaku yang tidak terduga saat siswa berinteraksi dengan add-on Anda, seperti memuat iframe Tampilan Pengajar, bukan iframe Tampilan Siswa. Oleh karena itu, Anda memiliki dua pilihan untuk cara menyetel pointsEarned:

  • Menggunakan kredensial pengajar yang login.
  • Menggunakan kredensial pengajar tersimpan (offline).

Bagian berikut membahas kompromi dari setiap pendekatan sebelum mendemonstrasikan setiap implementasi. Perhatikan bahwa contoh yang kami berikan menunjukkan kedua pendekatan untuk meneruskan nilai ke Classroom; lihat petunjuk khusus bahasa di bawah untuk melihat cara memilih pendekatan saat menjalankan contoh yang diberikan:

Python

Temukan deklarasi SET_GRADE_WITH_LOGGED_IN_USER_CREDENTIALS di bagian atas file webapp/attachment_routes.py. Tetapkan nilai ini ke True untuk meneruskan nilai menggunakan kredensial pengajar yang login. Tetapkan nilai ini ke False untuk meneruskan nilai menggunakan kredensial tersimpan saat siswa mengirimkan aktivitas.

Menetapkan nilai menggunakan kredensial pengajar yang login

Gunakan kredensial pengguna yang login untuk mengajukan permintaan guna menyetel pointsEarned. Hal ini seharusnya tampak cukup intuitif karena mencerminkan seluruh implementasi sejauh ini, dan memerlukan sedikit upaya untuk mewujudkannya.

Namun, pertimbangkan bahwa pengajar hanya berinteraksi dengan kiriman siswa di iframe Ulasan Tugas Siswa. Hal ini memiliki beberapa implikasi penting:

  • Tidak ada nilai yang diisi di Classroom hingga pengajar mengambil tindakan di UI Classroom.
  • Pengajar mungkin harus membuka setiap kiriman siswa untuk mengisi semua nilai siswa.
  • Ada penundaan singkat antara penerimaan nilai dan tampilannya di UI Classroom. Penundaan ini biasanya berlangsung selama lima hingga sepuluh detik, tetapi dapat berlangsung hingga 30 detik.

Kombinasi faktor-faktor ini berarti bahwa pengajar mungkin harus melakukan pekerjaan manual yang cukup memakan waktu untuk mengisi nilai kelas sepenuhnya.

Untuk menerapkan pendekatan ini, tambahkan satu panggilan API tambahan ke rute Ulasan Tugas Siswa yang ada.

Setelah mengambil data lampiran dan kiriman siswa, evaluasi tugas yang dikirimkan siswa dan simpan nilai yang dihasilkan. Tetapkan nilai di kolom pointsEarned objek AddOnAttachmentStudentSubmission. Terakhir, kirimkan permintaan PATCH ke endpoint courses.courseWork.addOnAttachments.studentSubmissions dengan instance AddOnAttachmentStudentSubmission dalam isi permintaan. Perhatikan bahwa kita juga harus menentukan pointsEarned di updateMask dalam permintaan PATCH:

Python

# Look up the student's submission in our database.
student_submission = Submission.query.get(flask.session["submissionId"])

# Look up the attachment in the database.
attachment = Attachment.query.get(student_submission.attachment_id)

grade = 0

# See if the student response matches the stored name.
if student_submission.student_response.lower(
) == attachment.image_caption.lower():
    grade = attachment.max_points

# Create an instance of the Classroom service.
classroom_service = ch._credential_handler.get_classroom_service()

# Build an AddOnAttachmentStudentSubmission instance.
add_on_attachment_student_submission = {
    # Specifies the student's score for this attachment.
    "pointsEarned": grade,
}

# Issue a PATCH request to set the grade numerator for this attachment.
patch_grade_response = classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

Menetapkan nilai menggunakan kredensial pengajar offline

Pendekatan kedua untuk menetapkan nilai mengharuskan penggunaan kredensial tersimpan untuk pengajar yang membuat lampiran. Implementasi ini mengharuskan Anda membuat kredensial menggunakan token refresh dan akses pengajar yang sebelumnya diizinkan, lalu menggunakan kredensial ini untuk menetapkan pointsEarned.

Keuntungan penting dari pendekatan ini adalah nilai diisi tanpa memerlukan tindakan guru di UI Classroom, sehingga menghindari masalah yang disebutkan di atas. Hasilnya, pengguna akhir akan merasakan pengalaman penilaian yang lancar dan efisien. Selain itu, pendekatan ini memungkinkan Anda memilih saat Anda memberikan nilai, seperti saat siswa menyelesaikan aktivitas atau secara asinkron.

Selesaikan tugas berikut untuk menerapkan pendekatan ini:

  1. Mengubah data database Pengguna untuk menyimpan token akses.
  2. Mengubah catatan database Lampiran untuk menyimpan ID pengajar.
  3. Ambil kredensial pengajar dan (opsional) buat instance layanan Classroom baru.
  4. Menetapkan nilai kiriman.

Untuk tujuan demonstrasi ini, tetapkan nilai saat siswa menyelesaikan aktivitas; yaitu, saat siswa mengirimkan formulir dalam rute Tampilan Siswa.

Mengubah data database Pengguna untuk menyimpan token akses

Dua token unik diperlukan untuk melakukan panggilan API, yaitu token refresh dan token akses. Jika Anda telah mengikuti rangkaian panduan sejauh ini, skema tabel User Anda seharusnya sudah menyimpan token refresh. Menyimpan token refresh sudah cukup jika Anda hanya melakukan panggilan API dengan pengguna yang login, karena Anda menerima token akses sebagai bagian dari alur autentikasi.

Namun, sekarang Anda perlu melakukan panggilan sebagai orang selain pengguna yang login, yang berarti alur autentikasi tidak tersedia. Dengan demikian, Anda harus menyimpan token akses bersama dengan token refresh. Perbarui skema tabel User untuk menyertakan token akses:

Python

Dalam contoh yang kami berikan, ini ada dalam file webapp/models.py.

# Database model to represent a user.
class User(db.Model):
    # The user's identifying information:
    id = db.Column(db.String(120), primary_key=True)
    display_name = db.Column(db.String(80))
    email = db.Column(db.String(120), unique=True)
    portrait_url = db.Column(db.Text())

    # The user's refresh token, which will be used to obtain an access token.
    # Note that refresh tokens will become invalid if:
    # - The refresh token has not been used for six months.
    # - The user revokes your app's access permissions.
    # - The user changes passwords.
    # - The user belongs to a Google Cloud organization
    #   that has session control policies in effect.
    refresh_token = db.Column(db.Text())

    # An access token for this user.
    access_token = db.Column(db.Text())

Kemudian, perbarui setiap kode yang membuat atau memperbarui data User agar juga menyimpan token akses:

Python

Dalam contoh yang kami berikan, ini ada dalam file webapp/credential_handler.py.

def save_credentials_to_storage(self, credentials):
    # Issue a request for the user's profile details.
    user_info_service = googleapiclient.discovery.build(
        serviceName="oauth2", version="v2", credentials=credentials)
    user_info = user_info_service.userinfo().get().execute()
    flask.session["username"] = user_info.get("name")
    flask.session["login_hint"] = user_info.get("id")

    # See if we have any stored credentials for this user. If they have used
    # the add-on before, we should have received login_hint in the query
    # parameters.
    existing_user = self.get_credentials_from_storage(user_info.get("id"))

    # If we do have stored credentials, update the database.
    if existing_user:
        if user_info:
            existing_user.id = user_info.get("id")
            existing_user.display_name = user_info.get("name")
            existing_user.email = user_info.get("email")
            existing_user.portrait_url = user_info.get("picture")

        if credentials and credentials.refresh_token is not None:
            existing_user.refresh_token = credentials.refresh_token
            # Update the access token.
            existing_user.access_token = credentials.token

    # If not, this must be a new user, so add a new entry to the database.
    else:
        new_user = User(
            id=user_info.get("id"),
            display_name=user_info.get("name"),
            email=user_info.get("email"),
            portrait_url=user_info.get("picture"),
            refresh_token=credentials.refresh_token,
            # Store the access token as well.
            access_token=credentials.token)

        db.session.add(new_user)

    db.session.commit()

Mengubah data database Lampiran untuk menyimpan ID pengajar

Untuk menetapkan nilai aktivitas, lakukan panggilan untuk menetapkan pointsEarned sebagai pengajar dalam kursus. Ada beberapa cara untuk melakukannya:

  • Simpan pemetaan lokal kredensial pengajar ke ID mata pelajaran. Namun, perlu diperhatikan bahwa pengajar yang sama mungkin tidak selalu dikaitkan dengan kursus tertentu.
  • Buat permintaan GET ke endpoint courses Classroom API untuk mendapatkan pengajar saat ini. Kemudian, buat kueri data pengguna lokal untuk menemukan kredensial pengajar yang cocok.
  • Saat membuat lampiran add-on, simpan ID pengajar di database lampiran lokal. Kemudian, ambil kredensial pengajar dari attachmentId yang diteruskan ke iframe Tampilan Siswa.

Contoh ini menunjukkan opsi terakhir karena Anda menetapkan nilai saat siswa menyelesaikan lampiran aktivitas.

Tambahkan kolom ID pengajar ke tabel Attachment database Anda:

Python

Dalam contoh yang kami berikan, ini ada dalam file webapp/models.py.

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

    # The ID of the teacher that created the attachment.
    teacher_id = db.Column(db.String(120))

Kemudian, perbarui kode apa pun yang membuat atau memperbarui data Attachment untuk menyimpan ID pembuat juga:

Python

Dalam contoh yang kami berikan, ini ada dalam metode create_attachments di file webapp/attachment_routes.py.

# Store the attachment by id.
new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    max_points=int(resp.get("maxPoints")),
    teacher_id=flask.session["login_hint"])
db.session.add(new_attachment)
db.session.commit()

Mengambil kredensial pengajar

Temukan rute yang menayangkan iframe Tampilan Siswa. Segera setelah menyimpan respons siswa di database lokal, ambil kredensial pengajar dari penyimpanan lokal Anda. Hal ini seharusnya mudah dilakukan mengingat persiapan di dua langkah sebelumnya. Anda juga dapat menggunakannya untuk membuat instance layanan Classroom baru bagi pengguna pengajar:

Python

Dalam contoh yang kami berikan, hal ini terjadi dalam metode load_activity_attachment dalam file webapp/attachment_routes.py.

# Create an instance of the Classroom service using the tokens for the
# teacher that created the attachment.

# We're assuming that there are already credentials in the session, which
# should be true given that we are adding this within the Student View
# route; we must have had valid credentials for the student to reach this
# point. The student credentials will be valid to construct a Classroom
# service for another user except for the tokens.
if not flask.session.get("credentials"):
    raise ValueError(
        "No credentials found in session for the requested user.")

# Make a copy of the student credentials so we don't modify the original.
teacher_credentials_dict = deepcopy(flask.session.get("credentials"))

# Retrieve the requested user's stored record.
teacher_record = User.query.get(attachment.teacher_id)

# Apply the user's tokens to the copied credentials.
teacher_credentials_dict["refresh_token"] = teacher_record.refresh_token
teacher_credentials_dict["token"] = teacher_record.access_token

# Construct a temporary credentials object.
teacher_credentials = google.oauth2.credentials.Credentials(
    **teacher_credentials_dict)

# Refresh the credentials if necessary; we don't know when this teacher last
# made a call.
if teacher_credentials.expired:
    teacher_credentials.refresh(Request())

# Request the Classroom service for the specified user.
teacher_classroom_service = googleapiclient.discovery.build(
    serviceName=CLASSROOM_API_SERVICE_NAME,
    version=CLASSROOM_API_VERSION,
    credentials=teacher_credentials)

Menetapkan nilai kiriman

Prosedur dari sini sama dengan menggunakan kredensial guru yang login. Namun, perlu diperhatikan bahwa Anda harus melakukan panggilan dengan kredensial guru yang diambil di langkah sebelumnya:

Python

# Issue a PATCH request as the teacher to set the grade numerator for this
# attachment.
patch_grade_response = teacher_classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

Menguji add-on

Serupa dengan panduan sebelumnya, buat tugas dengan lampiran jenis aktivitas sebagai pengajar, kirimkan respons sebagai siswa, lalu buka kiriman mereka di iframe Ulasan Tugas Siswa. Anda akan dapat melihat nilai muncul pada waktu yang berbeda bergantung pada pendekatan penerapan Anda:

  • Jika Anda memilih untuk memberikan nilai saat siswa menyelesaikan aktivitas, Anda seharusnya sudah melihat nilai draf mereka di UI sebelum membuka iframe Ulasan Tugas Siswa. Anda juga dapat melihatnya dalam daftar siswa saat membuka tugas, dan di kotak "Nilai" di samping iframe Ulasan Tugas Siswa.
  • Jika Anda memilih untuk meneruskan nilai saat pengajar membuka iframe Ulasan Tugas Siswa, nilai akan muncul di kotak "Nilai" segera setelah iframe dimuat. Seperti yang disebutkan di atas, proses ini dapat memerlukan waktu hingga 30 detik. Setelah itu, nilai untuk siswa tertentu juga akan muncul di tampilan buku nilai Classroom lainnya.

Pastikan skor yang benar muncul untuk siswa.

Selamat! Anda siap melanjutkan ke langkah berikutnya: membuat lampiran di luar Google Classroom.