إنشاء مرفقات خارج Google Classroom

يتناول هذا الدليل كيفية إنشاء مرفقات للإضافات في موقعك الإلكتروني أو تطبيقك. تشبه التفاعلات إنشاء مهام باستخدام نقاط نهاية CourseWork API. نفِّذ هذه الرحلة للسماح للمستخدمين بإنشاء مرفقات للإضافات من موقعك الإلكتروني أو تطبيقك.

ملاحظة مهمة: ننصحك بشدة بتنفيذ عملية إنشاء المرفقات هذه إذا كنت تنشئ حاليًا واجبات CourseWork. يتيح لك توسيع نطاق تنفيذ CourseWork جذب المزيد من المستخدمين إلى تطبيقك الإضافي، ولا يتطلّب ذلك سوى القليل من العمل الإضافي.

سير العمل

بشكل عام، تتّبع رحلة إنشاء المرفقات التسلسل التالي:

1. يفتح المعلّم موقعك الإلكتروني أو تطبيقك، ثم يختار قطعة من المحتوى لتكليف الطلاب بها.
2. تأكَّد من أنّ المستخدم يمكنه إنشاء مرفقات إضافية.
3. إذا تعذّر على المستخدم إنشاء مرفقات للإضافة، يمكنك إنشاء مهمة في CourseWork باستخدام عنوان URL للمحتوى المحدّد كمادة رابط.
4. إذا كان بإمكان المستخدم إنشاء مرفقات إضافات، اتّبِع الخطوات التالية:
   1. أنشئ مهمة.
   2. أنشئ مرفقًا للإضافة يرتبط بالمحتوى المحدّد واربطه بالمَهمّة الجديدة.
5. إبلاغ المعلّم بأنّه تم إنشاء المهمة بنجاح

يتم وصف كل إجراء في الأقسام التالية.

التحقّق مما إذا كان بإمكان المستخدم إنشاء مرفقات إضافات

يمكنك إنشاء مرفقات للإضافات نيابةً عن مستخدم مؤهَّل. المستخدم المؤهّل هو المستخدم الذي يكون معلّمًا في الدورة التدريبية التي تحاول إنشاء مهام فيها في و لديه ترخيص إصدار Teaching & Learning أو Education Plus من Google Workspace for Education.

نقطة أساسية: قد تختلف أهلية إنشاء مرفقات للإضافات من مستخدم إلى آخر، وقد تتغيّر مع الوقت. يجب دائمًا التحقّق من أهلية المستخدم قبل محاولة إنشاء مرفقات للإضافة.

ملاحظة مهمة: تتوفّر عمليات التحقّق من الأهلية باستخدام Classroom API في الإصدار التجريبي العلني، وهي متاحة في الإصدار التجريبي V1_20240930_PREVIEW والإصدارات الأحدث. لاستخدام طرق API في الإصدار التجريبي العلني، يجب أن تكون جزءًا من برنامج الإصدار التجريبي من Google Workspace للمطوّرين وإجراء عملية إعداد إضافية تتجاوز الاستخدام العادي لواجهة Classroom API.

ابدأ بتحديد ما إذا كان بإمكان المستخدم إنشاء مرفقات إضافات. يمكنك إجراء ذلك عن طريق إرسال طلب إلى نقطة النهاية userProfiles.checkUserCapability مع مَعلمة الإمكانية CREATE_ADD_ON_ATTACHMENT. افحص الحقل المنطقي allowed في الردّ، وتشير القيمة true إلى أنّ المستخدم مؤهَّل لإنشاء مرفقات إضافية.

تحذير: لا يمكن ضمان نجاح طلبات إنشاء مرفقات إضافية للمستخدمين الذين لديهم إذن CREATE_ADD_ON_ATTACHMENT. على سبيل المثال، سيتلقّى المستخدم الذي لديه الإذن رسالة خطأ 403 إذا حاولت إنشاء مرفقات إضافية نيابةً عنه في دورة تدريبية لا يكون فيها المستخدم معلّمًا.

Python

eligibility_response = (
  classroom_service.userProfiles()
  .checkUserCapability(
    userId="me",
    capability="CREATE_ADD_ON_ATTACHMENT",
    # The previewVersion is necessary while the method is available in the
    # Workspace Developer Preview Program.
    previewVersion="V1_20240930_PREVIEW",
  ).execute()
)
is_create_attachment_eligible = (
  eligibility_response.get('allowed')
)
print('User eligibility for add-on attachment creation: '
      f'{is_create_attachment_eligible}.')

توجيه المستخدم استنادًا إلى أهليته

تحدّد الأهلية ما إذا كان بإمكانك إنشاء مرفقات إضافية لمستخدم.

ملاحظة مهمة: تقدّم الإضافات مزايا كبيرة لتحسين تجربة المستخدم. يجب دائمًا إنشاء مرفقات إضافية للمستخدمين المؤهَّلين.

مستخدم غير مؤهّل

إذا تعذّر على المستخدم إنشاء مرفقات إضافية، أنشئ CourseWork مَهمّة جديدة باستخدام عنوان URL للمحتوى الذي اختاره المستخدم كـ Link.

Python

if not is_create_attachment_eligible:
  coursework = {
    'title': 'My CourseWork Assignment with Link Material',
    'description': 'Created using the Classroom CourseWork API.',
    'workType': 'ASSIGNMENT',
    'state': 'DRAFT',  # Set to 'PUBLISHED' to assign to students.
    'maxPoints': 100,
    'materials': [
      {'link': {'url': my_content_url}}
    ]
  }

  assignment = (
    service.courses()
    .courseWork()
    .create(courseId=course_id, body=coursework)
    .execute()
  )

  print(
    f'Link Material assignment created with ID: {assignment.get("id")}'
  )

تحتوي الاستجابة على مهمة في الدورة التدريبية المطلوبة مع المحتوى المرفق. يمكن للمستخدمين النقر على Link لفتح المحتوى في موقعك الإلكتروني في علامة تبويب جديدة.

الشكل 1. طريقة عرض المعلّم لمهمة CourseWork في مسودة تتضمّن مواد مرتبطة

مستخدم مؤهَّل

اتّبِع الخطوات التالية إذا كان بإمكان المستخدم إنشاء مرفقات إضافات.

1. أنشئ CourseWork مهمة جديدة بدون أي مرفقات.
2. إنشاء مرفق إضافة
   • اضبط itemId AddOnAttachment على id للمهمة التي تم إنشاؤها حديثًا.
   • تأكَّد من تقديم عناوين URL للمحتوى الذي يختاره المستخدم لكل طريقة عرض متوافقة.

Python

if is_create_attachment_eligible:
  coursework = {
    'title': 'My CourseWork Assignment with Add-on Attachment',
    'description': 'Created using the Classroom CourseWork API.',
    'workType': 'ASSIGNMENT',
    'state': 'DRAFT',  # Set to 'PUBLISHED' to assign to students.
    'maxPoints': 100,
  }

  assignment = (
    classroom_service.courses()
    .courseWork()
    .create(courseId=course_id, body=coursework)
    .execute()
  )

  print(
    f'Empty assignment created with ID: {assignment.get("id")}'
  )

  attachment = {
    'teacherViewUri': {'uri': teacher_view_url},
    'studentViewUri': {'uri': student_view_url},
    'studentWorkReviewUri': {'uri': grade_student_work_url},
    'title': f'Test Attachment {test_label}',
  }

  add_on_attachment = (
    service.courses()
    .courseWork()
    .addOnAttachments()
    .create(
      courseId=course_id,
      itemId=assignment.get("id"),  # ID of the new assignment.
      body=attachment,
    )
    .execute()
  )

  print(
    f'Add-on attachment created with ID: {add_on_attachment.get("id")}'
  )

ملاحظة: لا يلزم توفير رمز مميّز للإضافة عند إنشاء مرفق في مهمة أنشأتها.

تظهر الإضافة كبطاقة مرفق في Classroom. تُفتح عناوين URL المحدّدة في الطلب في إطار iframe المناسب لكلّ "عرض".