Mengelola periode penilaian menggunakan Classroom API

Panduan ini menjelaskan cara menggunakan endpoint periode penilaian di Google Classroom API.

Ringkasan

Periode penilaian dibuat untuk mengatur pekerjaan rumah, kuis, dan project ke dalam rentang tanggal tertentu. Classroom API memungkinkan developer membuat, mengubah, dan membaca periode penilaian di Classroom atas nama administrator dan pengajar. Anda juga dapat menggunakan Classroom API untuk menetapkan periode penilaian di CourseWork.

Classroom API menawarkan dua endpoint untuk membaca dan menulis informasi periode penilaian dalam kursus:

  • GetGradingPeriodSettings: Memungkinkan Anda membaca setelan periode penilaian dalam kursus.
  • UpdateGradingPeriodSettings: Memungkinkan Anda mengelola setelan periode penilaian dalam kursus dengan menambahkan, mengubah, dan menghapus periode penilaian, serta menerapkan periode penilaian yang dikonfigurasi ke semua Tugas Kursus yang ada.

Persyaratan pemberian lisensi

Mengubah setelan periode penilaian di kursus

Untuk membuat, mengubah, atau menghapus periode penilaian dalam kursus menggunakan endpoint UpdateGradingPeriodSettings, kondisi berikut harus dipenuhi:

Membaca setelan periode penilaian di kursus

Administrator domain dan pengajar kursus dapat membaca setelan periode penilaian, apa pun lisensi yang ditetapkan untuk mereka. Artinya, permintaan ke endpoint GetGradingPeriodSettings diizinkan atas nama administrator atau pengajar domain mana pun.

Menetapkan ID periode penilaian di CourseWork

Pengajar kursus dapat menyertakan gradingPeriodId saat membuat atau memperbarui CourseWork menggunakan API, terlepas dari lisensi yang ditetapkan.

Memeriksa kelayakan pengguna untuk menyiapkan periode penilaian

Permintaan ke endpoint checkGradingPeriodsSetupEligibility diizinkan atas nama administrator atau pengajar. Gunakan ini untuk menentukan apakah pengguna dapat mengubah periode penilaian dalam kursus.

Prasyarat

Panduan ini memberikan contoh kode dalam Python, dan mengasumsikan bahwa Anda memiliki:

  • Project Google Cloud. Anda dapat menyiapkannya dengan mengikuti petunjuk di panduan memulai Python.
  • Menambahkan cakupan berikut ke layar izin OAuth project Anda:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • ID kursus yang periode penilaiannya harus diubah. Pemilik kursus harus memiliki lisensi Google Workspace for Education Plus.
  • Akses ke kredensial pengajar atau administrator dengan lisensi Google Workspace for Education Plus. Anda memerlukan kredensial pengajar untuk membuat atau mengubah Tugas Kursus. Administrator tidak dapat membuat atau mengubah CourseWork jika bukan pengajar di kursus.

Mengelola resource GradingPeriodSettings

Resource GradingPeriodSettings mencakup daftar setiap GradingPeriods dan kolom boolean yang disebut applyToExistingCoursework.

Daftar GradingPeriods mewakili semua periode penilaian individual dalam kursus. Anda harus menentukan judul, tanggal mulai, dan tanggal akhir untuk setiap periode penilaian dalam daftar. Setiap periode penilaian dalam kursus harus memiliki judul yang unik, dan tanggal mulai dan akhir periode penilaian yang berbeda tidak boleh tumpang-tindih. Setiap periode penilaian akan memiliki ID yang ditetapkan Classroom API.

Boolean applyToExistingCoursework adalah setelan yang dipertahankan yang memungkinkan Anda mengatur CourseWork yang dibuat sebelumnya ke dalam periode penilaian tanpa harus melakukan panggilan API terpisah untuk mengubah gradingPeriodId untuk setiap CourseWork. Jika ditetapkan ke True, Classroom akan otomatis menetapkan gradingPeriodId di semua Tugas yang ada jika courseWork.dueDate berada dalam tanggal mulai dan akhir periode penilaian yang ada. Jika tidak ada batas waktu yang ditetapkan di CourseWork, Classroom akan menggunakan courseWork.scheduledTime. Jika tidak ada kolom atau tidak ada kecocokan dalam tanggal mulai dan akhir periode penilaian yang ada, Materi Kursus tidak akan dikaitkan dengan periode penilaian apa pun.

Menentukan apakah pengguna dapat mengubah setelan periode penilaian di kursus

Karena kemampuan untuk membuat dan mengubah periode penilaian di Classroom hanya tersedia untuk pengguna dengan lisensi tertentu, Classroom API menyediakan endpoint checkGradingPeriodsSetupEligibility untuk membantu Anda secara proaktif menentukan apakah pengguna dapat membuat permintaan ke endpoint UpdateGradingPeriodSettings.

Python

def check_grading_period_setup_eligibility(classroom, course_id):
    """Checks whether a user is able to create and modify grading periods in a course."""
    try:
        grading_period_eligibility_response = classroom.courses().checkGradingPeriodsSetupEligibility(
          courseId=course_id, previewVersion="V1_20240401_PREVIEW").execute()

        # Retrieve the isGradingPeriodsSetupEligible boolean from the response.
        # If the boolean is `True`, the user is able to modify grading period settings in the course.
        is_grading_periods_eligible = grading_period_eligibility_response.get("isGradingPeriodsSetupEligible")
        return is_grading_periods_eligible
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Menambahkan periode penilaian

Setelah yakin bahwa pengguna memiliki lisensi yang diperlukan untuk mengubah setelan periode penilaian dalam kursus, Anda dapat mulai mengeluarkan permintaan ke endpoint UpdateGradingPeriodSettings. Setiap modifikasi pada resource GradingPeriodSettings dilakukan menggunakan endpoint UpdateGradingPeriodSettings, baik Anda menambahkan periode penilaian individual, mengubah periode penilaian yang ada, maupun menghapus periode penilaian.

Python

Dalam contoh berikut, resource gradingPeriodSettings diubah untuk menyertakan dua periode penilaian. Boolean applyToExistingCoursework ditetapkan ke True yang akan mengubah gradingPeriodId pada Tugas Kuliah yang ada yang berada di antara tanggal mulai dan tanggal akhir satu periode penilaian. Perhatikan bahwa updateMask menyertakan kedua kolom tersebut. Simpan ID untuk setiap periode penilaian setelah ditampilkan dalam respons. Anda harus menggunakan ID ini untuk memperbarui periode penilaian jika diperlukan.

def create_grading_periods(classroom, course_id):
    """
    Create grading periods in a course and apply the grading periods
    to existing courseWork.
    """
    try:
        body = {
          "gradingPeriods": [
            {
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": True
        }
        gradingPeriodSettingsResponse = classroom.courses().updateGradingPeriodSettings(
          courseId=course_id,
          updateMask='gradingPeriods,applyToExistingCoursework',
          body=body,
          previewVersion="V1_20240401_PREVIEW"
        ).execute();

        print(f"Grading period settings updated.")
        return gradingPeriodSettingsResponse

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Membaca setelan periode penilaian

GradingPeriodSettings dibaca menggunakan endpoint GetGradingPeriodSettings. Semua pengguna, terlepas dari lisensinya, dapat membaca setelan periode penilaian di kursus.

Python

def get_grading_period_settings(classroom, course_id):
    """Read grading periods settings in a course."""
    try:
        gradingPeriodSettings = classroom.courses().getGradingPeriodSettings(
          courseId=course_id, previewVersion="V1_20240401_PREVIEW").execute()
        return gradingPeriodSettings
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Menambahkan masing-masing periode penilaian ke daftar

Pembaruan pada setiap periode penilaian harus dilakukan dengan mengikuti pola baca-ubah-tulis. Artinya, Anda harus:

  1. Baca daftar periode penilaian dalam resource GradingPeriodSettings menggunakan endpoint GetGradingPeriodSettings.
  2. Lakukan modifikasi yang dipilih pada daftar periode penilaian.
  3. Kirim daftar periode penilaian baru dalam permintaan ke UpdateGradingPeriodSettings.

Pola ini akan membantu Anda memastikan bahwa setiap judul periode penilaian dalam kursus berbeda dan tidak ada tumpang-tindih antara tanggal mulai dan akhir periode penilaian.

Perhatikan aturan berikut tentang memperbarui daftar periode penilaian:

  1. Periode penilaian yang ditambahkan ke daftar tanpa ID dianggap sebagai tambahan.
  2. Periode penilaian yang tidak ada dalam daftar dianggap sebagai penghapusan.
  3. Periode penilaian dengan ID yang ada, tetapi data yang diubah dianggap sebagai pengeditan. Properti yang tidak diubah akan dibiarkan apa adanya.
  4. Periode penilaian dengan ID baru atau tidak dikenal dianggap sebagai error.

Python

Kode berikut akan dibuat berdasarkan contoh dalam panduan ini. Periode penilaian baru dibuat dengan judul, "Musim Panas". Boolean applyToExistingCoursework ditetapkan ke False dalam isi permintaan.

Untuk melakukannya, GradingPeriodSettings saat ini dibaca, periode penilaian baru ditambahkan ke daftar, dan boolean applyToExistingCoursework ditetapkan ke False. Perhatikan bahwa periode penilaian yang telah diterapkan ke Tugas Kuliah yang ada tidak akan dihapus. Pada contoh sebelumnya, periode penilaian "Semester 1" dan "Semester 2" telah diterapkan ke CourseWork yang ada dan tidak akan dihapus dari CourseWork jika applyToExistingCoursework ditetapkan ke False dalam permintaan berikutnya.

def add_grading_period(classroom, course_id):
    """
    A new grading period is added to the list, but it is not applied to existing courseWork.
    """
    try:
        # Use the `GetGradingPeriodSettings` endpoint to retrieve the existing
        # grading period IDs. You will need to include these IDs in the request
        # body to make sure existing grading periods aren't deleted.
        body = {
          "gradingPeriods": [
            {
              # Specify the ID to make sure the grading period is not deleted.
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              # Specify the ID to make sure the grading period is not deleted.
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            },
            {
              # Does not include an ID because this grading period is an addition.
              "title": "Summer",
              "start_date": {
                "day": 1,
                "month": 6,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 8,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": False
        }

        gradingPeriodSettings = classroom.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework',
          previewVersion="V1_20240401_PREVIEW").execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Petunjuk bermanfaat tentang kolom boolean applyToExistingCoursework

Perlu diingat bahwa boolean applyToExistingCoursework dipertahankan, yang berarti bahwa jika boolean ditetapkan ke True dalam panggilan API sebelumnya dan tidak diubah, pembaruan berikutnya pada periode penilaian akan diterapkan ke CourseWork yang ada.

Perhatikan bahwa jika Anda mengubah nilai boolean ini dari True menjadi False dalam permintaan ke UpdateGradingPeriodSettings, hanya perubahan baru yang Anda buat pada GradingPeriodSettings yang tidak akan diterapkan ke CourseWork yang ada. Semua informasi periode penilaian yang diterapkan ke CourseWork dalam panggilan API sebelumnya saat boolean ditetapkan ke True tidak akan dihapus. Cara yang berguna untuk memikirkan setelan boolean ini adalah bahwa setelan ini mendukung pengaitan CourseWork yang ada dengan periode penilaian yang Anda konfigurasikan, tetapi tidak mendukung penghapusan pengaitan yang ada antara CourseWork dan periode penilaian yang dikonfigurasi.

Jika Anda menghapus atau mengubah judul periode penilaian, perubahan tersebut akan disebarkan ke semua CourseWork yang ada, terlepas dari setelan boolean applyToExistingCoursework.

Memperbarui setiap periode penilaian dalam daftar

Untuk mengubah beberapa data yang terkait dengan periode penilaian yang ada, sertakan ID periode penilaian yang ada dalam daftar dengan data yang diubah.

Python

Dalam contoh ini, tanggal akhir periode penilaian "Musim Panas" akan diubah. Kolom applyToExistingCoursework akan ditetapkan ke True. Perhatikan bahwa menyetel boolean ini ke True akan menerapkan semua periode penilaian yang dikonfigurasi pada CourseWork yang ada. Dalam permintaan API sebelumnya, boolean ditetapkan ke False sehingga periode penilaian "Musim Panas" tidak diterapkan ke CourseWork yang ada. Setelah kolom boolean ini ditetapkan ke True, periode penilaian "Musim Panas" akan diterapkan ke semua CourseWork yang cocok.

def update_existing_grading_period(classroom, course_id):
    """
    An existing grading period is updated.
    """
    try:
        # Use the `GetGradingPeriodSettings` endpoint to retrieve the existing
        # grading period IDs. You will need to include these IDs in the request
        # body to make sure existing grading periods aren't deleted.
        body = {
          "gradingPeriods": [
            {
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            },
            {
              # The end date for this grading period will be modified from August 31, 2024 to September 10, 2024.
              # Include the grading period ID in the request along with the new data.
              "id": "SUMMER_GRADING_PERIOD_ID",
              "title": "Summer",
              "start_date": {
                "day": 1,
                "month": 6,
                "year": 2024
              },
              "end_date": {
                "day": 10,
                "month": 9,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": True
        }

        gradingPeriodSettings = classroom.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework',
          previewVersion="V1_20240401_PREVIEW").execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Menghapus periode penilaian satu per satu

Untuk menghapus periode penilaian, hapus periode penilaian dari daftar. Perhatikan bahwa jika periode penilaian dihapus, referensi apa pun ke periode penilaian di CourseWork juga akan dihapus, terlepas dari setelan applyToExistingCoursework.

Python

Untuk melanjutkan contoh dalam panduan ini, hapus periode penilaian, "Musim Panas", untuk menghapusnya.

def delete_grading_period(classroom, course_id):
    """
    An existing grading period is deleted.
    """
    try:
        body = {
          "gradingPeriods": [
            {
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            }
          ]
        }

        gradingPeriodSettings = classroom.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods',
          previewVersion="V1_20240401_PREVIEW").execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Mengelola kolom gradingPeriodId di CourseWork

Resource CourseWork menyertakan kolom gradingPeriodId. Anda dapat menggunakan endpoint CourseWork untuk membaca dan menulis periode penilaian yang terkait dengan CourseWork. Ada tiga cara untuk mengelola pengaitan ini:

  • pengaitan periode penilaian berbasis tanggal otomatis
  • periode penilaian terkait kustom
  • tidak ada asosiasi periode penilaian

1. Asosiasi periode penilaian berbasis tanggal

Saat membuat Tugas Mata Pelajaran, Anda dapat mengizinkan Classroom menangani atribusi periode penilaian untuk Anda. Untuk melakukannya, hapus kolom gradingPeriodId dari permintaan CourseWork. Kemudian, tentukan kolom dueDate atau scheduledTime dalam permintaan CourseWork. Jika dueDate berada dalam rentang tanggal periode penilaian yang ada, Classroom akan menetapkan ID periode penilaian tersebut di Tugas Kuliah. Jika kolom dueDate tidak ditentukan, Classroom akan menentukan gradingPeriodId berdasarkan kolom scheduledTime. Jika tidak ada kolom yang ditentukan, atau jika tidak ada kecocokan rentang tanggal periode penilaian, tidak ada gradingPeriodId yang akan ditetapkan di CourseWork.

2. Periode penilaian terkait kustom

Jika ingin mengaitkan CourseWork dengan periode penilaian yang berbeda dari periode yang sesuai dengan dueDate atau scheduledTime, Anda dapat menetapkan kolom gradingPeriodId secara manual saat membuat atau memperbarui CourseWork. Jika Anda menetapkan gradingPeriodId secara manual, Classroom tidak akan melakukan pengaitan periode penilaian berbasis tanggal secara otomatis.

3. Tidak ada asosiasi periode penilaian

Jika Anda tidak ingin CourseWork dikaitkan dengan periode penilaian apa pun, tetapkan kolom gradingPeriodId dalam permintaan CourseWork ke string kosong (gradingPeriodId: "").

Apa yang terjadi pada ID periode penilaian jika tanggal jatuh tempo diperbarui?

Jika Anda memperbarui kolom dueDate CourseWork dan ingin mempertahankan asosiasi periode penilaian kustom atau tidak ada, Anda harus menyertakan dueDate dan gradingPeriodId dalam updateMask dan isi permintaan. Tindakan ini akan memberi tahu Classroom untuk tidak mengganti gradingPeriodId dengan periode pemberian nilai yang cocok dengan dueDate baru.

Python

body = {
  "dueDate": {
    "month": 6,
    "day": 10,
    "year": 2024
  },
  "dueTime": {
    "hours": 7
  },
  "gradingPeriodId": "<INSERT-GRADING-PERIOD-ID-OR-EMPTY-STRING>"
}
courseWork = classroom.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId', # include the gradingPeriodId field in the updateMask
  previewVersion="V1_20240401_PREVIEW").execute()
Sebelumnya
Menetapkan &memperbarui nilai
Berikutnya
Batasan