יצירת תוסף ל-Classroom

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

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

ההדרכה המפורטת כוללת את הדברים הבאים:

• יוצרים פרויקט חדש ב-Google Cloud לתוסף.
• צור אפליקציית אינטרנט בסיסית עם לחצני כניסה באמצעות placeholder.
• מפרסמים דף אפליקציה בחנות Google Workspace Marketplace בשביל התוסף.

בסיום אפשר להתקין את התוסף ולטעון אותו iframe של תוספים ל-Classroom.

דרישות מוקדמות

בוחרים שפה כדי לראות את הדרישות המוקדמות המתאימות:

python -m ensurepip --upgrade

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

cd flask/01-basic-app
pip install -r requirements.txt

npm install

java --version
./mvnw --version

java -version
mvnw.cmd --version

הגדרת פרויקט ב-Google Cloud

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

יצירת הפרויקט

כדי ליצור פרויקט חדש ב-Google Cloud, נכנסים לדף יצירת הפרויקט. אפשר מזינים שם לפרויקט החדש. לוחצים על Create.

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

צירוף של Google Workspace Marketplace SDK לפרויקט ב-Google Cloud

עוברים לדפדפן של API Library. חיפוש של Google Workspace Marketplace SDK ה-SDK אמור להופיע ברשימה של תוצאות.

בוחרים את הכרטיס של Google Workspace Marketplace SDK ולוחצים על הפעלה.

הגדרת ה-SDK של Google Workspace Marketplace

Google Workspace Marketplace מספק את דף האפליקציה שדרכו המשתמשים אדמינים מתקינים את התוסף. מגדירים את הגדרת האפליקציה ושל Marketplace SDK רשימה ומסך ההסכמה של OAuth כדי להמשיך.

הגדרת האפליקציה

עוברים לדף הגדרת אפליקציה של Marketplace SDK. מספקים את הפרטים הבאים:

• מגדירים את הרשאות גישה לאפליקציה לערך Public או Private.

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

• אם רוצים, משנים את הגדרות ההתקנה ל-Admin Only install. להגביל את ההתקנה למנהלי דומיין בלבד.

• בקטע שילוב האפליקציה, בוחרים באפשרות תוסף ל-Classroom. היתרה שלך תוצג בקשה ל-URI מאובטח להגדרת קבצים מצורפים; זו כתובת ה-URL ייטענו כשמשתמש פותח את התוסף. למטרות ההדרכה המפורטת, היא צריכה להיות https://<your domain>/addon-discovery.

• הקידומות המותרות של URI של קבצים מצורפים משמשות לאימות של מזהי ה-URI שהוגדרו AddOnAttachment באמצעות courses.*.addOnAttachments.create courses.*.addOnAttachments.patch שיטות. האימות מילולי התאמה לתחילית של מחרוזת ולא מאפשרת להשתמש בתווים כלליים לחיפוש בשלב הזה בזמן האימון. מוסיפים לפחות את הדומיין הבסיסי (root) של שרת התוכן, כמו https://localhost:5000/ או https://cdn.myedtech.com/.

• מוסיפים את אותם היקפי הרשאות OAuth שמופיעים במסך ההסכמה של OAuth השלב הקודם.

• ממלאים את השדות בהתאם לארגון בקטע מפתח קישורים.

רישום חנות

עוברים אל דף דף האפליקציה בחנות של Marketplace SDK. מספקים את הפרטים הבאים:

• בקטע פרטי האפליקציה, מוסיפים שפה או מרחיבים את התפריט הנפתח שלצד שפה שכבר רשומה. לספק שם אפליקציה ותיאורים; האלה יופיעו בדף האפליקציה בחנות Google Workspace Marketplace של התוסף. לוחצים על סיום כדי לשמור.
• בוחרים קטגוריה לתוסף.
• בקטע נכסים גרפיים, מספקים תמונות של שדות החובה. האתרים האלה יכולים יכולים להשתנות מאוחר יותר, והם יכולים להיות placeholders כרגע.
• בקטע קישורים לתמיכה, מציינים את כתובות ה-URL הנדרשות. האפשרויות האלה יכולות להיות placeholders אם הגדרתם את חשיפת האפליקציה כפרטית בכל פעימה.

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

מסך הסכמה ל-OAuth

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

עוברים לדף ליצירת מסך ההסכמה של OAuth. צריך לספק את הפרטים הבאים מידע:

• מגדירים את User Type כ-External (חיצוני). לוחצים על Create.
• בדף הבא, ממלאים את הפרטים הנדרשים של האפליקציה ואת הפרטים ליצירת קשר. צריך לספק את כל הדומיינים שמארחים את האפליקציה בקטע דומיינים מורשים. לוחצים על שמירה והמשך.

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

  עליך לבקש לפחות אחד מההיקפים הבאים כדי ש-Google תוכל שולחים את פרמטר השאילתה login_hint. הסבר מפורט יותר בנושא ההתנהגות זמינה במדריך להגדרת OAuth:

  • https://www.googleapis.com/auth/userinfo.email (כבר כלול)
  • https://www.googleapis.com/auth/userinfo.profile (כבר כלול)

  ההיקפים הבאים ספציפיים לתוספים ל-Classroom:

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

  לכלול גם את כל היקפי ההרשאות של Google API שהאפליקציה שלכם דורשת מקצה. משתמשים.

  לוחצים על שמור והמשך.

• צריך לציין את כתובות האימייל של כל חשבונות הבדיקה בדף משתמשים לבדיקה. לוחצים על שמירה והמשך.

מוודאים שההגדרות נכונות ואז חוזרים אל מרכז הבקרה.

התקנת התוסף

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

פיתוח של אפליקציית אינטרנט בסיסית

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

מטמיעים את שתי נקודות הקצה הבאות:

• /: מציג הודעת פתיחה ולחצן לסגירה של הכרטיסייה הנוכחית ו-iframe של התוסף.
• /addon-discovery: הצגת הודעת פתיחה ושני לחצנים: אחד לסגירה רכיב ה-iframe של התוסף ותוסף אחד לפתיחת אתר בכרטיסייה חדשה.

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

יצירת סקריפט של כלי עזר

יוצרים ספריית static/scripts. יצירת קובץ חדש addon-utils.js. מוסיפים את לאחר שתי פונקציות.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

יצירת מסלולים

הטמעת נקודות הקצה /addon-discovery ו-/.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/addon-discovery', addonRouter);

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
  });
});

import org.springframework.web.bind.annotation.GetMapping;

@org.springframework.stereotype.Controller
public class Controller {

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

בדיקת התוסף

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

מעולה! עכשיו אפשר להמשיך לשלב הבא: כניסת משתמשים באמצעות SSO של Google.