Google Workspace 外掛程式資訊清單

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Apps Script 專案會使用 manifest 檔案來設定指令碼及其作業的特定詳細資料。如要瞭解如何檢視及編輯資訊清單,請參閱資訊清單

這份說明文件會詳細說明 Google Workspace 外掛程式的資訊清單設定。

Google Workspace 外掛程式的資訊清單結構

Google Workspace 外掛程式會使用 Apps Script 專案資訊清單檔案,定義外掛程式外觀和行為的幾個層面。Google Workspace 外掛程式的資訊清單屬性歸類於 Manifest 物件結構的 addOns 區段

Google Workspace 外掛程式資訊清單設定範例

下方資訊清單範例顯示了定義 Google Workspace 外掛程式的資訊清單檔案區段,包括以下方面:

  • 資訊清單的 addOns.common 部分定義外掛程式的名稱、標誌網址、顏色,以及其他與主機相關的獨立設定。
  • 資訊清單會定義通用首頁,但也會定義日曆、雲端硬碟、文件、試算表和簡報的首頁。Gmail 會使用預設首頁。
  • 範例資訊清單設定啟用下列功能:
    • 日曆 eventOpeneventUpdated 觸發條件,以及兩個日曆會議解決方案
    • 兩個通用動作。
    • onItemsSelectedTrigger
    • Gmail 撰寫動作和內容觸發條件。
    • Google 文件、試算表和簡報的檔案專用介面。
  • oauthScopes 欄位可設定專案的授權範圍 (使用外掛程式時通常需要)。
  • urlFetchWhitelist 欄位可確保任何擷取的端點符合指定的 HTTPS 網址前置字串清單。這是測試部署作業的選用欄位,但這是部署作業的選用項目。詳情請參閱將網址加入許可清單一文。

範例中的連結會導向資訊清單參考說明文件中該欄位的說明。

// Sample configuration of the addOns section in a manifest file:
{
  "addOns": {
    "calendar": {
      "createSettingsUrlFunction": "getConferenceSettingsPageUrl",
      "conferenceSolution": [{
        "id": "my-video-conf",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "name": "My Video Conference",
        "onCreateFunction": "onCreateMyVideoConference"
      }, {
        "id": "my-streamed-conf",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "name": "My Streamed Conference",
        "onCreateFunction": "onCreateMyStreamedConference"
      }],
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "onDefaultHomePageOpen",
        "enabled": true
      },
      "layoutProperties": {
        "primaryColor": "#ff392b",
        "secondaryColor": "#d68617"
      },
      "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png",
      "name": "Demo Google Workspace Add-on",
      "openLinkUrlPrefixes": [
        "https://mail.google.com/",
        "https://script.google.com/a/google.com/d/",
        "https://drive.google.com/a/google.com/file/d/",
        "https://en.wikipedia.org/wiki/",
        "https://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },

    "drive": {
      "homepageTrigger": {
        "runFunction": "onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "onDriveItemsSelected"
      }
    },

    "gmail": {
      "composeTrigger": {
        "selectActions": [
          {
            "text": "Add images to email",
            "runFunction": "getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ]
    },

    "docs": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },

    "sheets": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },

    "slides": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.addons.current.event.read",
    "https://www.googleapis.com/auth/calendar.addons.current.event.write",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/script.locale",
    "https://www.googleapis.com/auth/script.scriptapp",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/documents.currentonly",
    "https://www.googleapis.com/auth/spreadsheets.currentonly",
    "https://www.googleapis.com/auth/presentations.currentonly"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ],
}

許可清單網址

您可以使用許可清單指定特定網址,這些指令碼已預先經過核准,可由指令碼或外掛程式存取。許可清單可協助保護使用者資料;定義許可清單時,指令碼專案無法存取未加入許可清單的網址。

您可以在指令碼或外掛程式執行以下動作時,使用許可清單:

  • 使用 Apps Script UrlFetch 服務從外部位置 (例如 HTTPS 端點) 擷取或擷取資訊。如要將網址擷取到許可清單,請在資訊清單檔案中加入 urlFetchWhitelist 欄位。
  • 開啟或顯示網址,以回應使用者的動作 (如果 Google Workspace 外掛程式已開啟或顯示 Google 以外的網址,則為必填)。如要將網址加入許可清單,請在資訊清單檔案中加入 addOns.common.openLinkUrlPrefixes 欄位。

將前置字串加入許可清單

在資訊清單檔案中 (包括 addOns.common.openLinkUrlPrefixesurlFetchWhitelist 欄位) 指定許可清單時,您必須加入網址前置字串清單。新增至資訊清單的前置字串必須符合下列需求:

  • 每個前置字串都必須是有效的網址。
  • 每個前置字串都必須使用 https://,而不是 http://
  • 每個前置字串都必須具備完整網域。
  • 每個前置字串必須包含非空白的路徑。例如,https://www.google.com/ 有效,但 https://www.google.com 無效。
  • 您可以使用萬用字元來比對網址子網域的前置字元。
  • addOns.common.openLinkUrlPrefixes 欄位可以使用單一 * 萬用字元來比對所有連結,但我們不建議這麼做,因為這可能會讓使用者資料暴露於風險中,進而延長附加審查程序。只有在需要附加功能時才需要使用萬用字元。

在判斷網址是否與加入許可清單的前置字串相符時,系統會套用下列規則:

  • 路徑比對須區分大小寫。
  • 如果前置字元與網址完全相同,系統會視為相符的網址。
  • 如果網址相同或與前置字串的子項相符,就會視為相符。

舉例來說,前置字串 https://example.com/foo 可比對下列網址:

  • https://example.com/foo
  • https://example.com/foo/
  • https://example.com/foo/bar
  • https://example.com/foo?bar
  • https://example.com/foo#bar

使用萬用字元

您可以使用單一萬用字元 (*) 來比對 urlFetchWhitelistaddOns.common.openLinkUrlPrefixes 欄位的子網域。您只能使用一個萬用字元來比對多個子網域,而且萬用字元必須代表網址的前置前置字元。

例如,前置字串 https://*.example.com/foo 會比對下列網址:

  • https://subdomain.example.com/foo
  • https://any.number.of.subdomains.example.com/foo

前置字串 https://*.example.com/foo 與下列網址相符:

  • https://subdomain.example.com/bar (後置字串不相符)
  • https://example.com/foo (至少要有一個子網域)

當您嘗試儲存資訊清單時,系統會強制執行部分前置字串規則。舉例來說,如果在嘗試儲存時,下列前置字串含有錯誤,就會造成錯誤:

  • https://*.*.example.com/foo (禁止使用多個萬用字元)
  • https://subdomain.*.example.com/foo (萬用字元必須做為前置前置字串使用)