Pliki manifestu dodatków do Google Workspace

Dodatek używa pliku manifestu do konfigurowania określonych szczegółów dotyczących aplikacji i jej działania.

W tym dokumencie znajdziesz szczegółowe informacje o konfigurowaniu pliku manifestu dodatku do Google Workspace.

Struktura pliku manifestu dodatków do Google Workspace

Dodatki do Google Workspace używają pliku manifestu do określania różnych aspektów wyglądu i działania.

Właściwości pliku manifestu dodatków do Google Workspace są uporządkowane w sekcji addOns.

Więcej informacji o plikach manifestu Google Apps Script znajdziesz w sekcji Struktura manifestu.
Informacje o plikach manifestu dodatków utworzonych za pomocą punktów końcowych HTTP znajdziesz w projects.deployments.

Pliki manifestu Google Chat

Jeśli dodatek do Google Workspace rozszerza Google Chat, skonfiguruj aplikację do Google Chat, włączając i konfigurując interfejs Google Chat API w konsoli Google Cloud.

W Google Chat ignorowane są typowe ustawienia konfiguracji pliku manifestu (w tym addons.common). Za pomocą interfejsu Chat API możesz skonfigurować te ustawienia Chatu:

Nazwa, logo i opis aplikacji do Google Chat w interfejsie Chat.
Triggery aplikacji do obsługi czatu

Jeśli dodatek został utworzony w Apps Script, dodaj lub zaktualizuj te obiekty w pliku manifestu:

addons.chat (wymagane)
oauthScopes (Wymagane, jeśli aplikacja Google Chat korzysta z OAuth)

Aby skonfigurować ustawienia Google Chat dla dodatku, zapoznaj się z artykułem Konfigurowanie aplikacji Google Chat.

Przykładowa konfiguracja pliku manifestu dodatku do Google Workspace

Poniższe przykłady pokazują fragment pliku manifestu, który definiuje dodatek do Google Workspace, w tym te aspekty:

addOns.common określa nazwę, logo, kolory i inne ogólne ustawienia dodatku.
Plik manifestu definiuje wspólną stronę główną, ale także strony główne dla Kalendarza Google, Dysku Google, Dokumentów Google, Arkuszy Google i Prezentacji Google. Gmail używa domyślnej strony głównej.
Przykładowe ustawienia pliku manifestu umożliwiają:
- wyzwalacze Kalendarza eventOpen i eventUpdated;
- (tylko Apps Script) Dwa rozwiązania konferencyjne w Kalendarzu.
- Dwa działania uniwersalne.
- A Dysk onItemsSelectedTrigger.
- działanie tworzenia wiadomości w Gmailu i wyzwalacz kontekstowy;
- Obiekt linkPreviewTriggers Dokumentów Google. Zobacz Wyświetlanie podglądu linków za pomocą elementów inteligentnych.
- Obiekt createActionTriggers Dokumentów Google. Zobacz Tworzenie zasobów innych firm za pomocą menu @.
- Interfejsy specyficzne dla plików w Dokumentach, Arkuszach i Prezentacjach.
- Opcja Google Meet sidePanelUri i addOnOrigins.
- (tylko HTTP) Dwa HttpOptions do wysyłania nagłówka autoryzacji i obsługi szczegółowej zgody.
Pole oauthScopes określa zakresy autoryzacji projektu.
(Tylko Apps Script) Tag urlFetchWhitelist zapewnia, że pobrane punkty końcowe pasują do określonych prefiksów adresów URL HTTPS. Zobacz Listę adresów URL, które mogą używać protokołu HTTP.

Linki w przykładach przekierowują do opisów pól w dokumentacji manifestu dodatków do Google Workspace utworzonych w Apps Script i HTTP.

Manifesty zawierają inne komponenty. Pola w sekcji addOns są bezpośrednio związane z dodatkami do Google Workspace. Ten przykład przedstawia tylko część pełnego pliku manifestu i nie działa samodzielnie.

Google 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"
  ]
}

Adresy URL na liście dozwolonych

Listy dozwolonych służą do wyznaczania konkretnych adresów URL, które są wstępnie zatwierdzone do dostępu przez skrypt lub dodatek. Listy dozwolonych pomagają chronić dane użytkowników. Gdy zdefiniujesz listę dozwolonych, projekty skryptów nie będą mieć dostępu do adresów URL, które nie zostały dodane do tej listy.

To pole jest opcjonalne podczas instalowania wdrożenia testowego, ale jest wymagane podczas tworzenia wdrożenia z określoną wersją.

Listy dozwolonych są używane, gdy skrypt lub dodatek wykonuje te działania:

Pobiera informacje z zewnętrznej lokalizacji (np. punktów końcowych HTTPS) za pomocą usługi Apps Script UrlFetch. Aby dodać adresy URL do listy dozwolonych na potrzeby pobierania, dodaj do pliku manifestu pole urlFetchWhitelist.
Otwiera lub wyświetla adres URL w odpowiedzi na działanie użytkownika (wymagane w przypadku dodatków do Google Workspace, które otwierają lub wyświetlają adresy URL zewnętrzne w stosunku do Google). Aby dodać adresy URL do listy dozwolonych, w pliku manifestu umieść pole addOns.common.openLinkUrlPrefixes.

Dodawanie prefiksów do listy dozwolonych

Gdy określasz listy dozwolonych w pliku manifestu (uwzględniając pole addOns.common.openLinkUrlPrefixes lub urlFetchWhitelist), musisz podać listę prefiksów adresów URL. Prefiksy dodane do pliku manifestu muszą spełniać te wymagania:

Każdy prefiks musi być prawidłowym adresem URL.
Każdy prefiks musi używać znaku https://, a nie http://.
Każdy prefiks musi zawierać pełną domenę.
Każdy prefiks musi mieć niepustą ścieżkę. Na przykład wartość https://www.google.com/ jest prawidłowa, ale https://www.google.com już nie.
Możesz używać symboli wieloznacznych, aby dopasowywać prefiksy subdomen adresów URL.
W polu addOns.common.openLinkUrlPrefixes można użyć pojedynczego symbolu wieloznacznego *, aby dopasować wszystkie linki, ale nie jest to zalecane, ponieważ może narazić dane użytkownika na ryzyko i wydłużyć proces weryfikacji dodatku. Symbolu wieloznacznego używaj tylko wtedy, gdy jest to wymagane przez funkcję dodatku.

Podczas sprawdzania, czy adres URL pasuje do prefiksu na liście dozwolonych, obowiązują te reguły:

W dopasowywaniu ścieżek rozróżniana jest wielkość liter.
Jeśli prefiks jest identyczny z adresem URL, następuje dopasowanie.
Jeśli adres URL jest taki sam jak prefiks lub jest jego elementem podrzędnym, następuje dopasowanie.

Na przykład prefiks https://example.com/foo pasuje do tych adresów URL:

https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar

Korzystanie z symboli wieloznacznych

Aby dopasować subdomenę w polach urlFetchWhitelist i addOns.common.openLinkUrlPrefixes, możesz użyć pojedynczego symbolu wieloznacznego (*). Nie możesz używać więcej niż jednego symbolu wieloznacznego do dopasowywania wielu subdomen, a symbol wieloznaczny musi reprezentować początkowy prefiks adresu URL.

Na przykład prefiks https://*.example.com/foo pasuje do tych adresów URL:

https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo

Prefiks https://*.example.com/foo nie pasuje do tych adresów URL:

https://subdomain.example.com/bar (niezgodność sufiksu)
https://example.com/foo (musi być co najmniej 1 subdomena)

Niektóre reguły dotyczące prefiksów są egzekwowane podczas próby zapisania pliku manifestu. Na przykład te prefiksy powodują błąd, jeśli znajdują się w pliku manifestu podczas próby zapisania:

https://*.*.example.com/foo (wiele symboli wieloznacznych jest niedozwolonych)
https://subdomain.*.example.com/foo(symbole wieloznaczne muszą być używane jako prefiks)