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 theo phạm vi ngày cụ thể. API Lớp học cho phép nhà phát triển tạo, sửa đổi và đọc giai đoạn chấm điểm trong Lớp học thay mặt cho quản trị viên và giáo viên. Bạn cũng có thể sử dụng API Lớp học để đặt giai đoạn chấm điểm trên CourseWork.

API Lớp học cung cấp 2 điểm cuối để đọc và ghi thông tin về giai đoạn 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ý các 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á giai đoạn chấm điểm, cũng như áp dụng giai đoạn chấm điểm đã định cấu hình cho tất cả các 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á 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:

• Người dùng đưa ra yêu cầu sẽ được cấp giấy phép Google Workspace for Education Plus.
• Chủ sở hữu khoá học được cấp giấy phép Google Workspace for Education Plus.

Đọ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 giai đoạn chấm điểm, bất kể họ được cấp 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ể thêm gradingPeriodId khi tạo hoặc cập nhật Lớp học bằng API, bất kể họ được cấp giấy phép nào.

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

Mọi quản trị viên hoặc giáo viên đều được phép gửi yêu cầu đến điểm cuối checkGradingPeriodsSetupEligibility thay mặt cho họ. Sử dụng dữ liệu này để xác định xem người dùng có thể sửa đổi giai đoạn 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ã bằng Python và giả định rằng bạn đã:

• Một dự án trên Google Cloud. Bạn có thể thiết lập bằng cách làm theo hướng dẫn trong phần Bắt đầu nhanh về Python.
• Thêm các phạm vi sau vào màn hình xin phép bằng OAuth cho dự án của bạn:
  • https://www.googleapis.com/auth/classroom.courses
  • https://www.googleapis.com/auth/classroom.coursework.students
• Mã của một khoá học có giai đoạn chấm điểm cần được sửa đổi. 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 một giáo viên hoặc quản trị viên khi có 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 CourseWork. Quản trị viên không thể tạo hoặc sửa đổi CourseWork nếu họ 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 một danh sách GradingPeriods riêng lẻ và một trường boolean có tên applyToExistingCoursework.

Danh sách GradingPeriods thể hiện tất 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, đồng thời ngày bắt đầu và ngày kết thúc của các giai đoạn chấm điểm khác nhau 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.

Giá trị boolean applyToExistingCoursework là một chế độ cài đặt cố định, cho phép bạn sắp xếp CourseWork được tạo trước đó vào các giai đoạn chấm điểm mà không phải thực hiện lệnh gọi API riêng để sửa đổi gradingPeriodId cho từng CourseWork. Nếu bạn đặt chính sách này thành True, thì Lớp học sẽ tự động đặt gradingPeriodId cho tất cả Bài tập trên khoá học hiện có nếu courseWork.dueDate rơi vào ngày bắt đầu và ngày kết thúc của giai đoạn chấm điểm hiện tại. 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 hiển thị hoặc không có trường nào trùng 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 tại, thì CourseWork 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 dùng được tính năng 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

Bây giờ, khi bạn chắc chắn rằng người dùng có giấy phép cần thiết để sửa đổi các chế độ cài đặt giai đoạn chấm điểm trong một khoá học, bạn có thể bắt đầu gửi yêu cầu cho điểm cuối của UpdateGradingPeriodSettings. Mọi hoạt động sửa đổi đối với tài nguyên GradingPeriodSettings đều được thực hiện thông qua điểm cuối UpdateGradingPeriodSettings, bất kể bạn thêm giai đoạn chấm điểm riêng lẻ, sửa đổi giai đoạn chấm điểm hiện có hay xoá 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. Giá trị boolean applyToExistingCoursework được đặt thành True. Thao tác này sẽ sửa đổi gradingPeriodId trên mọi Lớp học hiện có nằm trong khoảng thời gian từ ngày bắt đầu đến ngày 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 chúng được trả về trong phản hồi. Bạn sẽ cần sử dụng các mã 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, dù có giấy phép gì, đề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 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 giai đoạn chấm điểm trong tài nguyên GradingPeriodSettings bằng điểm cuối GetGradingPeriodSettings.
2. Thực hiện các nội dung 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 biệt và không có sự trùng lặp giữa ngày bắt đầu và ngày kết thúc của 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. Giai đoạn chấm điểm được thêm vào danh sách mà không có mã nhận dạng được coi là bổ sung.
2. Giai đoạn chấm điểm bị thiếu trong danh sách được coi là dấu xoá.
3. Giai đoạn chấm điểm với 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. Giai đoạn chấm điểm bằng mã nhận dạng mới hoặc không xác định bị coi là lỗi.

Lưu ý quan trọng: Hãy nhớ đưa mã nhận dạng của mọi giai đoạn chấm điểm mà bạn không muốn xoá vào yêu cầu UpdateGradingPeriodSettings.

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 sẽ được tạo với tiêu đề "Mùa hè". boolean applyToExistingCoursework được đặt thành False trong nội dung yêu cầu.

Để làm việc này, GradingPeriodSettings hiện tại sẽ được đọc, một giai đoạn chấm điểm mới sẽ được thêm vào danh sách và boolean applyToExistingCoursework được đặt thành False. Xin lưu ý rằng mọi giai đoạn chấm điểm đã áp dụng cho CourseWork hiện tại 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 Khoá học nếu applyToExistingCoursework được đặt thành False 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

Con trỏ hữu ích về trường boolean applyToExistingCoursework

Điều quan trọng cần nhớ là boolean applyToExistingCoursework được giữ nguyên, 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 nội dung cập nhật tiếp theo cho 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ề giai đoạn chấm điểm áp dụng cho CourseWork trong các lệnh gọi API trước đây khi giá trị 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 giai đoạn chấm điểm, những thay đổi đó sẽ được áp dụng qua tất cả Bài tập trên khoá học hiện có, bất kể chế độ cài đặt của giá trị boolean applyToExistingCoursework là gì.

Lưu ý quan trọng: Việc đặt trường applyToExistingCoursework thành False sẽ không xoá bất kỳ giai đoạn chấm điểm và mối liên kết nào đã có từ trước đối với Khoá học. Việc xoá hoặc thay đổi tên của giai đoạn chấm điểm sẽ được áp dụng trên tất cả Bài tập trên khoá học bất kể chế độ cài đặt applyToExistingCoursework là gì.

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 giai đoạn chấm điểm hiện có, hãy thêm mã nhận dạng của giai đoạn 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 giai đoạn chấm điểm "Mùa hè" sẽ được sửa đổi. Trường applyToExistingCoursework sẽ được đặt thành True. Lưu ý rằng việc đặt giá trị boolean này thành True sẽ áp dụng tất cả giai đoạn chấm điểm đã định cấu hình trên CourseWork hiện có. Trong yêu cầu API trước đó, boolean được đặt thành False để giai đoạn chấm điểm "Mùa hè" không được áp dụng cho Bài tập hiện tại. Giờ đây, trường boolean này đã được đặt thành True, nên giai đoạn chấm điểm "Mùa hè" sẽ được áp dụng cho mọi trường hợp hiện có trùng khớp trên một Khóa học.

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á từng giai đoạn chấm điểm

Để 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 giai đoạn chấm điểm bị xoá, mọi thông tin tham chiếu đến giai đoạn chấm điểm trênCourseWork 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 của CourseWork có một trường gradingPeriodId. Bạn có thể sử dụng các điểm cuối của Lớp học để đọc và ghi giai đoạn chấm điểm liên kết với một Bài tập Khoá học. 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 liên quan
• không 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 Khoá học, bạn có thể cho phép Lớp học xử lý việc liên kết giai đoạn 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 của CourseWork. Sau đó, hãy chỉ định các trường dueDate hoặc scheduledTime trong yêu cầu của CourseWork. Nếu dueDate rơi vào một phạm vi ngày của giai đoạn chấm điểm hiện có, Lớp học sẽ đặt mã giai đoạn chấm điểm đó trên CourseWork. Nếu bạn không chỉ định trường dueDate, Lớp học sẽ xác định gradingPeriodId dựa trên trường scheduledTime. Nếu bạn không chỉ định trường nào hoặc nếu không có phạm vi ngày nào trong 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 liên kết

Nếu muốn liên kết CourseWork với một giai đoạn chấm điểm khác với giai đoạn chấm điểm tương ứng 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, Lớp học sẽ không tự động liên kết 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 bạn cập nhật ngày đến hạn?

Nếu bạn đang cập nhật trường dueDate của CourseWork 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 muốn dùng 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()

Lưu ý quan trọng: Khi cập nhật trường dueDate của một CourseWork, hãy thêm trường gradingPeriodId vào updateMask và yêu cầu nội dung để lưu giữ một trường tuỳ chỉnh hoặc không có mối liên kết nào. Việc này sẽ đảm bảo Lớp học không ghi đè trường gradingPeriodId bằng trường khớp với dueDate mới.