ساختار 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 به برخی از اطلاعات دانش آموزان مانند تکالیفشان دسترسی دارند.

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

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

یک آیتم CourseWork یک وظیفه واحد را نشان می دهد که به گروهی از دانش آموزان در یک دوره اختصاص داده شده است. این شامل جزئیاتی مانند توضیحات، تاریخ مقرر، و مواد و همچنین ابرداده مانند زمان ایجاد است. مواد شامل عنوان، تصویر کوچک، و URL، و همچنین یک شناسه است که می تواند با API های مناسب (مانند Drive، YouTube) استفاده شود.

موارد CourseWork یکی از انواع وظایف زیر را توصیف می کند:

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

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

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

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

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

مطالب درسی و اطلاعیه ها

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

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

موضوعات

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

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

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

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

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

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

ثبت نام ها

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

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