راهپیمایی ها

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

افزونه شما باید با پروژه Google Cloud تعامل داشته باشد. اگر با Google Cloud آشنایی ندارید، توصیه می کنیم راهنمای شروع کار را مطالعه کنید. شما اعتبارنامه ها، دسترسی به API و Google Workspace Marketplace SDK را در کنسول Google Cloud مدیریت می کنید. برای اطلاعات بیشتر در مورد Marketplace SDK، از صفحه راهنمای فهرست Google Workspace Marketplace دیدن کنید.

این راهنما موضوعات زیر را پوشش می دهد:

  • از Google Cloud برای ایجاد صفحه ای برای نمایش در iframe در Classroom استفاده کنید.
  • Google single sign-on (SSO) را اضافه کنید و به کاربران اجازه ورود به سیستم را بدهید.
  • برای پیوست کردن افزونه خود به یک تکلیف، تماس‌های API برقرار کنید.
  • به الزامات ارسال افزودنی کلیدی و ویژگی های مورد نیاز رسیدگی کنید.

این راهنما فرض می کند که شما با برنامه نویسی و مفاهیم اساسی توسعه وب آشنا هستید. ما قویاً توصیه می کنیم قبل از شروع مراحل، راهنمای پیکربندی پروژه را بخوانید. این صفحه حاوی جزئیات مهمی از پیکربندی است که به طور کامل در دستورالعمل ها پوشش داده نشده است.

نمونه اجراها

یک مثال مرجع کامل در پایتون موجود است. پیاده سازی جزئی نیز در جاوا و Node.js موجود است. این پیاده سازی ها منابع کد نمونه ای هستند که در صفحات بعدی یافت می شوند.

از کجا دانلود کنیم

نمونه های پایتون و جاوا در مخازن GitHub موجود هستند:

نمونه Node.js را می توان به صورت یک فایل فشرده دانلود کرد:

پیش نیازها

برای تهیه یک پروژه افزودنی جدید، بخش های زیر را مرور کنید.

گواهی HTTPS

در حالی که می توانید برنامه خود را در هر محیط توسعه میزبانی کنید، افزونه Classroom شما فقط از طریق https:// در دسترس است. بنابراین، شما به یک سرور با رمزگذاری SSL برای استقرار برنامه خود یا آزمایش آن در iframe افزودنی نیاز دارید.

امکان استفاده از localhost با گواهی SSL وجود دارد. اگر نیاز به ایجاد گواهی برای توسعه محلی دارید، mkcert را در نظر بگیرید.

پروژه Google Cloud

شما باید یک پروژه Google Cloud را برای استفاده با این مثال ها پیکربندی کنید. برای مروری بر مراحل لازم برای شروع به راهنمای ایجاد پروژه Google Cloud مراجعه کنید. بخش Set up a Google Cloud project در اولین مرحله نیز مراحل پیکربندی خاصی را انجام می دهد.

پس از اتمام، شناسه مشتری OAuth 2.0 خود را به عنوان یک فایل JSON دانلود کنید. شما باید این فایل اعتبارنامه را به دایرکتوری نمونه زیپ نشده اضافه کنید. به درک فایل ها برای مکان های خاص مراجعه کنید.

اعتبارنامه OAuth

این مراحل را برای ایجاد اعتبارنامه OAuth جدید دنبال کنید:

  • به صفحه Google Cloud Credentials بروید. مطمئن شوید که پروژه صحیح را در بالای صفحه انتخاب کرده اید.
  • روی CREATE CREDENTIALS کلیک کنید و شناسه مشتری OAuth را از منوی کشویی انتخاب کنید.
  • در صفحه بعد:
    • نوع برنامه را روی برنامه وب تنظیم کنید.
    • در قسمت URIهای تغییر مسیر مجاز ، روی ADD URI کلیک کنید. مسیر کامل یک مسیر برگشت به تماس را برای برنامه خود اضافه کنید. برای مثال، https://my.domain.com/auth-callback یا https://localhost:5000/callback . این مسیر را بعداً در این راهنما ایجاد کرده و مدیریت می‌کنید. هر زمان خواستید می‌توانید چنین مسیرهایی را ویرایش یا اضافه کنید.
    • روی CREATE کلیک کنید.
  • سپس یک دیالوگ با اعتبار جدید ایجاد شده خود دریافت می کنید. گزینه DOWNLOAD JSON را انتخاب کنید. فایل JSON دانلود شده را در فهرست سرور خود کپی کنید.

پیش نیازهای خاص زبان

فایل README را در هر مخزن برای به روزترین لیست پیش نیازها مشاهده کنید.

پایتون

مثال پایتون ما از چارچوب Flask استفاده می کند. می توانید سورس کد کامل را از لینک های ارائه شده دانلود کنید.

در صورت لزوم، پایتون 3.7+ را نصب کنید و مطمئن شوید که pip در دسترس است.

python3 -m ensurepip --upgrade

همچنین توصیه می کنیم یک محیط مجازی پایتون جدید را راه اندازی و فعال کنید.

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

در نمونه‌های دانلود شده در هر زیرشاخه راهنما، یک requirements.txt وجود دارد. با استفاده از pip می توانید به سرعت کتابخانه های مورد نیاز را نصب کنید. از دستورات زیر برای نصب کتابخانه های مورد نیاز برای اولین قدم استفاده کنید. 

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

Node.js

مثال Node.js ما از چارچوب Express استفاده می کند. می توانید سورس کد کامل را از لینک های ارائه شده دانلود کنید.

این مثال به Node.js نسخه 16.13 یا جدیدتر نیاز دارد.

ماژول های گره مورد نیاز را با استفاده از npm نصب کنید. 

npm install

جاوا

مثال جاوا ما از چارچوب Spring Boot استفاده می کند. می توانید سورس کد کامل را از لینک های ارائه شده دانلود کنید.

اگر جاوا 11+ را روی دستگاه خود نصب نکرده اید، نصب کنید.

برنامه های Spring Boot می توانند از Gradle یا Maven برای مدیریت ساخت ها و مدیریت وابستگی ها استفاده کنند. این مثال شامل پوشش Maven است که ساخت موفقیت آمیز را بدون نیاز به نصب خود Maven تضمین می کند.

در فهرستی که پروژه را دانلود یا کلون کرده اید، دستورات زیر را اجرا کنید تا مطمئن شوید که پیش نیازهای اجرای پروژه را دارید.

java --version
./mvnw --version

یا در ویندوز: 

java -version
mvnw.cmd --version

فایل ها را درک کنید

بخش‌های زیر طرح‌بندی دایرکتوری‌های نمونه را توضیح می‌دهند.

نام دایرکتوری ها

هر مخزن شامل چندین دایرکتوری است که نام آنها با یک عدد شروع می شود، مانند /01-basic-app/ . اعداد مربوط به مراحل پیاده‌روی خاص هستند. هر دایرکتوری شامل یک برنامه وب کاملاً کاربردی است که ویژگی های توصیف شده در یک راهنما خاص را پیاده سازی می کند. به عنوان مثال، دایرکتوری /01-basic-app/ شامل اجرای نهایی برای راهنما ایجاد یک افزونه است.

محتویات دایرکتوری

محتویات دایرکتوری بسته به زبان پیاده سازی متفاوت است:

پایتون

  • ریشه دایرکتوری حاوی فایل های زیر است:

    • main.py - نقطه ورود برنامه پایتون. پیکربندی سروری که می خواهید در این فایل استفاده کنید را مشخص کنید، سپس آن را اجرا کنید تا سرور راه اندازی شود.
    • requirements.txt - ماژول های پایتون مورد نیاز برای اجرای برنامه وب. اینها را می توان به طور خودکار با استفاده از pip install -r requirements.txt نصب کرد.

    • client_secret.json - فایل مخفی مشتری دانلود شده از Google Cloud. توجه داشته باشید که در آرشیو نمونه گنجانده نشده است. شما باید فایل اعتبارنامه دانلود شده خود را تغییر نام داده و در ریشه هر دایرکتوری کپی کنید.

  • config.py - گزینه های پیکربندی برای سرور Flask.

  • دایرکتوری webapp حاوی محتوای برنامه وب است. شامل موارد زیر است:

  • فهرست /templates/ با الگوهای Jinja برای صفحات مختلف.

  • دایرکتوری /static/ با تصاویر، CSS و فایل های جاوا اسکریپت کمکی.

  • routes.py - روش های کنترل کننده مسیرهای برنامه وب.

  • __init__.py - آغازگر ماژول webapp . این شروع کننده سرور Flask را راه اندازی می کند و گزینه های پیکربندی تنظیم شده در config.py را بارگیری می کند.

  • فایل‌های اضافی در صورت نیاز یک مرحله گذری خاص.

Node.js

هر مرحله از walkthough را می توان در زیر پوشه <step> خود یافت. هر مرحله شامل:

  • فایل های ثابت مانند جاوا اسکریپت، CSS و تصاویر در پوشه ./<step>/public یافت می شوند.
  • روترهای اکسپرس در پوشه های ./<step>/routes یافت می شوند.
  • قالب های HTML در پوشه های ./<step>/views یافت می شوند.
  • برنامه سرور ./<step>/app.js است.

جاوا

دایرکتوری پروژه شامل موارد زیر است:

  • دایرکتوری src.main حاوی کد منبع و پیکربندی برای اجرای موفقیت آمیز برنامه است. این دایرکتوری شامل موارد زیر است: + دایرکتوری java.com.addons.spring حاوی فایل های Application.java و Controller.java است. فایل Application.java مسئول اجرای سرور برنامه است در حالی که فایل Controller.java منطق نقطه پایانی را مدیریت می کند. فهرست resources + حاوی دایرکتوری templates با فایل های HTML و جاوا اسکریپت است. همچنین حاوی فایل application.properties است که پورت اجرای سرور، مسیر فایل keystore و مسیر دایرکتوری templates را مشخص می کند. این مثال شامل فایل keystore در فهرست resources است. می‌توانید آن را در هر کجا که ترجیح می‌دهید ذخیره کنید، اما مطمئن شوید که فایل application.properties را مطابق با مسیر به‌روزرسانی می‌کنید.
    • pom.xml حاوی اطلاعات مورد نیاز برای ساخت پروژه و تعریف وابستگی های مورد نیاز است.
    • .gitignore حاوی نام فایل هایی است که نباید در git آپلود شوند. مطمئن شوید که مسیر را به keystore خود در این .gitignore اضافه کرده اید. در مثال ارائه شده، این secrets/*.p12 است (هدف ذخیره کلید در بخش زیر مورد بحث قرار گرفته است). برای مرحله 2 و بالاتر، باید مسیر فایل client_secret.json خود را نیز وارد کنید تا مطمئن شوید که اسرار خود را در یک مخزن راه دور قرار نمی دهید. برای مرحله 3 و بالاتر، باید مسیر را به فایل دیتابیس H2 و کارخانه datastore فایل اضافه کنید. اطلاعات بیشتر در مورد راه اندازی این فروشگاه های داده را می توان در سومین راهنمای مدیریت بازدیدهای مکرر یافت.
    • mvnw و mvnw.cmd به ترتیب فایل های اجرایی Maven wrapper برای یونیکس و ویندوز هستند. برای مثال، اجرای ./mvnw --version در یونیکس، نسخه Apache Maven را در کنار سایر اطلاعات، خروجی می دهد.
    • دایرکتوری .mvn حاوی پیکربندی برای پوشش Maven است.

سرور نمونه را اجرا کنید

شما باید سرور خود را راه اندازی کنید تا آن را آزمایش کنید. این دستورالعمل ها را دنبال کنید تا سرور نمونه را به زبان انتخابی خود اجرا کنید:

پایتون

اعتبارنامه OAuth

اعتبارنامه OAuth خود را همانطور که قبلا توضیح داده شد ایجاد و دانلود کنید. فایل JSON را در دایرکتوری ریشه در کنار فایل راه اندازی سرور برنامه خود قرار دهید.

سرور را پیکربندی کنید

شما چندین گزینه برای اجرای وب سرور دارید. در انتهای فایل پایتون یکی از موارد زیر را اضافه کنید:

  1. localhost ناامن توجه داشته باشید که این فقط برای آزمایش مستقیم در پنجره مرورگر مناسب است. دامنه های ناامن را نمی توان در iframe افزودنی Classroom بارگیری کرد.

    if __name__ == "__main__":
  # Disable OAuthlib's HTTPs verification.
  os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"

  # Run the web app at http://localhost:5000.
  app.run(debug=True)

  2. localhost ایمن شما باید چندین فایل کلید SSL را برای آرگومان ssl_context مشخص کنید.

    if __name__ == "__main__":
  # Run the web app at https://localhost:5000.
  app.run(host="localhost",
          ssl_context=("localhost.pem", "localhost-key.pem"),
          debug=True)

  3. سرور Gunicorn . این برای سرور آماده تولید یا استقرار ابری مناسب است. توصیه می کنیم یک متغیر محیطی PORT را برای استفاده با این گزینه راه اندازی تنظیم کنید.

    if __name__ == "__main__":
  # Run the web app at https://<your domain>:<server_port>.
  # Defaults to https://<your domain>:8080.
  server_port = os.environ.get("PORT", "8080")
  app.run(debug=True, port=server_port, host="0.0.0.0")

سرور را راه اندازی کنید

برنامه پایتون خود را اجرا کنید تا سرور همانطور که در مرحله قبل پیکربندی شده بود راه اندازی شود.

python main.py

روی URL ظاهر شده کلیک کنید تا برنامه وب خود را در مرورگر مشاهده کنید تا تأیید کنید که درست اجرا می شود.

Node.js

سرور را پیکربندی کنید

برای اجرای سرور از طریق HTTPS، باید یک گواهی خودکار ایجاد کنید که برای اجرای برنامه از طریق HTTPS استفاده می شود. این اعتبارنامه ها باید به صورت sslcert/cert.pem و sslcert/key.pem در پوشه ریشه مخزن ذخیره شوند. ممکن است لازم باشد این کلیدها را به زنجیره کلید سیستم عامل خود اضافه کنید تا مرورگر شما آنها را بپذیرد.

مطمئن شوید که *.pem در فایل .gitignore شما باشد زیرا نمی خواهید فایل را به git commit کنید.

سرور را راه اندازی کنید

می توانید برنامه را با دستور زیر اجرا کنید و step01 به جای مرحله صحیحی که می خواهید به عنوان سرور اجرا کنید (به عنوان مثال step01 برای 01-basic-app و step02 برای 02-sign-in) اجرا کنید.

npm run step01

یا

npm run step02

این سرور وب را در https://localhost:5000 راه اندازی می کند.

می توانید سرور را با Control + C در ترمینال خود خاتمه دهید.

جاوا

سرور را پیکربندی کنید

برای اجرای سرور از طریق HTTPS، باید یک گواهی خودکار ایجاد کنید که برای اجرای برنامه از طریق HTTPS استفاده می شود.

استفاده از mkcert را برای توسعه محلی در نظر بگیرید. هنگامی که mkcert را نصب کردید، دستورات زیر یک گواهی ذخیره شده محلی برای اجرا بر روی HTTPS ایجاد می کنند.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

این مثال شامل فایل keystore در فهرست منابع است. می‌توانید آن را در هر کجا که ترجیح می‌دهید ذخیره کنید، اما مطمئن شوید که فایل application.properties را مطابق با مسیر به‌روزرسانی می‌کنید. نام دامنه دامنه ای است که پروژه را روی آن اجرا می کنید (مثلاً localhost ).

مطمئن شوید که *.p12 در فایل .gitignore شما باشد زیرا نمی خواهید فایل را به git commit کنید.

سرور را راه اندازی کنید

سرور را با اجرای متد main در فایل Application.java راه اندازی کنید. برای مثال، در IntelliJ، می‌توانید روی Application.java کلیک راست کنید > Run 'Application' در پوشه src/main/java/com/addons/spring اجرا کنید یا فایل Application.java را باز کنید تا روی فلش سبز سمت چپ کلیک کنید. امضای متد main(String[] args) . همچنین، می‌توانید پروژه را در یک پنجره ترمینال اجرا کنید:

./mvnw spring-boot:run

یا در ویندوز:

mvnw.cmd spring-boot:run

این سرور را در https://localhost:5000 یا در پورتی که در application.properties مشخص کرده‌اید راه‌اندازی می‌کند.