在 Google 课堂之外创建附件

本指南介绍了如何在网站或应用中创建插件附件。这些互动与使用 CourseWork API 端点创建作业类似。实现此转化历程，让用户能够通过您的网站或应用创建插件附件。

工作流程

概括来讲，附件创建流程遵循以下顺序：

  1. 教师用户打开您的网站或应用。他们选择要布置给学生的内容。
  2. 检查用户是否可以创建插件附件。
  3. 如果用户无法创建插件附件，请创建作业，并将所选内容的网址作为链接材料添加到作业中。
  4. 如果用户可以创建插件附件，请执行以下操作：
    1. 创建作业。
    2. 创建一个指向所选内容的插件附件，并将其与新作业相关联。
  5. 告知教师作业已成功创建。

以下各部分介绍了每项操作。

检查用户是否可以创建插件附件

您可以代表符合条件的用户创建插件附件。符合条件的用户是指您尝试在其中创建课业作业的课程的教师，并且已获配 Google Workspace 教育版的教与学或教育 Plus 版许可。

首先，确定用户是否可以创建插件附件。为此，您可以使用 CREATE_ADD_ON_ATTACHMENT capability 参数向 userProfiles.checkUserCapability 端点发出请求。检查响应中的布尔值 allowed 字段；true 值表示用户有资格创建插件附件。

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 作业，并将用户选择的内容网址作为 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. 教师视图：包含链接资料的课程作业草稿。

符合条件的用户

如果用户可以创建插件附件，请执行以下操作。

  1. 创建一个不含任何附件的 CourseWork 作业。
  2. 创建插件附件。

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")}'
  )

该插件会以附件卡片的形式显示在 Google 课堂中。请求中指定的网址会在每个 View 的适当 iframe 中打开。