ایجاد و مدیریت گروه های دانشجویی

می‌توانید از گروه‌های دانش‌آموزی برای سازماندهی دانش‌آموزان در گروه‌های خاص برای تجارب آموزشی پیشرفته، مانند تکالیف هدفمند و فعالیت‌های مشترک استفاده کنید. از Classroom API برای ایجاد، اصلاح و خواندن گروه‌های دانش‌آموز در یک دوره از طرف مدیران و معلمان استفاده کنید.

با استفاده از روش‌های زیر می‌توانید گروه‌های دانش‌آموزی را ایجاد، به‌روزرسانی، حذف و بخوانید:

همچنین می‌توانید اعضای یک گروه دانش‌آموزی را با استفاده از روش‌های زیر اضافه، حذف و بخوانید:

به روش‌های گروه‌های دانش‌آموز در برنامه پیش‌نمایش برنامه‌نویس دسترسی داشته باشید

برای دسترسی به متدهای گروه دانش آموز در پیش نمایش، باید موارد زیر را انجام دهید:

  • به برنامه پیش نمایش توسعه دهندگان (DPP) بپیوندید.
  • کتابخانه مشتری خود را برای دسترسی به ویژگی های پیش نمایش تنظیم کنید. روش‌های موجود در DPP در کتابخانه‌های مشتری استاندارد و درخواست‌های استاندارد HTTP نمایش داده نمی‌شوند. پس از پیوستن موفقیت آمیز به DPP، می توانید به کتابخانه های سرویس گیرنده گروه های دانشجویی برای زبان های برنامه نویسی خاص دسترسی پیدا کرده و دانلود کنید. برای آشنایی با نحوه راه‌اندازی کتابخانه مشتری انتخابی خود با نسخه پیش‌نمایش و برچسب، به صفحه APIهای پیش‌نمایش Access مراجعه کنید.
  • هنگام درخواست API، نسخه پیش‌نمایش و برچسب پیش‌نمایش را تنظیم کنید. برای روش‌های گروه‌های دانش‌آموز، نسخه پیش‌نمایش V1_20250630_PREVIEW و برچسب پیش‌نمایش DEVELOPER_PREVIEW است. می‌توانید نمونه‌هایی از درخواست‌های API را با نسخه پیش‌نمایش در بخش مدیریت گروه‌های دانش‌آموز بیابید.

الزامات مجوز و واجد شرایط بودن

برای ایجاد، تغییر یا حذف گروه های دانشجویی در یک دوره و افزودن یا حذف اعضا از گروه های دانشجویی، شرایط زیر باید رعایت شود:

  • کاربر درخواست کننده باید معلم دوره یا مدیر دامنه باشد.
  • کاربر درخواست کننده باید مجوز Google Workspace for Education Plus را به او اختصاص داده باشد.
  • صاحب دوره باید مجوز Google Workspace for Education Plus به او اختصاص داده شده باشد.

خواندن گروه های دانش آموزی و اعضای آن

مدیران و معلمان یک دوره می توانند داده های گروه دانش آموزی را بدون توجه به مجوزی که به آنها اختصاص داده شده است بخوانند . این بدان معناست که درخواست‌ها به نقاط پایانی ListStudentGroups و ListStudentGroupMembers از طرف هر مدیر یا معلمی در یک دوره مجاز است.

پیش نیازهای نمونه کد

این راهنما نمونه هایی از کد را در پایتون ارائه می دهد و فرض می کند که شما موارد زیر را دارید:

  • یک پروژه Google Cloud. می‌توانید یکی از دستورالعمل‌های موجود در راه‌اندازی سریع پایتون را تنظیم کنید.
  • دامنه های زیر را به صفحه رضایت OAuth پروژه شما اضافه کرد:
    • https://www.googleapis.com/auth/classroom.rosters
    • https://www.googleapis.com/auth/classroom.rosters.readonly برای نقاط پایانی فقط خواندنی.
  • شناسه دوره ای که در آن گروه های دانشجویی باید مدیریت شوند. مالک دوره باید دارای مجوز Google Workspace for Education Plus باشد.
  • با مجوز Google Workspace for Education Plus به اعتبار معلم یا سرپرست دسترسی پیدا کنید.

اگر شروع سریع پایتون را به عنوان نقطه شروع دنبال کرده اید، سرویس Classroom را برای دسترسی به روش های پیش نمایش تغییر دهید.

پایتون 

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

واجد شرایط بودن کاربر را بررسی کنید

Classroom API نقطه پایانی userProfiles.checkUserCapability را فراهم می کند تا به شما کمک کند به طور فعال تعیین کنید که آیا کاربر قادر به ایجاد و تغییر گروه های دانش آموز و اعضای آن است یا خیر.

نقطه پایان userProfiles.checkUserCapability فقط ارزیابی می کند که آیا کاربر واجد شرایط استفاده از یک قابلیت خاص است، مانند تغییر گروه های دانش آموزی. هیچ اطلاعاتی در مورد نقش دوره ارائه نمی دهد. به عنوان مثال، حتی اگر کاربری دارای قابلیت CREATE_STUDENT_GROUP باشد، اگر دانشجوی دوره باشد، درخواست به نقطه پایانی CreateStudentGroup موفق نخواهد شد.

پایتون 

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.")

گروه های دانشجویی را مدیریت کنید

گروه های دانشجویی را می توان با استفاده از نقطه پایانی CreateStudentGroup ایجاد کرد.

پایتون 

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)

پاسخ شامل id گروه دانشجویی تازه ایجاد شده، courseId و title گروه دانشجویی است.

id گروه دانش آموزی را می توان برای به روز رسانی یا حذف گروه دانش آموزی استفاده کرد.

پایتون 

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)

با استفاده از نقطه پایانی ListStudentGroups می توانید گروه های دانشجویی را در یک دوره بازیابی کنید:

پایتون 

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

اعضای گروه دانش آموزی را مدیریت کنید

هنگامی که گروه دانش آموزی با موفقیت ایجاد شد، می توانید اعضا را به آن اضافه کنید.

پایتون 

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)

اگر می‌خواهید عضوی را از یک گروه دانشجویی حذف کنید، درخواستی مانند زیر ارائه دهید:

پایتون 

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)

با درخواست زیر می توانید اعضای یک گروه را بخوانید:

پایتون 

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

هر منبع StudentGroupMember شامل courseId ، studentGroupId و userId عضو گروه است.

قبلی
ایجاد و مدیریت نگهبان، ایجاد و مدیریت نگهبان