این سری از راهنماها، تمام قسمتهای متحرک یک افزونه 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 را در دایرکتوری ریشه در کنار فایل راه اندازی سرور برنامه خود قرار دهید.
سرور را پیکربندی کنید
شما چندین گزینه برای اجرای وب سرور دارید. در انتهای فایل پایتون یکی از موارد زیر را اضافه کنید:
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)
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)
سرور 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
مشخص کردهاید راهاندازی میکند.