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

老師要在 Classroom 中新增第三方內容的方法之一，就是在作業建立頁面中以「連結附件」的形式貼上連結。為了建立老師熟悉的應用，您現在可以設定外掛程式，讓老師將連結附件升級為外掛程式附件。

總覽

如果您是利用這項功能設定外掛程式，當老師在作業建立頁面中貼上連結附件時，系統會提示老師升級外掛程式附件的連結。系統只會提示已安裝外掛程式的老師。

一旦老師同意將連結升級為外掛程式附件，系統就會以下列查詢參數啟動連結升級 iframe：

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint (使用者必須已授權您的應用程式)

前四個查詢參數會反映在附件探索 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 也可用來為老師提供存取內容的適當權限。