Projekt Apps Script używa pliku manifestu do konfigurowania określonych szczegółów skryptu i jego działania. Aby dowiedzieć się, jak wyświetlić i edytować plik manifestu, przeczytaj artykuł Pliki manifestu.
Ta dokumentacja zawiera szczegółowe informacje o konfigurowaniu pliku manifestu dla dodatku do Google Workspace.
Struktura pliku manifestu dodatków do Google Workspace
Dodatki do Google Workspace korzystają z pliku manifestu projektu Apps Script do określania kilku aspektów wyglądu i działania dodatku. Właściwości pliku manifestu dodatków do Google Workspace są uporządkowane w sekcji addOns
struktury obiektu manifestu.
Przykładowa konfiguracja pliku manifestu dodatku do Google Workspace
Poniższy przykładowy plik manifestu pokazuje sekcję pliku manifestu, która określa dodatki do Google Workspace, w tym te aspekty:
- Sekcja
addOns.common
pliku manifestu zawiera nazwę, adres URL logo, kolory i inne ogólne ustawienia dodatku niezależne od hosta. - Plik manifestu określa wspólną stronę główną, ale także strony główne związane z Kalendarzem, Dyskiem, Dokumentami, Arkuszami i Prezentacjami. Gmail używa domyślnej strony głównej.
- Przykładowe ustawienia pliku manifestu umożliwiają:
- Wyzwalacze
eventOpen
ieventUpdated
Kalendarza oraz 2 rozwiązania do obsługi konferencji Kalendarza. - Dwa uniwersalne działania.
- Dysk
onItemsSelectedTrigger
. - Działanie tworzenia wiadomości w Gmailu i reguła kontekstowa.
- Plik Dokumentów
linkPreviewTrigger
. Więcej informacji o tej regule znajdziesz w artykule Wyświetlanie podglądu linków za pomocą elementów inteligentnych. - interfejsach plików Dokumentów, Arkuszy i Prezentacji.
- Wyzwalacze
- Pole
oauthScopes
określa zakresy autoryzacji projektu (zwykle wymagane w przypadku dodatków). - Pole
urlFetchWhitelist
jest polem, które dba o to, aby wszystkie pobrane punkty końcowe pasują do określonej listy prefiksów adresów URL HTTPS. Więcej informacji znajdziesz w artykule Umieszczanie adresów URL na liście dozwolonych.
Linki w przykładzie prowadzą do opisów tego pola w dokumentacji referencyjnej pliku manifestu.
{ "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://en.wikipedia.org/wiki/", "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" } ] }, "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/" ] }
Adresy URL listy dozwolonych
Listy dozwolonych pozwalają wyznaczać konkretne adresy URL, do których skrypt lub dodatek ma dostęp wstępnie zatwierdzony. Listy dozwolonych pomagają chronić dane użytkowników. Gdy zdefiniujesz listę dozwolonych, projekty skryptów nie będą miały dostępu do adresów URL spoza tej listy.
To pole jest opcjonalne w przypadku instalowania wdrożenia testowego, ale wymagane podczas tworzenia wdrożenia z różnymi wersjami.
Listy dozwolonych są używane, gdy skrypt lub dodatek wykonuje te działania:
- Pobiera lub pobiera informacje z lokalizacji zewnętrznej (np. punktów końcowych HTTPS) za pomocą usługi Apps Script
UrlFetch
. Aby dodać adresy URL do listy dozwolonych na potrzeby pobierania, do pliku manifestu dołącz poleurlFetchWhitelist
. - 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 spoza Google). Aby dodać adresy URL do listy dozwolonych, umieść w pliku manifestu pole
addOns.common.openLinkUrlPrefixes
.
Dodawanie prefiksów do listy dozwolonych
Gdy określisz listy dozwolonych w pliku manifestu (dołączając pole addOns.common.openLinkUrlPrefixes
lub urlFetchWhitelist
), musisz podać listę prefiksów adresów URL. Prefiksy, które dodajesz do pliku manifestu, muszą spełniać te wymagania:
- Każdy prefiks musi być prawidłowym adresem URL.
- Każdy prefiks musi używać
https://
, a niehttp://
. - Każdy prefiks musi zawierać pełną domenę.
- Każdy prefiks musi mieć ścieżkę, która nie jest pusta. Na przykład wartość
https://www.google.com/
jest prawidłowa, alehttps://www.google.com
już nie. - Do dopasowywania prefiksów subdomen adresów URL możesz używać symboli wieloznacznych.
- 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 sprawdzania dodatków. Symbolu wieloznacznego używaj tylko wtedy, gdy wymaga tego funkcja dodatku.
Podczas określania, czy adres URL pasuje do prefiksu z listy dozwolonych, obowiązują te reguły:
- W dopasowywaniu ścieżki wielkość liter ma znaczenie.
- Jeśli prefiks jest taki sam jak adres URL, zostaje dopasowany.
- Jeśli adres URL jest taki sam lub podrzędny wobec danego prefiksu, zostaje dopasowany.
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
Możesz użyć pojedynczego symbolu wieloznacznego (*
), aby dopasować subdomenę w polach urlFetchWhitelist
i addOns.common.openLinkUrlPrefixes
. Nie możesz użyć więcej niż 1 symbolu wieloznacznygo, aby dopasować wiele subdomen. Symbol wieloznaczny musi przedstawiać wiodący 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 istnieć co najmniej jedna subdomena)
Podczas zapisywania pliku manifestu wymuszane są niektóre z reguł prefiksu. Na przykład te prefiksy mogą powodować błąd, jeśli znajdują się one w pliku manifestu podczas próby zapisania:
https://*.*.example.com/foo
(nie można użyć wielu symboli wieloznacznych)https://subdomain.*.example.com/foo
(Symbole wieloznaczne muszą być używane jako początkowy prefiks)