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 外掛程式。

注意：資訊清單包含其他元件。當中的欄位 「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"
      }
    }
  },
  "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 欄位 資訊清單檔案

注意： 許可清單 (如 urlFetchWhitelist 使用中) 是已淘汰的字詞，並由許可清單取代。詳情請參閱編寫具包容性的說明文件。

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

在資訊清單檔案中指定許可清單 (透過加入 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 (萬用字元必須用於前置字串)