建立 Google Workspace 外掛程式

如要建立新的 Google Workspace 外掛程式，請按照下列一般程序操作：

  1. 設定外掛程式的專案，並選擇擁有者和協作者。
  2. 設計外掛程式的外觀和行為。
  3. 設定外掛程式的專案資訊清單或部署資源。
  4. 撰寫程式碼來定義外掛程式的外觀和行為。
  5. 驗證外掛程式的 OAuth 範圍。
  6. 在其擴充的主機應用程式中測試外掛程式。
  7. 發布外掛程式。

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

如果您是在 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 物件。

您可以使用 CalendarApp 等其他內建 Apps Script 服務擷取要在建構的外掛程式資訊卡中顯示的資訊。您可以使用從非 Google 服務擷取的資料。

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

施工順序

建立資訊卡時，您必須從頭開始建構。也就是說，您必須使用以下建構順序：

  1. 建構小工具。
  2. 將小工具新增至資訊卡部分。
  3. 重複上述步驟，直到卡片區塊顯示所有小工具為止。
  4. 在資訊卡中新增卡片專區。

此為必要項目，因為當您將小工具新增至資訊卡或資訊卡區段時，實際上就是新增小工具的副本。您在新增小工具物件後所做的任何變更，都不會反映在最終的資訊卡中。

通用動作

您可以使用通用動作來提供與結構定義無關的功能。無論顯示何種資訊卡，通用動作都是外掛程式 UI 中提供的選單項目。所有已定義的通用動作一律會顯示在外掛程式的資訊卡選單中。

詳情請參閱通用動作。

驗證外掛程式 OAuth 範圍

範圍定義外掛程式可代表使用者執行的動作。最佳做法是，讓外掛程式僅擁有執行順序必要動作所需的範圍，且其他項目不可行。

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

詳情請參閱範圍。

測試外掛程式

您可以安裝未發布的外掛程式來測試未發布的外掛程式。安裝並授權後，您就可以在帳戶中使用這個外掛程式，並在其擴充的主機應用程式中測試其外觀與行為。您應確認外掛程式的行為是否符合結構定義和使用者動作的預期。

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

發布外掛程式

發布外掛程式後，其他使用者 (無論公開或僅限您網域中的使用者) 都能使用該外掛程式。在開始發布程序之前，請務必參閱發布項目總覽。發布程序十分複雜，需要準備和時間才能完成。

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

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