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. Classroom API'yi kullanarak CourseWork'ta notlandırma dönemlerini 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ı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 kursta notlandırma dönemleri oluşturmak, değiştirmek veya silmek için aşağıdaki koşulların karşılanması gerekir:
- İsteği gönderen kullanıcıya Google Workspace for Education Plus lisansı atanmış olmalıdır.
- Kursun sahibine Google Workspace for Education Plus lisansı atanmış olmalıdır.
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.
Ders çalışmasında 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ının notlandırma dönemleri ayarlama uygunluğunu kontrol etme
checkGradingPeriodsSetupEligibility uç noktasına yapılan isteklere herhangi bir yönetici veya öğretmen adına izin verilir. Kullanıcının bir kurstaki notlandırma dönemlerini değiştirip değiştiremeyeceğini belirlemek için bu özelliği kullanın.
Ön koşullar
Bu kılavuzda Python'da kod örnekleri verilmiştir ve aşağıdakileri bildiğiniz varsayılmaktadır:
- Bir Google Cloud projesi. Python hızlı başlangıç kılavuzundaki talimatları uygulayarak bir tane ayarlayabilirsiniz.
- Projenizin OAuth izin ekranına aşağıdaki kapsamları ekleyin:
https://www.googleapis.com/auth/classroom.courseshttps://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. Ödev oluşturmak veya mevcut bir ödevi değiştirmek için öğretmen kimlik bilgilerine ihtiyacınız vardır. Yöneticiler, kursta öğretmen değilse Ödev oluşturamaz veya mevcut ödevleri 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, 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 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. GradingPeriodSettings kaynağında yapılan tüm değişiklikler, ayrı notlandırma dönemleri ekleme, mevcut notlandırma dönemlerini değiştirme veya notlandırma dönemini silme işlemlerinde 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ı kullanılarak yapılmalıdır. Bu nedenle:
GetGradingPeriodSettingsuç noktasını kullanarakGradingPeriodSettingskaynağındaki notlandırma dönemleri listesini okuyun.- Notlandırma dönemleri listesinde istediğiniz değişiklikleri yapın.
- Yeni notlandırma dönemleri listesini
UpdateGradingPeriodSettingsadresine bir istek göndererek 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ıç 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:
- Listeye kimlik olmadan eklenen notlandırma dönemleri ekleme olarak kabul edilir.
- Listede eksik olan notlandırma dönemleri silinmiş olarak kabul edilir.
- Mevcut bir kimliğe sahip 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.
- 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 doğru/yanlış değeri, istek metninde 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, boole değeri önceki bir API çağrısında True olarak ayarlandıysa ve değiştirilmediyse notlandırma dönemlerinde yapılan sonraki güncellemelerin mevcut CourseWork'a uygulanacağı anlamına gelir.
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 notlandırma dönemini tek tek 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ığına göre, "Yaz" notlandırma dönemi, eşleşen tüm mevcut CourseWork'lara uygulanacaktı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ğe devam etmek için notlandırma dönemini (Yaz) atlayarak silin.
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şkilendirmesi
- ö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 gelirse Classroom, sınıf çalışmasında ilgili notlandırma dönemi kimliğini ayarlar. dueDate alanı belirtilmezse Classroom, gradingPeriodId değerini 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 değerini manuel olarak ayarlarsanız Classroom, tarihe dayalı notlandırma dönemi ilişkilendirmesini otomatik olarak gerçekleştirmez.
3. Notlandırma dönemi ilişkilendirmesi yok
CourseWork'ın hiçbir notlandırma dönemiyle ilişkilendirilmesini istemiyorsanız CourseWork isteğinde gradingPeriodId alanını boş bir dize olarak ayarlayın (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ş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()