Google Workspace 外掛程式的資訊清單

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

本文件提供如何為 Google Workspace 外掛程式設定資訊清單的詳細資訊。

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

Google Workspace 外掛程式使用 Apps Script 專案資訊清單檔案,定義外掛程式外觀和行為的幾個面向。Google Workspace 外掛程式的資訊清單屬性是放在資訊清單物件結構的 addOns 區段底下。

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

下列資訊清單範例顯示定義 Google Workspace 外掛程式的資訊清單檔案中的部分,其中包含以下方面:

  • 資訊清單的 addOns.common 區段會定義外掛程式的名稱、標誌網址、顏色,以及其他與主機無關的設定。
  • 資訊清單定義了一個通用首頁,但同時定義了 Google 日曆、雲端硬碟、文件、試算表和簡報專屬的首頁。Gmail 會使用預設首頁。
  • 資訊清單設定範例會啟用下列項目:
    • 日曆 eventOpeneventUpdated 觸發條件,以及兩個日曆會議解決方案
    • 兩個通用動作。
    • 行車時間 onItemsSelectedTrigger
    • Gmail 撰寫動作和內容比對觸發條件。
    • 文件 linkPreviewTrigger。如要瞭解這項觸發條件,請參閱「預覽內含智慧型方塊的連結」一文。
    • Google 文件、試算表和簡報的檔案專屬介面。
  • oauthScopes 欄位會設定專案的授權範圍 (外掛程式通常需要)。
  • urlFetchWhitelist 欄位可確保所有擷取的端點都符合指定的 HTTPS 網址前置字串清單。詳情請參閱「將網址加入許可清單」。

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

{
  "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"
      },
      "linkPreviewTriggers": [
        {
        "runFunction": "onLinkPreview",
        "patterns": [
            {
              "hostPattern": "example.com",
              "pathPrefix": "example-path"
            }
        ],
        "labelText": "Link preview",
        "localizedLabelText": {
          "es": "Link preview localized in Spanish"
        },
        "logoUrl": "https://www.example.com/images/smart-chip-icon.png"
        }
      ]
    },
    "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",
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ]
}

將網址加入許可清單

您可以使用許可清單來指定允許指令碼或外掛程式預先核准存取的特定網址。許可清單有助於保護使用者資料;定義許可清單後,指令碼專案無法存取未加入許可清單的網址。

當您安裝測試部署時,此為選用欄位,但建立版本化部署時為必填。

當您的指令碼或外掛程式執行下列動作時,請使用許可清單:

  • 使用 Apps Script UrlFetch 服務擷取或擷取外部位置 (例如 HTTPS 端點) 的資訊。如要將網址加入許可清單以用於擷取,請在資訊清單檔案中加入 urlFetchWhitelist 欄位。
  • 開啟或顯示網址以回應使用者動作 (對於開啟或顯示網址 Google 外部的 Google Workspace 外掛程式需要此外掛程式)。如要將網址加入許可清單以便開啟,請在資訊清單檔案中加入 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 (萬用字元必須做為前置字元前置字元)