ציונים של קבצים מצורפים וחזרת ציונים

זהו המדריך השישי בסדרת המדריכים שלנו על תוספים ל-Classroom.

במדריך הזה נעביר אתכם על שינוי הדוגמה מהשלב הקודם במדריך, כדי ליצור קובץ מצורף מסוג פעילות שניתן לתת עליו ציונים. אתם יכולים גם להעביר חזרה ל-Google Classroom ציון באופן פרוגרמטי, והוא יופיע ביומן הציונים של המורה כטיוטה.

המדריך הזה שונה במקצת מהמדריכים האחרים בסדרה, כי יש בו שתי גישות אפשריות להעברת הציונים בחזרה ל-Classroom. לשני הגורמים האלה יש השפעה שונה על חוויית המשתמש וחוויית המפתח, ולכן חשוב להביא בחשבון את שניהם בתכנון התוסף ל-Classroom. אפשר לקרוא את המדריך בנושא אינטראקציה עם קבצים מצורפים כדי לקבל מידע נוסף על אפשרויות ההטמעה.

לתשומת ליבכם: תכונות הדירוג ב-API הן אופציונליות. אפשר להשתמש בהם עם כל קובץ מצורף מסוג פעילות.

במהלך המדריך הזה תלמדו:

• משנים את הבקשות הקודמות ליצירת קבצים מצורפים ל-Classroom API כך שיגדירו גם את המכנה של הציון של הקובץ המצורף.
• מתן ציון באופן פרוגרמטי להגשה של התלמיד או התלמידה והגדרת המונה של הציון של הקובץ המצורף.
• איך מטמיעים שתי גישות להעברת הציון של המטלה ל-Classroom באמצעות פרטי כניסה של מורים או פרטי כניסה אופליין.

בסיום, הציונים יופיעו ביומן הציונים של Classroom אחרי שההתנהגות של העברת הנתונים תופעל. הרגע המדויק שבו זה קורה תלוי בשיטת ההטמעה.

לצורך הדוגמה הזו, נשתמש שוב בפעילות מההדרכה הקודמת, שבה מוצגת לתלמידים תמונה של אתר היסטורי מפורסם והם מתבקשים להזין את השם שלו. נותנים ציונים מלאים על הקובץ המצורף אם התלמיד/ה מזינים את השם הנכון, ואפס אחרת.

הסבר על התכונה של מתן ציונים דרך API של תוספים ל-Classroom

התוסף יכול להגדיר גם את המונה וגם את המכנה של הציון לקובץ המצורף. הערכים האלה מוגדרים באמצעות הערכים pointsEarned ו-maxPoints ב-API. כרטיס הקובץ בממשק המשתמש של Classroom מציג את הערך של maxPoints אחרי שהוא מוגדר.

איור 1. ממשק המשתמש ליצירת מטלה עם שלוש כרטיסיות של קבצים מצורפים של תוספי Classroom שמוגדרת בהם האפשרות 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 מאוחר יותר כשתנתנו ציונים למטלות של התלמידים. עם זאת, חשוב לזכור שיכול להיות שהמורים ישנו את ההגדרות של הציונים במטלות ללא קשר לתוסף. שולחים בקשת 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. בדרך כלל, ההשהיה נמשכת בין חמש ל-10 שניות, אבל היא יכולה להימשך עד 30 שניות.

השילוב של הגורמים האלה עשוי לחייב את המורים לבצע עבודה ידנית משמעותית וממושכת כדי לאכלס את הציונים של הכיתה באופן מלא.

כדי להטמיע את הגישה הזו, מוסיפים קריאה נוספת ל-API למסלול הקיים של בדיקת המטלות של התלמידים.

אחרי אחזור הרשומות של ההגשה והקבצים המצורפים של התלמיד, צריך להעריך את ההגשה של התלמיד ולאחסן את הציון שהתקבל. מגדירים את הציון בשדה pointsEarned של אובייקט AddOnAttachmentStudentSubmission. לבסוף, שולחים בקשת PATCH אל נקודת הקצה (endpoint) 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. להגדיר ציון למטלה.

לצורך ההדגמה הזו, נגדיר את הציון כשהתלמיד/ה ישלים את הפעילות, כלומר כשהתלמיד/ה ישלח/ה את הטופס במסלול 'תצוגת התלמיד/ה'.

שינוי הרשומות במסד הנתונים של המשתמשים כדי לאחסן את טוקן הגישה

כדי לבצע קריאות ל-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 של תצוגת התלמיד/ה.

הדוגמה הזו מדגימה את האפשרות האחרונה, כי אתם מגדירים ציונים כשהתלמיד/ה משלים/ה את הקובץ המצורף לפעילות.

מוסיפים שדה של מזהה מורה לטבלה 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.