Quản lý giai đoạn chấm điểm bằng API Lớp học

Hướng dẫn này giải thích cách sử dụng điểm cuối của giai đoạn chấm điểm trong API Google Lớp học.

Tổng quan

Giai đoạn chấm điểm được tạo để sắp xếp bài tập về nhà, bài kiểm tra và dự án vào các phạm vi ngày cụ thể. API Lớp học cho phép nhà phát triển thay mặt quản trị viên và giáo viên tạo, sửa đổi và đọc các giai đoạn chấm điểm trong Lớp học. Bạn cũng có thể sử dụng API Lớp học để đặt khoảng thời gian chấm điểm trên CourseWork.

API Lớp học cung cấp hai điểm cuối để đọc và ghi thông tin về khoảng thời gian chấm điểm trong một khoá học:

  • GetGradingPeriodSettings: Cho phép bạn đọc chế độ cài đặt giai đoạn chấm điểm trong một khoá học.
  • UpdateGradingPeriodSettings: Cho phép bạn quản lý chế độ cài đặt giai đoạn chấm điểm trong một khoá học bằng cách thêm, sửa đổi và xoá các giai đoạn chấm điểm, đồng thời áp dụng các giai đoạn chấm điểm đã định cấu hình cho tất cả Bài tập trong khoá học hiện có.

Yêu cầu về giấy phép

Sửa đổi chế độ cài đặt giai đoạn chấm điểm trong một khoá học

Để tạo, sửa đổi hoặc xoá các giai đoạn chấm điểm trong một khoá học bằng điểm cuối UpdateGradingPeriodSettings, bạn phải đáp ứng các điều kiện sau:

Đọc chế độ cài đặt giai đoạn chấm điểm trong một khoá học

Quản trị viên miền và giáo viên của một khoá học có thể đọc chế độ cài đặt khoảng thời gian chấm điểm bất kể họ được chỉ định loại giấy phép nào. Điều này có nghĩa là mọi quản trị viên miền hoặc giáo viên sẽ được phép yêu cầu điểm cuối GetGradingPeriodSettings thay mặt cho mọi quản trị viên miền.

Đặt mã giai đoạn chấm điểm trên CourseWork

Giáo viên của một khoá học có thể đưa gradingPeriodId vào khi tạo hoặc cập nhật CourseWork bằng API, bất kể họ được chỉ định giấy phép nào.

Kiểm tra xem người dùng có đủ điều kiện thiết lập giai đoạn chấm điểm hay không

Các yêu cầu đến điểm cuối checkGradingPeriodsSetupEligibility được phép thay mặt cho bất kỳ quản trị viên hoặc giáo viên nào. Sử dụng thuộc tính này để xác định xem người dùng có thể sửa đổi khoảng thời gian chấm điểm trong một khoá học hay không.

Điều kiện tiên quyết

Hướng dẫn này cung cấp các ví dụ về mã trong Python và giả định rằng bạn đã:

  • Một dự án trên Google Cloud. Bạn có thể thiết lập một môi trường theo hướng dẫn trong bài viết Bắt đầu nhanh với Python.
  • Thêm các phạm vi sau vào màn hình xin phép bằng OAuth của dự án:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • Mã của một khoá học mà bạn cần sửa đổi giai đoạn chấm điểm. Chủ sở hữu khoá học phải có giấy phép Google Workspace for Education Plus.
  • Quyền truy cập vào thông tin đăng nhập của giáo viên hoặc quản trị viên thông qua giấy phép Google Workspace for Education Plus. Bạn cần có thông tin đăng nhập của giáo viên để tạo hoặc sửa đổi Bài tập. Quản trị viên không thể tạo hoặc sửa đổi Bài tập nếu không phải là giáo viên trong khoá học.

Quản lý tài nguyên GradingPeriodSettings

Tài nguyên GradingPeriodSettings bao gồm danh sách các GradingPeriods riêng lẻ và một trường boolean có tên là applyToExistingCoursework.

Danh sách GradingPeriods đại diện cho tất cả các giai đoạn chấm điểm riêng lẻ trong một khoá học. Bạn phải chỉ định tiêu đề, ngày bắt đầu và ngày kết thúc cho từng giai đoạn chấm điểm riêng lẻ trong danh sách. Mỗi giai đoạn chấm điểm trong một khoá học phải có một tiêu đề riêng biệt và ngày bắt đầu và ngày kết thúc của các giai đoạn chấm điểm không được trùng lặp. Mỗi giai đoạn chấm điểm sẽ có giá trị nhận dạng riêng do API Lớp học chỉ định.

Boolean applyToExistingCoursework là một chế độ cài đặt ổn định cho phép bạn sắp xếp Bài tập đã tạo trước đó thành các giai đoạn chấm điểm mà không cần thực hiện lệnh gọi API riêng để sửa đổi gradingPeriodId cho từng Bài tập. Nếu bạn đặt giá trị này thành True, Lớp học sẽ tự động đặt gradingPeriodId trên tất cả Bài tập trên lớp hiện có nếu courseWork.dueDate nằm trong khoảng thời gian bắt đầu và kết thúc của một kỳ chấm điểm hiện có. Nếu bạn không đặt ngày đến hạn trên CourseWork, Lớp học sẽ sử dụng courseWork.scheduledTime. Nếu không có trường nào hoặc không có ngày khớp trong ngày bắt đầu và ngày kết thúc của giai đoạn chấm điểm hiện có, thì Bài tập sẽ không được liên kết với bất kỳ giai đoạn chấm điểm nào.

Xác định xem người dùng có thể sửa đổi chế độ cài đặt giai đoạn chấm điểm trong một khoá học hay không

Vì chỉ những người dùng có giấy phép cụ thể mới có thể tạo và sửa đổi giai đoạn chấm điểm trong Lớp học, nên API Lớp học cung cấp điểm cuối checkGradingPeriodsSetupEligibility để giúp bạn chủ động xác định xem người dùng có thể gửi yêu cầu đến điểm cuối UpdateGradingPeriodSettings hay không.

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

Thêm giai đoạn chấm điểm

Giờ đây, khi đã chắc chắn rằng người dùng có giấy phép cần thiết để sửa đổi chế độ cài đặt khoảng thời gian chấm điểm trong một khoá học, bạn có thể bắt đầu đưa ra yêu cầu cho điểm cuối UpdateGradingPeriodSettings. Mọi nội dung sửa đổi đối với tài nguyên GradingPeriodSettings đều được thực hiện bằng cách sử dụng điểm cuối UpdateGradingPeriodSettings, cho dù bạn đang thêm các giai đoạn chấm điểm riêng lẻ, sửa đổi các giai đoạn chấm điểm hiện có hay xoá một giai đoạn chấm điểm.

Python

Trong ví dụ sau, tài nguyên gradingPeriodSettings được sửa đổi để bao gồm hai giai đoạn chấm điểm. Boolean applyToExistingCoursework được đặt thành True. Giá trị này sẽ sửa đổi gradingPeriodId trên bất kỳ Bài tập hiện có nào nằm trong khoảng thời gian bắt đầu và kết thúc của một giai đoạn chấm điểm. Xin lưu ý rằng updateMask bao gồm cả hai trường. Lưu mã nhận dạng cho từng giai đoạn chấm điểm sau khi các mã này được trả về trong phản hồi. Bạn sẽ cần sử dụng các mã nhận dạng này để cập nhật giai đoạn chấm điểm nếu cần.

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

Đọc chế độ cài đặt giai đoạn chấm điểm

GradingPeriodSettings được đọc bằng điểm cuối GetGradingPeriodSettings. Mọi người dùng, bất kể giấy phép, đều có thể đọc chế độ cài đặt giai đoạn chấm điểm trong một khoá học.

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

Thêm một giai đoạn chấm điểm riêng lẻ vào danh sách

Bạn phải cập nhật từng giai đoạn chấm điểm theo mẫu đọc-sửa đổi-ghi. Điều này có nghĩa là bạn nên:

  1. Đọc danh sách các giai đoạn chấm điểm trong tài nguyên GradingPeriodSettings bằng cách sử dụng điểm cuối GetGradingPeriodSettings.
  2. Thực hiện các sửa đổi đã chọn đối với danh sách giai đoạn chấm điểm.
  3. Gửi danh sách giai đoạn chấm điểm mới trong yêu cầu đến UpdateGradingPeriodSettings.

Mẫu này sẽ giúp bạn đảm bảo rằng tiêu đề của từng giai đoạn chấm điểm trong một khoá học là khác nhau và không trùng lặp giữa ngày bắt đầu và ngày kết thúc của các giai đoạn chấm điểm.

Xin lưu ý các quy tắc sau đây khi cập nhật danh sách giai đoạn chấm điểm:

  1. Các giai đoạn chấm điểm được thêm vào danh sách mà không có mã được coi là phần bổ sung.
  2. Các giai đoạn chấm điểm thiếu trong danh sách được coi là bị xoá.
  3. Các giai đoạn chấm điểm có mã nhận dạng hiện có nhưng dữ liệu đã sửa đổi được coi là bản chỉnh sửa. Các thuộc tính chưa sửa đổi sẽ giữ nguyên.
  4. Các giai đoạn chấm điểm có mã nhận dạng mới hoặc không xác định được coi là lỗi.

Python

Mã sau đây sẽ dựa trên ví dụ trong hướng dẫn này. Một giai đoạn chấm điểm mới được tạo với tiêu đề là "Mùa hè". Boolean applyToExistingCoursework được đặt thành False trong nội dung yêu cầu.

Để thực hiện việc này, GradingPeriodSettings hiện tại sẽ được đọc, một khoảng thời gian chấm điểm mới sẽ được thêm vào danh sách và boolean applyToExistingCoursework sẽ được đặt thành False. Xin lưu ý rằng mọi giai đoạn chấm điểm đã được áp dụng cho Bài tập trên lớp hiện có sẽ không bị xoá. Trong ví dụ trước, giai đoạn chấm điểm "Học kỳ 1" và "Học kỳ 2" đã được áp dụng cho Bài tập Khoá học hiện tại và sẽ không bị xoá khỏi Khóa học nếu bạn đặt applyToExistingCoursework thành Sai trong các yêu cầu tiếp theo.

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

Các con trỏ hữu ích về trường boolean applyToExistingCoursework

Điều quan trọng cần nhớ là boolean applyToExistingCoursework được duy trì, nghĩa là nếu boolean được đặt thành True trong lệnh gọi API trước đó và không thay đổi, thì các bản cập nhật tiếp theo cho các giai đoạn chấm điểm sẽ được áp dụng cho CourseWork hiện có.

Lưu ý rằng nếu bạn thay đổi giá trị boolean này từ True thành False trong yêu cầu đến UpdateGradingPeriodSettings, thì chỉ những thay đổi mới mà bạn đang thực hiện đối với GradingPeriodSettings mới không được áp dụng cho CourseWork hiện có. Mọi thông tin về khoảng thời gian chấm điểm áp dụng cho Bài tập trong các lệnh gọi API trước đó khi boolean được đặt thành True sẽ không bị xoá. Một cách hữu ích để bạn xem xét chế độ cài đặt boolean này là chế độ này hỗ trợ việc liên kết Khoá học hiện có với giai đoạn chấm điểm đã định cấu hình, nhưng không hỗ trợ việc xoá các mối liên kết hiện có giữa CourseWork và giai đoạn chấm điểm đã định cấu hình.

Nếu bạn xoá hoặc thay đổi tiêu đề của một kỳ chấm điểm, thì những thay đổi đó sẽ được truyền qua tất cả Bài tập hiện có, bất kể chế độ cài đặt của boolean applyToExistingCoursework.

Cập nhật từng giai đoạn chấm điểm trong danh sách

Để sửa đổi một số dữ liệu liên kết với một kỳ chấm điểm hiện có, hãy thêm mã nhận dạng của kỳ chấm điểm hiện có vào danh sách cùng với dữ liệu đã sửa đổi.

Python

Trong ví dụ này, ngày kết thúc kỳ chấm điểm "Mùa hè" sẽ được chỉnh sửa. Trường applyToExistingCoursework sẽ được đặt thành True. Xin lưu ý rằng việc đặt boolean này thành True sẽ áp dụng tất cả các giai đoạn chấm điểm đã định cấu hình trên Bài tập hiện có. Trong yêu cầu API trước, boolean được đặt thành False để không áp dụng giai đoạn chấm điểm "Mùa hè" cho Bài tập hiện có. Giờ đây, khi trường boolean này được đặt thành True, thì giai đoạn chấm điểm "Mùa hè" sẽ được áp dụng cho tất cả các Bài tập hiện có khớp với giai đoạn này.

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

Xoá một giai đoạn chấm điểm riêng lẻ

Để xoá một giai đoạn chấm điểm, hãy bỏ giai đoạn chấm điểm đó khỏi danh sách. Xin lưu ý rằng nếu một giai đoạn chấm điểm bị xoá, thì mọi nội dung tham chiếu đến giai đoạn chấm điểm đó trên CourseWork cũng sẽ bị xoá, bất kể chế độ cài đặt applyToExistingCoursework là gì.

Python

Để tiếp tục ví dụ trong hướng dẫn này, hãy bỏ qua giai đoạn chấm điểm "Mùa hè" để xoá giai đoạn chấm điểm.

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

Quản lý trường gradingPeriodId trên CourseWork

Tài nguyên CourseWork bao gồm một trường gradingPeriodId. Bạn có thể sử dụng các điểm cuối của Bài tập để đọc và ghi giai đoạn chấm điểm liên kết với một Bài tập. Có 3 cách để quản lý mối liên kết này:

  • tự động liên kết giai đoạn chấm điểm dựa trên ngày
  • giai đoạn chấm điểm tuỳ chỉnh được liên kết
  • không có liên kết giai đoạn chấm điểm

1. Liên kết giai đoạn chấm điểm dựa trên ngày

Khi tạo Bài tập, bạn có thể cho phép Lớp học xử lý việc liên kết khoảng thời gian chấm điểm cho bạn. Để thực hiện việc này, hãy bỏ qua trường gradingPeriodId khỏi yêu cầu CourseWork. Sau đó, hãy chỉ định các trường dueDate hoặc scheduledTime trong yêu cầu CourseWork. Nếu dueDate nằm trong phạm vi ngày của khoảng thời gian chấm điểm hiện có, thì Lớp học sẽ đặt mã nhận dạng khoảng thời gian chấm điểm đó trên Bài tập. Nếu bạn không chỉ định trường dueDate, thì Classroom sẽ xác định gradingPeriodId dựa trên trường scheduledTime. Nếu không có trường nào được chỉ định hoặc nếu không có phạm vi ngày của giai đoạn chấm điểm trùng khớp, thì sẽ không có gradingPeriodId nào được đặt trên CourseWork.

2. Giai đoạn chấm điểm tuỳ chỉnh được liên kết

Nếu muốn liên kết CourseWork với một khoảng thời gian chấm điểm khác với khoảng thời gian phù hợp với dueDate hoặc scheduledTime, bạn có thể đặt trường gradingPeriodId theo cách thủ công khi tạo hoặc cập nhật CourseWork. Nếu bạn đặt gradingPeriodId theo cách thủ công, thì Lớp học sẽ không thực hiện việc liên kết tự động giai đoạn chấm điểm dựa trên ngày.

3. Không liên kết giai đoạn chấm điểm

Nếu bạn hoàn toàn không muốn liên kết CourseWork với bất kỳ giai đoạn chấm điểm nào, hãy đặt trường gradingPeriodId trong yêu cầu của CourseWork thành một chuỗi trống (gradingPeriodId: "").

Điều gì sẽ xảy ra với mã giai đoạn chấm điểm nếu ngày đến hạn được cập nhật?

Nếu bạn đang cập nhật trường "courseWork dueDate" và muốn giữ nguyên mối liên kết giữa giai đoạn chấm điểm tuỳ chỉnh hoặc không có giai đoạn chấm điểm, bạn nên thêm dueDate và gradingPeriodId vào mặt nạ cập nhật và nội dung yêu cầu. Thao tác này sẽ yêu cầu Lớp học không ghi đè gradingPeriodId có giai đoạn chấm điểm khớp với dueDate mới.

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