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

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

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

در طول این راهنمای گام به گام، موارد زیر را تکمیل می‌کنید:

• یک پروژه جدید Google Cloud برای افزونه خود ایجاد کنید.
• یک برنامه وب اسکلت‌دار با دکمه‌های ورود به سیستم ایجاد کنید.
• یک فهرست فروشگاه Google Workspace Marketplace برای افزونه خود منتشر کنید.

پس از اتمام، می‌توانید افزونه خود را نصب کرده و آن را در iframe افزونه‌های کلاس درس بارگذاری کنید.

پیش‌نیازها

برای مشاهده پیش‌نیازهای مربوطه، یک زبان را انتخاب کنید:

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

راه‌اندازی یک پروژه گوگل کلود

دسترسی به API کلاس درس و روش‌های احراز هویت مورد نیاز توسط پروژه‌های Google Cloud کنترل می‌شوند. دستورالعمل‌های زیر شما را در حداقل مراحل ایجاد و پیکربندی یک پروژه جدید برای استفاده با افزونه‌تان راهنمایی می‌کند.

پروژه را ایجاد کنید

با مراجعه به صفحه ایجاد پروژه، یک پروژه جدید Google Cloud ایجاد کنید. می‌توانید هر نامی برای پروژه جدید انتخاب کنید. روی ایجاد کلیک کنید.

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

کیت توسعه نرم‌افزار (SDK) بازار فضای کاری گوگل (Google Workspace Marketplace) را به پروژه گوگل کلود (Google Cloud) متصل کنید.

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

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

پیکربندی SDK بازار فضای کاری گوگل

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

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

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

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

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

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

• در بخش «یکپارچه‌سازی برنامه» ، افزونه‌ی کلاس درس را انتخاب کنید. از شما خواسته می‌شود آدرس اینترنتی (URI) مربوط به تنظیمات پیوست امن را وارد کنید؛ این همان آدرس اینترنتی است که انتظار دارید هنگام باز شدن افزونه توسط کاربر، بارگذاری شود. برای اهداف این راهنما، این آدرس باید https://<your domain>/addon-discovery باشد.

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

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

• فیلدهای مربوط به سازمان خود را در قسمت پیوندهای توسعه‌دهندگان (Developer Links) تکمیل کنید.

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

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

• در قسمت جزئیات برنامه ، یک زبان اضافه کنید یا منوی کشویی کنار زبانی که از قبل فهرست شده است را باز کنید. نام برنامه و توضیحات آن را وارد کنید؛ این موارد در صفحه فهرست فروشگاه Google Workspace Marketplace افزونه شما نمایش داده می‌شوند. برای ذخیره، روی «انجام شد» کلیک کنید.
• یک دسته بندی برای افزونه خود انتخاب کنید.
• در بخش دارایی‌های گرافیکی ، برای فیلدهای مورد نیاز تصویر وارد کنید. این تصاویر را می‌توان بعداً تغییر داد و فعلاً می‌توان از آنها به عنوان جایگزین استفاده کرد.
• در قسمت پیوندهای پشتیبانی ، آدرس‌های اینترنتی (URL) درخواستی را وارد کنید. اگر در مرحله قبل، قابلیت مشاهده برنامه (App Visibility) را روی خصوصی (Private) تنظیم کرده باشید، این آدرس‌ها می‌توانند به عنوان جایگزین (placeholder) استفاده شوند.

اگر در مرحله قبل، قابلیت مشاهده برنامه را روی خصوصی (Private) تنظیم کرده‌اید، روی انتشار (PUBLISH) کلیک کنید؛ برنامه شما بلافاصله برای نصب در دسترس است. اگر قابلیت مشاهده برنامه را روی عمومی (Public) تنظیم کرده‌اید، آدرس‌های ایمیل را در قسمت پیش‌نویس آزمایش‌کنندگان (Draft Testers) برای هر کاربر آزمایشی اضافه کنید و روی ذخیره پیش‌نویس (Save Draft) کلیک کنید.

صفحه رضایت OAuth

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

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

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

• هر محدوده‌ی OAuth مورد نیاز برنامه‌ی وب خود را اضافه کنید. برای بحث عمیق‌تر در مورد محدوده‌ها و هدف آنها، به راهنمای پیکربندی OAuth مراجعه کنید.

  برای اینکه گوگل پارامتر کوئری login_hint را ارسال کند، باید حداقل یکی از scopeهای زیر را درخواست کنید. توضیح دقیق‌تر این رفتار در راهنمای پیکربندی 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

  همچنین هرگونه محدوده API گوگل دیگری را که برنامه شما از کاربران نهایی درخواست می‌کند، لحاظ کنید.

  روی ذخیره و ادامه کلیک کنید.

• آدرس‌های ایمیل حساب‌های آزمایشی را در صفحه کاربران آزمایشی فهرست کنید. روی ذخیره و ادامه کلیک کنید.

تأیید کنید که تنظیمات شما صحیح است، سپس به داشبورد برگردید.

افزونه را نصب کنید

اکنون می‌توانید افزونه خود را با استفاده از لینکی که در بالای صفحه فهرست فروشگاه Marketplace SDK قرار دارد، نصب کنید. برای مشاهده فهرست ، روی «مشاهده در بازار» در بالای صفحه کلیک کنید، سپس «نصب» را انتخاب کنید.

ساخت یک برنامه وب پایه

یک برنامه وب اسکلتی با دو مسیر راه‌اندازی کنید. مراحل بعدی این برنامه را گسترش می‌دهند، بنابراین فعلاً فقط یک صفحه فرود برای افزونه /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 .