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

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

Genel Bakış

Notlandırma dönemleri, ödevleri, testleri ve projeleri belirli tarih aralıklarında düzenlemek için oluşturulur. Classroom API, geliştiricilerin yöneticiler ve öğretmenler adına Classroom'da 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 ekleme, değiştirme ve silme ve yapılandırılmış notlandırma dönemlerini mevcut tüm ders çalışmalarına uygulama yoluyla bir kurstaki notlandırma dönemi ayarlarını yönetmenize olanak tanır.

Lisanslama koşulları

Bir kurstaki 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:

Bir kurstaki notlandırma dönemi ayarlarını okuma

Alan yöneticileri ve bir dersin öğretmenleri, atanmış oldukları lisanstan bağımsız olarak notlandırma dönemi ayarlarını okuyabilir. Bu, GetGradingPeriodSettings uç noktasına yapılan isteklerin herhangi bir alan yöneticisi veya öğretmen adına izin verildiği anlamına gelir.

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

Bir dersin öğretmenleri, atanmış oldukları lisanstan bağımsız olarak API'yi kullanarak CourseWork'u oluştururken veya güncellerken gradingPeriodId değerini ekleyebilir.

Kullanıcıların notlandırma dönemleri ayarlama 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:

  • Bir Google Cloud projesi. Python hızlı başlangıç kılavuzundaki talimatları uygulayarak tek bir kod oluşturabilirsiniz.
  • Projenizin OAuth izin ekranına aşağıdaki kapsamları ekleyin:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • Notlandırma dönemlerinin değiştirilmesi gereken bir dersin kimliği. Kurs sahibinin Google Workspace for Education Plus lisansı olmalıdır.
  • Google Workspace for Education Plus lisansına sahip bir öğretmenin 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önetme

GradingPeriodSettings kaynağı, bağımsız GradingPeriods öğelerinin 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öneminin benzersiz bir başlığı 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 atanan kendi tanımlayıcıları vardır.

applyToExistingCoursework doğru/yanlış değeri, daha önce oluşturulmuş ders çalışmalarını her ders çalışması için gradingPeriodId değerini değiştirmek üzere ayrı bir API çağrısı yapmak zorunda kalmadan notlandırma dönemlerine ayırmanıza olanak tanıyan kalıcı bir ayardır. Bu değer True olarak ayarlanırsa Classroom, courseWork.dueDate mevcut bir notlandırma döneminin başlangıç ve bitiş tarihlerine denk gelirse mevcut tüm CourseWork'larda gradingPeriodId değerini otomatik olarak ayarlar. Ödev için teslim tarihi ayarlanmamışsa Classroom, courseWork.scheduledTime değerini kullanır. Bu iki alan da mevcut değilse veya mevcut bir notlandırma döneminin başlangıç ve bitiş tarihleriyle eşleşme yoksa ders çalışması herhangi bir notlandırma dönemiyle ilişkilendirilmez.

Kullanıcıların bir kurstaki 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 özelliği yalnızca belirli bir lisansa sahip kullanıcılar tarafından kullanılabildiğinden, Classroom API, 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 ekleme

Kullanıcının, bir kurstaki 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 ayarlanır. Bu durumda, bir notlandırma döneminin başlangıç ve bitiş tarihi arasına denk gelen mevcut CourseWork öğelerindeki gradingPeriodId değiştirilir. updateMask'ün her iki alanı da içerdiğini unutmayın. Yanıtta döndürüldükten sonra ayrı notlandırma dönemlerine ait kimlikleri 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. Lisanstan bağımsız olarak tüm kullanıcılar, bir kurstaki notlandırma dönemleri 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

Belirli bir notlandırma dönemindeki güncellemeler, okuma-değiştirme-yazma kalıbına göre yapılmalıdır. Bu nedenle:

  1. GetGradingPeriodSettings uç noktasını kullanarak GradingPeriodSettings kaynağındaki notlandırma dönemleri listesini okuyun.
  2. Notlandırma dönemleri listesinde istediğiniz 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 farklı olmasını ve notlandırma dönemlerinin başlangıç ile bitiş tarihleri arasında çakışma olmamasına yardımcı olur.

Notlandırma dönemleri listesini güncellemeyle ilgili 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 silinmiş 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 örnekten yararlanır. "Yaz" başlıklı yeni bir notlandırma dönemi oluşturulur. applyToExistingCoursework boole değeri, istek gövdesinde False olarak ayarlanmıştır.

Bunu yapmak için mevcut GradingPeriodSettings okunur, listeye yeni bir notlandırma dönemi eklenir ve applyToExistingCoursework doğru/yanlış değeri False olarak ayarlanır. Mevcut Ödevler'e uygulanmış notlandırma dönemlerinin kaldırılmayacağını unutmayın. Önceki örnekte, "1. Dönem" ve "2. Dönem" notlandırma dönemleri mevcut CourseWork'a zaten uygulanmıştır ve sonraki isteklerde applyToExistingCoursework False olarak ayarlanırsa CourseWork'tan 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ıyla ilgili faydalı ipuçları

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 bu boole değerini True yerine False olarak değiştirirseniz yalnızca GradingPeriodSettings'da yaptığınız yeni değişiklikler mevcut CourseWork'a uygulanmaz. Doğru/yanlış değeri True olarak ayarlandığında önceki API çağrılarında CourseWork'a uygulanan tüm notlandırma dönemi bilgileri kaldırılmaz. Bu boole ayarını, mevcut ders çalışmalarını yapılandırılmış notlandırma dönemlerinizle ilişkilendirmeyi desteklediği ancak ders çalışmaları ile yapılandırılmış notlandırma dönemleri arasındaki mevcut ilişkilendirmeleri kaldırmayı desteklemediği şeklinde düşünebilirsiniz.

Bir notlandırma döneminin başlığını siler veya değiştirirseniz bu değişiklikler, applyToExistingCoursework doğru/yanlış değerinin ayarından bağımsız olarak mevcut tüm CourseWork'lara dağıtılır.

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

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

Python

Bu örnekte, "Yaz" notlandırma dönemi bitiş tarihi değiştirilecektir. applyToExistingCoursework alanı True olarak ayarlanır. Bu boole değerini True olarak ayarladığınızda, yapılandırılmış tüm notlandırma dönemleri mevcut CourseWork'a uygulanır. Önceki API isteğinde, "Yaz" notlandırma döneminin mevcut CourseWork'a uygulanmaması için boole değeri False olarak ayarlandı. 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

Notlandırma dönemlerini tek tek silme

Notlandırma dönemini silmek için notlandırma dönemini listeden çıkarın. Bir notlandırma dönemi silinirse applyToExistingCoursework ayarından bağımsız olarak CourseWork'ta notlandırma dönemine yapılan tüm referansların da silineceğini unutmayın.

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'ta gradingPeriodId alanını yönetme

CourseWork kaynağı bir gradingPeriodId alanı içerir. CourseWork uç noktalarını kullanarak CourseWork ile ilişkili notlandırma dönemini okuyabilir ve yazabilirsiniz. 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

Ödev oluştururken Classroom'un notlandırma dönemi ilişkilendirmesini sizin adınıza yapmasını sağlayabilirsiniz. Bunu yapmak için CourseWork isteğinden 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. Hiçbir alan belirtilmezse veya notlandırma dönemi tarih aralığı eşleşmesi yoksa CourseWork'ta gradingPeriodId ayarlanmaz.

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

Ödevi, dueDate veya scheduledTime ile uyumlu olandan farklı bir notlandırma dönemiyle ilişkilendirmek istiyorsanız Ödev'i oluştururken veya 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.

Son tarih güncellenirse notlandırma dönemi kimliğine ne olur?

CourseWork dueDate alanını güncelliyorsanız ve özel bir notlandırma dönemi ilişkilendirmesini veya notlandırma dönemi ilişkilendirmesini korumak istiyorsanız updateMask ve istek gövdesine dueDate ve gradingPeriodId öğelerini eklemeniz gerekir. Bu işlem, Classroom'a gradingPeriodId değerini yeni dueDate ile eşleşen notlandırma dönemiyle geçersiz kılmaması gerektiğini söyler.

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()
Önceki
Notları ayarlama ve güncelleme
Sonraki
Sınırlamalar