Google Workspace 外掛程式的資訊清單

外掛程式會使用資訊清單檔案，設定應用程式及其運作方式的特定詳細資料。

這份文件涵蓋為 Google Workspace 外掛程式設定資訊清單的詳細資料。

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

Google Workspace 外掛程式會使用資訊清單檔案定義外觀和行為的各個層面。

Google Workspace 外掛程式的資訊清單屬性會整理在 addOns 部分下方。

如要瞭解 Google Apps Script 資訊清單檔案，請參閱「資訊清單結構」。
如要瞭解使用 HTTP 端點建構的增益集資訊清單檔案，請參閱「projects.deployments」。

Google Chat 的資訊清單

如果 Google Workspace 外掛程式會擴充 Google Chat，請在 Google Cloud 控制台中啟用並設定 Google Chat API，設定 Google Chat 應用程式。

Chat 會忽略常見的資訊清單設定 (包括 addons.common)。使用 Chat API 設定下列 Chat 設定：

Chat 應用程式的名稱、標誌和說明，適用於 Chat 使用者介面。
觸發 Chat 應用程式。

如果您是在 Apps Script 中建構外掛程式，請在資訊清單中新增或更新下列物件：

addons.chat (必要)
oauthScopes (如果 Google Chat 應用程式使用 OAuth，則為必填)

如要設定外掛程式的 Chat 設定，請參閱「設定 Google Chat 應用程式」。

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

下列範例顯示資訊清單中定義 Google Workspace 外掛程式的部分，包括以下各方面：

addOns.common 定義外掛程式的名稱、標誌、顏色和其他一般設定。
資訊清單定義了通用首頁，但同時也定義了 Google 日曆、Google 雲端硬碟、Google 文件、Google 試算表和 Google 簡報專用的首頁。Gmail 會使用預設首頁。
範例資訊清單設定會啟用下列項目：
- 日曆 eventOpen 和 eventUpdated 觸發條件。
- (僅限 Apps Script) 兩個日曆會議解決方案。
- 兩個全域動作。
- 行駛 onItemsSelectedTrigger。
- Gmail 撰寫動作和情境觸發條件。
- Docs linkPreviewTriggers 物件。請參閱「使用智慧型方塊預覽連結」。
- Docs createActionTriggers 物件。請參閱「透過 @ 選單建立第三方資源」。
- Google 文件、試算表和簡報的專屬介面。
- Google Meet 的 sidePanelUri 和 addOnOrigins 選項。
- (僅限 HTTP) 兩個 HttpOptions，用於傳送授權標頭及支援細分式同意。
「oauthScopes」欄位會設定專案的授權範圍。
(僅限 Apps Script) urlFetchWhitelist 可確保擷取的端點符合指定的 HTTPS 網址前置字串。請參閱「將網址加入許可清單」。

範例中的連結會重新導向至 Apps Script 和 HTTP Google Workspace 外掛程式的資訊清單參考資料中的欄位說明。

資訊清單包含其他元件。「addOns」下方的欄位直接與 Google Workspace 外掛程式相關。這個範例只顯示完整資訊清單檔案的一部分，無法單獨運作。

Apps Script

{
  "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://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"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "exampleFunction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/logoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
    },
  },
  "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/"
  ]
}

HTTP

{
  "addOns": {
    "calendar": {
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=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://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "actions": [
          {
            "label": "Add images to email",
            "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "https://myownpersonaldomain.com/mypage?trigger=onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=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"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCreateAction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/meetWebLogoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
      ]
    },
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN",
      "granularOauthPermissionSupport": "OPT_IN"
    }
  },
  "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"
  ]
}

將網址列入許可清單

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

安裝測試部署時，這個欄位為選填，但建立版本化部署時，則為必填。

當指令碼或外掛程式執行下列動作時，您可以使用許可清單：

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

在許可清單中新增前置字串

在資訊清單檔案中指定允許清單時 (包含 addOns.common.openLinkUrlPrefixes 或 urlFetchWhitelist 欄位)，您必須加入網址前置字元清單。您在資訊清單中新增的前置字元必須符合下列規定：

每個前置字串都必須是有效的網址。
每個前置字串都必須使用 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

使用萬用字元

您可以在 urlFetchWhitelist 和 addOns.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 (萬用字元必須做為前置字串)

Google Workspace 外掛程式的資訊清單 透過集合功能整理內容 你可以依據偏好儲存及分類內容。