建立 Google Workspace 外掛程式

本頁將概略說明如何設計、建構及發布 Google Workspace 外掛程式。本總覽將說明以下步驟:

  1. 決定要讓使用者在哪些 Google Workspace 應用程式中使用外掛程式。
  2. 設定外掛程式的專案,並選擇擁有者和協作者。
  3. 設計外掛程式的外觀和行為。
  4. 設定外掛程式的專案資訊清單或部署資源。
  5. 編寫程式碼來定義外掛程式的外觀和行為。
  6. 驗證外掛程式的 OAuth 範圍。
  7. 在一或多個 Google Workspace 應用程式中測試外掛程式。
  8. 發布外掛程式。

選擇 Google Workspace 代管應用程式

您可以設定讓 Google Workspace 外掛程式顯示在下列 Google Workspace 主機應用程式中:

  • Gmail
  • Google 日曆
  • Google 文件
  • Google 雲端硬碟
  • Google 試算表
  • Google 簡報

如要瞭解如何為 Google Workspace 應用程式進行建構,請參閱「擴充 Google Workspace UI」。

設定外掛程式的專案,並選擇擁有者和協作者

如果您在 Apps Script 中建構外掛程式,就會同時建立 Apps Script 專案和 Google Cloud 專案。如果您使用 Apps Script 以外的語言建構外掛程式,只需建立 Google Cloud 專案即可。

開始開發外掛程式前,請選擇一個用戶帳戶來擁有專案,並決定其他帳戶要擔任協作者。專案的擁有者可以建立及管理專案檔案和相關設定,協作者則可協助您編寫程式碼和測試。

Apps Script 專案

您可以在共用雲端硬碟中建構外掛程式的 Apps Script 專案檔案,這樣就沒有單一帳戶擁有專屬權。將外掛程式指令碼檔案放在共用雲端硬碟中,可確保多位協作者都能存取指令碼專案。

發布外掛程式時,單一使用者帳戶會做為發布者。發布帳戶必須具備指令碼專案的編輯存取權,但不必是擁有者。

如要建立 Apps Script 專案,請參閱「指令碼專案」。

Google Cloud 專案

建議您為外掛程式的 Cloud 專案新增協作者。這樣一來,團隊成員就能隨時存取外掛程式的雲端設定。

如要建立 Google Cloud 專案,請參閱「建立 Google Cloud 專案」。

設計外掛程式的外觀和行為

請先決定要讓外掛程式呈現什麼樣貌,以及應如何運作,再開始建構。請考量外掛程式應嘗試為哪些用途提供解決方案。請先從簡單的設計開始,然後再進行更多調整。

如需設計外掛程式使用者體驗的規範,請參閱 Google Workspace 外掛程式樣式指南

設定外掛專案資訊清單

在 Apps Script 專案中,專案資訊清單是特殊的 JSON 檔案。它會指定專案的各種詳細資料,例如程式庫依附元件。對於 Google Workspace 外掛程式,資訊清單也會提供主機應用程式需要的基礎資訊,才能正確顯示外掛程式。

如要進一步瞭解如何在 Apps Script 中設定外掛程式的資訊清單,請參閱「資訊清單」一文。

在外掛程式中新增程式碼和功能時,請視需要編輯資訊清單,產生所需的外掛程式外觀和行為。

編寫外掛程式的程式碼

您必須為外掛程式實作資訊卡介面。使用 Apps Script 的資訊卡服務,或如果您使用其他程式語言編寫,請傳回格式正確的 JSON,讓介面以資訊卡顯示。

您也必須實作附加元件資訊清單中指定的任何觸發功能。如果外掛程式使用 OAuth 連線至第三方非 Google 服務,您也必須為該服務設定 OAuth

建構資訊卡

您可以建立 Card 物件,並填入小工具,藉此定義外掛程式使用者介面。資訊清單中指定的觸發函式必須傳回單一 Card 物件,或是代表外掛程式介面不同「頁面」的 Card 物件陣列。外掛程式也可以根據使用者動作建立及顯示新資訊卡。

在 Apps Script 中,您可以使用 CardBuilder 類別建立資訊卡。每張資訊卡都需要一個 CardHeader 和一或多個 CardSections。請在每個資訊卡區塊填入構成外掛程式介面的個別小工具。互動小工具通常會連結至動作,以定義互動行為。

透過 CardBuilder 將所有版面和小工具新增至資訊卡後,您必須呼叫 CardBuilder.build() 來建立對應的 Card 物件。

您可以使用其他內建的 Apps Script 服務 (例如 CalendarApp) 擷取資訊,並在您建立的加購資訊卡中顯示。您可以使用從非 Google 服務擷取的資料。

如果外掛程式需要存取需要 OAuth 的非 Google API,您必須設定並連線至該服務。詳情請參閱連線至非 Google 服務指南

施工順序

建構資訊卡時,您必須從頂端開始建構。也就是說,您必須使用以下建構順序:

  1. 建構小工具。
  2. 將小工具新增至資訊卡區段。
  3. 重複執行上述步驟,直到卡片區段包含所有小工具為止。
  4. 將卡片部分新增至卡片。

這是必要的,因為當您在資訊卡或資訊卡部分新增小工具時,實際上是新增該小工具的副本。您在新增小工具物件後所做的任何變更,都不會反映在最終資訊卡上。

通用動作

您可以使用通用動作提供不受背景限制的功能。無論顯示哪個資訊卡,通用動作都是可在外掛程式 UI 中使用的選單項目。所有定義的通用動作一律會顯示在外掛程式的資訊卡選單中。

詳情請參閱「通用動作」。

驗證外掛程式 OAuth 範圍

範圍定義外掛程式可代表使用者採取哪些動作。最佳做法是,外掛程式只應針對必須執行的動作設定範圍,不應超過這個範圍。

在外掛程式專案中,明確設定外掛程式範圍,確保外掛程式使用最寬鬆的範圍組合。您可以在外掛程式資訊清單中定義外掛程式使用的範圍。

詳情請參閱「範圍」。

測試外掛程式

如要測試未發布的外掛程式,請先安裝未發布的外掛程式。安裝並授權後,您就可以在帳戶中使用外掛程式,並在擴充主機應用程式中測試外觀和行為。您應驗證外掛程式是否會依預期處理背景資料和使用者動作。

詳情請參閱「測試 Google Workspace 外掛程式」。

發布外掛程式

發布外掛程式後,其他使用者 (不論是公開發布或僅限網域內使用者) 都能使用。開始發布程序前,請務必詳閱出版總覽。發布是複雜的程序,需要準備和時間才能完成。

Google Workspace 外掛程式會發布至 Google Workspace Marketplace。公開發布的外掛程式必須先完成應用程式審查才能發布。

詳情請參閱「發布 Google Workspace 外掛程式」。