المرفقات الخارجية والاستلام

هذه هي الجولة التفصيلية السابعة ضمن السلسلة التفصيلية لإضافات Classroom.

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

يمكنك أيضًا إضافة سلوك إلى الإضافة لتعديل مهمة باستخدام مرفقات الإضافات آليًا. يمكنك تعديل أي مهمة تحتوي على أحد مرفقات الإضافة الخاصة بك، بغض النظر عن من أنشأ المهمة. يُعد هذا مفيدًا بشكل خاص لتسليم المهام بعد أن يكمل الطالب أحد الأنشطة، مع الإشارة إلى المعلم باكتمال المهام المعينة وأن عمل الطالب جاهز للمراجعة.

يمكنك توسيع الإصدار النهائي من الإضافة التي تتيح استخدام نوع المحتوى أو المرفقات من نوع النشاط. يُستخدم المرفق من نوع المحتوى في هذا الدليل.

ملاحظة مهمة: قبل متابعة هذه الجولة التفصيلية، يُرجى إكمال الجولات التفصيلية السابقة في السلسلة. توسع هذه الجولة التفصيلية تطبيق الويب الذي تم تطويره في الجولات التفصيلية السابقة. يمكنك تنزيل رمز المصدر الكامل لجميع الجولات التفصيلية من صفحة "نظرة عامة". ويمكن العثور على رمز هذه الجولة التفصيلية في دليل /07-external-attachments/.

إضافة نطاق OAuth لإدارة المهام

تأكّد من أنّ طلبك يطلب النطاقات التالية:

• https://www.googleapis.com/auth/classroom.addons.teacher
• https://www.googleapis.com/auth/classroom.addons.student
• https://www.googleapis.com/auth/classroom.coursework.students

لم يكن النطاق classroom.coursework.students مطلوبًا من قبل، ويتم استخدامه لإنشاء مهام CourseWork أو تعديلها. أضِف هذا النطاق إلى قوائم النطاقات في حزمة تطوير البرامج (SDK) لـ Google Workspace Marketplace لمشروعك على السحابة الإلكترونية وشاشة موافقة OAuth ورمز الخادم.

Python

  SCOPES = [
    "https://www.googleapis.com/auth/classroom.addons.teacher",
    "https://www.googleapis.com/auth/classroom.addons.student",
    "https://www.googleapis.com/auth/classroom.coursework.students",
  ]

إنشاء مهمة في Classroom

ملاحظة مُهمة: لا تعدِّل أي من تجاربك ضمن إطارات iframe في هذه الخطوة التفصيلية. بدلاً من ذلك، عليك اتّباع سلوك لإنشاء مرفقات الإضافات من صفحة ويب خارج Classroom.

إضافة أزرار إلى صفحة ويب ليست ضمن إطار iframe

تسمح الخطوات الموضّحة في هذه الجولة التفصيلية للمستخدم بإنشاء مهام ومرفقات في Google Classroom من منتج غير تابع لشركة Google. من الناحية العملية، من المحتمل أن يكون هذا موقع الويب أو التطبيق الحالي لديك. في هذا المثال، تحتاج إلى إنشاء صفحة ويب وهمية لتكون بمثابة موقع خارجي. تحتاج إلى زر أو رابط يؤدي النقر عليه إلى فتح مسار جديد ينفّذ مسار CourseWork المقترَح لإنشاء مهمة جديدة.

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

Python

تم تعديل مسار /index الذي تم تقديمه في خطوة الجولة التفصيلية الأولى في مثال بايثون المقدَّم.

<!-- /webapp/templates/index.html -->
<a href="clear-credentials.html">Logout</a>
<a href="start-auth-flow.html">Login</a>

<br>

<a href="create-coursework-assignment.html">Create a CourseWork Assignment</a>

أضِف نموذج HTML لتمثيل وجهة في موقعك الإلكتروني. ستمثل هذه الصفحة المحتوى الذي سيتم إرفاقه بالمهمة CourseWork.

<!-- /webapp/templates/example-coursework-assignment.html -->
<h1>CourseWork assignment loaded!</h1>
<p>You've loaded a CourseWork assignment! It was created from an external web page.</p>

قم بإنشاء ملف وحدة بايثون جديد للتعامل مع المسارات ذات الصلة بـ CourseWork. تمثّل هذه السمة coursework_routes.py في المثال الذي نقدّمه. أضف المسارات الثلاثة التالية؛ لاحظ أنك ستقوم بملء بعض المحتويات لاحقًا.

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """

  # Check that the user is signed in. If not, perform the OAuth 2.0
  # authorization flow.
  credentials = get_credentials()

  if not credentials:
    return start_auth_flow("coursework_assignment_callback")

  # Construct the Google Classroom service.
  classroom_service = get_classroom_service()

  pass  # To be completed later.

@app.route("/example-coursework-assignment/<assignment_type>")
def example_coursework_assignment(assignment_type):
  """
  Renders the "example-coursework-assignment.html" template.
  """
  return flask.render_template(
      "example-coursework-assignment.html", assignment_type=assignment_type
  )

@app.route("/coursework-assignment-callback")
def coursework_assignment_callback():
  """
  Completes the OAuth 2.0 handshake and stores credentials in the session.
  This is identical to the callback introduced in the sign-in walkthrough,
  but redirects the user to the index page instead of the attachment
  discovery page.
  """
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE,
      scopes=SCOPES,
      state=flask.session["state"],
      redirect_uri=flask.url_for("coursework_assignment_callback", _external=True),
  )

  flow.fetch_token(authorization_response=flask.request.url)

  credentials = flow.credentials
  flask.session["credentials"] = session_credentials_to_dict(
      credentials
  )

  # Close the current window and redirect the user to the index page.
  return flask.render_template("close-me.html", redirect_destination="index")

ملاحظة مهمة: أضِف أي مسارات جديدة لمعاودة الاتصال ببروتوكول OAuth إلى معرِّف عميل OAuth ومعرِّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه في صفحة بيانات الاعتماد ضمن مشروعك على Google Cloud. بالنسبة إلى المثال الذي نقدّمه، يجب إضافة https://<<your server>>/index وhttps://<<your server>>/coursework-assignment-callback.

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

نقطة رئيسية: تحقَّق دائمًا مما إذا كان المستخدم مؤهَّلاً لإنشاء مرفقات الإضافات قبل محاولة إنشاء مرفقات الإضافات. وقد تختلف الأهلية حسب المستخدم والدورة التدريبية ومشروعك على Google Cloud.

هناك العديد من المتطلبات الأساسية التي يجب أن يستوفيها المستخدم قبل أن تتمكّن من إنشاء مرفقات الإضافات نيابةً عنه. لتسهيل الاستخدام، توفّر Google طريقة courses.checkAddOnCreationEligibility لتحديد ما إذا كان المستخدم يستوفي هذه المتطلبات الأساسية. يُشار إلى المستخدم الذي يستوفي المتطلبات الأساسية باسم مستخدم مؤهل.

أضِف عملية التحقّق من الأهلية إلى عملية تنفيذ مسار إنشاء "CourseWork". بعد ذلك، اختبِر الحقل isCreateAttachmentEligible في الردّ. بالنسبة إلى المستخدمين المؤهَّلين، اتّبِع المنطق لإنشاء مهمة تتضمّن مرفق إضافة. بخلاف ذلك، يمكنك إنشاء مادة الرابط. ستحتاج إلى معرفة معرّف الدورة التدريبية التي يريد المستخدم إنشاء مهمة فيها. عادةً، ستطلب من المستخدم تحديد الدورة التدريبية التي يجب استخدامها. ولتبسيط الأمر، نستخدم قيمة غير قابلة للتغيير في هذا المثال.

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

ملاحظة: لن تتم تعبئة الحقل isCreateAttachmentEligible إلا عندما يكون المستخدم مؤهّلاً. قد لا يتضمّن الردّ.

Python

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """
  # ... Check that the user is signed in and get the Classroom service ...

  # The ID of the course to which the assignment will be added.
  course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

  # Check whether the user can create add-on attachments.
  eligibility_response = (
      classroom_service.courses()
      .checkAddOnCreationEligibility(courseId=course_id)
      .execute()
  )
  is_create_attachment_eligible = eligibility_response.get("isCreateAttachmentEligible")

  if is_create_attachment_eligible:
    # See the "Create an assignment with add-on attachment for eligible users" section for implementation.
  if not is_create_attachment_eligible:
    # See the "Create a Link Material" section for implementation.

إنشاء مهمة دراسية تحتوي على مرفق إضافة للمستخدمين المؤهَّلين

إذا كان المستخدم مؤهَّلاً لإنشاء مرفقات الإضافات، يُرجى اتّباع الخطوات التالية:

1. يمكنك إرسال طلب بيانات من واجهة برمجة التطبيقات لإنشاء مهمة حول "courseWork" في Google Classroom بدون مرفقات.
2. استخرِج id من المهمة التي تم إنشاؤها حديثًا.
3. إنشاء CourseWork AddOnAttachment جديد.
4. إرسال طلب لإنشاء مرفق إضافة بالمهمة التي تم إنشاؤها حديثًا في Google Classroom

نقطة رئيسية: يجب إصدار الطلبَين بشكل منفصل. يجب إنشاء المهمة "CourseWork" بنجاح لكي يتم ربط مرفق الإضافة الجديدة بمعرّف المهمة.

Python

# /webapp/coursework_routes.py
if is_create_attachment_eligible:
  # Create an assignment.
  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.
  }

  # Issue a request to create the assignment.
  create_assignment_response = (
      classroom_service.courses()
      .courseWork()
      .create(courseId=course_id, body=coursework)
      .execute()
  )

  # Create an add-on attachment that links to the selected content and
  # associate it with the new assignment.
  content_url = flask.url_for(
      "example_coursework_assignment",
      assignment_type="add-on-attachment",
      _scheme="https",
      _external=True,
  )

  # Construct an AddOnAttachment instance.
  attachment = {
      "teacherViewUri": {"uri": content_url},
      "studentViewUri": {"uri": content_url},
      "title": f'Test Attachment for Assignment {create_assignment_response.get("id")}',
  }

  # Issue a request to create the attachment.
  add_on_attachment_response = (
      classroom_service.courses()
      .courseWork()
      .addOnAttachments()
      .create(
          courseId=course_id,
          itemId=create_assignment_response.get("id"),  # ID of the new assignment.
          body=attachment,
      )
      .execute()
  )

إنشاء مادة رابط

نقطة رئيسية: إذا كان منتجك ينشئ حاليًا CourseWork مهمة، من المحتمل أن يتّبع الخطوات الموضّحة هنا.

إذا كان المستخدم غير مؤهل لإنشاء مرفقات الإضافات، يمكنك إنشاء "مادة رابط" بدلاً من ذلك من خلال اتّباع الخطوات التالية:

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.
        # Specify the URL for your content as a Link Material.
        "materials": [
            {
                "link": {
                    "url": flask.url_for(
                        "example_coursework_assignment",
                        assignment_type="link-material",
                        _scheme="https",
                        _external=True,
                    )
                }
            }
        ],
    }

    # Issue a request to create the assignment.
    assignment_response = (
        classroom_service.courses()
        .courseWork()
        .create(courseId=course_id, body=coursework)
        .execute()
    )

تعديل مهمة سبق أن تم إنشاؤها

نقطة رئيسية: من المزايا الرئيسية لمرفقات الإضافات أنّها تمنحك القدرة على تنفيذ طلبات البيانات من واجهة برمجة التطبيقات في عنصر البث الرئيسي.

يمكنك الوصول إلى أي عنصر مصدر بيانات Google Classroom أو تعديله أو تسليمه أو استرداده أو إرجاعه، والذي يحتوي على مرفق واحد على الأقل من مرفقات الإضافات، بغض النظر عن الشخص الذي أنشأ عنصر البث. عناصر ساحة المشاركات هي أي مهام Announcement أو CourseWork أو CourseWorkMaterial.

لتوضيح ذلك، عليك إضافة مسار لتعديل عنصر بث معيّن. استخدِم هذه الطريقة للتأكّد من إمكانية وصولك إلى عناصر ساحة المشاركات التي أنشأتها باستخدام واجهة برمجة التطبيقات والتي أنشأها المعلّم من خلال واجهة مستخدم Google Classroom.

أضِف رابطًا أو زرًا آخر إلى صفحة الويب التي عدّلتها أولاً في هذه الجولة التفصيلية. يجب أن يتم فتح مسار جديد لتعديل مهمة CourseWork.

Python

في مثال بايثون المُقدَّم، يتم تعديل مسار "/index" الذي تم تعديله في وقت سابق من هذه الجولة التفصيلية.

<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>

أنشئ مسارًا جديدًا للتعامل مع المسارات ذات الصلة بـ CourseWork. يمكنك العثور على ذلك في ملف coursework_routes.py ضِمن المثال الذي قدّمناه.

# Check that the user is signed in.
credentials = get_credentials()

if not credentials:
  return start_auth_flow("coursework_assignment_callback")

# Get the Google Classroom service.
classroom_service = get_classroom_service()

# The ID of the course to which the assignment will be added.
# Ordinarily, you'll prompt the user to specify which course to use. For
# simplicity, we use a hard-coded value in this example.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.
assignment_id = 1234567890  # TODO(developer) Replace with an actual assignment ID.

# Retrieve details about the CourseWork assignment.
get_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .get(courseId=course_id, id=assignment_id)
    .execute()
)

# Alter the current title.
assignment_title = f"{get_coursework_response.get('title')} (Modified by API request)"

# Issue a request to modify the assignment.
modify_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .patch(
        courseId=course_id,
        id=assignment_id,
        updateMask="title",
        body={"title": assignment_title},
    )
    .execute()
)

اختبار الإضافة

ملاحظة مهمّة: في هذه المرحلة من عملية التطوير، لا يمكنك اختبار تطبيقك إلا في إطارات iframe الخاصة بإضافات Classroom. اقرأ صفحة دليل إطارات iframe ومعلمات طلب البحث للحصول على وصف لكل إطار iframe. تفترض جميع التعليمات المقدمة في هذه الجولة التفصيلية أن الإضافة قابلة للاستخدام في سياق إطار iframe.

لتبسيط الأمور، تستخدم الأمثلة المقدَّمة معرّفات الدورات التدريبية والمهام الدراسية. يمكنك الحصول على هذه المعرّفات من خلال إرسال طلبات باستخدام بيانات اعتماد المعلِّمين إلى طريقتَي get وlist في الموردَين courses وcourseWork. ويتم عرضها أيضًا في الرد عند إنشاء courseWork مهمة.

اختبار إنشاء مواد الرابط

شغِّل خادمك، ثم انتقِل إلى صفحة الفهرس وسجِّل الدخول بصفتك مستخدم معلّم بدون ترخيص Google Workspace for Education Teaching & Learning أو Plus. يمكنك تبديل حالة ترخيص المستخدم من "وحدة تحكّم المشرف" في نطاقك التجريبي.انقر على الزر إنشاء مهمة دراسية في دورة CourseWork، ثم افتح واجهة مستخدم Google Classroom وتحقَّق من إنشاء مهمة دراسية تحتوي على مرفق "مادة الرابط". يجب أن يعرض المرفق عنوان صفحة الويب المرتبطة وعنوان URL.

اختبار إنشاء مرفقات الإضافة

ارجع إلى صفحة الفهرس وسجِّل الدخول بصفتك مستخدمًا معلّمًا لديه ترخيص Google Workspace for Education Teaching & Learning أو Plus. انقر على الزر إنشاء مهمة دراسية في CourseWork، ثم افتح واجهة مستخدم Google Classroom وتحقَّق من إنشاء مهمة دراسية تحتوي على مرفق إضافة. يجب أن يُظهر المرفق اسم تطبيق الإضافة والعنوان المحدد في التعليمة البرمجية.

اختبار تعديل المهام الدراسية

ارجع إلى صفحة الفهرس وتأكَّد من تسجيل الدخول كمستخدم معلّم لديه ترخيص Teaching & Learning أو Plus. انقر على زر تعديل مهمة في CourseWork، ثم ارجع إلى واجهة مستخدم Google Classroom وتحقّق من أنه تم تغيير عنوان المهمة.

تهانينا لقد أكملت سلسلة الجولة التفصيلية.