یک افزونه Classroom ایجاد کنید

این اولین قدم در مجموعه مروری بر افزونه های Classroom است.

در این راهنما، شما زمینه را برای توسعه یک برنامه وب و انتشار آن به عنوان یک افزونه Classroom فراهم می کنید. مراحل پیش رو آینده این برنامه را گسترش می دهد.

در طول این راهنما موارد زیر را تکمیل می کنید:

• یک پروژه Google Cloud جدید برای افزونه خود ایجاد کنید.
• یک برنامه وب اسکلت با دکمه های ورود به سیستم نگهدارنده مکان ایجاد کنید.
• فهرست فروشگاه 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 جدید ایجاد کنید. شما می توانید هر نامی را برای پروژه جدید ارائه دهید. روی ایجاد کلیک کنید.

چند لحظه طول می کشد تا پروژه جدید به طور کامل ایجاد شود. پس از انجام، حتما پروژه را انتخاب کنید . می‌توانید آن را در منوی کشویی انتخابگر پروژه در بالای صفحه انتخاب کنید، یا روی SELECT PROJECT در منوی اعلان‌ها در بالا سمت راست کلیک کنید.

Google Workspace Marketplace SDK را به پروژه Google Cloud وصل کنید

به مرورگر API Library بروید. Google Workspace Marketplace SDK را جستجو کنید. باید ببینید SDK در لیست نتایج ظاهر می شود.

کارت Google Workspace Marketplace SDK را انتخاب کنید، سپس روی فعال کردن کلیک کنید.

Google Workspace Marketplace SDK را پیکربندی کنید

Google Workspace Marketplace فهرستی را ارائه می دهد که از طریق آن کاربران و سرپرستان افزونه شما را نصب می کنند. برای ادامه، پیکربندی برنامه و فهرست فروشگاه SDK Marketplace و صفحه رضایت OAuth را پیکربندی کنید.

پیکربندی برنامه

به صفحه پیکربندی برنامه Marketplace SDK بروید. اطلاعات زیر را ارائه دهید:

• مشاهده برنامه را روی Public یا Private تنظیم کنید.

  • تنظیمات عمومی برای برنامه هایی در نظر گرفته شده است که در نهایت برای کاربران نهایی منتشر می شوند. یک برنامه عمومی قبل از انتشار برای کاربران نهایی باید مراحل تأیید را طی کند، اما می‌توانید کاربرانی را مشخص کنید که بتوانند آن را به عنوان پیش‌نویس نصب و آزمایش کنند. این یک حالت پیش از انتشار است که به شما امکان می دهد افزونه خود را قبل از ارسال برای تأیید آزمایش و توسعه دهید.
  • تنظیمات خصوصی برای آزمایش و توسعه داخلی مناسب است. یک برنامه خصوصی را فقط کاربران می توانند در همان دامنه ای که پروژه ایجاد شده است نصب کنند. بنابراین ، فقط در صورتی که پروژه در دامنه‌ای با اشتراک Google Workspace for Education ایجاد شده باشد، باید قابلیت مشاهده را روی خصوصی تنظیم کنید ، در غیر این صورت کاربران آزمایشی شما نمی‌توانند افزونه‌های Classroom را راه‌اندازی کنند.

• تنظیمات نصب را روی Admin Only install که بخواهید نصب را به مدیران دامنه محدود کنید.

• در بخش App Integration ، افزونه Classroom را انتخاب کنید. از شما خواسته می شود که URI ایمن تنظیم پیوست را انتخاب کنید. این نشانی اینترنتی است که انتظار دارید زمانی که کاربر افزونه شما را باز می کند، بارگیری شود. برای اهداف این راهنما، این باید https://<your domain>/addon-discovery باشد.

• پیشوندهای Allowed Attachment URI برای اعتبارسنجی URIهای تنظیم شده در AddOnAttachment با استفاده از courses.*.addOnAttachments.create و courses.*.addOnAttachments.patch استفاده می‌شوند. اعتبارسنجی یک تطبیق پیشوند رشته تحت اللفظی است و در حال حاضر اجازه استفاده از کارت های وحشی را نمی دهد. حداقل دامنه اصلی سرور محتوای خود را اضافه کنید، مانند https://localhost:5000/ یا https://cdn.myedtech.com/ .

• همان محدوده های OAuth را که در صفحه رضایت OAuth در مرحله قبل ارائه شده است، اضافه کنید.

• فیلدها را مطابق با سازمان خود در زیر پیوندهای برنامه نویس تکمیل کنید.

فهرست فروشگاه

به صفحه فهرست فروشگاه Marketplace SDK بروید. اطلاعات زیر را ارائه دهید:

• در قسمت جزئیات برنامه ، یک زبان اضافه کنید یا منوی کشویی کنار زبانی که از قبل فهرست شده است را گسترش دهید. نام و توضیحات برنامه را ارائه دهید. اینها در صفحه فهرست فروشگاه Google Workspace Marketplace افزونه شما ظاهر می شوند. برای ذخیره روی Done کلیک کنید.
• یک دسته برای افزونه خود انتخاب کنید.
• در بخش Graphics Assets ، تصاویری را برای فیلدهای مورد نیاز ارائه دهید. اینها را می توان بعداً تغییر داد، و فعلاً می توانند مکان هایی باشند.
• در زیر پیوندهای پشتیبانی ، URL های درخواستی را ارائه دهید. اگر در مرحله قبل نمایان بودن برنامه را روی Private تنظیم کنید، اینها می توانند متغیرهایی باشند.

اگر در مرحله قبل App Visibility را روی Private تنظیم کرده اید، روی PUBLISH کلیک کنید. برنامه شما بلافاصله برای نصب در دسترس است. اگر نمایان بودن برنامه را روی عمومی تنظیم کرده‌اید، آدرس‌های ایمیل را در قسمت آزمایش‌کنندگان پیش‌نویس برای کاربران آزمایشی اضافه کنید و روی ذخیره پیش‌نویس کلیک کنید.

صفحه رضایت OAuth

هنگامی که کاربران برای اولین بار برنامه شما را مجوز می دهند، صفحه رضایت OAuth ظاهر می شود. از آن‌ها می‌خواهد که به برنامه شما اجازه دهند تا به اطلاعات شخصی و حسابشان دسترسی داشته باشد، همانطور که محدوده‌هایی که شما فعال می‌کنید دیکته می‌شود.

به صفحه ایجاد صفحه رضایت OAuth بروید. اطلاعات زیر را ارائه دهید:

• نوع کاربر را روی خارجی قرار دهید. روی ایجاد کلیک کنید.
• در صفحه بعد، جزئیات برنامه و اطلاعات تماس مورد نیاز را پر کنید. دامنه‌هایی را که میزبان برنامه شما هستند در زیر دامنه‌های مجاز ارائه کنید. روی ذخیره و ادامه کلیک کنید.

• هر محدوده OAuth را که برنامه وب شما نیاز دارد اضافه کنید. راهنمای پیکربندی OAuth را برای بحث عمیق در مورد دامنه ها و هدف آنها ببینید.

  شما باید حداقل یکی از حوزه های زیر را درخواست کنید تا Google پارامتر query 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 و / endpoints را پیاده سازی کنید.

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 شوید. به برگه Classwork بروید و یک تکلیف جدید ایجاد کنید. افزونه خود را از انتخابگر افزونه ها انتخاب کنید. iframe باز می‌شود و افزونه URI تنظیمات پیوست را که در صفحه پیکربندی برنامه Marketplace SDK مشخص کرده‌اید، بارگیری می‌کند.

تبریک می گویم! شما آماده هستید تا به مرحله بعدی بروید: ورود به سیستم کاربران با Google SSO .