علامات المرفقات ودرجات التراجع عن الظهور

هذه هي الجولة التفصيلية السادسة في إضافات Classroom. لسلسلة الجولات التفصيلية.

في هذه الجولة التفصيلية، يمكنك تعديل المثال من خطوة الجولة التفصيلية السابقة. لإنشاء مرفق مقيّم من نوع النشاط. يمكنك أيضًا اجتياز درجة مرة أخرى على Google Classroom آليًا، وتظهر في صف المعلّم الكتاب كدرجة أولية.

تختلف هذه الجولة التفصيلية قليلاً عن الطرق التفصيلية الأخرى في السلسلة حيث إنها وتقديم نهجين محتملين لتمرير الدرجات إلى Classroom. كلاهما يؤثر بشكل واضح على المطوّر والمستخدم وخبراتهم يمكنك استخدامهما معًا أثناء تصميم إضافة Classroom. اقرأ صفحة دليل التفاعل مع المرفقات لمزيد من المناقشة حول خيارات التنفيذ.

تجدر الإشارة إلى أنّ ميزات وضع الدرجات في واجهة برمجة التطبيقات اختيارية. يمكن استخدامها مع أي مرفق لنوع النشاط.

خلال هذه الجولة التفصيلية، يمكنك إكمال ما يلي:

• تعديل طلبات إنشاء المرفقات السابقة إلى تتيح Classroom API أيضًا ضبط محدِّد الدرجة للمرفق.
• تسجيل درجات الطالب المُقدّمة بشكل آلي وتعيين درجة المرفق بسط الدرجة.
• تنفيذ نهجين لتمرير درجة التقديم إلى Classroom باستخدام بيانات اعتماد المعلّم الذين سجّلوا الدخول أو بلا إنترنت.

بعد الانتهاء، تظهر الدرجات في دفتر علامات Classroom بعد يتم تشغيل سلوك التراجع عن الظهور. تعتمد اللحظة الدقيقة التي يحدث فيها هذا على نهج التنفيذ.

لأغراض هذا المثال، يُرجى إعادة استخدام النشاط من الجدول الزمني السابق جولة تفصيلية، حيث يتم عرض صورة لأحد المعالم الشهيرة على الطالب يُطلب منك إدخال اسمها. تعيين العلامات الكاملة للمرفق إذا كان الطالب يتم إدخال الاسم الصحيح، أو صفر في الحالات الأخرى.

التعرّف على ميزة وضع الدرجات في واجهات برمجة التطبيقات لإضافات Classroom

يمكن لإضافتك ضبط كل من بسط الدرجة ومقام الدرجة المرفق. يتم ضبط هذه الإعدادات باستخدام pointsEarned وmaxPoints على التوالي. القيم في واجهة برمجة التطبيقات. تظهر بطاقة مرفق في واجهة مستخدم Classroom قيمة maxPoints عند ضبطها.

الشكل 1. واجهة المستخدم لإنشاء المهام الدراسية التي تتضمن ثلاث بطاقات مرفقات إضافية مجموعة maxPoints.

تتيح لك واجهة برمجة تطبيقات إضافات 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 في قاعدة بيانات المرفقات المحلية؛ فإن هذا يوفر الحاجة إلى إجراء استدعاء واجهة برمجة التطبيقات لاحقًا عند وضع درجات على تسليمات الطلاب. ومع ذلك، لاحظ أنه من الممكن تغيير المعلمين إعدادات درجة المهمة بشكل مستقل عن إضافتك. إرسال طلب GET إلى نقطة النهاية courses.courseWork للاطّلاع على maxPoints على مستوى التعيين. عند إجراء ذلك، عليك اجتياز 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. يجب عدم منح نطاق teacher للمستخدمين من الطلاب، فقد يؤدي ذلك إلى سلوك غير متوقع عندما يتفاعل الطلاب مع الإضافة مثل تحميل يمكن للمعلّمين عرض إطار iframe بدلاً من إطار iframe لعرض الطلاب. لذلك لديك خياران خيارات كيفية ضبط pointsEarned:

• باستخدام بيانات اعتماد المعلّم الذي سجّل الدخول
• باستخدام بيانات اعتماد المعلّم المخزّنة (بلا إنترنت)

تناقش الأقسام التالية المفاضلات بين كل نهج قبل وإظهار كل عملية تنفيذ. لاحظ أن الأمثلة المقدمة توضح كلا النهجين لاجتياز درجة إلى Classroom؛ اطّلِع على تعليمات خاصة باللغة أدناه لمعرفة كيفية اختيار أسلوب عند تشغيل الأمثلة المقدمة:

ضبط الدرجات باستخدام بيانات اعتماد المعلّم الذي سجّل الدخول

استخدِم بيانات اعتماد المستخدم الذي سجَّل الدخول لإصدار الطلب لضبط pointsEarned. يجب أن يبدو هذا بديهيًا إلى حد ما لأنه يعكس بقية التنفيذ حتى الآن، وتتطلب القليل من الجهد لإدراكها.

ومع ذلك، ضع في اعتبارك أن المعلّم يتفاعل فقط مع نشاط الطالب المشروع في إطار iframe لمراجعة عمل الطالب. وينطوي ذلك على بعض الآثار المترتبة على ذلك:

• لا تتم تعبئة أي درجات في Classroom حتى يأخذ المعلّم. الإجراء في واجهة مستخدم Classroom.
• قد يضطر المعلّم إلى فتح كل طلب من الطالب لتعبئة جميع درجات الطلاب.
• حدث تأخير لفترة وجيزة بين حصول Classroom على العلامة. ومظهره في واجهة مستخدم Classroom. ويبلغ التأخير عادةً ما تتراوح من خمس إلى عشر ثوانٍ، لكن يمكن أن تصل مدتها إلى 30 ثانية.

عبر الجمع بين هذه العوامل، قد يضطر المعلمون إلى القيام عمل يدوي كبير ويستغرق وقتًا طويلاً لملء درجات الفصل بالكامل.

لتنفيذ هذه الطريقة، أضِف طلب بيانات آخر من واجهة برمجة التطبيقات إلى صفحة "الطالب الحالي" مسار مراجعة العمل.

بعد جلب عمليات الإرسال التي قدمها الطالب وسجلات المرفقات، قم بتقييم تسليم الطالب وتخزين الدرجة الناتجة. حدِّد الدرجة في الحقل 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.

ومن المزايا المهمة لهذا المنهج أنّه تتم تعبئة التصنيفات بدون الحاجة إلى إجراء المعلّم في واجهة مستخدم Classroom لتجنُّب المشاكل المذكورة أعلاه والنتيجة هي أن المستخدمين النهائيين يرون تجربة التقييم سلسة وفعالة. بالإضافة إلى ذلك، يتيح لك هذا المنهج اختيار اللحظة التي تتراجع فيها عن الدرجات، مثل إكمال الطلاب نشاط أو بشكل غير متزامن.

أكمل المهام التالية لتنفيذ هذا النهج:

1. تعديل سجلات قاعدة بيانات المستخدم لتخزين رمز دخول
2. قم بتعديل سجلات قاعدة بيانات المرفقات لتخزين معرّف مدرس.
3. استرداد بيانات اعتماد المدرس وإنشاء حساب جديد (اختياري) مثال خدمة Classroom
4. ضبط درجة أحد المهام

لأغراض هذا العرض التوضيحي، حدد الدرجة عند إكمال الطالب. والنشاط؛ أي عندما يرسل الطالب النموذج في طريقة عرض الطالب المسار الصحيح.

تعديل سجلات قاعدة بيانات المستخدم لتخزين رمز الدخول المميز

يلزم وجود رمزين مميزين فريدين لإجراء طلبات البيانات من واجهة برمجة التطبيقات، وهما الرمز المميز للتحديث رمز الدخول. إذا كنت تتابع السلسلة التفصيلية حتى الآن، يجب أن يخزِّن مخطط جدول User رمزًا مميّزًا لإعادة التحميل. تخزين عملية إعادة التحميل يكون الرمز المميز كافيًا عند إجراء طلبات بيانات من واجهة برمجة التطبيقات فقط مع المستخدم الذي سجّل الدخول، لأنه تحصل على رمز الدخول كجزء من إجراءات المصادقة.

ومع ذلك، تحتاج الآن إلى إجراء المكالمات كشخص آخر غير المستخدم الذي سجّل الدخول، ما يعني أن مسار المصادقة غير متاح. وبالتالي، تحتاج إلى تخزين الدخول إلى جانب الرمز المميز للتحديث. تعديل مخطط الجدول "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 لعرض الطلاب.

يوضح هذا المثال الخيار الأخير نظرًا لأنك تقوم بتعيين الدرجات عند إكمال الطالب لمرفق نشاط.

إضافة حقل معرّف المعلّم إلى جدول 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، ويجب أن تظهر الدرجة في "الدرجة" بعد فترة وجيزة يتم تحميل إطار iframe. كما ذكرنا أعلاه، يمكن أن تستغرق هذه العملية مدة تصل إلى 30 ثانية. بعد ذلك، يجب أن تظهر الدرجة للطالب المحدَّد أيضًا في طرق العرض الأخرى لدفتر العلامات في Classroom.

تأكَّد من ظهور الدرجة الصحيحة للطالب.

تهانينا! يمكنك الآن المتابعة إلى الخطوة التالية: إنشاء المرفقات. خارج Google Classroom.