تتوفّر الآن إضافات Google Classroom بشكل عام للمطوّرين. يُرجى الاطّلاع على مستندات الإضافات للحصول على مزيد من المعلومات.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

هذا هو الإرشاد السابع في سلسلة الإرشادات الخاصة بإضافات Classroom.

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

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

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

إضافة نطاق 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

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

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

Python

يعدّل مثال 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>

أنشئ ملف وحدة Python جديدًا للتعامل مع المسارات ذات الصلة بـ 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 الطريقة userProfiles.checkUserCapability لتحديد ما إذا كان المستخدم يستوفي هذه المتطلبات الأساسية. يُشار إلى المستخدم الذي يستوفي المتطلبات الأساسية باسم مستخدم مؤهَّل.

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

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 ...

  # Check whether the user can create add-on attachments.
  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")

  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.

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

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

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

Python

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

# /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()
  )

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

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

Python

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

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

يعدّل مثال 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()
)

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

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

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

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

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

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

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

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

تهانينا! لقد أكملت سلسلة الجولات الإرشادية.

المرفقات الخارجية والاستلام تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

Python

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

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

Python

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

Python

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

Python

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

Python

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

Python

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

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

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

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

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