Öğrenci grupları oluşturma ve yönetme

Öğrencileri belirli gruplara ayırarak (ör. belirli bir gruba yönelik ödevler ve ortak çalışmalar) daha iyi bir eğitim deneyimi sunmak için öğrenci gruplarını kullanabilirsiniz. Yöneticiler ve öğretmenler adına bir kurstaki öğrenci gruplarını oluşturmak, değiştirmek ve okumak için Classroom API'yi kullanın.

Aşağıdaki yöntemleri kullanarak öğrenci grupları oluşturabilir, güncelleyebilir, silebilir ve okuyabilirsiniz:

Ayrıca, aşağıdaki yöntemleri kullanarak öğrenci grubuna üye ekleyebilir, üyeleri kaldırabilir ve okuyabilirsiniz:

Geliştirici Önizleme Programı'nda öğrenci grupları yöntemlerine erişme

Önizlemedeki öğrenci grupları yöntemlerine erişmek için aşağıdakileri yapmanız gerekir:

  • Geliştirici Önizleme Programı'na (DPP) katılın.
  • Önizleme özelliklerine erişmek için istemci kitaplığınızı ayarlayın. DPP'deki yöntemler, standart istemci kitaplıklarında ve standart HTTP isteklerinde kullanıma sunulmaz. DPP'ye başarılı bir şekilde katıldıktan sonra belirli programlama dilleri için öğrenci grupları istemci kitaplıklarına erişebilir ve bunları indirebilirsiniz. Seçtiğiniz istemci kitaplığını önizleme sürümü ve etiketiyle nasıl ayarlayacağınızı öğrenmek için Önizleme API'lerine erişim sayfasını inceleyin.
  • API istekleri gönderirken önizleme sürümünü ve önizleme etiketini ayarlayın. Öğrenci grupları yöntemleri için önizleme sürümü V1_20250630_PREVIEW, önizleme etiketi ise DEVELOPER_PREVIEW şeklindedir. Önizleme sürümüyle ilgili API isteklerinin örneklerini Öğrenci gruplarını yönetme bölümünde bulabilirsiniz.

Lisanslama ve uygunluk koşulları

Bir kursta öğrenci grupları oluşturmak, değiştirmek veya silmek ve öğrenci gruplarına üye eklemek ya da üye kaldırmak için aşağıdaki koşulların karşılanması gerekir:

Öğrenci gruplarını ve üyelerini okuma

Bir kursun yöneticileri ve öğretmenleri, hangi lisansın kendilerine atandığına bakılmaksızın öğrenci grubu verilerini okuyabilir. Bu, ListStudentGroups ve ListStudentGroupMembers uç noktalarına yapılan isteklerin, kurstaki herhangi bir yönetici veya öğretmen adına izin verildiği anlamına gelir.

Kod örneği ö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.rosters
    • Salt okunur uç noktalar için https://www.googleapis.com/auth/classroom.rosters.readonly.
  • Öğrenci gruplarının yönetilmesi 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

Başlangıç noktası olarak Python hızlı başlangıç kılavuzunu kullandıysanız önizleme yöntemlerine erişmek için Classroom hizmetini değiştirin.

Python

classroom_service = googleapiclient.discovery.build(
    serviceName='classroom',
    version='v1',
    credentials=creds,
    static_discovery=False,
    discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY')

Kullanıcı uygunluğunu kontrol etme

Classroom API, kullanıcının öğrenci grupları ve üyelerini oluşturup değiştirebileceğini proaktif olarak belirlemenize yardımcı olmak için userProfiles.checkUserCapability uç noktasını sağlar.

userProfiles.checkUserCapability uç noktası yalnızca kullanıcının belirli bir özelliği (ör. öğrenci gruplarını değiştirme) kullanmaya uygun olup olmadığını değerlendirir. Kurs rolü hakkında bilgi verilmez. Örneğin, bir kullanıcının CREATE_STUDENT_GROUP özelliği olsa bile kursa kayıtlı bir öğrenciyse CreateStudentGroup uç noktasına yapılan istek başarılı olmaz.

Python

def check_student_groups_update_capability(classroom_service, course_id):
    """Checks whether a user is able to create and modify student groups in a course."""
    capability = classroom_service.userProfiles().checkUserCapability(
        userId="me", # Can also be set to a different user's email address or ID
        capability="CREATE_STUDENT_GROUP",
        previewVersion="V1_20240930_PREVIEW" # Required while the method is in the DPP.
    ).execute()

    if capability.get("allowed"): # Retrieve the `allowed` boolean from the response.
        print("User is allowed to create and modify student groups.")
    else:
        print("User is not allowed to create and modify student groups.")

Öğrenci gruplarını yönetme

Öğrenci grupları, CreateStudentGroup uç noktası kullanılarak oluşturulabilir.

Python

def create_student_group(classroom_service, course_id):
    body = {
        "title": "Team Blue"
    }

    response = classroom_service.courses().studentGroups().create(
        courseId=course_id,
        body=body,
        previewVersion="V1_20250630_PREVIEW",
    ).execute()

    print(response)

Yanıt, yeni oluşturulan öğrenci grubunun id, courseId ve öğrenci grubu title bilgilerini içerir.

Öğrenci grubu id, tek tek öğrenci gruplarını güncellemek veya silmek için kullanılabilir.

Python

def update_student_group(classroom_service, course_id, student_group_id):
    body = {
        "title": "Team Green"
    }

    response = classroom_service.courses().studentGroups().patch(
        courseId=course_id,
        id=student_group_id,
        body=body,
        updateMask="title",
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(response)

def delete_student_group(classroom_service, course_id, student_group_id):
    response = classroom_service.courses().studentGroups().delete(
        courseId=course_id,
        id=student_group_id,
        previewVersion="V1_20250630_PREVIEW",
    ).execute()

    print(response)

Bir kurstaki öğrenci gruplarını ListStudentGroups uç noktasını kullanarak alabilirsiniz:

Python

def list_student_groups(classroom_service, course_id):
    results = classroom_service.courses().studentGroups().list(
        courseId=course_id,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    studentGroups = results.get("studentGroups")

Öğrenci grubu üyelerini yönetme

Öğrenci grubu başarıyla oluşturulduktan sonra gruba üye ekleyebilirsiniz.

Python

def add_student_group_member(classroom_service, course_id, student_group_id):
    body = {
        "userId": "student@schooldomain.com"
    }

    response = classroom_service.courses().studentGroups().studentGroupMembers().create(
        courseId=course_id,
        studentGroupId=student_group_id,
        body=body,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(response)

Bir öğrenci grubundan üye kaldırmak istiyorsanız aşağıdaki gibi bir istekte bulunun:

Python

def delete_student_group_member(classroom_service, course_id, student_group_id):
    response = classroom_service.courses().studentGroups().studentGroupMembers().delete(
        courseId=course_id,
        studentGroupId=student_group_id,
        userId="student@schooldomain.com",
        previewVersion="V1_20250630_PREVIEW"
    ).execute()
    print(response)

Aşağıdaki isteği göndererek bir gruptaki üyeleri okuyabilirsiniz:

Python

def list_student_group_members(classroom_service, course_id, student_group_id):
    results = classroom_service.courses().studentGroups().studentGroupMembers().list(
        courseId=course_id,
        studentGroupId=student_group_id,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(results.get("studentGroupMembers"))

Her StudentGroupMember kaynağı, grup üyesinin courseId, studentGroupId ve userId bilgilerini içerir.

Önceki
Veli oluşturma ve yönetme