پیکربندی پروژه Google Cloud

این صفحه شامل اطلاعاتی است که شما باید در مورد ایجاد و پیکربندی پروژه‌های Google Cloud برای افزونه‌های Classroom بدانید. پروژه‌های Google Cloud برای پیاده‌سازی Google Single Sign-On از طریق OAuth 2.0 (Google SSO)، برای تأیید درخواست‌های ارسال شده توسط افزونه شما و برای مدیریت فهرست افزونه در فروشگاه Google Workspace Marketplace استفاده می‌شوند.

برای اطلاعات عمومی بیشتر در مورد انتشار یک افزونه در Marketplace ، به بخش انتشار یک برنامه مراجعه کنید.

ایجاد پروژه گوگل کلود

دو نوع پروژه برای ایجاد وجود دارد: یک پروژه خصوصی که برای توسعه استفاده می‌شود و یک پروژه عمومی که توسط کاربران نهایی قابل دسترسی است. برچسب‌های "عمومی" و "خصوصی" به قابلیت مشاهده برنامه شما در Google Workspace Marketplace اشاره دارند؛ یک برنامه خصوصی Marketplace فقط می‌تواند توسط کاربران درون دامنه‌ای که در آن ایجاد شده است نصب شود، در حالی که یک برنامه عمومی Marketplace برای هر دامنه Google Workspace در دسترس است. این دو باید دو برنامه جداگانه باشند، زیرا یک پروژه نمی‌تواند هم عمومی و هم خصوصی باشد. برنامه‌های عمومی قبل از اینکه در بازار موجود شوند، باید بررسی و تأیید شوند.

برای اطلاعات عمومی در مورد ایجاد پروژه Google Cloud، به بخش «ایجاد یک پروژه Google Cloud» مراجعه کنید.

ایجاد یک پروژه عمومی گوگل کلود

این پروژه، برنامه‌ی افزونه‌ای را نشان می‌دهد که توسط مدیران، معلمان و دانش‌آموزان قابل دسترسی است. یک پروژه‌ی عمومی قبل از راه‌اندازی یا نصب، باید توسط تیم Google Workspace Marketplace بررسی و تأیید شود.

  1. یک پروژه جدید Google Cloud در دامنه تولید خود ایجاد کنید.

    ایجاد یک پروژه گوگل کلود

  2. API کلاس درس را در پروژه ابری خود فعال کنید.

    فعال کردن API کلاس درس

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

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

  4. گزینه Marketplace SDK App Configuration App Visibility را روی Public تنظیم کنید و گزینه Unlisted را تیک بزنید.

  5. فیلدهای مورد نیاز را در صفحه فهرست فروشگاه SDK Marketplace تکمیل کنید و روی انتشار کلیک کنید.

  6. برنامه شما توسط تیم Google Workspace Marketplace بررسی خواهد شد. آنها با استفاده از آدرس ایمیل توسعه‌دهنده مشخص شده در Marketplace SDK با شما ارتباط برقرار خواهند کرد. پس از تأیید برنامه، کادر Unlisted را پاک کنید تا معلمان و مدیران بتوانند آن را در Marketplace پیدا کنند.

ایجاد یک پروژه خصوصی گوگل کلود

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

برای ایجاد یک پروژه خصوصی، به دسترسی به دامنه Google Workspace for Education با مجوز Teaching & Learning یا Plus نیاز دارید. اگر از قبل به چنین دامنه‌ای دسترسی ندارید، این مراحل را برای راه‌اندازی دامنه آزمایشی Google Workspace for Education، ارتقاء آن به مجوز Plus و اجازه دسترسی به API افزونه‌های Classroom دنبال کنید:

  1. مراحل دریافت دامنه آزمایشی توسعه‌دهنده را تکمیل کنید.

  2. در حالی که به عنوان مدیر در دامنه آزمایشی وارد سیستم شده‌اید، یک پروژه جدید Google Cloud ایجاد کنید.

    ایجاد یک پروژه گوگل کلود

    اگر نمی‌توانید به کنسول گوگل کلود دسترسی پیدا کنید یا پروژه‌های ابری ایجاد کنید، موارد زیر را در کنسول ادمین بررسی کنید:

    • به صفحه تنظیمات حساب کاربری > تنظیمات دسترسی مبتنی بر سن مراجعه کنید و گزینه « همه کاربران این گروه یا واحد سازمانی ۱۸ سال یا بیشتر دارند» را انتخاب کنید.
    • در قسمت برنامه‌ها > سرویس‌های اضافی گوگل :
    • پلتفرم ابری گوگل برای همه فعال است.
    • تنظیمات ایجاد پروژه عبارتند از : به کاربران اجازه دهید پروژه ایجاد کنند .
    • تنظیمات دسترسی به Cloud Shell عبارتند از: Allow access to Cloud Shell .

  3. فرم درخواست ارتقاء دامنه آزمایشی را تکمیل و ارسال کنید. ارسال این فرم از گوگل درخواست می‌کند که دامنه آزمایشی شما را به Google Workspace for Education Plus با ده مجوز ارتقا دهد و به پروژه Cloud شما اجازه می‌دهد تا به API افزونه‌های Classroom متصل شود.

    پس از تکمیل فرآیندهای ارتقا و فهرست مجوزها، ایمیلی دریافت خواهید کرد. مجوزهای پلاس را در کنسول مدیریت به حساب‌های معلم آزمون خود اختصاص دهید. در قسمت فهرست > کاربران ، حساب‌های معلم آزمون خود را ایجاد یا انتخاب کنید. در مجوزهای هر معلم، تأیید کنید که Google Workspace for Education Plus اختصاص داده شده است.

  4. API کلاس درس را در پروژه ابری خود فعال کنید.

    فعال کردن API کلاس درس

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

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

  6. قابلیت مشاهده‌ی برنامه‌ی پیکربندی برنامه‌ی SDK بازار را روی خصوصی تنظیم کنید.

  7. فیلدهای مورد نیاز را در صفحه فهرست فروشگاه SDK Marketplace تکمیل کنید و روی انتشار کلیک کنید. پس از انتشار فهرست برنامه، کاربران دامنه می‌توانند برنامه را در Google Workspace Marketplace یا با مراجعه به URL برنامه نشان داده شده در صفحه فهرست فروشگاه پیدا کرده و نصب کنند.

اواوت ۲.۰

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

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

برای مشاهده لیست کاملی از تمام scopeهای موجود و کاربردهای آنها، به صفحه OAuth Scopes for Google APIs مراجعه کنید. برای اطلاعات کلی پیکربندی OAuth، به صفحه Configure OAuth در مستندات Workspace مراجعه کنید.

مجوزهای کاربر

برنامه وب شما باید حداقل یکی از scope های زیر را درخواست کند:

  • https://www.googleapis.com/auth/userinfo.email که به یک برنامه اجازه می‌دهد آدرس ایمیل کاربر را مشاهده کند.
  • https://www.googleapis.com/auth/userinfo.profile ، که به یک برنامه اجازه می‌دهد اطلاعات شخصی مانند تصویر، نام و نام خانوادگی و سایر اطلاعات شخصی که کاربر به صورت عمومی در دسترس قرار داده است را مشاهده کند.

پس از اینکه کاربر یکی از این محدوده‌ها را در افزونه شما مجاز کرد، آنها توسط پارامتر کوئری login_hint شناسایی می‌شوند. این پارامتر هنگام باز شدن یک iframe به هر یک از URL های برنامه وب شما ارسال می‌شود. اگر کاربری یکی از این محدوده‌ها را مجاز نکرده باشد، login_hint ارسال نخواهد شد.

login_hint یک پارامتر استاندارد OpenID Connect است که می‌توانید به صورت اختیاری هنگام استفاده از Google Sign-in یا درخواست توکن OAuth به گوگل ارسال کنید. هدف از این کار، روان‌تر کردن فرآیند احراز هویت برای کاربر نهایی است.

دامنه‌های افزونه‌های کلاس درس

حوزه‌های زیر مختص افزونه‌های Classroom هستند:

  • https://www.googleapis.com/auth/classroom.addons.teacher ، که امکان دسترسی به همه متدهای API را فراهم می‌کند.
  • https://www.googleapis.com/auth/classroom.addons.student که امکان دسترسی برای راه‌اندازی عملیات اعتبارسنجی و خواندن پیوست‌ها را فراهم می‌کند.

حتی با وجود یک توکن دسترسی معتبر OAuth که نشان‌دهنده‌ی اعتبارنامه‌های کاربر است، فراخوانی‌های API به دلیل الزامات اضافی مسدود می‌شوند:

  • همه متدها مستلزم آن هستند که کاربر در دوره مشخص شده توسط courseId در درخواست، معلم یا دانش‌آموز باشد.
  • ایجاد پیوست، به‌روزرسانی، حذف و بازیابی نمره مستلزم آن است که کاربر معلم باشد.
  • تماس‌ها به یک پست خاص در گوگل کلاس‌روم با بررسی‌های زیر مسدود می‌شوند.
    • وقتی یک افزونه از قبل حداقل یک پیوست در یک پست داشته باشد، می‌تواند درخواست‌هایی برای موارد زیر ارسال کند:
      • اعتبارسنجی اجرای iframe
      • عملیات خواندن، به‌روزرسانی و حذف پیوست‌ها
      • به‌روزرسانی‌های نمره در آن پست
    • وقتی iframe مربوط به Attachment Discovery برای اولین بار باز می‌شود، ممکن است افزونه هنوز پیوستی در پست نداشته باشد. یک پارامتر کوئری addOnToken ارائه شده است که می‌تواند برای درخواست موارد زیر استفاده شود:
      • ایجاد پیوست در زیر پست ( addOnToken الزامی است)
      • اعتبارسنجی را شروع کنید ( addOnToken در صورت ارائه اعتبارسنجی می‌شود و زمانی که افزونه پیوستی در پست ندارد، لازم است)

تأیید هویت OAuth

افزونه‌ی Classroom از APIهای گوگل برای دسترسی به داده‌های کاربران گوگل استفاده می‌کند.

برای اطلاعات بیشتر در مورد فرآیند تأیید، به سوالات متداول تأیید API OAuth مراجعه کنید.

فهرست بازار کار گوگل (Google Workspace Marketplace)

برای اطلاعات عمومی پیکربندی SDK بازار کار گوگل، به «فعال کردن و پیکربندی SDK بازار کار گوگل» و «ایجاد فهرست فروشگاه بازار کار گوگل» مراجعه کنید.

ملاحظات فهرست‌بندی

فهرست فروشگاه SDK بازار پروژه عمومی Google Cloud شما، نام و توضیحات برنامه شما را که برای کاربران نهایی است، مشخص می‌کند. می‌توانید این جزئیات را به چندین زبان در قسمت جزئیات برنامه ارائه دهید.

این دستورالعمل‌ها را در فهرست‌های خود دنبال کنید:

  • زیر جزئیات برنامه :
    • از علائم نگارشی در نام برنامه خودداری کنید. برای مثال، به جای «شرکت من : افزونه من» یا «افزونه من، توسط شرکت من» از «افزونه من توسط شرکت من» استفاده کنید.
    • شرح مختصر و شرح مفصل نباید دقیقاً شامل متن یکسانی باشند.
    • مطمئن شوید که برای فیلد قیمت‌گذاری، مقداری انتخاب کرده‌اید. این فیلد شامل گزینه‌های رایگان ، پرداخت با دوره آزمایشی رایگان ، پرداخت با ویژگی‌های رایگان و قیمت‌گذاری پولی است. نیازی به مشخص کردن مبلغ هزینه در فهرست بازار نیست.
    • مطمئن شوید که برای فیلد دسته‌بندی، مقداری انتخاب کرده‌اید. منابع دانشگاهی یا ابزارهای معلم و مدیر می‌توانند گزینه‌های خوبی برای افزونه‌ی کلاس درس باشند.
    • برای اطلاعات بیشتر، به موارد ذکر شده در توضیحات جزئیات برنامه Marketplace مراجعه کنید.
  • زیر مجموعه‌ی دارایی‌های گرافیکی :
  • زیر لینک‌های پشتیبانی :
    • مطمئن شوید که لینکی به شرایط خدمات برنامه خود ارائه داده‌اید.
  • مطمئن شوید که دستورالعمل‌های برندسازی API گوگل را که شامل نام‌ها و توضیحات مجاز می‌شود، رعایت می‌کنید.
  • اگر در فهرست خود به هر یک از محصولات گوگل اشاره می‌کنید، از نام آن در قالبی که در فهرست علائم تجاری ارائه شده است استفاده کنید. در صورت مشخص شدن، مطمئن شوید که نماد علامت تجاری (™) را درج می‌کنید؛ از « Google Docs™ » استفاده کنید، نه «Google Docs».

با سرویس‌های صدور مجوز و صورتحساب گوگل ادغام شوید

اگر علاقه‌مند هستید که برنامه‌های Google Workspace Marketplace شما با سرویس‌های صدور مجوز و صورتحساب گوگل ادغام شوند، از Marketplace API دیدن کنید.

تنظیمات نصب

افزونه‌ها می‌توانند علاوه بر نصب از طریق مدیر ، امکان نصب انفرادی را نیز فراهم کنند. این صفحه برخی از تفاوت‌های بین دو نوع نصب را برجسته می‌کند. این صفحه قصد ندارد هیچ یک از این دو نوع نصب را تبلیغ کند. می‌توانید در صفحه پیکربندی برنامه SDK بازار Google Workspace ، انتخاب کنید که آیا نصب انفرادی مجاز است یا خیر.

نصب مدیر

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

در ادامه به برخی از ملاحظات مربوط به نصب مدیر اشاره شده است.

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

برای اطلاعات بیشتر در مورد نحوه انجام نصب‌های مدیریتی و نحوه عملکرد ساختار سازمانی برای کسب اطلاعات بیشتر در مورد واحدهای سازمانی و گروه‌های دسترسی، به «نصب برنامه‌های بازار در دامنه خود» مراجعه کنید.

نصب انفرادی

نصب‌های جداگانه، یک افزونه را به حساب کاربری کاربر اضافه می‌کنند. در حین نصب، از کاربر خواسته می‌شود تا با محدوده‌های دسترسی افزونه موافقت کند.

در ادامه به برخی ملاحظات مربوط به نصب انفرادی اشاره شده است.

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

علاوه بر نصب افزونه‌ها از طرف کاربران، مدیران می‌توانند یک لیست مجاز نیز داشته باشند تا به کاربران اجازه دهند افزونه‌هایی را نصب کنند که امکان نصب جداگانه را فراهم می‌کنند. اگر افزونه‌ای در لیست مجاز نباشد، کاربران همچنان می‌توانند فهرست افزونه را در Google Workspace Marketplace مشاهده کنند اما نمی‌توانند افزونه را نصب کنند؛ در عوض، پیامی را مشاهده می‌کنند که توضیح می‌دهد افزونه توسط مدیر دامنه برای نصب مجاز نشده است. برای کسب اطلاعات بیشتر در مورد این رفتار، به مدیریت برنامه‌های Google Workspace Marketplace در لیست مجاز خود مراجعه کنید.

برای اطلاعات بیشتر به مستندات تنظیمات نصب Google Workspace Marketplace مراجعه کنید.

ادغام برنامه

شما باید یک URL مربوط به iframe راه‌اندازی را در فیلد Attachment Setup URI وارد کنید. این URL به عنوان مقدار src iframe برای iframe Attachment Discovery استفاده می‌شود. iframe Attachment Discovery توسط معلمان برای یافتن محتوا یا فعالیت‌هایی که باید به تکلیف خود پیوست کنند، استفاده می‌شود. این iframe را می‌توان در کنسول پروژه Google Cloud تنظیم کرد.

پیکربندی آدرس اینترنتی iFrame

پیشوندهای مجاز URI پیوست برای اعتبارسنجی URI های تنظیم شده در AddOnAttachment با استفاده از متدهای *.addOnAttachments.create و *.addOnAttachments.patch استفاده می‌شوند. اعتبارسنجی یک تطبیق پیشوند رشته‌ای تحت‌اللفظی است و اجازه استفاده از wildcardها را نمی‌دهد.

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

هر دوی این مقادیر را در صفحه پیکربندی برنامه Marketplace SDK پروژه Google Cloud خود تنظیم کنید.

حساب‌های آزمایشی

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

حساب‌های آزمایشی پیشنهادی:

  • معلم تامی، tammy.teacher@<دامنه آزمایشی شما>
  • سام دانشجو، sam.student@<دامنه آزمایشی شما>
  • سالی دانشجو، sally.student@<دامنه آزمایشی شما>

برای ایجاد یک حساب آزمایشی جدید، این مراحل را دنبال کنید:

  1. به کنسول مدیریت خود وارد شوید.
  2. به بخش کاربران بروید.
  3. روی افزودن کاربر جدید کلیک کنید (شکل 1 را ببینید).
  4. اطلاعات کاربر را وارد کنید و نقش‌های مناسب را به او اختصاص دهید.

روی افزودن کاربر جدید کلیک کنید شکل ۱. محل قرارگیری لینک افزودن کاربر جدید در کنسول مدیریت.

برای ایجاد یک گروه آزمایشی جدید، این روش را دنبال کنید:

  1. به کنسول مدیریت خود وارد شوید.
  2. به گروه‌ها بروید.
  3. روی ایجاد گروه کلیک کنید (شکل 2 را ببینید).
  4. اعضا و مالکان گروه را وارد کنید.

روی ایجاد گروه کلیک کنید شکل ۲. محل قرارگیری لینک ایجاد گروه در کنسول مدیریت.