Zarządzanie okresami oceniania przy użyciu interfejsu Classroom API

Z tego przewodnika dowiesz się, jak używać punktów końcowych okresów oceniania w interfejsie Google Classroom API.

Omówienie

Okresy oceniania są tworzone w celu uporządkowania prac domowych, testów i projektów w określonych zakresach dat. Interfejs Classroom API umożliwia deweloperom tworzenie, modyfikowanie i odczytywanie okresów oceniania w Classroom w imieniu administratorów i nauczycieli. Interfejsu Classroom API możesz też używać do określania okresów oceniania w usłudze CourseWork.

Interfejs Classroom API udostępnia 2 punkty końcowe do odczytu i zapisu informacji o okresie oceniania w kursie:

• GetGradingPeriodSettings: umożliwia odczytanie ustawień okresu oceniania w kursie.
• UpdateGradingPeriodSettings: umożliwia zarządzanie ustawieniami okresów oceniania w kursie poprzez dodawanie, modyfikowanie i usuwanie okresów oceniania oraz stosowanie skonfigurowanych okresów oceniania do wszystkich istniejących zadań z kursu.

Wymagania dotyczące licencjonowania i kryteria kwalifikacji

Modyfikowanie ustawień okresu oceniania na zajęciach

Aby utworzyć, zmodyfikować lub usunąć okresy oceniania w kursie za pomocą punktu końcowego UpdateGradingPeriodSettings, muszą być spełnione te warunki:

• Użytkownik przesyłający prośbę musi być nauczycielem na zajęciach lub administratorem.
• Użytkownik przesyłający prośbę ma przypisaną licencję na Google Workspace for Education Plus.
• właściciel kursu ma przypisaną licencję Google Workspace for Education Plus.

Odczytywanie ustawień okresu oceniania na zajęciach

Administratorzy domeny i nauczyciele zajęć mogą czytać ustawienia okresu oceniania niezależnie od tego, jaka licencja jest im przypisana. Oznacza to, że żądania do punktu końcowego GetGradingPeriodSettings są dozwolone w imieniu dowolnego administratora domeny lub nauczyciela.

Ustawianie identyfikatora okresu oceniania w CourseWork

Nauczyciele mogą uwzględnić gradingPeriodId podczas tworzenia lub aktualizowania zajęć za pomocą interfejsu API niezależnie od przypisanej licencji.

Sprawdzanie, czy użytkownik może konfigurować okresy oceniania

W ramach żądań do punktu końcowego userProfiles.checkUserCapability są dozwolone żądania w imieniu dowolnego administratora lub nauczyciela. Określa, czy użytkownik może modyfikować okresy oceniania.

Wymagania wstępne

Ten przewodnik zawiera przykłady kodu w Pythonie i zakłada, że masz:

• projekt Google Cloud, Możesz go skonfigurować, postępując zgodnie z instrukcjami w artykule Szybki start z Pythonem.
• Dodaliśmy do ekranu zgody OAuth w projekcie te zakresy:
  • https://www.googleapis.com/auth/classroom.courses
  • https://www.googleapis.com/auth/classroom.coursework.students
• Identyfikator kursu, w którym mają zostać zmienione okresy oceniania. Właściciel kursu musi mieć licencję Google Workspace for Education Plus.
• Dostęp do danych logowania nauczyciela lub administratora z licencją Google Workspace for Education Plus. Aby utworzyć lub zmodyfikować zadanie, musisz mieć dane logowania nauczyciela. Administratorzy nie mogą tworzyć ani modyfikować zadań, jeśli nie są nauczycielami na zajęciach.

Zarządzanie zasobem GradingPeriodSettings

Zasób GradingPeriodSettings zawiera listę poszczególnych elementów GradingPeriods oraz pole logiczne o nazwie applyToExistingCoursework.

Upewnij się, że każdy użytkownik GradingPeriods na liście spełnia te wymagania:

• Tytuł, data rozpoczęcia i zakończenia: każdy okres oceniania musi mieć tytuł, datę rozpoczęcia i zakończenia.
• Unikalny tytuł: każdy okres oceniania musi mieć unikalny tytuł, który nie może być taki sam jak w przypadku innych okresów oceniania na zajęciach.
• Nienakładające się daty: daty rozpoczęcia i zakończenia każdego okresu oceniania nie mogą się pokrywać z datami innych okresów oceniania na kursie.
• Kolejność chronologiczna: okresy oceniania muszą być wymienione w kolejności chronologicznej na podstawie dat rozpoczęcia i zakończenia.

Każdemu okresowi oceniania przypisano identyfikator interfejsu Classroom API w momencie jego utworzenia.

Wartość logiczna applyToExistingCoursework to trwałe ustawienie, które umożliwia organizowanie wcześniej utworzonych zadań w ramach okresów oceniania bez konieczności wysyłania osobnego wywołania interfejsu API w celu zmodyfikowania wartości gradingPeriodId dla każdego zadania. Jeśli zasada True ma wartość gradingPeriodId, Classroom automatycznie ustawia zasadę gradingPeriodId dla wszystkich istniejących zadań, jeśli courseWork.dueDate przypada w okresie rozpoczęcia i zakończenia obecnego okresu oceniania. Jeśli nie ustawiono terminu realizacji projektu, Classroom użyje wartości courseWork.scheduledTime. Jeśli żadne z pól nie jest obecne lub nie ma zgodności w ramach dat rozpoczęcia i zakończenia istniejącego okresu oceniania, zadanie nie będzie powiązane z żadnym okresem oceniania.

Określanie, czy użytkownik może modyfikować ustawienia okresu oceniania w kursie

Interfejs Classroom API udostępnia punkt końcowy userProfiles.checkUserCapability, który ułatwia proaktywne ustalanie, czy użytkownik może przesyłać żądania do punktu końcowego UpdateGradingPeriodSettings.

Ostrzeżenie: punkt końcowy userProfiles.checkUserCapability sprawdza tylko, czy użytkownik może korzystać z określonej funkcji, na przykład modyfikować okresy oceniania. Nie zawiera ona żadnych informacji o roli w kursie. Na przykład nawet jeśli użytkownik ma uprawnienia UPDATE_GRADING_PERIOD_SETTINGS, a jest uczniem w kursie, to żądanie do punktu końcowego UpdateGradingPeriodSettings nie powiedzie się.

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

Dodawanie okresów oceniania

Gdy już upewnisz się, że użytkownik może modyfikować ustawienia okresu oceniania w kursie, możesz zacząć wysyłać żądania do punktu końcowego UpdateGradingPeriodSettings. Wszelkie modyfikacje zasobu GradingPeriodSettings są wykonywane za pomocą punktu końcowego UpdateGradingPeriodSettings, niezależnie od tego, czy dodajesz poszczególne okresy oceniania, modyfikujesz istniejące okresy oceniania czy usuwasz okres oceniania.

Python

W tym przykładzie zasób gradingPeriodSettings jest modyfikowany, aby obejmował 2 okresy oceniania. Wartość logiczna applyToExistingCoursework jest ustawiona na True, co spowoduje zmodyfikowanie wartości gradingPeriodId w przypadku wszystkich istniejących zadań z kursu, które przypadają w okresie między datą rozpoczęcia a datą zakończenia okresu oceniania. Pamiętaj, że updateMask zawiera oba pola. Zapisz identyfikatory poszczególnych okresów oceniania, gdy zostaną zwrócone w odpowiedzi. W razie potrzeby użyj tych identyfikatorów, aby zaktualizować okresy oceniania.

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

Odczytywanie ustawień okresu oceniania

Dane GradingPeriodSettings są odczytywane za pomocą punktu końcowego GetGradingPeriodSettings. Każdy użytkownik, niezależnie od licencji, może odczytać ustawienia okresów oceniania w kursie.

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

Dodawanie do listy indywidualnego okresu oceniania

Aktualizacje poszczególnych okresów oceniania muszą być wykonywane zgodnie ze wzorcem odczyt-modyfikuj-zapisz. Oznacza to, że trzeba przestrzegać pewnych zaleceń.

1. Odczytaj listę okresów oceniania w zasobie GradingPeriodSettings za pomocą punktu końcowego GetGradingPeriodSettings.
2. Wprowadź wybrane modyfikacje na liście okresów oceniania.
3. Prześlij listę nowych okresów oceniania w prośbie do UpdateGradingPeriodSettings.

Dzięki temu masz pewność, że nazwy poszczególnych okresów oceniania w kursie są różne, a daty rozpoczęcia i zakończenia okresów oceniania się nie pokrywają.

Pamiętaj o tych zasadach dotyczących aktualizowania listy okresów oceniania:

1. Okresy oceniania dodane do listy bez identyfikatora są uważane za dodatki.
2. Okresy oceny brakujące na liście są uznawane za usunięte.
3. Okresy oceny z dotychczasowym identyfikatorem, ale z zmienionymi danymi są uznawane za edycje. Niezmienione właściwości pozostają bez zmian.
4. Okresy oceniania z nowymi lub nieznanymi identyfikatorami są uznawane za błędy.

Ważne: w żądaniu UpdateGradingPeriodSettings uwzględnij identyfikatory okresów oceniania, których nie chcesz usuwać.

Python

Poniżej znajdziesz kod, który rozszerza przykładowy kod z tego poradnika. Utworzono nowy okres oceniania o nazwie „Lato”. W treści żądania parametr boolean applyToExistingCoursework ma wartość False.

W tym celu odczytuje bieżącą wartość GradingPeriodSettings, doda do listy nowy okres oceniania, a wartość logiczna applyToExistingCoursework zostanie ustawiona na False. Pamiętaj, że okresy oceniania, które zostały już zastosowane do istniejących zadań, nie zostaną usunięte. W poprzednim przykładzie okresy oceniania „Semester 1” i „Semester 2” zostały już zastosowane do istniejących zadań CourseWork i nie zostaną usunięte z tych zadań, jeśli parametr applyToExistingCoursework zostanie ustawiony na wartość False w kolejnych żądaniach.

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

Wskazówki dotyczące pola logicznego applyToExistingCoursework

Pamiętaj, że parametr logiczny applyToExistingCoursework jest trwały, co oznacza, że jeśli w poprzednim wywołaniu interfejsu API parametr logiczny został ustawiony na True i nie został zmieniony, kolejne aktualizacje okresów oceniania zostaną zastosowane do istniejącej pracy zaliczeniowej.

Jeśli w prośbie zmienisz tę wartość logiczną z True na False, a potem na UpdateGradingPeriodSettings, tylko nowe zmiany wprowadzone w GradingPeriodSettings nie zostaną zastosowane do istniejącej pracy zaliczeniowej. Wszystkie informacje o okresie oceniania zastosowane do CourseWork w poprzednich wywołaniach interfejsu API, gdy parametr boolean miał wartość logiczną True, nie zostaną usunięte. Wartość logiczna tego ustawienia oznacza, że można przypisać istniejące zadania CourseWork do skonfigurowanych okresów oceniania, ale nie można usunąć istniejących powiązań między zadaniami CourseWork a skonfigurowanymi okresami oceniania.

Jeśli usuniesz lub zmienisz tytuł okresu oceniania, zmiany te zostaną rozpowszechnione we wszystkich istniejących komponentach zajęć, niezależnie od ustawienia wartości logicznej applyToExistingCoursework.

Ważne: ustawienie pola applyToExistingCoursework na False nie spowoduje usunięcia żadnych wcześniej utworzonych okresów oceniania ani powiązań z zadaniami. Usunięcie lub zmiana tytułu okresu oceniania zostanie rozpowszechnione we wszystkich komponentach zajęć niezależnie od ustawienia applyToExistingCoursework.

Aktualizowanie na liście pojedynczego okresu oceniania

Aby zmodyfikować niektóre dane powiązane z istniejącym okresem oceniania, dodaj identyfikator tego okresu do listy zmodyfikowanych danych.

Python

W tym przykładzie zostanie zmieniona data zakończenia okresu oceniania „Lato”. Pole applyToExistingCoursework będzie miało wartość True. Ustawienie tej wartości logicznej na True spowoduje zastosowanie wszystkich skonfigurowanych okresów oceniania do istniejących zadań. W poprzednim żądaniu interfejsu API parametr boolean był ustawiony na wartość False, aby okres oceniania „Lato” nie był stosowany do istniejących zadań. Teraz, gdy to pole logiczne ma wartość True, okres oceniania „Lato” zostanie zastosowany do wszystkich istniejących zadań CourseWork, które pasują do tego pola.

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

Usuwanie pojedynczego okresu oceniania

Aby usunąć okres oceniania, pomiń go na liście. Pamiętaj, że jeśli okres oceniania zostanie usunięty, wszystkie odniesienia do tego okresu w CourseWork zostaną również usunięte niezależnie od ustawienia applyToExistingCoursework.

Python

W tym przykładzie w tym przewodniku pomiń okres oceniania „Lato”, aby go usunąć.

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

Zarządzanie polem gradingPeriodId w CourseWork

Zasób CourseWork zawiera pole gradingPeriodId. Punkty końcowe CourseWork umożliwiają odczytywanie i zapisywanie okresu oceniania powiązanego z CourseWork. Połączeniem można zarządzać na 3 sposoby:

• automatyczne powiązanie okresu oceniania na podstawie daty
• niestandardowy powiązany okres oceniania
• Brak powiązania z okresem oceniania

1. Powiązanie okresu oceniania na podstawie daty

Podczas tworzenia projektu możesz pozwolić Classroom na samodzielne powiązanie go z okresem oceniania. Aby to zrobić, pomiń pole gradingPeriodId w żądaniu CourseWork. Następnie określ pola dueDate lub scheduledTime w żądaniu dotyczącym pracy zaliczeniowej. Jeśli dueDate mieści się w zakresie dat okresu oceniania, Classroom ustawi identyfikator tego okresu w zadaniu. Jeśli pole dueDate nie zostanie określone, Classroom określi wartość gradingPeriodId na podstawie pola scheduledTime. Jeśli żadne z pól nie zostanie określone lub nie będzie zgodności zakresu dat okresu oceniania, w zadaniu nie zostanie ustawiona wartość gradingPeriodId.

2. Niestandardowy powiązany okres oceniania

Jeśli chcesz powiązać projekt edukacyjny z innym okresem oceniania niż ten, który jest zgodny z dueDate lub scheduledTime, możesz ręcznie ustawić pole gradingPeriodId podczas tworzenia lub aktualizowania projektu edukacyjnego. Jeśli ustawisz gradingPeriodId ręcznie, Classroom nie będzie automatycznie przypisywać okresów oceniania na podstawie dat.

3. Brak powiązania z okresem oceniania

Jeśli nie chcesz, aby CourseWork był powiązany z żadnym okresem oceniania, ustaw pole gradingPeriodId w żądaniu CourseWork na pusty ciąg znaków (gradingPeriodId: "").

Jeśli używasz języka programowania Go i chcesz ustawić okres bez oceny, w ciele żądania musisz też podać pole ForceSendFields. W przypadku biblioteki klienta Go wartości domyślne są pomijane w żądaniach interfejsu API z powodu obecności tagu pola omitempty we wszystkich polach. Pole ForceSendFields omija to i wysyła pusty ciąg znaków, aby wskazać, że nie chcesz, aby w przypadku danej pracy zaliczeniowej był ustawiony okres oceniania. Więcej informacji znajdziesz w dokumentacji biblioteki klienta interfejsów Google Go.

Przeczytaj

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

Ważne: jeśli używasz języka programowania Go, dodaj pole ForceSendFields do treści żądania, aby biblioteka klienta mogła wysyłać wartości domyślne.

Co się stanie z identyfikatorem okresu oceniania, jeśli data upływu terminu zostanie zmieniona?

Jeśli aktualizujesz pole CourseWork dueDate i chcesz zachować niestandardowe powiązanie lub brak powiązania z okresem oceniania, w treści updateMask i żądania musisz uwzględnić wartości dueDate i gradingPeriodId. Spowoduje to, że Classroom nie zastąpi gradingPeriodId okresem oceniania odpowiadającym nowej dueDate.

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

Ważne: podczas aktualizowania pola dueDate w zadaniu z kursu uwzględnij pole gradingPeriodId w treści updateMask i żądania, aby zachować niestandardowe powiązanie lub brak powiązania. Dzięki temu Classroom nie zastąpi pola gradingPeriodId polem odpowiadającym nowemu polu dueDate.