在 Google Classroom 以外的地方建立附件

本指南說明如何在網站或應用程式中建立外掛程式附件。互動方式與使用 CourseWork API 端點建立作業類似。實作這個歷程，讓使用者可透過網站或應用程式建立外掛程式附件。

重要事項： 如果您已建立 CourseWork 指派作業，強烈建議您實作這個附件建立流程。擴充 CourseWork 實作可讓您將更多使用者轉換為外掛程式，且只需進行少許額外作業。

工作流程

大致來說，附件建立流程會依照以下順序進行：

1. 老師使用者開啟您的網站或應用程式，並選取要指派給學生的內容。
2. 確認使用者能否建立外掛程式附件。
3. 如果使用者無法建立外掛程式附件，請建立 CourseWork 作業，並將所選內容的網址設為連結素材。
4. 如果使用者「可以」建立外掛程式附件，請執行下列操作：
   1. 建立作業。
   2. 建立連結至所選內容的外掛程式附件，並與新作業建立關聯。
5. 告知老師已成功建立作業。

以下各節將說明各項操作。

檢查使用者是否可以建立外掛程式附件

您可以代表符合資格的使用者建立外掛程式附件。符合資格的使用者是指您嘗試在課程中建立 CourseWork 作業的授課老師，並擁有 Teaching & Learning 或 Education Plus Google Workspace for Education 版本授權。

重點： 每位使用者建立外掛程式附件的資格可能不同，且可能隨時間變動。請務必先檢查使用者的資格，再嘗試建立外掛程式附件。

重要事項： 使用 Classroom API 的資格檢查功能目前處於公開預先發布階段，並可在預先發布版 V1_20240930_PREVIEW 以上版本中使用。如要在公開預先發布版中使用 API 方法，您必須加入 Google Workspace 開發人員預覽版計畫，並執行額外設定，以便使用不同於一般 Classroom API 的用途。

首先，請判斷使用者是否能建立外掛程式附件。您可以透過 CREATE_ADD_ON_ATTACHMENT 能力參數，向 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. 老師檢視含有連結教材的 CourseWork 作業草稿。

符合資格的使用者

如果使用者「可以」建立外掛程式附件，請執行下列操作。

1. 建立新的 CourseWork 指派，不含任何附件。
2. 建立外掛程式附件。
   • 將 AddOnAttachment 的 itemId 設為新建立指派項目的 id。
   • 請務必為您支援的每個 View 提供使用者選取的內容網址。

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 中。要求中指定的網址會在每個 View 的 iframe 中開啟。