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. Classroom API juga dapat digunakan 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 di 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 CourseWork yang ada.

Persyaratan pemberian lisensi

Mengubah setelan periode penilaian dalam kursus

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

Membaca setelan periode penilaian dalam kursus

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

Menetapkan ID periode penilaian di CourseWork

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

Memeriksa kelayakan pengguna untuk menyiapkan periode penilaian

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

Prasyarat

Panduan ini menyediakan contoh kode di Python, dan mengasumsikan Anda telah:

  • Project Google Cloud. Anda dapat membuatnya 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 CourseWork. Administrator tidak dapat membuat atau memodifikasi CourseWork jika mereka bukan pengajar dalam kursus.

Mengelola resource GradingPeriodSettings

Resource GradingPeriodSettings mencakup daftar GradingPeriods individu 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 individual dalam daftar. Setiap periode penilaian dalam kursus harus memiliki judul yang unik, serta tanggal mulai dan akhir periode penilaian yang berbeda tidak boleh tumpang-tindih. Setiap periode penilaian akan memiliki ID yang ditetapkan Classroom API masing-masing.

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

Menentukan apakah pengguna dapat mengubah setelan periode penilaian dalam kursus

Karena kemampuan untuk membuat dan mengubah periode penilaian di Classroom hanya tersedia bagi 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

Tambahkan periode penilaian

Setelah Anda 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, atau menghapus periode penilaian.

Python

Pada contoh berikut, resource gradingPeriodSettings diubah untuk menyertakan dua periode penilaian. Boolean applyToExistingCoursework ditetapkan ke True yang akan mengubah gradingPeriodId pada CourseWork yang ada dan berada di antara tanggal mulai dan akhir periode penilaian. Perhatikan bahwa updateMask menyertakan kedua kolom. 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

Baca 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 periode penilaian satu per satu 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. Buat perubahan 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 penambahan.
  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 dibiarkan apa adanya.
  4. Periode penilaian dengan ID baru atau yang tidak diketahui dianggap sebagai error.

Python

Kode berikut akan dibuat berdasarkan contoh dalam panduan ini. Periode penilaian baru dibuat dengan judul, "{i>Summer<i}/Musim Panas". Boolean applyToExistingCoursework ditetapkan ke False dalam isi permintaan.

Untuk melakukannya, GradingPeriodSettings saat ini akan dibaca, periode penilaian baru ditambahkan ke daftar, dan boolean applyToExistingCoursework ditetapkan ke False. Perhatikan bahwa setiap periode penilaian yang telah diterapkan ke CourseWork yang ada tidak akan dihapus. Pada contoh sebelumnya, periode penilaian "Semester 1" dan "Semester 2" sudah 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

Pointer berguna tentang kolom boolean applyToExistingCoursework

Penting untuk diingat bahwa boolean applyToExistingCoursework dipertahankan, artinya jika boolean ditetapkan ke True dalam panggilan API sebelumnya dan tidak diubah, pembaruan periode penilaian berikutnya 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. Informasi periode penilaian apa pun yang diterapkan ke CourseWork di panggilan API sebelumnya saat boolean ditetapkan ke True tidak akan dihapus. Cara terbaik untuk memahami setelan boolean ini adalah karena setelan ini mendukung pengaitan CourseWork yang ada dengan periode penilaian yang telah dikonfigurasi, 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 diterapkan ke semua CourseWork yang ada, terlepas dari setelan boolean applyToExistingCoursework.

Memperbarui periode penilaian satu per satu dalam daftar

Untuk mengubah beberapa data yang terkait dengan periode penilaian yang sudah 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. Perlu diperhatikan bahwa menetapkan 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 ada 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. Perlu diperhatikan bahwa jika periode penilaian dihapus, semua referensi ke periode penilaian di CourseWork juga akan dihapus terlepas dari setelan applyToExistingCoursework.

Python

Untuk melanjutkan contoh dalam panduan ini, hapus periode penilaian, "Summer", 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 mencakup 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 khusus
  • tidak ada pengaitan periode penilaian

1. Pengaitan periode penilaian berbasis tanggal

Saat membuat CourseWork, Anda dapat mengizinkan Classroom menangani pengaitan periode penilaian untuk Anda. Untuk melakukannya, hapus kolom gradingPeriodId dari permintaan CourseWork. Kemudian, tentukan kolom dueDate atau scheduledTime dalam permintaan CourseWork. Jika dueDate termasuk dalam rentang tanggal periode penilaian yang sudah ada, Classroom akan menetapkan ID periode penilaian tersebut di CourseWork. 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 khusus

Jika ingin mengaitkan CourseWork dengan periode penilaian yang berbeda dengan 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 otomatis.

3. Tidak ada pengaitan 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 batas waktu diperbarui?

Jika Anda memperbarui kolom dueDate CourseWork dan ingin mempertahankan pengaitan periode penilaian kustom atau tanpa periode penilaian, Anda harus menyertakan dueDate dan gradingPeriodId dalam updateMask dan isi permintaan. Tindakan ini akan memberi tahu Classroom agar tidak mengganti gradingPeriodId dengan periode penilaian yang sesuai dengan dueDate yang 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()