نمرات ضمیمه و برگشت نمره

این ششمین قدم در مجموعه مروری بر افزونه‌های Classroom است.

در این راهنما، شما مثال مرحله پیشین قبلی را برای ایجاد یک پیوست از نوع فعالیت درجه بندی شده تغییر می دهید. همچنین نمره‌ای را به‌صورت برنامه‌ریزی به Google Classroom پس می‌دهید که در کتاب نمره معلم به‌عنوان پیش‌نویس نمایش داده می‌شود.

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

توجه داشته باشید که ویژگی های درجه بندی در API اختیاری هستند. آنها را می توان با هر نوع پیوست فعالیتی استفاده کرد.

در طول این راهنما، موارد زیر را تکمیل می کنید:

• درخواست‌های ایجاد پیوست قبلی را به Classroom API تغییر دهید تا مخرج درجه پیوست را نیز تنظیم کنید.
• به‌صورت برنامه‌ای به ارسالی دانش‌آموز امتیاز دهید و شماره‌گر نمره پیوست را تنظیم کنید.
• دو رویکرد را برای ارسال نمره ارسالی به Classroom با استفاده از اعتبارنامه معلم وارد شده یا آفلاین اجرا کنید.

پس از اتمام، نمرات در دفتر نمره Classroom پس از فعال شدن رفتار پس‌انداز ظاهر می‌شوند. لحظه دقیقی که این اتفاق می افتد به رویکرد پیاده سازی بستگی دارد.

برای اهداف این مثال، مجدداً از فعالیت مرحله پیشین قبلی استفاده کنید، که در آن تصویری از یک مکان دیدنی معروف به دانش‌آموز نشان داده می‌شود و از او خواسته می‌شود نام آن را وارد کند. اگر دانش آموز نام صحیح را وارد کرد، برای پیوست نمره کامل در نظر بگیرید، در غیر این صورت صفر.

ویژگی درجه‌بندی API افزونه‌های Classroom را بدانید

برافزای شما می‌تواند هم عدد و هم مخرج نمره را برای پیوست تنظیم کند. اینها به ترتیب با استفاده از مقادیر pointsEarned و maxPoints در API تنظیم می شوند. یک کارت پیوست در Classroom UI مقدار maxPoints را هنگامی که تنظیم شده است نشان می دهد.

شکل 1. رابط کاربری ایجاد تکلیف با سه کارت پیوست افزودنی که دارای مجموعه maxPoints هستند.

API افزونه‌های Classroom به شما امکان می‌دهد تنظیمات را برای نمرات پیوست پیکربندی کرده و امتیاز کسب شده را تنظیم کنید. اینها با نمرات تکلیف یکسان نیستند. با این حال، تنظیمات درجه تکلیف از تنظیمات درجه پیوست پیوستی پیروی می‌کند که برچسب همگام‌سازی درجه را در کارت پیوست دارد. وقتی پیوست «همگام‌سازی نمره» pointsEarned برای ارسال دانش‌آموز تنظیم می‌کند، همچنین نمره پیش‌نویس دانش‌آموز را برای تکلیف تعیین می‌کند.

معمولاً اولین پیوستی که به تکلیفی که maxPoints تنظیم می‌کند اضافه می‌شود، برچسب «همگام‌سازی درجه» را دریافت می‌کند. برای نمونه ای از برچسب "همگام سازی درجه"، مثال ایجاد انتساب را که در شکل 1 نشان داده شده است، ببینید. توجه داشته باشید که کارت "پیوست 1" دارای برچسب "همگام سازی نمره" است و نمره تکلیف در کادر قرمز به 50 امتیاز به روز شده است. همچنین توجه داشته باشید که اگرچه شکل 1 سه کارت پیوست را نشان می دهد، فقط یک کارت دارای برچسب "همگام سازی درجه" است. این یک محدودیت کلیدی اجرای فعلی است: فقط یک پیوست می‌تواند برچسب "همگام‌سازی درجه" را داشته باشد .

اگر چندین پیوست وجود دارد که maxPoints را تنظیم کرده‌اند، حذف پیوست با «همگام‌سازی درجه»، «همگام‌سازی درجه» را در هیچ یک از پیوست‌های باقی‌مانده فعال نمی‌کند . افزودن پیوست دیگری که maxPoints را تنظیم می‌کند، همگام‌سازی درجه را در پیوست جدید فعال می‌کند و حداکثر نمره تخصیص مطابق با آن تنظیم می‌شود. هیچ مکانیزمی وجود ندارد که به صورت برنامه‌ریزی ببیند کدام پیوست دارای برچسب «همگام‌سازی درجه» است و یا اینکه ببینید یک تکلیف خاص چند پیوست دارد.

حداکثر نمره یک پیوست را تنظیم کنید

این بخش تنظیم مخرج برای درجه پیوست را شرح می دهد. یعنی حداکثر امتیاز ممکنی که همه دانش آموزان می توانند برای مطالب ارسالی خود کسب کنند. برای انجام این کار، مقدار maxPoints پیوست را تنظیم کنید.

برای فعال کردن ویژگی‌های درجه‌بندی، فقط یک تغییر جزئی در پیاده‌سازی موجود ما لازم است. هنگام ایجاد پیوست، مقدار maxPoints را در همان شی AddOnAttachment که حاوی studentWorkReviewUri ، teacherViewUri و سایر فیلدهای پیوست است، اضافه کنید.

توجه داشته باشید که حداکثر امتیاز پیش‌فرض برای یک تکلیف جدید 100 است. پیشنهاد می‌کنیم maxPoints روی مقداری غیر از 100 تنظیم کنید تا بتوانید تأیید کنید که نمره‌ها به درستی تنظیم شده‌اند. maxPoints به عنوان نمایش بر روی 50 تنظیم کنید:

attachment = {
    # Specifies the route for a teacher user.
    "teacherViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True),
    },
    # Specifies the route for a student user.
    "studentViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True)
    },
    # Specifies the route for a teacher user when the attachment is
    # loaded in the Classroom grading view.
    "studentWorkReviewUri": {
        "uri":
            flask.url_for(
                "view_submission", _scheme='https', _external=True)
    },
    # Sets the maximum points that a student can earn for this activity.
    # This is the denominator in a fractional representation of a grade.
    "maxPoints": 50,
    # The title of the attachment.
    "title": f"Attachment {attachment_count}",
}

برای اهداف این نمایش، شما همچنین مقدار maxPoints را در پایگاه داده پیوست محلی خود ذخیره می کنید. این امر باعث می‌شود که بعداً هنگام رتبه‌بندی مطالب ارسالی دانش‌آموز، یک تماس API اضافی برقرار کنید. البته توجه داشته باشید که ممکن است معلمان تنظیمات نمره تکلیف را مستقل از افزونه شما تغییر دهند. برای مشاهده مقدار maxPoints در سطح تکلیف، یک درخواست GET به نقطه پایانی courses.courseWork ارسال کنید. هنگام انجام این کار، itemId را در قسمت CourseWork.id ارسال کنید.

اکنون مدل پایگاه داده خود را به روز کنید تا مقدار maxPoints پیوست را نیز حفظ کند. توصیه می کنیم از مقدار maxPoints از پاسخ CREATE استفاده کنید:

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    # Store the maxPoints value returned in the response.
    max_points=int(resp.get("maxPoints")))
db.session.add(new_attachment)
db.session.commit()

پیوست اکنون دارای حداکثر نمره است. اکنون باید بتوانید این رفتار را آزمایش کنید. یک پیوست را به یک تکلیف جدید اضافه کنید و مشاهده کنید که کارت پیوست برچسب "همگام سازی نمره" را نشان می دهد و مقدار "امتیاز" تخصیص تغییر می کند.

نمره ارسال دانش آموز را در Classroom تنظیم کنید

این بخش تنظیم شمارنده برای درجه پیوست را شرح می دهد. این، امتیاز یک دانش آموز برای پیوست است. برای انجام این کار، مقدار pointsEarned یک ارسال دانشجو را تعیین کنید.

اکنون باید یک تصمیم مهم بگیرید: افزونه شما چگونه باید درخواستی برای تعیین pointsEarned صادر کند ؟

مسئله این است که تنظیم pointsEarned به teacher OAuth scope نیاز دارد . شما نباید حوزه teacher را به کاربران دانش آموز اختصاص دهید. این می تواند منجر به رفتار غیرمنتظره ای در هنگام تعامل دانش آموزان با برافزای شما شود، مانند بارگیری iframe Teacher View به جای iframe Student View. بنابراین شما دو انتخاب برای نحوه تعیین pointsEarned دارید:

• با استفاده از اعتبارنامه معلم وارد شده.
• استفاده از اطلاعات ذخیره شده (آفلاین) معلم.

بخش‌های بعدی، پیش از نمایش هر پیاده‌سازی، مبادلات هر رویکرد را مورد بحث قرار می‌دهند. توجه داشته باشید که مثال های ارائه شده ما هر دو رویکرد را برای گذراندن یک نمره در Classroom نشان می دهد. برای مشاهده نحوه انتخاب رویکرد هنگام اجرای مثال‌های ارائه‌شده، دستورالعمل‌های مختص زبان زیر را ببینید:

با استفاده از اعتبار معلمی که وارد سیستم شده است، نمرات را تنظیم کنید

از اطلاعات کاربری کاربر وارد شده برای صدور درخواست تنظیم pointsEarned استفاده کنید. این باید کاملاً شهودی به نظر برسد، زیرا تا کنون بقیه پیاده‌سازی را منعکس می‌کند و برای تحقق بخشیدن به تلاش کمی نیاز دارد.

با این حال، در نظر بگیرید که معلم فقط با ارسال دانش‌آموز در چارچوب بررسی کار دانشجویی تعامل دارد. این چند پیامد مهم دارد:

• تا زمانی که معلم در رابط کاربری Classroom اقدامی انجام ندهد، هیچ نمره‌ای در Classroom جمع نمی‌شود.
• یک معلم ممکن است مجبور شود هر ارسالی دانش آموز را باز کند تا بتواند تمام نمرات دانش آموز را پر کند.
• تأخیر کوتاهی بین دریافت نمره Classroom و ظاهر شدن آن در رابط کاربری Classroom وجود دارد. تأخیر معمولاً پنج تا ده ثانیه است، اما می تواند تا 30 ثانیه باشد.

ترکیب این عوامل به این معنی است که معلمان ممکن است مجبور باشند کارهای دستی قابل توجه و وقت گیر را انجام دهند تا نمرات یک کلاس را به طور کامل جمع کنند.

برای پیاده‌سازی این رویکرد، یک فراخوان API اضافی را به مسیر بررسی کار دانشجویی خود اضافه کنید.

پس از واکشی سوابق ارسالی و پیوست دانش آموز، ارسالی دانش آموز را ارزیابی کرده و نمره حاصل را ذخیره کنید. نمره را در قسمت pointsEarned یک شی AddOnAttachmentStudentSubmission تنظیم کنید. در نهایت، یک درخواست PATCH به courses.courseWork.addOnAttachments.studentSubmissions با نمونه AddOnAttachmentStudentSubmission در بدنه درخواست صادر کنید. توجه داشته باشید که ما همچنین باید pointsEarned در updateMask در درخواست PATCH خود مشخص کنیم:

# Look up the student's submission in our database.
student_submission = Submission.query.get(flask.session["submissionId"])

# Look up the attachment in the database.
attachment = Attachment.query.get(student_submission.attachment_id)

grade = 0

# See if the student response matches the stored name.
if student_submission.student_response.lower(
) == attachment.image_caption.lower():
    grade = attachment.max_points

# Create an instance of the Classroom service.
classroom_service = ch._credential_handler.get_classroom_service()

# Build an AddOnAttachmentStudentSubmission instance.
add_on_attachment_student_submission = {
    # Specifies the student's score for this attachment.
    "pointsEarned": grade,
}

# Issue a PATCH request to set the grade numerator for this attachment.
patch_grade_response = classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

با استفاده از مدارک آفلاین معلم نمرات را تنظیم کنید

رویکرد دوم برای تعیین نمرات مستلزم استفاده از اعتبارنامه های ذخیره شده برای معلمی است که پیوست را ایجاد کرده است. این پیاده‌سازی مستلزم آن است که اعتبارنامه‌ها را با استفاده از نشانه‌های تازه‌سازی و دسترسی معلم قبلاً مجاز بسازید، و سپس از این اعتبارنامه‌ها برای تنظیم pointsEarned استفاده کنید.

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

برای اجرای این رویکرد، وظایف زیر را کامل کنید:

1. سوابق پایگاه داده کاربر را برای ذخیره یک نشانه دسترسی تغییر دهید.
2. سوابق پایگاه داده پیوست را برای ذخیره شناسه معلم تغییر دهید.
3. اعتبارنامه معلم را بازیابی کنید و (به صورت اختیاری) یک نمونه سرویس جدید Classroom بسازید.
4. نمره یک ارسال را تنظیم کنید.

برای اهداف این نمایش، زمانی که دانش آموز فعالیت را کامل می کند، نمره را تعیین کنید. این زمانی است که دانشجو فرم را در مسیر Student View ارسال می کند.

سوابق پایگاه داده کاربر را برای ذخیره نشانه دسترسی تغییر دهید

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

با این حال، اکنون باید به عنوان فردی غیر از کاربر وارد شده تماس برقرار کنید، به این معنی که جریان احراز هویت در دسترس نیست. بنابراین، شما باید رمز دسترسی را در کنار نشانه رفرش ذخیره کنید. طرح جدول User خود را به‌روزرسانی کنید تا یک نشانه دسترسی داشته باشد:

# Database model to represent a user.
class User(db.Model):
    # The user's identifying information:
    id = db.Column(db.String(120), primary_key=True)
    display_name = db.Column(db.String(80))
    email = db.Column(db.String(120), unique=True)
    portrait_url = db.Column(db.Text())

    # The user's refresh token, which will be used to obtain an access token.
    # Note that refresh tokens will become invalid if:
    # - The refresh token has not been used for six months.
    # - The user revokes your app's access permissions.
    # - The user changes passwords.
    # - The user belongs to a Google Cloud organization
    #   that has session control policies in effect.
    refresh_token = db.Column(db.Text())

    # An access token for this user.
    access_token = db.Column(db.Text())

سپس، هر کدی را که یک رکورد User ایجاد یا به‌روزرسانی می‌کند، به‌روزرسانی کنید تا رمز دسترسی نیز ذخیره شود:

def save_credentials_to_storage(self, credentials):
    # Issue a request for the user's profile details.
    user_info_service = googleapiclient.discovery.build(
        serviceName="oauth2", version="v2", credentials=credentials)
    user_info = user_info_service.userinfo().get().execute()
    flask.session["username"] = user_info.get("name")
    flask.session["login_hint"] = user_info.get("id")

    # See if we have any stored credentials for this user. If they have used
    # the add-on before, we should have received login_hint in the query
    # parameters.
    existing_user = self.get_credentials_from_storage(user_info.get("id"))

    # If we do have stored credentials, update the database.
    if existing_user:
        if user_info:
            existing_user.id = user_info.get("id")
            existing_user.display_name = user_info.get("name")
            existing_user.email = user_info.get("email")
            existing_user.portrait_url = user_info.get("picture")

        if credentials and credentials.refresh_token is not None:
            existing_user.refresh_token = credentials.refresh_token
            # Update the access token.
            existing_user.access_token = credentials.token

    # If not, this must be a new user, so add a new entry to the database.
    else:
        new_user = User(
            id=user_info.get("id"),
            display_name=user_info.get("name"),
            email=user_info.get("email"),
            portrait_url=user_info.get("picture"),
            refresh_token=credentials.refresh_token,
            # Store the access token as well.
            access_token=credentials.token)

        db.session.add(new_user)

    db.session.commit()

سوابق پایگاه داده پیوست را برای ذخیره شناسه معلم تغییر دهید

به منظور تعیین نمره برای یک فعالیت، برای تعیین pointsEarned به عنوان معلم در دوره تماس بگیرید. چندین راه برای انجام این کار وجود دارد:

• یک نقشه محلی از اعتبار معلمان در شناسه دوره ذخیره کنید. توجه داشته باشید، با این حال، یک معلم ممکن است همیشه با یک دوره خاص مرتبط نباشد.
• برای دریافت معلم(های) فعلی، درخواست‌های GET را به نقطه پایانی courses Classroom API صادر کنید. سپس، سوابق کاربر محلی را پرس و جو کنید تا اعتبارنامه معلم منطبق را پیدا کنید.
• هنگام ایجاد یک پیوست افزودنی، شناسه معلم را در پایگاه داده پیوست‌های محلی ذخیره کنید. سپس، اعتبارنامه معلم را از attachmentId که به iframe View Student ارسال شده است، بازیابی کنید.

این مثال آخرین گزینه را نشان می‌دهد، زیرا وقتی دانش‌آموز یک پیوست فعالیت را تکمیل می‌کند، نمرات را تنظیم می‌کنید.

یک فیلد شناسه معلم به جدول Attachment پایگاه داده خود اضافه کنید:

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

    # The ID of the teacher that created the attachment.
    teacher_id = db.Column(db.String(120))

سپس، هر کدی را که یک رکورد Attachment ایجاد یا به‌روزرسانی می‌کند، به‌روزرسانی کنید تا شناسه سازنده نیز ذخیره شود:

# Store the attachment by id.
new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    max_points=int(resp.get("maxPoints")),
    teacher_id=flask.session["login_hint"])
db.session.add(new_attachment)
db.session.commit()

اعتبارنامه معلم را بازیابی کنید

مسیری را بیابید که به نمای دانشجویی iframe سرویس می‌دهد. بلافاصله پس از ذخیره پاسخ دانش آموز در پایگاه داده محلی خود، اعتبار معلم را از حافظه محلی خود بازیابی کنید. این باید با توجه به آماده سازی در دو مرحله قبلی ساده باشد. همچنین می‌توانید از اینها برای ساختن نمونه جدیدی از سرویس Classroom برای کاربر معلم استفاده کنید:

# Create an instance of the Classroom service using the tokens for the
# teacher that created the attachment.

# We're assuming that there are already credentials in the session, which
# should be true given that we are adding this within the Student View
# route; we must have had valid credentials for the student to reach this
# point. The student credentials will be valid to construct a Classroom
# service for another user except for the tokens.
if not flask.session.get("credentials"):
    raise ValueError(
        "No credentials found in session for the requested user.")

# Make a copy of the student credentials so we don't modify the original.
teacher_credentials_dict = deepcopy(flask.session.get("credentials"))

# Retrieve the requested user's stored record.
teacher_record = User.query.get(attachment.teacher_id)

# Apply the user's tokens to the copied credentials.
teacher_credentials_dict["refresh_token"] = teacher_record.refresh_token
teacher_credentials_dict["token"] = teacher_record.access_token

# Construct a temporary credentials object.
teacher_credentials = google.oauth2.credentials.Credentials(
    **teacher_credentials_dict)

# Refresh the credentials if necessary; we don't know when this teacher last
# made a call.
if teacher_credentials.expired:
    teacher_credentials.refresh(Request())

# Request the Classroom service for the specified user.
teacher_classroom_service = googleapiclient.discovery.build(
    serviceName=CLASSROOM_API_SERVICE_NAME,
    version=CLASSROOM_API_VERSION,
    credentials=teacher_credentials)

نمره یک ارسال را تنظیم کنید

روال از اینجا مشابه روش استفاده از اعتبار معلمی است که وارد سیستم شده است . با این حال، توجه داشته باشید که باید با اعتبار معلم بازیابی شده در مرحله قبل تماس بگیرید:

# Issue a PATCH request as the teacher to set the grade numerator for this
# attachment.
patch_grade_response = teacher_classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

افزونه را تست کنید

مشابه مرحله پیشین قبلی، به عنوان معلم یک تکلیف با پیوستی از نوع فعالیت ایجاد کنید، پاسخی را به عنوان دانش آموز ارسال کنید، سپس ارسال آن را در قالب بررسی کار دانشجویی باز کنید. بسته به رویکرد پیاده سازی شما باید بتوانید درجه را در زمان های مختلف مشاهده کنید:

• اگر زمانی که دانش‌آموز فعالیت را به پایان رساند، نمره را پس می‌گیرید، باید پیش‌نویس نمره پیش‌نویس او را قبل از باز کردن iframe بررسی کار دانشجویی در رابط کاربری ببینید. همچنین می‌توانید آن را در فهرست دانش‌آموز هنگام باز کردن تکلیف، و در کادر «نمره» در کنار iframe بررسی کار دانشجویی مشاهده کنید.
• اگر زمانی که معلم iframe بررسی کار دانشجویی را باز می‌کند، انتخاب کرده‌اید که نمره را پس دهید، نمره باید بلافاصله پس از بارگیری iframe در کادر "Grade" ظاهر شود. همانطور که در بالا ذکر شد ، این می تواند تا 30 ثانیه طول بکشد. پس از آن، نمره دانش‌آموز خاص باید در سایر نماهای دفترچه نمرات Classroom نیز ظاهر شود.

تأیید کنید که نمره صحیح برای دانش آموز ظاهر می شود.

تبریک می گویم! برای ادامه مرحله بعدی آماده‌اید: ایجاد پیوست‌های خارج از Google Classroom .