Nilai lampiran dan passback nilai

Selama panduan ini, Anda akan menyelesaikan hal berikut:

• Ubah permintaan pembuatan lampiran sebelumnya ke Classroom API untuk juga menetapkan denominator nilai lampiran.
• Beri skor secara terprogram pada kiriman siswa dan tetapkan penghitung 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. Momen persis saat hal ini terjadi bergantung pada pendekatan penerapan.

Untuk tujuan contoh ini, gunakan kembali aktivitas dari walkthrough sebelumnya, saat siswa melihat gambar landmark terkenal dan diminta untuk memasukkan namanya. Berikan nilai penuh untuk lampiran jika siswa memasukkan nama yang benar, atau nol jika tidak.

Memahami fitur penilaian API add-on Classroom

Add-on Anda dapat menetapkan pembilang 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.

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 kiriman siswa, lampiran tersebut juga menetapkan nilai draf siswa untuk tugas.

Biasanya, lampiran pertama yang ditambahkan ke tugas yang menetapkan maxPoints akan menerima label "Sinkronisasi nilai". Lihat contoh UI pembuatan tugas yang ditampilkan pada 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 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, tetapkan 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:

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 diperhatikan bahwa guru 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:

# 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)

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 kini 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 setelan 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:

Menetapkan nilai menggunakan kredensial pengajar yang login

Gunakan kredensial pengguna yang login untuk mengeluarkan permintaan guna menetapkan pointsEarned. Hal ini akan tampak cukup intuitif karena mencerminkan implementasi lainnya 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 Classroom menerima 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 tugas siswa, evaluasi kiriman tugas siswa dan simpan nilai yang dihasilkan. Tetapkan nilai di kolom pointsEarned objek AddOnAttachmentStudentSubmission. Terakhir, terbitkan 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:

# 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 memerlukan penggunaan kredensial tersimpan untuk pengajar yang membuat lampiran. Implementasi ini mengharuskan Anda membuat kredensial menggunakan token akses dan refresh pengajar yang telah diotorisasi sebelumnya, 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 data database Lampiran untuk menyimpan ID pengajar.
3. Ambil kredensial pengajar dan (opsional) buat instance layanan Classroom baru.
4. Menetapkan nilai pengiriman.

Untuk tujuan demonstrasi ini, tetapkan nilai saat siswa menyelesaikan aktivitas; yaitu, saat siswa mengirimkan formulir di 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 perlu menyimpan token akses bersama dengan token refresh. Perbarui skema tabel User untuk menyertakan token akses:

# 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 kode apa pun yang membuat atau memperbarui data User agar juga menyimpan token akses:

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:

• Menyimpan pemetaan lokal kredensial pengajar ke ID kursus. 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:

# 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 kumpulan data Attachment untuk juga menyimpan ID kreator:

# 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:

# 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 tugas

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:

# 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.