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ış

Ödevleri, testleri ve projeleri belirli tarih aralıklarına göre düzenlemek için notlandırma dönemleri 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. Classroom API'yi kullanarak CourseWork'te notlandırma dönemleri de ayarlayabilirsiniz.

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

  • GetGradingPeriodSettings: Bir kurstaki notlandırma dönemi ayarlarını okumanıza olanak tanır.
  • UpdateGradingPeriodSettings: Notlandırma dönemleri ekleyerek, değiştirerek ve silerek notlandırma dönemi ayarlarını yönetmenize ve yapılandırılan notlandırma dönemlerini mevcut tüm Kurs Çalışmaları'na uygulamanıza olanak tanır.

Lisanslama ve uygunluk koşulları

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

UpdateGradingPeriodSettings uç noktasını kullanarak bir kursta 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 ders öğretmenleri, hangi lisansın kendilerine atandığına bakılmaksızın not verme dönemi ayarlarını okuyabilir. Bu, herhangi bir alan yöneticisi veya öğretmen adına GetGradingPeriodSettings uç noktasına istek gönderilmesine izin verildiği anlamına gelir.

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

Bir dersin öğretmenleri, hangi lisans atanmış olursa olsun API'yi kullanarak CourseWork oluştururken veya güncellerken gradingPeriodId simgesini ekleyebilir.

Kullanıcının notlandırma dönemleri oluşturmaya uygun olup olmadığını kontrol etme

userProfiles.checkUserCapability uç noktasına yapılan istekler, herhangi bir yönetici veya öğretmen adına izin verilir. Kullanıcının notlandırma dönemlerini değiştirip değiştiremeyeceğini belirlemek için bu ayarı kullanın.

Ön koşullar

Bu kılavuzda Python dilinde kod örnekleri verilmektedir ve aşağıdaki şartları karşıladığınız varsayılmaktadır:

  • Google Cloud projesi. Python hızlı başlangıç bölümündeki talimatları uygulayarak bir tane oluşturabilirsiniz.
  • Projenizin OAuth kullanıcı rızası ekranına aşağıdaki 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 bir kursun 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 Kurs içeriği oluşturmak veya değiştirmek için öğretmen kimlik bilgilerine ihtiyacınız vardır. Yöneticiler, kursta öğretmen değilse CourseWork oluşturamaz veya değiştiremez.

GradingPeriodSettings kaynağını yönetme

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

Listedeki her bir GradingPeriods öğesinin aşağıdaki koşulları karşıladığından emin olun:

  • Başlık, başlangıç tarihi ve bitiş tarihi: Her notlandırma döneminin başlığı, başlangıç tarihi ve bitiş tarihi olmalıdır.
  • Benzersiz başlık: Her notlandırma döneminin, kurstaki diğer notlandırma dönemleriyle eşleşmeyen benzersiz bir başlığı olmalıdır.
  • Çakışmayan tarihler: Her notlandırma döneminin başlangıç veya bitiş tarihleri, kurstaki diğer notlandırma dönemleriyle çakışmamalıdır.
  • Kronolojik sıra: Notlandırma dönemleri, başlangıç ve bitiş tarihlerine göre kronolojik sırada listelenmelidir.

Her notlandırma dönemine, oluşturulurken Classroom API tarafından atanmış bir tanımlayıcı atanır.

applyToExistingCoursework boole değeri, daha önce oluşturulan CourseWork'leri her CourseWork için gradingPeriodId değerini değiştirmek üzere ayrı bir API çağrısı yapmanıza gerek kalmadan notlandırma dönemleri halinde düzenlemenize olanak tanıyan kalıcı bir ayardır. True olarak ayarlanırsa Classroom, courseWork.dueDate mevcut bir notlandırma döneminin başlangıç ve bitiş tarihleri içinde yer alıyorsa mevcut tüm CourseWork'lerde gradingPeriodId değerini otomatik olarak ayarlar. Classroom, CourseWork'te teslim tarihi ayarlanmamışsa courseWork.scheduledTime tarihini kullanır. Alanlardan hiçbiri mevcut değilse veya mevcut bir notlandırma döneminin başlangıç ve bitiş tarihleri içinde eşleşme yoksa CourseWork herhangi bir notlandırma dönemiyle ilişkilendirilmez.

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

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 userProfiles.checkUserCapability uç noktasını sağlar.

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

Notlandırma dönemi ekleme

Kullanıcının bir kurstaki notlandırma dönemi ayarlarını değiştirmeye uygun olduğundan emin olduğunuzda UpdateGradingPeriodSettings uç noktasına istek göndermeye başlayabilirsiniz. GradingPeriodSettings kaynağında yapılan tüm değişiklikler, tek tek notlandırma dönemleri ekliyor, mevcut notlandırma dönemlerini değiştiriyor veya bir notlandırma dönemini siliyor olmanızdan bağımsız olarak GradingPeriodSettings uç noktası kullanılarak gerçekleştirilir.UpdateGradingPeriodSettings

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, bir notlandırma döneminin başlangıç ve bitiş tarihi arasında kalan mevcut CourseWork'lerdeki gradingPeriodId değerini değiştirir. updateMask alanının her iki alanı da içerdiğini unutmayın. Yanıt döndürüldüğünde ayrı 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_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

Notlandırma dönemi ayarlarını okuma

GradingPeriodSettings, GetGradingPeriodSettings uç noktası kullanılarak okunur. Lisansı ne olursa olsun tüm kullanıcılar, bir kurstaki notlandırma dönemleri ayarlarını okuyabilir.

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

Listeye tek bir notlandırma dönemi ekleme

Notlandırma döneminde yapılan güncellemeler, okuma-değiştirme-yazma düzenine göre yapılmalıdır. Bu nedenle:

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

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

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

  1. Kimlik olmadan listeye eklenen notlandırma dönemleri ekleme olarak kabul edilir.
  2. Listede olmayan notlandırma dönemleri silme olarak kabul edilir.
  3. Mevcut bir kimliğe sahip ancak verileri değiştirilmiş notlandırma dönemleri düzenleme olarak kabul edilir. Değiştirilmeyen ö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. İstek gövdesinde applyToExistingCoursework boolean değeri False olarak ayarlanmış.

Bunu yapmak için mevcut GradingPeriodSettings okunur, listeye yeni bir notlandırma dönemi eklenir ve applyToExistingCoursework boole değeri False olarak ayarlanır. Mevcut ödevlere uygulanmış olan 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'e zaten uygulanmıştı ve sonraki isteklerde applyToExistingCoursework False olarak ayarlanırsa CourseWork'ten kaldırılmaz.

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

applyToExistingCoursework Boole alanı hakkında faydalı ipuçları

applyToExistingCoursework Boole değerinin kalıcı olduğunu unutmayın. Yani Boole değeri önceki bir API çağrısında True olarak ayarlanmışsa ve değiştirilmemişse notlandırma dönemleriyle ilgili sonraki güncellemeler mevcut CourseWork'e uygulanır.

UpdateGradingPeriodSettings isteğinde bu Boole değerini True olarak değiştirirseniz GradingPeriodSettings üzerinde yaptığınız yeni değişikliklerin mevcut CourseWork'e uygulanmayacağını unutmayın.False 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ını, mevcut CourseWork'ü yapılandırılmış not verme dönemlerinizle ilişkilendirmeyi destekleyen ancak CourseWork ile yapılandırılmış not verme dönemleri arasındaki mevcut ilişkilendirmeleri kaldırmayı desteklemeyen bir ayar olarak düşünebilirsiniz.

Bir notlandırma döneminin başlığını siler veya değiştirirseniz bu değişiklikler, applyToExistingCoursework boole'unun ayarından bağımsız olarak mevcut tüm CourseWork'e yayılır.

Listedeki bağımsız 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 verilerin bulunduğu listeye ekleyin.

Python

Bu örnekte, "Yaz" notlandırma döneminin bitiş tarihi değiştirilecektir. applyToExistingCoursework alanı True olarak ayarlanır. Bu boole değerini True olarak ayarlamanın, mevcut CourseWork'e yapılandırılmış tüm notlandırma dönemlerini uygulayacağını unutmayın. Önceki API isteğinde, "Yaz" notlandırma döneminin mevcut CourseWork'e uygulanmaması için boole değeri False olarak ayarlanmıştı. Bu boole alanı True olarak ayarlandığında, eşleşen tüm mevcut CourseWork'e "Yaz" notlandırma dönemi uygulanır.

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

Tek bir notlandırma dönemini silme

Bir 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'teki notlandırma dönemine yapılan tüm referansların da silineceğini unutmayın.

Python

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

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

CourseWork'te gradingPeriodId alanını yönetme

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

  • tarihe dayalı otomatik notlandırma dönemi ilişkilendirmesi
  • özel ilişkilendirilmiş notlandırma dönemi
  • notlandırma dönemi ilişkilendirilmemişse

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

CourseWork oluştururken Classroom'un notlandırma dönemi ilişkilendirmesini sizin için yapmasına izin verebilirsiniz. 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 not verme dönemi tarih aralığına giriyorsa Classroom, CourseWork'e söz konusu not verme dönemi kimliğini atar. dueDate alanı belirtilmezse Classroom, gradingPeriodId değerini scheduledTime alanına göre belirler. İki alan da belirtilmemişse veya notlandırma dönemi tarih aralığı eşleşmesi yoksa CourseWork'te gradingPeriodId ayarlanmaz.

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

CourseWork'ü dueDate veya scheduledTime ile uyumlu olanın dışında farklı bir notlandırma dönemiyle ilişkilendirmek istiyorsanız CourseWork'ü oluştururken veya güncellerken gradingPeriodId alanını manuel olarak ayarlayabilirsiniz. gradingPeriodId değerini manuel olarak ayarlarsanız Classroom, otomatik tarih tabanlı notlandırma dönemi ilişkilendirmesini gerçekleştirmez.

3. Notlandırma dönemi ilişkilendirilmemiş

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

Go programlama dilini kullanıyorsanız ve notlandırma dönemi ayarlamak istemiyorsanız istek gövdesine ForceSendFields alanını da eklemeniz gerekir. Go istemci kitaplığıyla, tüm alanlarda omitempty alan etiketi bulunduğundan API isteklerinde varsayılan değerler atlanır. ForceSendFields alanı bunu atlar ve boş dize göndererek bu CourseWork için herhangi bir notlandırma dönemi ayarlanmasını istemediğinizi belirtir. Daha fazla bilgi için Google API'leri Go istemci kitaplığı belgelerine bakın.

Go

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

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şkilendirmemesini korumak istiyorsanız updateMask ve istek gövdesine dueDate ve gradingPeriodId öğelerini eklemeniz gerekir. Bu işlem, Classroom'a gradingPeriodId yerine yeni dueDate ile eşleşen notlandırma dönemini kullanmaması talimatını verir.

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