منابع API

این راهنما یک نمای کلی از اجزای اصلی تشکیل دهنده Google Classroom API ارائه می دهد. Google Classroom API از منابع و خدمات تشکیل شده است. منابع موجودیت‌هایی را در Google Classroom نشان می‌دهند، مانند دوره یا تکلیف، و سرویس‌ها این منابع را بازیابی و مدیریت می‌کنند. برخی از این موجودیت‌ها علاوه بر آنچه در Classroom وجود دارد، دارای ویژگی‌های اضافی مخصوص API هستند. انواع موجودیت اولیه عبارتند از:

موجودیت	نمایندگی در کلاس درس
دوره ها	کلاسی مانند «ریاضی دوره چهارم ام. اسمیت».
نام مستعار	شناسه جایگزین برای یک دوره.
دعوت نامه ها	وسیله ای برای افزودن کاربران به یک کلاس.
دانش آموزان	یک دانش آموز در یک کلاس.
معلمان	یک معلم در یک کلاس.
پروفایل های کاربر	کاربر به طور کلی تر، خارج از زمینه دانش آموز یا معلم.
دوره کار	یک تکلیف در کلاس
ارسالی دانشجویان	یک دانش‌آموز برای یک تکلیف مشخص، مانند پاسخ‌ها یا کاربرگ‌ها، کار می‌کند.
CourseWorkMaterials	مواد برای دانش آموزان در یک کلاس.
اطلاعیه ها	اطلاعیه برای دانش آموزان در یک کلاس.
AddOnAttachment	محتوا یا فعالیت در یک تکلیف یا مطالبی که معمولاً به‌عنوان یک فریم تعبیه‌شده نمایش داده می‌شود.
موضوعات	گروه بندی بصری تکالیف و مطالب در یک کلاس.
ثبت نام ها	دستورالعملی برای ارسال اعلان‌ها به برنامه شما برای تغییرات داده‌ها، مانند فهرست کلاس.

اکثر منابع دارای روش های خدماتی برای عملیات استاندارد مانند خواندن، به روز رسانی و حذف نمونه های منبع هستند. برخی منابع همچنین دارای روش‌های سفارشی برای عملیات‌های دیگر هستند، مانند اصلاح فهرست دانش‌آموزانی که تکلیف خاصی به آنها اختصاص داده شده است.

برای اطلاعات دقیق در مورد منابع و روش‌های API، به مرجع Classroom API مراجعه کنید.

مروری بر روابط منابع

• Course شیء داده پایه در Google Classroom است.
• نام مستعار به عنوان شناسه های جایگزین برای Courses استفاده می شود.
• دعوت‌نامه‌ها برای دعوت از نمایه‌های کاربر برای تبدیل شدن به معلم یا دانش‌آموز در یک Course استفاده می‌شوند، اما کاربران می‌توانند مستقیماً توسط سرپرستان دامنه Google Workspace for Education نیز اضافه شوند.
• معلمان آیتم های Stream را ایجاد می کنند و آنها را در دوره های خود با دانش آموزان به اشتراک می گذارند. انواع موارد جریان ممکن عبارتند از Coursework , CourseWorkMaterials و Announcements . CourseWork و CourseWorkMaterials می توانند به صورت بصری در موضوعات سازماندهی شوند و می توانند حاوی AddOnAttachments باشند. دانش‌آموزان ارسال‌های دانشجویی را برای CourseWork خود ارسال می‌کنند.
• توسعه دهندگان می توانند ثبت نام ایجاد کنند تا در صورت تغییر برخی از این داده ها اعلان دریافت کنند.

Google Classroom برای دامنه‌هایی که مشترک Google Workspace for Education هستند در دسترس است. یک دامنه در زمینه Classroom معمولاً یک منطقه مدرسه را نشان می دهد. می‌توانید یک دامنه آزمایشی Google Workspace for Education برای اهداف توسعه ایجاد کنید، که به شما امکان کنترل نمونه تولیدی از Classroom را می‌دهد بدون اینکه بر کاربران واقعی تأثیر بگذارد.

دوره ها و نام های مستعار

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

Aliases شناسه های جایگزین برای یک کلاس هستند که ممکن است با یک دوره مرتبط باشد و به جای شناسه منحصر به فرد استفاده شود. هر نام مستعار در یک فضای نام وجود دارد که افراد می توانند آن را ایجاد و مشاهده کنند. دو فضای نام پشتیبانی می شود:

• دامنه: فضای نام دامنه برای ایجاد نام مستعار مفید است که همه کاربران نیاز به دسترسی به آنها دارند، اما مختص هیچ برنامه ای نیستند. به عنوان مثال، لیست های جایگزین برای یک دوره، مانند MATH 127 و COMSCI 127، باید در فضای نام دامنه ایجاد شود. نام مستعار در فضای نام دامنه فقط توسط مدیران دامنه ایجاد می شود اما برای همه کاربران یک دامنه قابل مشاهده است.
• پروژه توسعه دهنده: فضای نام پروژه توسعه دهنده برای مدیریت نام مستعار خاص یک برنامه کاربردی مفید است. به عنوان مثال، برنامه‌ای که از شناسه‌های جایگزین برای دوره‌ها استفاده می‌کند، می‌تواند نام مستعار ایجاد کند تا شناسه خود را به دوره‌های Classroom نگاشت کند. نام مستعار ایجاد شده در این فضای نام به یک کنسول API خاص Google گره خورده است. هر کاربر یک برنامه کاربردی می تواند نام مستعار را در فضای نام پروژه توسعه دهنده آن برنامه ایجاد و مشاهده کند.

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

فهرست دوره ها و کاربران

Students و Teachers نگاشت‌های خاصی بین نمایه کاربر و یک دوره هستند که نشان‌دهنده نقش آن کاربر در دوره هستند. تعیین دانش آموز و معلم جهانی نیست: یک کاربر می تواند به عنوان معلم برای یک دوره و یک دانش آموز در درس دیگر اختصاص داده شود. نام "دانشجو" یا "معلم" مجموعه ای از مجوزها را برای یک کاربر خاص در یک دوره خاص نشان می دهد. یک درس ممکن است بیش از یک معلم یا صفر دانش آموز داشته باشد. معلمان و دانش آموزان را می توان در هر زمان به یک دوره اضافه یا از آن حذف کرد.

دانش آموزان

یک منبع Student نشان دهنده کاربری است که به عنوان دانشجو در یک دوره خاص ثبت نام کرده است.

دانش آموزان مجاز به مشاهده جزئیات دوره و اساتید آن دوره هستند.

معلمان

یک منبع Teacher نشان دهنده کاربری است که دوره خاصی را تدریس می کند.

معلمان مجاز به مشاهده و تغییر جزئیات دوره، مشاهده معلمان و دانش آموزان و مدیریت معلمان و دانش آموزان اضافی هستند.

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

UserProfiles نشان دهنده یک نگاشت به نمایه دامنه کاربر است که توسط شناسه منحصر به فرد یا آدرس ایمیل کاربر بازگردانده شده توسط Directory API شناسایی شده است. کاربر فعلی همچنین ممکن است با استفاده از خلاصه "me" به شناسه خود مراجعه کند.

سرویس UserProfiles همچنین می‌تواند برای مدیریت و دعوت از Guardians استفاده شود، که نقشه‌برداری بین دانش‌آموز و سرپرست است. نگهبانان در Classroom به برخی از اطلاعات دانش آموزان مانند تکالیفشان دسترسی دارند.

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

جریان موارد

موارد جریان، قطعاتی از محتوای پست شده است که با اعضای یک دوره به اشتراک گذاشته می شود. توسعه دهندگان و معلمان می توانند سه نوع مورد جریان ایجاد کنند: Announcement ، CourseWork ، و CourseWorkMaterial .

معلمان Announcements در بالای صفحه جریان در رابط کاربری کلاس درس ایجاد می‌کنند. معلمان CourseWork و CourseWorkMaterials را با کلیک بر روی دکمه Create در برگه Classwork ایجاد می کنند. توسعه‌دهندگان می‌توانند همه انواع موارد جریانی را به‌صورت برنامه‌نویسی از طریق Classroom API ایجاد کنند.

موارد زیر در مورد موارد جریان صادق است:

• همه موارد جریان می‌توانند حاوی مواد تکمیلی باشند، مانند فایل‌های Google Drive، ویدیوهای YouTube، فرم‌های Google، پیوندهای URL و پیوست‌های افزودنی Classroom.
• همه موارد جریان را می توان به زیر مجموعه ای از دانش آموزان در دوره اختصاص داد.
• یک CourseWork ممکن است دارای درجه بندی یا بدون درجه بندی باشد. معلمان می توانند وضعیت نمره دهی یک تکلیف CourseWork را در هر زمان تغییر دهند.
• یک مورد جریانی ممکن است بیش از یک پیوست داشته باشد.
• یک مورد جریانی ممکن است دارای انواع مختلف پیوست باشد. برای مثال، یک تکلیف CourseWork ممکن است فایل‌های Google Drive، ویدیوهای YouTube و پیوست‌های افزودنی Classroom را به طور همزمان داشته باشد.
• یک مورد جریان ممکن است دارای پیوست‌های افزودنی از بیش از یک برنامه‌نویس باشد.
• توسعه‌دهندگان می‌توانند جزئیات مربوط به هر منبع مورد جریانی را که یکی از پیوست‌های افزودنی آن‌ها را دارد، دریافت و تغییر دهند.
• برنامه‌نویسان می‌توانند ارسالی دانش‌آموز را برای یک تکلیف CourseWork که شامل یکی از پیوست‌های الحاقی آن‌ها است، تحویل دهند، مطالبه کنند یا بازگردانند.
• برنامه‌نویسان فقط می‌توانند نمرات ارسالی دانش‌آموزان را در تکالیفی که ایجاد کرده‌اند نهایی کنند.

موارد پخش جریانی کپی شد

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

کار درسی و ارسالی دانشجویان

یک مورد CourseWork یک تکلیف برای گروهی از دانش آموزان در یک دوره است. این تنها نوع مورد جریانی است که می‌تواند ارسال دانشجو را بپذیرد. یک منبع CourseWork حاوی جزئیاتی مانند توضیحات، تاریخ مقرر، حداکثر نمره و ابرداده مانند زمان ایجاد است.

هر منبع CourseWork یکی از انواع وظایف زیر را شرح می دهد:

• تکلیفی که دانش‌آموزان با ارسال کاربرگ‌ها یا پیوست‌های دیگر تکمیل می‌کنند.
• یک سوال پاسخ کوتاه یا یک سوال چند گزینه ای.

کار دانشجویی برای یک مورد CourseWork با StudentSubmission نشان داده می شود. این شامل یک پاسخ و ابرداده اضافی مانند وضعیت و درجه اختصاص یافته است.

محتویات StudentSubmission به نوع مورد مربوطه مربوط به CourseWork بستگی دارد و می تواند شامل موارد زیر باشد:

• کاربرگ‌ها و پیوست‌هایی که برای یک تکلیف ارسال می‌شوند، شامل عنوان، تصویر کوچک و نشانی اینترنتی آن‌ها، و همچنین شناسه‌هایی که می‌توانند با APIهای مناسب مانند Drive یا YouTube استفاده شوند.
• پاسخ به یک سوال پاسخ کوتاه یا سوال چند گزینه ای.

برای اطلاعات بیشتر در مورد مدیریت کار درسی و ارسال‌های دانشجو، به مدیریت کار درسی مراجعه کنید.

CourseWorkMaterials و اطلاعیه ها

مشابه CourseWork ، CourseWorkMaterials محتوای اختصاص داده شده به گروهی از دانش آموزان در یک دوره را نشان می دهد. هر منبع دارای جزئیاتی مانند عنوان و توضیحات به همراه مواد تکمیلی است. با این حال، برخلاف CourseWork ، CourseWorkMaterials از دانش‌آموزان نمی‌خواهد که هیچ اثری را ارسال کنند. به این ترتیب، تاریخ مقرر وجود ندارد، و StudentSubmissions برای CourseWorkMaterials وجود ندارد. معلمان ممکن است از CourseWorkMaterials برای ارسال مطالب پیشنهادی، برنامه درسی یا قوانین کلاس استفاده کنند.

Announcements همچنین محتوای به اشتراک گذاشته شده با گروهی از دانش‌آموزان را نشان می‌دهند، اما جزئیاتی مانند عنوان ندارند و نمی‌توانند بر اساس Topics مانند CourseWork یا CourseWorkMaterials سازماندهی شوند. معلمان ممکن است از اینها برای اعلام یادآوری یا اطلاعیه به کلاس استفاده کنند.

موضوعات

Topics برای سازماندهی بصری CourseWork و CourseWorkMaterials در یک کلاس استفاده می شود. اینها ممکن است برای گروه‌بندی تکالیف به «اختیاری» و «الزامی» یا «واحد 1» و «واحد 2» استفاده شوند.

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

افزونه یک رابط کاربری است که توسط توسعه‌دهندگان ارائه می‌شود و معمولاً در iframe نمایش داده می‌شود. افزونه‌ها به‌عنوان پیوست در یک مورد جریان ظاهر می‌شوند. آیتم جریان می تواند هر Announcements ، CourseWork ، یا CourseWorkMaterials باشد. پیوست های افزودنی توسط یک AddOnAttachment نشان داده می شوند.

پیوست‌های افزودنی می‌توانند یک فعالیت یا محتوا باشند.

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

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

ثبت نام ها

وقتی داده‌های خاصی در Google Classroom تغییر می‌کند، برنامه‌ها می‌توانند برای دریافت اعلان‌ها مشترک شوند. به عنوان مثال، زمانی که فهرست یک دوره به روز می شود. Registrations دستورالعملی برای ارسال این اعلان ها به برنامه شما است.

برای اطلاعات بیشتر به راهنمای اعلان‌های فشار مراجعه کنید.