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

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

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

سير العمل

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

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

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

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

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

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

ملاحظة مهمة: إنّ عمليات التحقّق من الأهلية باستخدام Classroom API متوفّرة في إصدار معاينة علنية ومتوفّرة في الإصدار V1_20240930_PREVIEW من الإصدار التجريبي والإصدارات اللاحقة. لاستخدام طرق واجهة برمجة التطبيقات في الإصدار التجريبي العلني، يجب أن تكون جزءًا من برنامج معاينة المطوّر في 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(f'User eligibility for course {course_id}'
      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 المناسب لكل عرض.