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

老師將第三方內容新增至 Classroom 的其中一種方式，是在作業建立頁面中，將連結貼為連結附件。為延續老師已熟悉的功能，您現在可以設定外掛程式，讓老師將連結附件升級為外掛程式附件。

總覽

如果您為外掛程式設定這項功能，老師在作業建立頁面中貼上連結附件時，系統會提示他們將連結升級為外掛程式附件。只有在老師已安裝外掛程式時，系統才會提示他們這麼做。

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

courseId
itemId
itemType
addOnToken
urlToUpgrade
login_hint (僅限使用者已授權應用程式時)

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

建立外掛程式附件後，系統會關閉 iframe，老師可以像平常一樣在作業中查看附件。

技術實作詳細資料

本節將說明這項功能的一些重要技術細節。

讀取 `urlToUpgrade` 查詢參數

在 Link Upgrade iframe 上傳遞 urlToUpgrade 查詢參數時，系統會對該參數進行 URI 編碼。您必須解碼網址，才能取得原始網址。舉例來說，如果您使用 JavaScript，可以透過 decodeURIComponent() 函式執行這項操作。

關閉「連結升級」iframe

為確保這項功能提供最佳使用者體驗，請在成功建立外掛程式附件後傳送 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 外掛程式的任何 Google Cloud 專案提供設定。建議您先為附加元件提供私人瀏覽權限的設定，以便在示範網域中開發及測試，而不影響實際使用者。

設定啟用後，您會收到電子郵件回覆。請注意，這項功能不支援使用「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 協助登入 (如有需要)，或顯示載入指標。為提供最佳使用者體驗，老師同意將貼上的連結升級為外掛程式附件後，系統就不應再提示老師提供任何額外資訊。不過，如果無法在附加元件中完成這項操作，您可以使用 Link Upgrade iframe 收集所需額外資訊。如果無法升級連結或發生錯誤，也可以使用 iframe 通知老師。

加入易於理解的存取錯誤訊息

如果老師貼上並升級他們無法存取的連結，請在 iframe 中顯示易於理解的錯誤訊息，讓老師瞭解問題。iframe 也可用於授予老師適當的權限，方便存取內容。