本頁面由 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 部分會定義外掛程式的名稱、標誌網址、顏色，以及與主機無關的其他一般設定。
資訊清單定義了通用的首頁，但同時也定義了 Google 日曆、雲端硬碟、文件、試算表和簡報專用的首頁。Gmail 會使用預設首頁。
範例資訊清單設定可啟用下列功能：
- 日曆 eventOpen 和 eventUpdated 觸發條件。
- (僅限 Apps Script) 兩項日曆會議解決方案。
- 兩項通用動作。
- 開車 onItemsSelectedTrigger。
- Gmail 撰寫動作和內容相關觸發條件。
- 文件 linkPreviewTriggers 物件。如要瞭解這項觸發條件，請參閱「預覽含有智慧型方塊的連結」一節。
- 文件 createActionTriggers 物件。如要瞭解這個觸發條件，請參閱使用 @ 選單建立第三方資源。
- Google 文件、試算表和簡報的檔案專屬介面
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"
  ]
}

許可清單網址

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

安裝測試部署作業時，這是選用欄位；當您建立版本化部署時，這是選用欄位。

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

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