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 di kursus dengan menambahkan, mengubah, dan menghapus periode penilaian, serta menerapkan periode penilaian yang dikonfigurasi ke semua Tugas Kelas yang ada.

Persyaratan pemberian lisensi dan kelayakan

Mengubah setelan periode penilaian dalam kursus

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

• Pengguna yang membuat permintaan harus berupa pengajar dalam kursus atau administrator.
• Pengguna yang membuat permintaan memiliki lisensi Google Workspace for Education Plus yang ditetapkan untuknya.
• Pemilik kursus memiliki lisensi Google Workspace for Education Plus yang ditetapkan kepadanya.

Membaca setelan periode penilaian dalam kursus

Administrator domain dan pengajar kursus dapat membaca setelan periode penilaian, terlepas dari lisensi yang ditetapkan kepada 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 kepada mereka.

Memeriksa kelayakan pengguna untuk menyiapkan periode penilaian

Permintaan ke endpoint userProfiles.checkUserCapability diizinkan atas nama administrator atau pengajar mana pun. Gunakan ini untuk menentukan apakah pengguna dapat mengubah periode penilaian.

Prasyarat

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

• Project Google Cloud. Anda dapat menyiapkannya dengan mengikuti petunjuk di Panduan memulai cepat 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 mengubah CourseWork jika mereka bukan pengajar dalam kursus.

Mengelola resource GradingPeriodSettings

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

Pastikan setiap GradingPeriods dalam daftar memenuhi persyaratan berikut:

• Judul, tanggal mulai, dan tanggal akhir: Setiap periode penilaian harus memiliki judul, tanggal mulai, dan tanggal akhir.
• Judul unik: Setiap periode penilaian harus memiliki judul unik yang tidak sama dengan periode penilaian lain dalam kursus.
• Tanggal yang tidak tumpang-tindih: Setiap periode penilaian tidak boleh memiliki tanggal mulai atau akhir yang tumpang-tindih dengan periode penilaian lainnya dalam kursus.
• Urutan kronologis: Periode penilaian harus dicantumkan dalam urutan kronologis berdasarkan tanggal mulai dan akhir.

Setiap periode penilaian akan diberi ID yang ditetapkan Classroom API saat dibuat.

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 disetel ke True, Classroom akan otomatis menyetel gradingPeriodId di semua CourseWork yang ada jika courseWork.dueDate berada dalam rentang tanggal mulai dan akhir periode penilaian yang ada. Jika tidak ada tanggal batas waktu yang ditetapkan pada CourseWork, Classroom akan menggunakan courseWork.scheduledTime. Jika kedua kolom tidak ada atau tidak ada kecocokan dalam tanggal mulai dan akhir periode penilaian yang ada, CourseWork tidak akan dikaitkan dengan periode penilaian apa pun.

Menentukan apakah pengguna dapat mengubah setelan periode penilaian dalam kursus

Classroom API menyediakan endpoint userProfiles.checkUserCapability untuk membantu Anda secara proaktif menentukan apakah pengguna dapat membuat permintaan ke endpoint UpdateGradingPeriodSettings.

Peringatan: Endpoint userProfiles.checkUserCapability hanya mengevaluasi apakah pengguna memenuhi syarat untuk menggunakan kemampuan tertentu, seperti mengubah periode penilaian. Tidak ada informasi tentang peran kursus. Misalnya, meskipun pengguna memiliki kemampuan UPDATE_GRADING_PERIOD_SETTINGS, jika dia adalah siswa dalam kursus, permintaan ke endpoint UpdateGradingPeriodSettings tidak akan berhasil.

Python

def check_grading_periods_update_capability(classroom_service, course_id):
    """Checks whether a user is able to create and modify grading periods in a course."""
    try:
        capability = classroom_service.userProfiles().checkUserCapability(
          userId="me",
          capability="UPDATE_GRADING_PERIOD_SETTINGS",
           # Required while the checkUserCapability method is available in the Developer Preview Program.
          previewVersion="V1_20240930_PREVIEW"
        ).execute()

        # Retrieve the `allowed` boolean from the response.
        if capability.get("allowed"):
          print("User is allowed to update grading period settings in the course.")
        else:
          print("User is not allowed to update grading period settings in the course.")
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Menambahkan periode penilaian

Setelah Anda yakin bahwa pengguna memenuhi syarat untuk mengubah setelan periode penilaian dalam kursus, Anda dapat mulai mengirim permintaan ke endpoint UpdateGradingPeriodSettings. Setiap modifikasi pada resource GradingPeriodSettings dilakukan menggunakan endpoint UpdateGradingPeriodSettings, baik saat Anda menambahkan periode penilaian satu per satu, mengubah periode penilaian yang ada, atau menghapus periode penilaian.

Python

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

def create_grading_periods(classroom_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id,
          updateMask='gradingPeriods,applyToExistingCoursework',
          body=body
        ).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 lisensi, dapat membaca setelan periode penilaian dalam kursus.

Python

def get_grading_period_settings(classroom_service, course_id):
    """Read grading periods settings in a course."""
    try:
        gradingPeriodSettings = classroom_service.courses().getGradingPeriodSettings(
          courseId=course_id).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 periode penilaian tertentu harus dilakukan dengan mengikuti pola baca-ubah-tulis. Artinya, Anda harus:

1. Baca daftar periode penilaian dalam resource GradingPeriodSettings menggunakan endpoint GetGradingPeriodSettings.
2. Lakukan 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 dimodifikasi dianggap sebagai pengeditan. Properti yang tidak diubah akan tetap seperti semula.
4. Periode penilaian dengan ID baru atau tidak diketahui dianggap sebagai error.

Penting: Pastikan Anda menyertakan ID periode penilaian yang tidak ingin Anda hapus dalam permintaan UpdateGradingPeriodSettings.

Python

Kode berikut akan dibuat berdasarkan contoh dalam panduan ini. Periode penilaian baru dibuat dengan judul, "Summer". Boolean applyToExistingCoursework disetel 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 CourseWork 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 disetel ke False dalam permintaan berikutnya.

def add_grading_period(classroom_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').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

Penting untuk diingat bahwa boolean applyToExistingCoursework akan dipertahankan, yang berarti 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 lakukan pada GradingPeriodSettings yang tidak akan diterapkan ke CourseWork yang ada. Informasi periode penilaian yang diterapkan ke CourseWork dalam panggilan API sebelumnya saat boolean disetel 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 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.

Penting: Menetapkan kolom applyToExistingCoursework ke False tidak akan menghapus periode penilaian dan asosiasi CourseWork yang sudah ada. Menghapus atau mengubah judul periode penilaian akan diterapkan di semua Tugas Kelas, terlepas dari setelan applyToExistingCoursework.

Memperbarui periode penilaian tertentu 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 berakhir periode penilaian "Summer" 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. Pada permintaan API sebelumnya, boolean disetel ke False sehingga periode penilaian "Summer" tidak diterapkan ke CourseWork yang ada. Sekarang, setelah kolom boolean ini disetel ke True, periode penilaian "Summer" akan diterapkan ke semua CourseWork yang ada dan cocok.

def update_existing_grading_period(classroom_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').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, hilangkan periode penilaian dari daftar. Perhatikan 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_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods').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 hubungan ini:

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

1. Asosiasi periode penilaian berbasis tanggal

Saat membuat TugasKelas, Anda dapat mengizinkan Classroom menangani asosiasi 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 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 kustom

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 mengupdate CourseWork. Jika Anda menetapkan gradingPeriodId secara manual, Classroom tidak akan melakukan pengaitan periode penilaian otomatis berbasis tanggal.

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: "").

Jika Anda menggunakan bahasa pemrograman Go dan tidak ingin menetapkan periode penilaian, Anda juga harus menyertakan kolom ForceSendFields dalam isi permintaan. Dengan library klien Go, nilai default dihilangkan dari permintaan API karena adanya tag kolom omitempty di semua kolom. Kolom ForceSendFields melewati hal ini dan mengirimkan string kosong untuk menunjukkan bahwa Anda tidak ingin periode penilaian ditetapkan untuk CourseWork tersebut. Lihat dokumentasi library klien Go Google API untuk mengetahui informasi selengkapnya.

Go

courseWork := &classroom.CourseWork{
  Title: "Homework questions",
  WorkType: "ASSIGNMENT",
  State: "DRAFT",
  // ...other CourseWork fields...
  GradingPeriodId: "",
  ForceSendFields: []string{"GradingPeriodId"},
}

Penting: Jika menggunakan bahasa pemrograman Go, sertakan kolom ForceSendFields di isi permintaan agar library klien dapat mengirim nilai default.

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 di updateMask dan isi permintaan. Tindakan ini akan memberi tahu Classroom untuk tidak mengganti gradingPeriodId dengan periode penilaian 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_service.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId') # include the gradingPeriodId field in the updateMask
.execute()

Penting: Saat mengupdate kolom dueDate CourseWork, sertakan kolom gradingPeriodId di updateMask dan isi permintaan untuk mempertahankan atau tidak ada asosiasi kustom. Tindakan ini akan memastikan bahwa Classroom tidak mengganti kolom gradingPeriodId dengan kolom yang cocok dengan dueDate baru.