將連結連結至 Classroom 外掛程式附件

老師要在 Classroom 中加入第三方內容，其中一種方法是在作業建立頁面中，以「連結附件」的形式貼上連結。如要進一步強化老師熟悉的功能，您現在可以設定外掛程式，讓老師將連結附件升級為外掛程式附件。

總覽

如果您使用這項功能設定外掛程式，老師在作業建立頁面貼上連結附件時，系統會提示他們升級外掛程式連結的連結。只有在老師已安裝外掛程式的情況下，系統才會提示老師執行這項操作。

老師同意將連結升級為外掛程式附件後，系統就會啟動「連結升級 iframe」，其中包含以下查詢參數：

  • courseId
  • itemId (重新命名自 postId)
  • itemType (新功能！)
  • addOnToken
  • login_hint 或 hd
  • urlToUpgrade (新功能！)

前四個查詢參數與附件探索 iframe 上啟動的查詢參數相同。這是全新的 urlToUpgrade 查詢參數，可協助您評估如何建立外掛程式附件。接著，您可以使用其他查詢參數來檢查使用者是否已登入，並根據 itemType 值呼叫 courseWork、courseWorkMaterials 或 announcements 的 CreateAddOnAttachment 方法。在 iframe 中，系統會顯示載入畫面，向老師指示正在建立外掛程式附件。

建立外掛程式附件後，iframe 會關閉，老師則可照常查看作業中的附件。

技術實作詳情

本節會重點介紹這項功能的重要技術細節。

讀取 urlToUpgrade 查詢參數

urlToUpgrade 查詢參數是經由連結升級 iframe 傳送時經過 URI 編碼。您必須對網址進行解碼，才能取得原始格式的網址。舉例來說，如果您使用 JavaScript，就可以使用 decodeURIComponent() 函式。

為確保這項功能提供最佳的使用者體驗，請在成功建立外掛程式連結後傳送 postMessage。這麼做會關閉 iframe。詳情請參閱 iframe 導入詳細資料頁面。

設定詳細資料

您必須完成下列設定，才能將這項功能整合至外掛程式：

  • 「連結升級 iframe」的網址：這是教師同意升級時，在 iframe 中開啟的網址。

  • Classroom 應偵測和嘗試升級的網址模式：網址模式可包含主機和多個路徑前置字串。

    • 您可以提供多個網址模式，
    • 如未提供任何路徑前置字串，凡是與主機相符的網址皆可升級。
    • 您只能升級採用 https 配置的網址。
    • 網址模式不得包含 localhost。
    • 路徑前置字元不得包含查詢參數或網址片段。
    • 路徑前置字串目前可支援萬用字元，但主機無法：
      • example.com 是有效的主機，/foo 和 /bar/*/baz 則是有效的路徑前置字串。
      • example.*.host.com 不是有效的主機。
    • 路徑前置字串元件之間的萬用字元只會比對單一元件，無法比對以斜線分隔的多個元件。假設有包含主機 example.com 和路徑前置字串 /bar/*/baz 的網址模式：
      • https://example.com/bar/123/baz 是有效的網址模式比對。
      • https://example.com/bar/123/baz/456/789 是網址模式的有效比對。
      • https://example.com/bar/123/456/baz 不是有效的網址模式，因為路徑前置字串中的萬用字元與 /123/456/ 不符。

開發流程

傳送電子郵件至 classroom-link-upgrade-external@google.com，以傳送測試或正式版外掛程式的連結升級 iframe 網址和網址模式。

您可以先為您的私人外掛程式和任何測試或開發環境提供設定。Classroom 團隊可以在啟用實際工作環境設定之前啟用這些測試設定，讓您在示範網域中測試流程。啟用設定之後，系統會透過電子郵件回覆您。請注意，這項功能不支援使用 localhost 的網址模式。

設定電子郵件格式，納入以下項目：

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
- Host:HOST_1
- Path prefixes:
  - PATH_PREFIX_1
  - PATH_PREFIX_2

- Host:HOST_2
- Path prefixes:
  - PATH_PREFIX_3
  - PATH_PREFIX_4

// add more hosts and path prefixes as needed

更改下列內容：

  • GCP_PROJECT_NUMBER：與這個外掛程式相關聯的 Google Cloud 專案數量。
  • LINK_UPGRADE_IFRAME_URL 在「連結升級」iframe 中開啟的網址。
  • HOST_1：Classroom 應偵測到的主機。 僅支援 https 配置。
  • PATH_PREFIX_1 和 PATH_PREFIX_2：與 HOST_1 相關聯的路徑前置字串，Classroom 應會偵測並嘗試升級。
  • HOST_2：Classroom 應偵測到的主機。 僅支援 https 配置。
  • PATH_PREFIX_3 和 PATH_PREFIX_4：與 HOST_2 相關聯的路徑前置字串，Classroom 應會偵測並嘗試升級。

實作這項功能時，建議參考以下建議。

避免老師進行額外作業

我們強烈建議您使用 iframe 協助使用者登入 (如有需要) 或顯示載入指標。為了提供最佳的使用者體驗，在他們要求將貼上的連結升級為外掛程式附件後，系統不應提示老師提供任何其他資訊。不過，如果您的外掛程式無法這麼做，可以使用「連結升級 iframe」收集所需的其他資訊。如果無法升級連結或發生錯誤，也可以使用 iframe 通知老師。

提供使用者容易理解的錯誤訊息

如果老師貼上及升級無法存取的連結，請在 iframe 中顯示使用者可理解的錯誤訊息，讓老師瞭解問題。iframe 也可用來為老師提供存取內容的適當權限。