با پیوست ها تعامل داشته باشید

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

یک پیوست ایجاد کنید

با ارسال یک درخواست CREATE برای courses.*.addOnAttachments.create endpoint. درخواست شما باید شامل یک نمونه از AddOnAttachment در بدنه درخواست باشد.

هنگام ایجاد پیوست، فیلدهای زیر الزامی است:

  • title : نام رشته پیوست.
  • teacherViewUri : URI برای نمای معلم پیوست.
  • studentViewUri : URI برای نمای دانشجویی پیوست.
  • studentWorkReviewUri : URI برای معلم برای دیدن کار دانش آموز در پیوست. این فیلد فقط برای پیوست‌های نوع فعالیت مورد نیاز است.

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

  • dueDate و dueTime در صورت تعیین زمان موعد پیوست.
  • maxPoints : حداکثر نمره برای پیوست. اگر می‌خواهید از پس‌بازگشت نمره پشتیبانی کنید، باید یک مقدار غیر صفر باشد. فقط برای پیوست‌های نوع فعالیت اعمال می‌شود.

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

جزئیات ارسال دانشجو

یک گردش کار ارسال معمولی مراحل زیر را دنبال می کند:

  1. یک دانش آموز studentViewUri برای تکمیل یک فعالیت راه اندازی می کند.
  2. این افزونه یک submissionId از متد getAddOnContext با استفاده از اعتبار دانشجویی بازیابی می کند.
  3. submissionId و attachmentId توسط توسعه دهنده افزونه به عنوان شناسه منحصر به فرد کار دانش آموز ذخیره می شود. در صورتی که معلم یک تکلیف را در Classroom کپی کند، می توانید از کلید ترکیبی این دو پارامتر برای نمایش یک پیوست جدید در تکلیف کپی شده استفاده کنید. برای جزئیات بیشتر به صفحه ما در مورد محتوای کپی شده مراجعه کنید.
  4. معلمی که علاقه مند به بررسی کار دانش آموز است studentWorkReviewUri را راه اندازی می کند. این درخواست شامل پارامترهای پرس و جو زیر است: courseId ، itemId ، itemType ، attachmentId و submissionId .
  5. توسعه دهنده افزونه از این چهار شناسه برای بازیابی کار دانشجویی استفاده می کند. از نقطه پایانی courses.courseWork.addOnAttachments.studentSubmissions برای بازیابی یا اصلاح اطلاعات ارسالی دانشجو استفاده کنید.

تشخیص وضعیت ارسال

یک درخواست GET به 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 به یک نمره پیش‌نویس تبدیل می‌شود که در رابط کاربری کلاس برای معلم قابل مشاهده است. معلمان می توانند پیش نویس نمره را قبل از بازگرداندن تکلیف به دانش آموزان تغییر دهند. برای جزئیات بیشتر در مورد نحوه ارائه نمرات به معلمان به نمای کلی درجه بندی در رابط کاربری کلاس درس مراجعه کنید.

توجه داشته باشید که فقط در صورتی می توانید نمره را با pointsEarned تنظیم کنید که موارد زیر درست باشد:

  • پیوست باید دارای مقدار maxPoints مثبت باشد.
  • افزونه باید سازنده اصلی پیوست بوده باشد.

همچنین توجه داشته باشید که می‌توانید مقدار maxPoints یک AddOnAttachment را که قبلا ایجاد شده است، با ارسال یک درخواست PATCH به نقطه پایانی addOnAttachments تغییر دهید.

چه زمانی برای تعیین نمره

زمانی که یک نمره به Google Classroom بازگردانده می شود، حق انتخاب دارید. تمایز مهم این است که آیا می‌خواهید اعتبار معلم را ذخیره کنید، زیرا فقط معلم می‌تواند نمره را تغییر دهد.

دو لحظه اضافی وجود دارد که ممکن است در آن نمره را به Google Classroom منتقل کنید: زمانی که دانش‌آموز کار خود را کامل می‌کند یا زمانی که معلم کار دانش‌آموز را در iframe Student Work Review باز می‌کند.

اگر می‌خواهید وقتی دانش‌آموز کار را کامل می‌کند، نمره‌ها را تنظیم کنید، باید اعتبار آفلاین معلم را ذخیره کنید، سپس آن‌ها را بازیابی کنید و وقتی دانش‌آموز کار را کامل کرد، نمره را تغییر دهید. این روش برخی از مزایای بالقوه را ارائه می دهد:

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

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

اگر نمی‌خواهید اعتبارنامه‌های معلم را در طول جلسه دانشجو بارگیری کنید، می‌توانید از اعتبارنامه‌های معلم فعال هنگام بارگیری مدارک ارسالی دانش‌آموز در Student Work Review iframe استفاده کنید. با این حال، این ممکن است تجربه کاربری آسانی را ارائه نکند زیرا نمرات در رابط کاربری کلاس درس به‌طور هم‌زمان به‌روزرسانی نمی‌شوند و معلمان باید هر ارسالی را باز کنند.

تشخیص تغییرات در نمرات تکالیف

این امکان برای معلمان وجود دارد که پس از ایجاد تکلیف، تنظیمات نمره را در Classroom ویرایش کنند. چنین ویرایش هایی ممکن است شامل موارد زیر باشد:

  • تغییر مقدار امتیاز اختصاص داده شده
  • تغییر مقدار maxPoints یک تکلیف.
  • تغییر اینکه آیا اصلاً تکلیف باید درجه بندی شود یا خیر.

برای مشاهده تنظیمات رتبه‌بندی فعلی یک تکلیف، توصیه می‌کنیم یک درخواست GET به courses.courseWork ارسال کنید. پاسخ شامل مقدار maxPoints فعلی است. یک تخصیص درجه بندی نشده دارای مقدار maxPoints تهی یا صفر است.

اگر نمره ای را به Classroom گذرانده اید، از نقطه پایانی courses.courseWork.addOnAttachments.studentSubmissions برای واکشی یا تغییر نمره برای پیوست الحاقی استفاده کنید. مقدار نمره با استفاده از قسمت pointsEarned تنظیم می شود. اگر محصول شما به معلمان اجازه می دهد امتیاز دانش آموز را برای یک فعالیت خاص ویرایش کنند، بررسی کنید و در صورت لزوم، این مقدار را به روز کنید.

،

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

یک پیوست ایجاد کنید

با ارسال یک درخواست CREATE برای courses.*.addOnAttachments.create endpoint. درخواست شما باید شامل یک نمونه از AddOnAttachment در بدنه درخواست باشد.

هنگام ایجاد پیوست، فیلدهای زیر الزامی است:

  • title : نام رشته پیوست.
  • teacherViewUri : URI برای نمای معلم پیوست.
  • studentViewUri : URI برای نمای دانشجویی پیوست.
  • studentWorkReviewUri : URI برای معلم برای دیدن کار دانش آموز در پیوست. این فیلد فقط برای پیوست‌های نوع فعالیت مورد نیاز است.

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

  • dueDate و dueTime در صورت تعیین زمان موعد پیوست.
  • maxPoints : حداکثر نمره برای پیوست. اگر می‌خواهید از پس‌بازگشت نمره پشتیبانی کنید، باید یک مقدار غیر صفر باشد. فقط برای پیوست‌های نوع فعالیت اعمال می‌شود.

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

جزئیات ارسال دانشجو

یک گردش کار ارسال معمولی مراحل زیر را دنبال می کند:

  1. یک دانش آموز studentViewUri برای تکمیل یک فعالیت راه اندازی می کند.
  2. این افزونه یک submissionId از متد getAddOnContext با استفاده از اعتبار دانشجویی بازیابی می کند.
  3. submissionId و attachmentId توسط توسعه دهنده افزونه به عنوان شناسه منحصر به فرد کار دانش آموز ذخیره می شود. در صورتی که معلم یک تکلیف را در Classroom کپی کند، می توانید از کلید ترکیبی این دو پارامتر برای نمایش یک پیوست جدید در تکلیف کپی شده استفاده کنید. برای جزئیات بیشتر به صفحه ما در مورد محتوای کپی شده مراجعه کنید.
  4. معلمی که علاقه مند به بررسی کار دانش آموز است studentWorkReviewUri را راه اندازی می کند. این درخواست شامل پارامترهای پرس و جو زیر است: courseId ، itemId ، itemType ، attachmentId و submissionId .
  5. توسعه دهنده افزونه از این چهار شناسه برای بازیابی کار دانشجویی استفاده می کند. از نقطه پایانی courses.courseWork.addOnAttachments.studentSubmissions برای بازیابی یا اصلاح اطلاعات ارسالی دانشجو استفاده کنید.

تشخیص وضعیت ارسال

یک درخواست GET به 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 به یک نمره پیش‌نویس تبدیل می‌شود که در رابط کاربری کلاس برای معلم قابل مشاهده است. معلمان می توانند پیش نویس نمره را قبل از بازگرداندن تکلیف به دانش آموزان تغییر دهند. برای جزئیات بیشتر در مورد نحوه ارائه نمرات به معلمان به نمای کلی درجه بندی در رابط کاربری کلاس درس مراجعه کنید.

توجه داشته باشید که فقط در صورتی می توانید نمره را با pointsEarned تنظیم کنید که موارد زیر درست باشد:

  • پیوست باید دارای مقدار maxPoints مثبت باشد.
  • افزونه باید سازنده اصلی پیوست بوده باشد.

همچنین توجه داشته باشید که می‌توانید مقدار maxPoints یک AddOnAttachment را که قبلا ایجاد شده است، با ارسال یک درخواست PATCH به نقطه پایانی addOnAttachments تغییر دهید.

چه زمانی برای تعیین نمره

زمانی که یک نمره به Google Classroom بازگردانده می شود، حق انتخاب دارید. تمایز مهم این است که آیا می‌خواهید اعتبار معلم را ذخیره کنید، زیرا فقط معلم می‌تواند نمره را تغییر دهد.

دو لحظه اضافی وجود دارد که ممکن است در آن نمره را به Google Classroom منتقل کنید: زمانی که دانش‌آموز کار خود را کامل می‌کند یا زمانی که معلم کار دانش‌آموز را در iframe Student Work Review باز می‌کند.

اگر می‌خواهید وقتی دانش‌آموز کار را کامل می‌کند، نمره‌ها را تنظیم کنید، باید اعتبار آفلاین معلم را ذخیره کنید، سپس آن‌ها را بازیابی کنید و وقتی دانش‌آموز کار را کامل کرد، نمره را تغییر دهید. این روش برخی از مزایای بالقوه را ارائه می دهد:

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

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

اگر نمی‌خواهید اعتبارنامه‌های معلم را در طول جلسه دانشجو بارگیری کنید، می‌توانید از اعتبارنامه‌های معلم فعال هنگام بارگیری مدارک ارسالی دانش‌آموز در Student Work Review iframe استفاده کنید. با این حال، این ممکن است تجربه کاربری آسانی را ارائه نکند زیرا نمرات در رابط کاربری کلاس درس به‌طور هم‌زمان به‌روزرسانی نمی‌شوند و معلمان باید هر ارسالی را باز کنند.

تشخیص تغییرات در نمرات تکالیف

این امکان برای معلمان وجود دارد که پس از ایجاد تکلیف، تنظیمات نمره را در Classroom ویرایش کنند. چنین ویرایش هایی ممکن است شامل موارد زیر باشد:

  • تغییر مقدار امتیاز اختصاص داده شده
  • تغییر مقدار maxPoints یک تکلیف.
  • تغییر اینکه آیا اصلاً تکلیف باید درجه بندی شود یا خیر.

برای مشاهده تنظیمات رتبه‌بندی فعلی یک تکلیف، توصیه می‌کنیم یک درخواست GET به courses.courseWork ارسال کنید. پاسخ شامل مقدار maxPoints فعلی است. یک تخصیص درجه بندی نشده دارای مقدار maxPoints تهی یا صفر است.

اگر نمره ای را به Classroom گذرانده اید، از نقطه پایانی courses.courseWork.addOnAttachments.studentSubmissions برای واکشی یا تغییر نمره برای پیوست الحاقی استفاده کنید. مقدار نمره با استفاده از قسمت pointsEarned تنظیم می شود. اگر محصول شما به معلمان اجازه می دهد امتیاز دانش آموز را برای یک فعالیت خاص ویرایش کنند، بررسی کنید و در صورت لزوم، این مقدار را به روز کنید.