本頁面由 Cloud Translation API 翻譯而成。

Google Workspace 外掛程式的資訊清單

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

本文件詳細說明如何設定 Google Workspace 外掛程式。

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

Google Workspace 外掛程式使用資訊清單檔案來定義外掛程式外觀和行為

Google Workspace 外掛程式的資訊清單屬性會整理在資訊清單物件結構的 addOns 部分。

如要進一步瞭解 Apps Script 資訊清單檔案，請參閱資訊清單結構。
如要瞭解使用 HTTP 端點建構的附加元件資訊清單檔案，請參閱「REST 資源：projects.deployments」

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

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

資訊清單的 addOns.common 部分會定義外掛程式的名稱、標誌網址、顏色和其他一般、不依主機設定的設定。
資訊清單定義了一般首頁，但也定義了日曆、雲端硬碟、文件、試算表和簡報專屬的首頁。Gmail 會使用預設首頁。
範例資訊清單設定啟用下列功能：
- 日曆 eventOpen 和 eventUpdated 觸發條件。
- (僅限 Apps Script) 兩種日曆會議解決方案。
- 兩項通用動作。
- 雲端硬碟 onItemsSelectedTrigger。
- Gmail 撰寫動作和內容相關觸發條件。
- 文件 linkPreviewTriggers 物件。如要瞭解這個觸發條件，請參閱「使用智慧型方塊預覽連結」。
- 文件 createActionTriggers 物件。如要瞭解這個觸發條件請參閱「使用 @ 選單建立第三方資源」。
- 文件、試算表、文件專屬的介面和簡報
oauthScopes 欄位會設定專案的授權範圍 (通常是外掛程式所需)。
(僅限 Apps Script) urlFetchWhitelist 欄位可確保任何擷取的端點都與指定的 HTTPS 網址前置字串清單相符。詳情請參閱「將網址加入許可清單」。

示例中的連結會導向說明相應欄位中的值 Apps Script 資訊清單參考文件和 HTTP 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"
      }
    }
  },
  "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"
      }
    }
  },
  "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"
  ]
}

許可清單網址

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

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

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

從外部位置 (例如 HTTPS) 擷取或擷取資訊端點) 使用 Apps Script UrlFetch 課程中也會快速介紹 Memorystore 這是 Google Cloud 的全代管 Redis 服務如要將網址加入取得的許可清單，請在資訊清單檔案中加入 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 (萬用字元必須用於前置字串)