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 bernilai. Anda juga akan mengirim nilai kembali ke Google Classroom secara terprogram, yang akan muncul di buku nilai pengajar sebagai nilai draf.

Panduan ini sedikit berbeda dari panduan lainnya dalam rangkaian ini karena ada dua kemungkinan pendekatan untuk mengirim 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 mengetahui pembahasan tambahan tentang opsi penerapan.

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

Selama panduan ini, Anda akan menyelesaikan hal berikut:

• Mengubah permintaan pembuatan lampiran sebelumnya ke Classroom API untuk juga menetapkan denominator nilai lampiran.
• Memberi skor pengiriman siswa secara terprogram dan menetapkan numerator nilai lampiran.
• Menerapkan dua pendekatan untuk mengirim nilai pengiriman ke Classroom menggunakan kredensial pengajar yang login atau offline.

Setelah selesai, nilai akan muncul di buku nilai Classroom setelah perilaku pengiriman kembali dipicu. Waktu yang tepat saat hal ini terjadi bergantung pada pendekatan penerapan.

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

Memahami fitur penilaian Classroom add-ons API

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

Gambar 1. UI pembuatan tugas dengan tiga kartu lampiran add-on yang memiliki maxPoints yang ditetapkan.

Classroom add-ons API memungkinkan Anda mengonfigurasi setelan untuk 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 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 di Gambar 1 untuk mengetahui 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 akan mengaktifkan "Sinkronisasi nilai" pada 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 denominator 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 akan menghemat kebutuhan untuk melakukan panggilan API tambahan nanti saat menilai pengiriman siswa. Namun, perhatikan 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 untuk 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 seharusnya dapat menguji perilaku ini sekarang. Tambahkan lampiran ke tugas baru, dan amati bahwa kartu lampiran menampilkan label "Sinkronisasi nilai" dan nilai "Poin" tugas berubah.

Menetapkan nilai pengiriman siswa di Classroom

Bagian ini menjelaskan cara menetapkan numerator untuk nilai lampiran; yaitu, skor siswa perorangan untuk lampiran. Untuk melakukannya, tetapkan nilai pointsEarned pengiriman lampiran siswa.

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

Masalahnya adalah menetapkan 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 menetapkan pointsEarned:

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

Bagian berikut membahas kelebihan dan kekurangan setiap pendekatan sebelum mendemonstrasikan setiap penerapan. Perhatikan bahwa contoh yang kami berikan mendemonstrasikan kedua pendekatan untuk mengirim 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 untuk menetapkan pointsEarned. Hal ini akan terlihat cukup intuitif karena mencerminkan sisa penerapan sejauh ini, dan hanya memerlukan sedikit upaya untuk mewujudkannya.

Namun, pertimbangkan bahwa pengajar hanya berinteraksi dengan pengiriman siswa di iframe Tinjauan 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 pengiriman siswa untuk mengisi semua nilai siswa.
• Ada penundaan singkat antara Classroom menerima nilai dan penampilannya di UI Classroom. Penundaan biasanya lima hingga sepuluh detik, tetapi bisa mencapai 30 detik.

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

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

Setelah mengambil pengiriman siswa dan data lampiran, evaluasi pengiriman siswa dan simpan nilai yang dihasilkan. Tetapkan nilai di kolom pointsEarned objek AddOnAttachmentStudentSubmission. Terakhir, kirim permintaan PATCH ke courses.courseWork.addOnAttachments.studentSubmissions endpoint dengan instance AddOnAttachmentStudentSubmission di isi permintaan. Perhatikan bahwa kita juga perlu 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

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

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

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

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

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

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