این صفحه جزئیات پیادهسازی برای ایجاد یک پیوست، اقدامات توصیهشده هنگام باز کردن پیوستها توسط کاربران و کار با مطالب ارسالی دانشآموزان را مورد بحث قرار میدهد. توجه داشته باشید که ممکن است هنگام ارسال این درخواستها، لازم باشد پارامترهای مربوط به پیوست را ارائه دهید.
ایجاد پیوست
با ارسال درخواست CREATE به courses.*.addOnAttachments.create مربوطه، یک پیوست ایجاد کنید. درخواست شما باید شامل نمونهای از AddOnAttachment در بدنه درخواست باشد.
هنگام ایجاد پیوست، فیلدهای زیر الزامی هستند:
-
title: نام رشتهای پیوست. -
teacherViewUri: آدرس URL مربوط به نمای معلمِ فایل پیوست. -
studentViewUri: آدرس اینترنتی (URI) مربوط به نمای دانشجویی فایل پیوست. -
studentWorkReviewUri: آدرس اینترنتی (URI) برای معلم جهت مشاهده کار دانشآموز روی پیوست. این فیلد فقط برای پیوستهای از نوع فعالیت الزامی است.
ممکن است بخواهید برخی از فیلدهای اختیاری زیر را نیز اضافه کنید:
-
dueDateوdueTimeدر صورتی که مشخص کنند چه زمانی باید پیوست را ارسال کرد. -
maxPoints: حداکثر امتیاز برای پیوست. اگر میخواهید از قابلیت بازگشت امتیاز پشتیبانی کنید، باید مقداری غیر از صفر باشد. فقط برای پیوستهای از نوع فعالیت اعمال میشود.
برای جزئیات بیشتر در مورد این فیلدها، به مرجع منبع AddOnAttachment مراجعه کنید.
اعتبارنامهها و نقش کاربر را تأیید کنید
آیفریم نمای دانشآموز ، آیفریم بررسی کار دانشآموز و آیفریم نمای معلم ، همگی برای ارائه محتوا به کاربر در نظر گرفته شدهاند تا تغییر تکلیف کلاس درس. هنگام باز شدن یکی از این نماها، موارد زیر را در نظر بگیرید:
- اعتبارنامههای OAuth را برای کاربر دریافت کنید.
- برای اعتبارسنجی نقش کاربر، بر اساس
itemTypeدرخواستهایcourseWork.getAddOnContext،courseWorkMaterials.getAddOnContextیاannouncements.getAddOnContextایجاد کنید. - پاسخ را بررسی کنید تا ببینید آیا
TeacherContextیاStudentContextوجود دارند یا خیر. فقط یکی میتواند برگردانده شود که مربوط به نقش کاربر در دوره است. - اگر کاربر فعلی دانشجو است و
itemTypeبرابر باcourseWorkاست،submissionIdرا از پاسخ به همراه کار دانشجو ثبت کنید.submissionIdsدر iframe های افزونه مطابقت دارند و برای ارسال نمرات به عقب و نمایش کار دانشجو به معلمان در ابزار نمره دهی مورد نیاز هستند. - اگر
attachmentIdاز قبل برای افزونه شناخته شده است، رابط کاربری پیوست مناسب را نمایش بده. - در غیر این صورت، این پیوست باید از یک آیتم یا دوره آموزشی دیگر کپی شده باشد. برای توصیههای مربوط به این سناریو، به راهنمای مدیریت محتوای کپی شده مراجعه کنید.
جزئیات ارسال مقاله توسط دانشجویان
یک گردش کار ارسال معمولی از این مراحل پیروی میکند:
- یک دانشجو
studentViewUriرا برای تکمیل یک فعالیت اجرا میکند. - این افزونه با استفاده از اطلاعات احراز هویت دانشآموز، یک
submissionIdاز متدgetAddOnContextبازیابی میکند. -
submissionIdوattachmentIdتوسط توسعهدهنده افزونه به عنوان شناسه منحصر به فرد کار دانشآموز ذخیره میشوند. در صورتی که معلمی یک تکلیف را در کلاس درس کپی کند، میتوانید از کلید ترکیبی این دو پارامتر برای نمایش یک پیوست جدید در تکلیف کپی شده استفاده کنید. برای جزئیات بیشتر به صفحه ما در مورد محتوای کپی شده مراجعه کنید. - معلمی که علاقهمند به بررسی کار دانشآموز است،
studentWorkReviewUriرا اجرا میکند. این درخواست شامل پارامترهای پرسوجوی زیر است:courseId،itemId،itemType،attachmentIdوsubmissionId. - توسعهدهنده افزونه از این چهار شناسه برای بازیابی کار دانشجو استفاده میکند. از نقطه پایانی
courses.courseWork.addOnAttachments.studentSubmissionsبرای بازیابی یا تغییر اطلاعات مربوط به ارسال دانشجو استفاده کنید.
تشخیص وضعیت ارسال
یک درخواست GET به endpoint مربوط به courses.courseWork.addOnAttachments.studentSubmissions ارسال کنید تا جزئیات مربوط به یک submissionId خاص را دریافت کنید. شما یک شیء AddOnAttachmentStudentSubmission دریافت میکنید که شامل نمره ارسال ( pointsEarned ) و وضعیت فعلی ( postSubmissionState ) است. وضعیت ارسال میتواند یکی از مقادیر زیر باشد:
-
NEW، اگر دانشجو هرگز به فایل ارسالی دسترسی نداشته باشد. -
CREATED، اگر دانشجو مطلبی را ایجاد کرده اما هنوز آن را ارسال نکرده است. -
TURNED_IN، اگر دانشآموز کار خود را به معلم تحویل داده باشد. -
RETURNED، اگر معلم، فایل ارسالی را به دانشآموز برگردانده باشد. -
RECLAIMED_BY_STUDENT، اگر دانشجو کار خود را "لغو ارسال" کرده باشد.
از این نقطه پایانی برای تشخیص وضعیت کار دانشآموز در افزونه خود استفاده کنید. سپس میتوانید نماها یا گزینههای ارائه شده به دانشآموز را بسته به وضعیت برگردانده شده تنظیم کنید. این ممکن است شامل ویژگیهایی مانند موارد زیر باشد:
- نمایش وضعیت تحویل تکالیف در افزونه شما. این میتواند به دانشآموزان کمک کند تا از سردرگمی احتمالی جلوگیری کنند و اطمینان حاصل کنند که به اشتباه در تحویل تکلیف کوتاهی نمیکنند.
- محدود کردن امتیازات ویرایش ارسال. اگر تکلیف دارای وضعیت
CREATEDیاRECLAIMED_BY_STUDENTباشد، ممکن است به دانشجو اجازه ویرایش ارسال خود داده شود. اگر تکلیف دارای وضعیتTURNED_INیاRETURNEDباشد، ممکن است به دانشجو اجازه ویرایش ارسال خود داده نشود.
نمرات و پیوستهای متعدد
فقط از یک پیوست افزونه میتوان برای تعیین نمره یک تکلیف استفاده کرد . اگر معلمی بیش از یک پیوست از نوع فعالیت ایجاد کند که مقدار maxPoints را ارائه دهد، فقط اولین پیوست از این نوع میتواند نمره تکلیف را تعیین کند. برای غیرفعال کردن بازیابی نمره برای یک پیوست، میتوانید مقدار maxPoints را تنظیم نکنید یا آن را روی صفر تنظیم کنید.
تعیین نمره یک اثر ارسالی
شما میتوانید با ارسال یک درخواست PATCH به نقطه پایانی courses.courseWork.addOnAttachments.studentSubmissions ، یک درخواست دانشجو را اصلاح کنید. بدنه درخواست باید شامل یک نمونه از AddOnAttachmentStudentSubmission با مقادیر اصلاح شده باشد. فیلد pointsEarned را برای اصلاح نمره یک درخواست تنظیم کنید. مقداری که در pointsEarned ارسال میشود، به یک نمره پیشنویس تبدیل میشود که برای معلم در رابط کاربری Classroom قابل مشاهده است. معلمان میتوانند نمره پیشنویس را قبل از بازگرداندن تکلیف به دانشآموزان اصلاح کنند. برای جزئیات بیشتر در مورد نحوه ارائه نمرات به معلمان، به «مروری بر نمرهدهی در رابط کاربری Classroom» مراجعه کنید.
توجه داشته باشید که فقط در صورت صحیح بودن موارد زیر میتوانید نمره را با pointsEarned تنظیم کنید:
- پیوست باید مقدار
maxPointsمثبت داشته باشد. - افزونه باید سازندهی اصلی پیوست بوده باشد.
همچنین توجه داشته باشید که میتوانید مقدار maxPoints مربوط به AddOnAttachment که از قبل ایجاد شده است را با ارسال یک درخواست PATCH به نقطه پایانی addOnAttachments تغییر دهید.
چه زمانی نمره تعیین کنیم
شما در مورد زمان ارسال نمره به Google Classroom حق انتخاب دارید. تفاوت اساسی این است که آیا میخواهید اطلاعات معلم را ذخیره کنید یا خیر، زیرا فقط معلم میتواند نمره را تغییر دهد.
دو لحظه افزودنی وجود دارد که میتوانید در آنها نمرهای به Google Classroom بدهید: زمانی که دانشآموز کار خود را تمام میکند یا زمانی که معلم کار دانشآموز را در iframe بررسی کار دانشآموز باز میکند.
اگر میخواهید نمرات را پس از اتمام کار توسط دانشآموز تنظیم کنید، باید اعتبارنامههای آفلاین معلم را ذخیره کنید، سپس آنها را بازیابی کرده و پس از اتمام کار توسط دانشآموز، برای اصلاح نمره استفاده کنید. این روش مزایای بالقوهای را ارائه میدهد:
- بهروزرسانیهای نمرات را به صورت یکپارچه ارائه دهید. معلمان نیازی به انجام هیچ اقدام خاصی برای نمایش نمرات در رابط کاربری کلاس درس ندارند.
- ارائه بینش آنی از پیشرفت کلاس از طریق انجام تکالیف. با تعیین نمرات همزمان با تکمیل پیوستها توسط دانشآموزان، معلمان میتوانند بدون باز کردن هر فایل ارسالی، از میزان درک دانشآموزان خود مطلع شوند.
توجه داشته باشید که این رویکرد، امکان همگامسازی نمرات به صورت غیرهمزمان را نیز فراهم میکند. شما میتوانید به صورت دورهای از نقطه پایانی AddOnAttachmentStudentSubmission نظرسنجی کنید تا تشخیص دهید که چه زمانی یک دانشجو کار خود را ارسال کرده است. پس از ارسال، نمره ارسالی را با استفاده از اعتبارنامههای ذخیره شده تنظیم کنید.
اگر نمیخواهید اعتبارنامههای معلم را در طول جلسه دانشآموزان بارگذاری کنید، میتوانید از اعتبارنامههای معلم فعال هنگام بارگذاری ارائه دانشآموز در iframe مرور کار دانشآموز استفاده کنید. با این حال، این ممکن است تجربه کاربری چندان روان و راحتی را ارائه ندهد زیرا نمرات در رابط کاربری کلاس درس به صورت بلادرنگ بهروزرسانی نمیشوند و معلمان ملزم به باز کردن iframe مرور کار دانشآموز برای هر ارائه هستند.
تشخیص تغییرات در نمرات تکالیف
معلمان میتوانند پس از ایجاد تکلیف، تنظیمات نمره را در کلاس درس ویرایش کنند. چنین ویرایشهایی ممکن است شامل موارد زیر باشد:
- تغییر ارزش امتیازهای اختصاص داده شده.
- تغییر مقدار
maxPointsیک تکلیف. - تغییر اینکه آیا اصلاً باید به تکلیف نمره داده شود یا خیر.
برای مشاهده تنظیمات نمرهدهی فعلی یک تکلیف، توصیه میکنیم یک درخواست GET به نقطه پایانی courses.courseWork ارسال کنید. پاسخ شامل مقدار فعلی maxPoints است. یک تکلیف بدون نمره دارای مقدار null یا صفر maxPoints است.
اگر نمرهای را به Classroom برگرداندهاید، از نقطه پایانی courses.courseWork.addOnAttachments.studentSubmissions برای دریافت یا تغییر نمره یک پیوست افزونه استفاده کنید. مقدار نمره با استفاده از فیلد pointsEarned تنظیم میشود. اگر محصول شما به معلمان اجازه میدهد نمره دانشآموز را برای یک فعالیت خاص ویرایش کنند، بررسی و در صورت لزوم بهروزرسانی این مقدار را در نظر بگیرید.