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

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

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

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

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

במהלך ההדרכה המפורטת הזו, תצטרכו:

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

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

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

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

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

איור 1. ממשק המשתמש ליצירת מטלות עם שלושה כרטיסים מצורפים אחרים, הוגדרו maxPoints.

אפשר לקבוע את ההגדרות של התוספים ב-Classroom API הציון שהרווחתם עבור ציונים של צירוף. הן לא זהות ציונים למטלות. עם זאת, הגדרות הציונים למטלה נקבעות לפי את ההגדרות של ציונים בקובץ המצורף, עם התווית סנכרון ציונים של הקובץ. את הכרטיס המצורף. מה קורה בקטע 'סנכרון ציונים' הקבצים המצורפים 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 אל נקודת הקצה (endpoint) 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 נדרש היקף הרשאות OAuth teacher. אסור להעניק היקף הרשאות של teacher למשתמשים לסטודנטים. כתוצאה מכך התנהגות לא צפויה כשתלמידים יוצרים אינטראקציה עם התוסף, למשל טעינה ה-iframe של תצוגת המורה במקום ה-iframe של תצוגת התלמידים. כלומר, האפשרויות להגדרה של pointsEarned:

• באמצעות פרטי הכניסה של המורה שמחובר לחשבון.
• שימוש בפרטי כניסה של מורים שמאוחסנים (אופליין).

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

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

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

עם זאת, חשוב לזכור שהמורה רק מקיים אינטראקציה עם התלמיד/ה ב-iframe של סקירת עבודות התלמידים. יש לזה כמה נקודות חשובות, השלכות:

• לא יופיעו ציונים ב-Classroom עד שהמורה יתמלא פעולה מסוימת בממשק המשתמש של Classroom.
• ייתכן שהמורה יצטרך לפתוח את כל העבודות של התלמידים כדי לאכלס את כל המטלות בציונים של התלמידים.
• יש עיכוב קצר עד לקבלת הציון ב-Classroom ואת המראה שלו בממשק המשתמש של Classroom. העיכוב הוא בדרך כלל חמש עד עשר שניות, אבל הוא יכול להימשך עד 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 בקשות לנקודת הקצה (endpoint) של 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.