תוספים ל-Google Classroom זמינים עכשיו למפתחים! למידע נוסף, יש לעיין במסמכי התיעוד בנושא תוספים.

דף זה תורגם על ידי Cloud Translation API.

קבצים מצורפים חיצוניים והגשה

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

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

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

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

הוספת היקף ההרשאות ל-OAuth לניהול הקצאות

צריך לוודא שהאפליקציה מבקשת את ההיקפים הבאים:

https://www.googleapis.com/auth/classroom.addons.teacher
https://www.googleapis.com/auth/classroom.addons.student
https://www.googleapis.com/auth/classroom.coursework.students

לא היה צורך בהיקף classroom.coursework.students בעבר, והוא משמש ליצירה או לשינוי של מטלות CourseWork. מוסיפים את ההיקף הזה לרשימות היקפי ההרשאות ב- Google Workspace Marketplace SDK, במסך ההסכמה של OAuth ובקוד השרת.

Python

  SCOPES = [
    "https://www.googleapis.com/auth/classroom.addons.teacher",
    "https://www.googleapis.com/auth/classroom.addons.student",
    "https://www.googleapis.com/auth/classroom.coursework.students",
  ]

יצירת מטלה ב-Classroom

הוספת לחצנים לדף אינטרנט שאינו iframe

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

אם עדיין אין לכם לחצן, תצטרכו להוסיף לחצן או קישור כדי לאפשר למשתמש להיכנס. תצטרכו את פרטי הכניסה של המשתמש כדי לשלוח את בקשות ה-API הבאות, ולכן המשתמשים יצטרכו להשלים את לחיצת היד ב-OAuth 2.0. הנחיות ספציפיות מופיעות בהדרכה המפורטת לכניסה.

Python

הדוגמה של Python שסופקה משנה את המסלול /index שנוסף בשלב ההדרכה הראשון.

<!-- /webapp/templates/index.html -->
<a href="clear-credentials.html">Logout</a>
<a href="start-auth-flow.html">Login</a>

<br>

<a href="create-coursework-assignment.html">Create a CourseWork Assignment</a>

צריך להוסיף תבנית HTML כדי לייצג יעד באתר. הדף הזה ייצג את התוכן שיצורף למטלה CourseWork.

<!-- /webapp/templates/example-coursework-assignment.html -->
<h1>CourseWork assignment loaded!</h1>
<p>You've loaded a CourseWork assignment! It was created from an external web page.</p>

יוצרים קובץ מודול Python חדש כדי לטפל במסלולים שקשורים ל-CourseWork. זהו coursework_routes.py בדוגמה שסופקה. מוסיפים את שלושת המסלולים הבאים, ושימו לב שאתם ממלאים חלק מהתוכן מאוחר יותר.

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """

  # Check that the user is signed in. If not, perform the OAuth 2.0
  # authorization flow.
  credentials = get_credentials()

  if not credentials:
    return start_auth_flow("coursework_assignment_callback")

  # Construct the Google Classroom service.
  classroom_service = get_classroom_service()

  pass  # To be completed later.

@app.route("/example-coursework-assignment/<assignment_type>")
def example_coursework_assignment(assignment_type):
  """
  Renders the "example-coursework-assignment.html" template.
  """
  return flask.render_template(
      "example-coursework-assignment.html", assignment_type=assignment_type
  )

@app.route("/coursework-assignment-callback")
def coursework_assignment_callback():
  """
  Completes the OAuth 2.0 handshake and stores credentials in the session.
  This is identical to the callback introduced in the sign-in walkthrough,
  but redirects the user to the index page instead of the attachment
  discovery page.
  """
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE,
      scopes=SCOPES,
      state=flask.session["state"],
      redirect_uri=flask.url_for("coursework_assignment_callback", _external=True),
  )

  flow.fetch_token(authorization_response=flask.request.url)

  credentials = flow.credentials
  flask.session["credentials"] = session_credentials_to_dict(
      credentials
  )

  # Close the current window and redirect the user to the index page.
  return flask.render_template("close-me.html", redirect_destination="index")

בדיקת הזכאות ליצירת תוספים למשתמש

כדי ליצור קבצים מצורפים לתוספים בשמו, יש כמה דרישות מוקדמות שהמשתמש צריך לעמוד בהן. לנוחיותכם, Google מספקת את השיטה courses.checkAddOnCreationEligibility כדי לקבוע אם משתמש עומד בדרישות המוקדמות האלה. משתמש שעומד בדרישות המוקדמות נחשב כמשתמש עומד בדרישות.

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

Python

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """
  # ... Check that the user is signed in and get the Classroom service ...

  # The ID of the course to which the assignment will be added.
  course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

  # Check whether the user can create add-on attachments.
  eligibility_response = (
      classroom_service.courses()
      .checkAddOnCreationEligibility(courseId=course_id)
      .execute()
  )
  is_create_attachment_eligible = eligibility_response.get("isCreateAttachmentEligible")

  if is_create_attachment_eligible:
    # See the "Create an assignment with add-on attachment for eligible users" section for implementation.
  if not is_create_attachment_eligible:
    # See the "Create a Link Material" section for implementation.

יצירת מטלה עם קובץ מצורף של תוסף למשתמשים שעומדים בדרישות

אם המשתמש עומד בדרישות ליצירת קבצים מצורפים של תוספים, צריך לבצע את הפעולות הבאות:

שולחים בקשת API ליצירת מטלה ב-courseWork ב-Google Classroom ללא קבצים מצורפים.
מחלצים את השדה id של המטלה החדשה שנוצרה.
יוצרים CourseWork AddOnAttachment חדש.
שולחים בקשה ליצירת קובץ מצורף של תוסף במטלה החדשה שנוצרה ב-Google Classroom.

Python

# /webapp/coursework_routes.py
if is_create_attachment_eligible:
  # Create an assignment.
  coursework = {
      "title": "My CourseWork Assignment with Add-on Attachment",
      "description": "Created using the Classroom CourseWork API.",
      "workType": "ASSIGNMENT",
      "state": "DRAFT",  # Set to 'PUBLISHED' to assign to students.
  }

  # Issue a request to create the assignment.
  create_assignment_response = (
      classroom_service.courses()
      .courseWork()
      .create(courseId=course_id, body=coursework)
      .execute()
  )

  # Create an add-on attachment that links to the selected content and
  # associate it with the new assignment.
  content_url = flask.url_for(
      "example_coursework_assignment",
      assignment_type="add-on-attachment",
      _scheme="https",
      _external=True,
  )

  # Construct an AddOnAttachment instance.
  attachment = {
      "teacherViewUri": {"uri": content_url},
      "studentViewUri": {"uri": content_url},
      "title": f'Test Attachment for Assignment {create_assignment_response.get("id")}',
  }

  # Issue a request to create the attachment.
  add_on_attachment_response = (
      classroom_service.courses()
      .courseWork()
      .addOnAttachments()
      .create(
          courseId=course_id,
          itemId=create_assignment_response.get("id"),  # ID of the new assignment.
          body=attachment,
      )
      .execute()
  )

יצירת חומר לימוד

אם המשתמש לא עומד בדרישות ליצירת קבצים מצורפים לתוספים, צריך לבצע את הפעולות הבאות כדי ליצור חומר קישור:

Python

if not is_create_attachment_eligible:
    coursework = {
        "title": "My CourseWork Assignment with Link Material",
        "description": "Created using the Classroom CourseWork API.",
        "workType": "ASSIGNMENT",
        "state": "DRAFT",  # Set to 'PUBLISHED' to assign to students.
        # Specify the URL for your content as a Link Material.
        "materials": [
            {
                "link": {
                    "url": flask.url_for(
                        "example_coursework_assignment",
                        assignment_type="link-material",
                        _scheme="https",
                        _external=True,
                    )
                }
            }
        ],
    }

    # Issue a request to create the assignment.
    assignment_response = (
        classroom_service.courses()
        .courseWork()
        .create(courseId=course_id, body=coursework)
        .execute()
    )

שינוי מטלה שכבר נוצרה

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

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

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

Python

הדוגמה של Python שסופקה משנה את המסלול של /index שהשתנה מוקדם יותר בהדרכה המפורטת הזו.

<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>

אפשר ליצור נתיב חדש כדי לטפל במסלולים שקשורים ל-CourseWork. זה הקובץ coursework_routes.py בדוגמה שסופקה.

# Check that the user is signed in.
credentials = get_credentials()

if not credentials:
  return start_auth_flow("coursework_assignment_callback")

# Get the Google Classroom service.
classroom_service = get_classroom_service()

# The ID of the course to which the assignment will be added.
# Ordinarily, you'll prompt the user to specify which course to use. For
# simplicity, we use a hard-coded value in this example.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.
assignment_id = 1234567890  # TODO(developer) Replace with an actual assignment ID.

# Retrieve details about the CourseWork assignment.
get_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .get(courseId=course_id, id=assignment_id)
    .execute()
)

# Alter the current title.
assignment_title = f"{get_coursework_response.get('title')} (Modified by API request)"

# Issue a request to modify the assignment.
modify_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .patch(
        courseId=course_id,
        id=assignment_id,
        updateMask="title",
        body={"title": assignment_title},
    )
    .execute()
)

בדיקת התוסף

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

בדיקת היצירה של חומר קישור

מפעילים את השרת, עוברים לדף האינדקס ונכנסים לחשבון בתור מורים בלי רישיון ל-Google Workspace for Education Teaching & Learning או Plus. אפשר לשנות את סטטוס הרישיון של המשתמש במסוף Admin של הדומיין לבדיקה.לוחצים על הלחצן Create a CourseWork Assignment, ואז פותחים את ממשק המשתמש של Google Classroom ומוודאים שנוצרה מטלה עם קובץ מצורף של חומר לימוד. הקובץ המצורף צריך לכלול את הכותרת של דף האינטרנט המקושר וכתובת URL.

בדיקת יצירת קובץ מצורף של תוסף

חוזרים לדף האינדקס ונכנסים בתור משתמשים של מורים עם רישיון Google Workspace for Education Teaching& Learning או Plus. לוחצים על הלחצן Create a CourseWork Assignment, ולאחר מכן פותחים את ממשק המשתמש של Google Classroom ומוודאים שנוצרת מטלה עם קובץ מצורף של תוסף. הקובץ המצורף צריך להציג את השם של אפליקציית התוסף ואת הכותרת שצוינה בקוד.

שינוי מטלה לבדיקה

עליכם לחזור לדף האינדקס ולוודא שנכנסתם למערכת כמשתמש/ת מורה עם רישיון ל-Teaching & Learning או ל-Plus. לוחצים על הלחצן Modify a CourseWork מטלה, חוזרים לממשק המשתמש של Google Classroom ומוודאים ששם המטלה השתנה.

כל הכבוד! השלמת את סדרת ההדרכה המפורטת.