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

老師在 Classroom 中新增第三方內容的其中一種方式如下： 在作業建立頁面中，以連結附件的形式貼上連結。建構 即可使用老師熟悉的功能，現在您可以 讓老師將連結附件升級為外掛程式附件。

總覽

如果您是透過這項功能設定外掛程式，系統會提示老師使用 使用者將連結附件貼入外掛程式附件時，將連結升級 作業建立頁面。系統只會在老師收到相關提示時提示您 已安裝外掛程式。

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

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

前四個查詢參數與 附件探索 iframe。urlToUpgrade 查詢參數是新的參數，可以 有助於評估建立外掛程式附件的方式。接著，您就能 其他查詢參數檢查使用者是否已登入，然後呼叫 CreateAddOnAttachment courseWork方法，courseWorkMaterials或 announcements (根據 itemType 值計算)。在 iframe 中，您可以 顯示載入畫面，向老師說明外掛程式附件 正在建立。

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

技術實作詳情

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

讀取 urlToUpgrade 查詢參數

urlToUpgrade 查詢參數是透過連結傳遞時，會經過 URI 編碼 升級 iframe。您必須將網址解碼，以取得原始格式的網址。如果 您使用 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/。

開發流程

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

您可以為任何代表 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：路徑 Classroom 應偵測和嘗試的 HOST_1 相關前置字串 升級。
  • HOST_2：Classroom 應偵測到的主機。只有 支援 https 配置。
  • PATH_PREFIX_3 和 PATH_PREFIX_4：路徑 Classroom 應偵測和嘗試的 HOST_2 相關前置字串 升級。

以下是實作這項功能時應考量的建議。

讓老師不必多費工夫

我們強烈建議您使用 iframe 協助登入 或顯示載入指標為了提供最佳使用者體驗， 老師應在學生 同意將貼上的連結升級為外掛程式附件。不過，如果這是 無法使用外掛程式，您可以使用「連結升級 iframe」 額外的資訊iframe 也可用來 老師無法升級連結或發生錯誤。

附上適合使用者存取的錯誤訊息

如果老師貼上並升級無法存取的連結，系統會顯示 iframe 中顯示容易易懂的錯誤訊息，讓老師瞭解問題。 iframe 也可用來為教師提供適當的 授予內容存取權限