Classroom API'yi kullanarak notlandırma dönemlerini yönetme

Bu kılavuzda, Google Classroom API'deki notlandırma dönemi uç noktalarının nasıl kullanılacağı açıklanmaktadır.

Genel bakış

Ev ödevlerini, testleri ve projeleri belirli tarih aralıklarına göre düzenlemek için notlama dönemleri oluşturulur. Classroom API, geliştiricilerin Classroom'da yöneticiler ve öğretmenler adına notlandırma dönemleri oluşturmasına, değiştirmesine ve okumasına olanak tanır. CourseWork'te notlandırma dönemlerini ayarlamak için Classroom API'yi de kullanabilirsiniz.

Classroom API, bir derste notlandırma dönemi bilgilerini okumak ve yazmak için iki uç nokta sunar:

  • GetGradingPeriodSettings: Bir kurstaki notlandırma dönemi ayarlarını okumanızı sağlar.
  • UpdateGradingPeriodSettings: Notlandırma dönemi ekleyip düzenleyerek, silerek ve yapılandırılmış notlandırma dönemlerini mevcut tüm CourseWork'lere uygulayarak bir dersteki notlandırma dönemi ayarlarını yönetmenize olanak tanır.

Lisanslama koşulları

Derste notlandırma dönemi ayarlarını değiştirme

UpdateGradingPeriodSettings uç noktasını kullanarak bir derste notlandırma dönemleri oluşturmak, değiştirmek veya silmek için aşağıdaki koşulların karşılanması gerekir:

Kurstaki notlandırma dönemi ayarlarını okuma

Bir dersin alan yöneticileri ve öğretmenleri, kendilerine atanan lisansa bakılmaksızın notlandırma dönemi ayarlarını okuyabilir. Bu, herhangi bir alan yöneticisi veya öğretmeni adına GetGradingPeriodSettings uç noktasına yapılan isteklere izin verildiği anlamına gelir.

CourseWork'te notlandırma dönemi kimliği ayarlama

Bir dersin öğretmenleri, aldıkları lisansa bakılmaksızın API'yi kullanarak CourseWork oluştururken veya güncellerken gradingPeriodId ekleyebilir.

Notlandırma dönemi ayarlamak için kullanıcıların uygunluğunu kontrol etme

Herhangi bir yönetici veya öğretmen adına checkGradingPeriodsSetupEligibility uç noktasına yönelik isteklere izin verilir. Kullanıcının bir dersteki notlandırma dönemlerini değiştirip değiştiremeyeceğini belirlemek için bunu kullanın.

Ön koşullar

Bu kılavuzda, Python'da kod örnekleri sağlanmakta ve aşağıdakilere sahip olduğunuz varsayılmaktadır:

  • Google Cloud projesi. Python hızlı başlangıç kılavuzundaki talimatları uygulayarak tek bir kod oluşturabilirsiniz.
  • Projenizin OAuth izin ekranına şu kapsamlar eklendi:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • Notlandırma dönemlerinin değiştirilmesi gereken dersin kimliği. Ders sahibinin Google Workspace for Education Plus lisansına sahip olması gerekir.
  • Google Workspace for Education Plus lisansı ile öğretmen veya yöneticinin kimlik bilgilerine erişim. CourseWork’ü oluşturmak ya da değiştirmek için bir öğretmenin kimlik bilgileri gerekiyor. Yöneticiler, derste öğretmen değilse CourseWork'ü oluşturamaz veya değiştiremez.

GradingPeriodSettings kaynağını yönetin

GradingPeriodSettings kaynağı, bağımsız GradingPeriods öğelerinin bir listesini ve applyToExistingCoursework adlı bir boole alanını içerir.

GradingPeriods listesi, bir kurstaki tüm notlandırma dönemlerini temsil eder. Listedeki her notlandırma dönemi için bir başlık, başlangıç tarihi ve bitiş tarihi belirtmeniz gerekir. Bir kurstaki her notlandırma dönemi benzersiz bir başlığa sahip olmalıdır ve farklı notlandırma dönemlerinin başlangıç ve bitiş tarihleri çakışamaz. Her notlandırma döneminin, Classroom API tarafından atanmış kendi tanımlayıcısı vardır.

applyToExistingCoursework boole, her CourseWork için gradingPeriodId öğesini değiştirmek amacıyla ayrı bir API çağrısı yapmak zorunda kalmadan, önceden oluşturulan CourseWork'ü notlandırma dönemlerine göre düzenlemenizi sağlayan kalıcı bir ayardır. True olarak ayarlanırsa ve courseWork.dueDate mevcut notlandırma döneminin başlangıç ve bitiş tarihlerine denk geliyorsa Classroom, mevcut tüm CourseWork'lerde gradingPeriodId ayarını otomatik olarak yapacaktır. CourseWork'te bir teslim tarihi ayarlanmamışsa Classroom, courseWork.scheduledTime öğesini kullanır. İki alan da yoksa ya da mevcut notlandırma döneminin başlangıç ve bitiş tarihleri arasında bir eşleşme yoksa CourseWork herhangi bir notlandırma dönemiyle ilişkilendirilmez.

Kullanıcının bir dersteki notlandırma dönemi ayarlarını değiştirip değiştiremeyeceğini belirleme

Classroom'da notlandırma dönemleri oluşturma ve değiştirme olanağı yalnızca belirli bir lisansa sahip olan kullanıcılara sunulduğundan Classroom API, bir kullanıcının UpdateGradingPeriodSettings uç noktasına istek gönderip gönderemeyeceğini proaktif olarak belirlemenize yardımcı olmak için checkGradingPeriodsSetupEligibility uç noktasını sağlar.

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

Notlandırma dönemi ekle

Kullanıcının bir derste notlandırma dönemi ayarlarını değiştirmek için gerekli lisansa sahip olduğundan emin olduğunuza göre UpdateGradingPeriodSettings uç noktasına istek göndermeye başlayabilirsiniz. Ayrı notlandırma dönemleri ekleme, mevcut notlandırma dönemlerini değiştirme veya notlandırma dönemi silme gibi işlemlerde GradingPeriodSettings kaynağında yapılan tüm değişiklikler UpdateGradingPeriodSettings uç noktası kullanılarak gerçekleştirilir.

Python

Aşağıdaki örnekte, gradingPeriodSettings kaynağı iki notlandırma dönemi içerecek şekilde değiştirilmiştir. applyToExistingCoursework boole değeri True olarak ayarlanmıştır. Bu durumda, bir notlandırma döneminin başlangıç ve bitiş tarihi arasında kalan mevcut tüm CourseWorks'te gradingPeriodId değiştirilir. updateMask değerinin her iki alanı da içerdiğini unutmayın. Yanıtta döndürülen notlandırma dönemlerinin kimliklerini kaydedin. Gerekirse notlandırma dönemlerini güncellemek için bu kimlikleri kullanmanız gerekir.

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

Notlandırma dönemi ayarlarını okuma

GradingPeriodSettings, GetGradingPeriodSettings uç noktası kullanılarak okunur. Lisanslarından bağımsız olarak tüm kullanıcılar bir dersteki notlandırma dönemi ayarlarını okuyabilir.

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

Listeye ayrı bir notlandırma dönemi ekleme

Tek bir notlandırma dönemindeki güncellemeler, oku, değiştir-yazma düzeni kullanılarak yapılmalıdır. Bu durumda şunları yapmanız gerekir:

  1. GetGradingPeriodSettings uç noktasını kullanarak GradingPeriodSettings kaynağındaki notlandırma dönemleri listesini okuyun.
  2. Notlandırma dönemleri listesinde seçilen değişiklikleri yapın.
  3. Yeni notlandırma dönemleri listesini UpdateGradingPeriodSettings isteğinde bulunun.

Bu kalıp, bir kurstaki notlandırma dönemi başlıklarının birbirinden farklı olmasını ve notlandırma dönemlerinin başlangıç ve bitiş tarihleri arasında çakışma olmadığından emin olmanızı sağlar.

Notlandırma dönemi listesini güncellerken aşağıdaki kuralları göz önünde bulundurun:

  1. Listeye kimlik olmadan eklenen notlandırma dönemleri, ekleme olarak kabul edilir.
  2. Listede eksik olan notlandırma dönemleri, silme olarak kabul edilir.
  3. Mevcut bir kimlikle ancak değiştirilmiş veriler içeren notlandırma dönemleri düzenleme olarak kabul edilir. Değiştirilmemiş özellikler olduğu gibi bırakılır.
  4. Yeni veya bilinmeyen kimliklere sahip notlandırma dönemleri hata olarak kabul edilir.

Python

Aşağıdaki kod, bu kılavuzdaki örnek üzerine geliştirilecektir. "Yaz" başlığıyla yeni bir notlandırma dönemi oluşturulur. applyToExistingCoursework boole değeri, istek gövdesinde False olarak ayarlanmıştır.

Bunun için mevcut GradingPeriodSettings okunur, listeye yeni bir notlandırma dönemi eklenir ve applyToExistingCoursework boole değeri False olarak ayarlanır. Mevcut CourseWork’e uygulanmış olan notlandırma dönemlerinin kaldırılmayacağını unutmayın. Önceki örnekte, "Semester 1" ve "Semester 2" notlandırma dönemleri mevcut CourseWork'e zaten uygulanmıştır ve applyToExistingCoursework sonraki isteklerde False olarak ayarlanırsa CourseWork'ten kaldırılmaz.

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

applyToExistingCoursework boole alanı hakkında faydalı işaretçiler

applyToExistingCoursework boole değerinin kalıcı olduğunu unutmayın. Bu durumda, boole değeri önceki bir API çağrısında True olarak ayarlanmışsa ve değiştirilmemişse notlandırma dönemlerinde yapılan sonraki güncellemeler mevcut CourseWork'e uygulanacaktır.

UpdateGradingPeriodSettings isteğinde bulunduğunuz bu boole değerini True yerine False olarak değiştirirseniz yalnızca GradingPeriodSettings üzerinde yaptığınız yeni değişikliklerin mevcut CourseWork'e uygulanmayacağını unutmayın. Boole değeri True olarak ayarlandığında, önceki API çağrılarında CourseWork'e uygulanan notlandırma dönemi bilgileri kaldırılmaz. Bu boole ayarı, mevcut CourseWork'ün yapılandırılmış notlandırma dönemlerinizle ilişkilendirilmesini destekler ancak CourseWork ile yapılandırılmış notlandırma dönemleri arasındaki mevcut ilişkilendirmelerin kaldırılmasını desteklemez.

Bir notlandırma döneminin başlığını siler veya başlığını değiştirirseniz bu değişiklikler, applyToExistingCoursework boole ayarından bağımsız olarak mevcut tüm CourseWork'te geçerli olur.

Listede tek bir notlandırma dönemini güncelleme

Mevcut bir notlandırma dönemiyle ilişkili bazı verileri değiştirmek için listeye, değiştirilen verilerle birlikte mevcut notlandırma döneminin kimliğini ekleyin.

Python

Bu örnekte, "Yaz" notlandırma dönemi bitiş tarihi değişecektir. applyToExistingCoursework alanı True olarak ayarlanır. Bu boole değeri True olarak ayarlandığında, mevcut CourseWork'te yapılandırılmış tüm notlandırma dönemleri uygulanır. Önceki API isteğinde boole değeri False olarak ayarlanmıştı. Böylece, "Yaz" notlandırma dönemi mevcut CourseWork'e uygulanmayacaktı. Bu boole alanı True olarak ayarlandığı için "Yaz" notlandırma dönemi, eşleşen mevcut tüm CourseWork'lere uygulanır.

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

Tek bir notlandırma dönemini silme

Notlandırma dönemini silmek için notlandırma dönemini listeden çıkarın. Notlandırma dönemi silindiğinde CourseWork'teki notlandırma dönemine yapılan tüm referanslar applyToExistingCoursework ayarından bağımsız olarak silinecektir.

Python

Bu kılavuzdaki örneği kullanmaya devam etmek için notlandırma dönemini ("Yaz") atlayın.

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

CourseWork'te gradingPeriodId alanını yönet

CourseWork kaynağı bir gradingPeriodId alanı içerir. CourseWork ile ilişkili notlandırma dönemini okuyup yazmak için CourseWork uç noktalarını kullanabilirsiniz. Bu ilişkilendirmeyi yönetmenin üç yolu vardır:

  • tarihe dayalı otomatik notlandırma dönemi ilişkilendirme
  • özel ilişkilendirilmiş notlandırma dönemi
  • notlandırma dönemi ilişkilendirmesi yok

1. Tarihe dayalı notlandırma dönemi ilişkilendirmesi

CourseWork oluştururken Classroom'un notlandırma dönemi ilişkilendirmesini sizin yerinize yapmasına izin verebilirsiniz. Bunu yapmak için CourseWork isteğindeki gradingPeriodId alanını çıkarın. Ardından CourseWork isteğinde dueDate veya scheduledTime alanlarını belirtin. dueDate, mevcut bir notlandırma dönemi tarih aralığına denk geliyorsa Classroom, notlandırma dönemi kimliğini CourseWork'te ayarlar. dueDate alanı belirtilmezse Classroom, gradingPeriodId öğesini scheduledTime alanına göre belirler. İki alan da belirtilmemişse veya notlandırma dönemi tarih aralığı eşleşmiyorsa CourseWork'te gradingPeriodId ayarlanmaz.

2. Özel ilişkilendirilmiş notlandırma dönemi

CourseWork'ü dueDate veya scheduledTime ile uyumlu olandan farklı bir notlandırma dönemiyle ilişkilendirmek istiyorsanız CourseWork'ü oluştururken ya da güncellerken gradingPeriodId alanını manuel olarak ayarlayabilirsiniz. gradingPeriodId ayarını manuel olarak yaparsanız Classroom, tarihe dayalı otomatik notlandırma dönemi ilişkilendirmesini gerçekleştirmez.

3. Notlandırma dönemi ilişkilendirmesi yok

CourseWork'ün herhangi bir notlandırma dönemiyle ilişkilendirilmesini istemiyorsanız CourseWork isteğindeki gradingPeriodId alanını boş bir dizeye (gradingPeriodId: "") ayarlayın.

Teslim tarihi güncellenirse notlandırma dönemi kimliğine ne olur?

CourseWork dueDate alanını güncelliyorsanız ve notlandırma dönemi özel olan veya olmayan ilişkilendirmesini korumak istiyorsanız updateMask ve istek gövdesine dueDate ile gradingPeriodId öğelerini dahil etmeniz gerekir. Bu durumda Classroom, gradingPeriodId özelliğini yeni dueDate ile eşleşen notlandırma dönemiyle geçersiz kılmamasını söyleyecektir.

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