在 Google 课堂之外创建附件

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

重要提示 ：如果您已创建 CourseWork 作业，我们强烈建议您实现此附件创建流程。通过扩展 Coursework 实现，您可以将更多用户转换为您的插件用户，而且只需进行少量额外工作。

工作流程

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

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

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

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

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

要点 ：各用户创建插件附件的资格条件可能不同，并且可能会随时间而变化。在尝试创建插件附件之前，请务必检查用户是否符合条件。

重要提示： 使用 Classroom API 进行的资格检查功能处于公开预览阶段，可在预览版 V1_20240930_PREVIEW 及更高版本中使用。如需在公开预览版中使用 API 方法，您必须加入 Google Workspace 开发者预览版计划，并执行额外的设置，而不仅仅是正常使用 Classroom API。

首先，确定用户是否可以创建插件附件。为此，您可以使用 CREATE_ADD_ON_ATTACHMENT capability 参数向 userProfiles.checkUserCapability 端点发出请求。检查响应中的布尔值 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 作业，并将用户选择的内容网址作为 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. 创建插件附件。
   • 将 AddOnAttachment 的 itemId 设置为新创建的作业的 id。
   • 确保为您支持的每个视图提供指向用户选择的内容的网址。

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 中打开。