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

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

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

工作流程

大致來說，建立附件的流程如下：

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

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

確認使用者能否建立外掛程式附件

您可以代表符合資格的使用者建立外掛程式附件。符合資格的使用者是指在您要建立課程作業的課程中擔任老師，且已獲派 Teaching & Learning 或 Education Plus Google Workspace for Education 版本授權。

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

重要事項： 使用 Classroom API 檢查資格的功能已推出公開預先發布版，並適用於預先發布版 V1_20240930_PREVIEW 和後續版本。如要使用公開預先發布版中的 API 方法，您必須是 Google Workspace 開發人員預先發布版計畫的成員，並另外執行不同於一般 Classroom API 使用情形的設定。

首先，請判斷使用者是否可以建立外掛程式附件。如要這麼做，請向 userProfiles.checkUserCapability 端點發出要求，並提供 CREATE_ADD_ON_ATTACHMENT 功能參數。檢查回應中的布林值 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('User eligibility for add-on attachment creation: '
      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")}'
  )

注意： 如果您在自己建立的作業中建立附件，則不需要外掛程式權杖。

外掛程式會以附件卡的形式顯示在 Classroom 中。要求中指定的網址會在每個檢視區塊的適當 iframe 中開啟。