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.

Przegląd

Okresy oceniania są tworzone w celu uporządkowania zadań 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. Za pomocą interfejsu Classroom API możesz też ustawiać okresy oceniania w CourseWork.

Interfejs Classroom API udostępnia 2 punkty końcowe do odczytywania i zapisywania informacji o okresach oceniania na zajęciach:

• GetGradingPeriodSettings: umożliwia odczytywanie ustawień okresu oceniania na zajęciach.
• UpdateGradingPeriodSettings: umożliwia zarządzanie ustawieniami okresu oceniania na zajęciach przez dodawanie, modyfikowanie i usuwanie okresów oceniania oraz stosowanie skonfigurowanych okresów oceniania do wszystkich istniejących zadań CourseWork.

Wymagania dotyczące licencji i kryteria kwalifikacji

Modyfikowanie ustawień okresu oceniania na zajęciach

Aby tworzyć, modyfikować lub usuwać okresy oceniania na zajęciach za pomocą punktu końcowego UpdateGradingPeriodSettings, musisz spełnić te warunki:

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

Odczytywanie ustawień okresu oceniania na zajęciach

Administratorzy domeny i nauczyciele na zajęciach mogą odczytywać ustawienia okresu oceniania niezależnie od przypisanej licencji. Oznacza to, że żądania do punktu końcowego GetGradingPeriodSettings są dozwolone w imieniu każdego administratora domeny lub nauczyciela.

Ustawianie identyfikatora okresu oceniania w CourseWork

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

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

Żądania do punktu końcowego userProfiles.checkUserCapability są dozwolone w imieniu każdego administratora lub nauczyciela. Użyj tego, aby określić, czy użytkownik może modyfikować okresy oceniania.

Wymagania wstępne

W tym przewodniku znajdziesz przykłady kodu w Pythonie. Zakładamy, że masz:

• Projekt Google Cloud. Możesz go skonfigurować, postępując zgodnie z instrukcjami w przewodniku Szybki start w Pythonie.
• Dodane te zakresy do ekranu akceptacji OAuth w projekcie:
  • https://www.googleapis.com/auth/classroom.courses
  • https://www.googleapis.com/auth/classroom.coursework.students
• Identyfikator zajęć, w których należy zmodyfikować okresy oceniania. Właściciel zajęć musi mieć licencję Google Workspace for Education Plus.
• Dostęp do danych logowania nauczyciela lub administratora z licencją Google Workspace for Education Plus. Aby tworzyć lub modyfikować CourseWork, musisz mieć dane logowania nauczyciela. Administratorzy nie mogą tworzyć ani modyfikować CourseWork, jeśli nie są nauczycielami na zajęciach.

Zarządzanie zasobem GradingPeriodSettings

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

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

• Tytuł, data rozpoczęcia i data zakończenia: każdy okres oceniania musi mieć tytuł, datę rozpoczęcia i datę zakończenia.
• Unikalny tytuł: każdy okres oceniania musi mieć unikalny tytuł, który nie pasuje do żadnego innego okresu oceniania na zajęciach.
• Niepokrywające się daty: każdy okres oceniania nie może mieć daty rozpoczęcia ani zakończenia, które pokrywają się z datami innych okresów oceniania na zajęciach.
• Kolejność chronologiczna: okresy oceniania muszą być wymienione w kolejności chronologicznej na podstawie daty rozpoczęcia i zakończenia.

Każdy okres oceniania otrzyma po utworzeniu identyfikator przypisany przez interfejs Classroom API.

Pole logiczne applyToExistingCoursework to ustawienie trwałe, które umożliwia uporządkowanie wcześniej utworzonych zadań CourseWork w okresach oceniania bez konieczności wykonywania osobnego wywołania interfejsu API w celu zmodyfikowania gradingPeriodId dla każdego zadania CourseWork. Jeśli to pole ma wartość True, Classroom automatycznie ustawi gradingPeriodId we wszystkich istniejących zadaniach CourseWork, jeśli courseWork.dueDate mieści się w zakresie dat rozpoczęcia i zakończenia istniejącego okresu oceniania. Jeśli w CourseWork nie ustawiono terminu, Classroom użyje courseWork.scheduledTime. Jeśli żadne z tych pól nie jest obecne lub nie ma dopasowania w zakresie dat rozpoczęcia i zakończenia istniejącego okresu oceniania, CourseWork nie będzie powiązane z żadnym okresem oceniania.

Określanie, czy użytkownik może modyfikować ustawienia okresu oceniania na zajęciach

Interfejs Classroom API udostępnia punkt końcowy userProfiles.checkUserCapability, który pomaga proaktywnie określić, czy użytkownik może wysył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, np. modyfikować okresy oceniania. Nie zawiera żadnych informacji o roli na zajęciach. Na przykład nawet jeśli użytkownik ma uprawnienie UPDATE_GRADING_PERIOD_SETTINGS, ale jest uczniem na zajęciach, żą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 masz pewność, że użytkownik może modyfikować ustawienia okresu oceniania na zajęciach, możesz zacząć wysyłać żądania do punktu końcowego UpdateGradingPeriodSettings. Wszystkie 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 tak, aby zawierał 2 okresy oceniania. Pole logiczne applyToExistingCoursework ma wartość True, co spowoduje zmodyfikowanie gradingPeriodId w przypadku wszystkich istniejących zadań CourseWork, które mieszczą się w zakresie dat rozpoczęcia i zakończenia okresu oceniania. Pamiętaj, że updateMask zawiera oba pola. Zapisz identyfikatory poszczególnych okresów oceniania, gdy zostaną zwrócone w odpowiedzi. Będziesz ich potrzebować, aby w razie potrzeby 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

GradingPeriodSettings są odczytywane za pomocą punktu końcowego GetGradingPeriodSettings. Każdy użytkownik, niezależnie od licencji, może odczytywać ustawienia okresów oceniania na zajęciach.

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 pojedynczego okresu oceniania do listy

Aktualizacje pojedynczego okresu oceniania muszą być wykonywane zgodnie ze wzorcem odczyt-modyfikacja-zapis. Oznacza to, że musisz:

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. Wyślij nową listę okresów oceniania w żądaniu do UpdateGradingPeriodSettings.

Ten wzorzec pomoże Ci upewnić się, że tytuły poszczególnych okresów oceniania na zajęciach są różne i nie ma nakładania się dat rozpoczęcia i zakończenia okresów oceniania.

Pamiętaj o tych regułach dotyczących aktualizowania listy okresów oceniania:

1. Okresy oceniania dodane do listy bez identyfikatora są traktowane jako dodatki.
2. Okresy oceniania brakujące na liście są traktowane jako usunięcia.
3. Okresy oceniania z istniejącym identyfikatorem , ale zmodyfikowanymi danymi są traktowane jako edycje. Niezmienione właściwości pozostają bez zmian.
4. Okresy oceniania z nowymi lub nieznanymi identyfikatorami są traktowane jako błędy.

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

Python

Poniższy kod będzie oparty na przykładzie z tego przewodnika. Nowy okres oceniania jest tworzony z tytułem „Summer”. Pole logiczne applyToExistingCoursework ma w treści żądania wartość False.

Aby to zrobić, odczytuje się bieżący GradingPeriodSettings, do listy dodaje się nowy okres oceniania, a pole logiczne applyToExistingCoursework ma wartość False. Pamiętaj, że okresy oceniania, które zostały już zastosowane do istniejących zadań CourseWork, 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ą z nich usunięte, jeśli w kolejnych żądaniach applyToExistingCoursework będzie mieć wartość False.

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

Przydatne wskazówki dotyczące pola logicznego applyToExistingCoursework

Pamiętaj, że pole logiczne applyToExistingCoursework jest trwałe , co oznacza, że jeśli w poprzednim wywołaniu interfejsu API miało wartość True i nie zostało zmienione, kolejne aktualizacje okresów oceniania zostaną zastosowane do istniejących zadań CourseWork.

Pamiętaj, że jeśli w żądaniu do UpdateGradingPeriodSettings zmienisz wartość tego pola logicznego z True na False, tylko nowe zmiany wprowadzane w GradingPeriodSettings nie zostaną zastosowane do istniejących zadań CourseWork. Wszystkie informacje o okresach oceniania zastosowane do CourseWork w poprzednich wywołaniach interfejsu API, gdy pole logiczne miało wartość True, nie zostaną usunięte. Warto pamiętać, że to ustawienie logiczne umożliwia powiązanie istniejących zadań CourseWork ze skonfigurowanymi okresami oceniania, ale nie umożliwia usuwania istniejących powiązań między CourseWork a skonfigurowanymi okresami oceniania.

Jeśli usuniesz lub zmienisz tytuł okresu oceniania, zmiany te zostaną zastosowane do wszystkich istniejących zadań CourseWork niezależnie od ustawienia pola logicznego applyToExistingCoursework.

Ważne: ustawienie pola applyToExistingCoursework na False nie spowoduje usunięcia żadnych istniejących powiązań między okresem oceniania a CourseWork. Usunięcie lub zmiana tytułu okresu oceniania zostanie zastosowana do wszystkich zadań CourseWork niezależnie od ustawienia applyToExistingCoursework.

Aktualizowanie pojedynczego okresu oceniania na liście

Aby zmodyfikować dane powiązane z istniejącym okresem oceniania, uwzględnij na liście identyfikator istniejącego okresu oceniania ze zmodyfikowanymi danymi.

Python

W tym przykładzie zostanie zmodyfikowana data zakończenia okresu oceniania „Summer”. Pole applyToExistingCoursework będzie mieć wartość True. Pamiętaj, że ustawienie tego pola logicznego na True spowoduje zastosowanie wszystkich skonfigurowanych okresów oceniania do istniejących zadań CourseWork. W poprzednim żądaniu do interfejsu API pole logiczne miało wartość False, więc okres oceniania „Summer” nie został zastosowany do istniejących zadań CourseWork. Teraz, gdy to pole logiczne ma wartość True, okres oceniania „Summer” zostanie zastosowany do wszystkich pasujących istniejących zadań CourseWork.

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 niego w CourseWork również zostaną usunięte niezależnie od ustawienia applyToExistingCoursework.

Python

Aby kontynuować przykład z tego przewodnika, pomiń okres oceniania „Summer”, 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. Za pomocą punktów końcowych CourseWork możesz odczytywać i zapisywać okres oceniania powiązany z CourseWork. Istnieją 3 sposoby zarządzania tym powiązaniem:

• 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 CourseWork możesz zezwolić Classroom na obsługę powiązania okresu oceniania. Aby to zrobić, pomiń pole gradingPeriodId w żądaniu CourseWork. Następnie w żądaniu CourseWork określ pola dueDate lub scheduledTime. Jeśli dueDate mieści się w zakresie dat istniejącego okresu oceniania, Classroom ustawi ten identyfikator okresu oceniania w CourseWork. Jeśli pole dueDate nie jest określone, Classroom określi gradingPeriodId na podstawie pola scheduledTime. Jeśli żadne z tych pól nie jest określone lub nie ma dopasowania w zakresie dat okresu oceniania, w CourseWork nie zostanie ustawiony żaden gradingPeriodId.

2. Niestandardowy powiązany okres oceniania

Jeśli chcesz powiązać CourseWork 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 CourseWork. Jeśli ręcznie ustawisz gradingPeriodId, Classroom nie będzie automatycznie powiązywać okresu oceniania na podstawie daty.

3. Brak powiązania z okresem oceniania

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

Jeśli używasz języka programowania Go i nie chcesz ustawiać okresu oceniania, w treści żądania uwzględnij też pole ForceSendFields. W bibliotece klienta Go wartości domyślne są pomijane w żądaniach interfejsu API ze względu na obecność tagu pola omitempty we wszystkich polach. Pole ForceSendFields pomija to i wysyła pusty ciąg znaków, aby wskazać, że nie chcesz ustawiać żadnego okresu oceniania dla tego zadania CourseWork. Więcej informacji znajdziesz w dokumentacji biblioteki klienta interfejsów API Google Go.

Go

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, w treści żądania uwzględnij pole ForceSendFields , aby biblioteka klienta mogła wysyłać wartości domyślne.

Co się stanie z identyfikatorem okresu oceniania, jeśli termin zostanie zaktualizowany?

Jeśli aktualizujesz pole dueDate w CourseWork i chcesz zachować niestandardowe powiązanie z okresem oceniania lub brak powiązania, w updateMask i treści żądania uwzględnij dueDate i gradingPeriodId. Dzięki temu Classroom nie zastąpi gradingPeriodId okresem oceniania, który pasuje do nowego 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 CourseWork uwzględnij pole gradingPeriodId w updateMask i treści żądania, aby zachować niestandardowe powiązanie lub brak powiązania. Dzięki temu Classroom nie zastąpi pola gradingPeriodId polem pasującym do nowego dueDate.