Dodatki używają pliku manifestu do konfigurowania pewnych szczegółów dotyczących aplikacji i jej działania.
Ta dokumentacja zawiera szczegółowe informacje na temat konfigurowania pliku manifestu dla Dodatek do Google Workspace.
Struktura pliku manifestu dla dodatków do Google Workspace
Dodatki do Google Workspace używają pliku manifestu do określania kilku aspektów jej wyglądu i działania.
Właściwości pliku manifestu to:
w sekcji addOns struktury obiektów manifestu.
- Informacje o plikach manifestu Apps Script znajdziesz w sekcji Struktura pliku manifestu.
- Informacje na temat plików manifestu dotyczących dodatków utworzonych przy użyciu
Punkty końcowe HTTP znajdziesz w zasobie REST:
projects.deployments.
Przykładowa konfiguracja pliku manifestu dodatku do Google Workspace
Poniższy przykład pliku manifestu pokazuje sekcję pliku manifestu, która definiuje dodatek Google Workspace, w tym:
- Sekcja
addOns.commonpliku manifestu definiuje nazwę, adres URL logo, kolory i inne ogólne ustawienia niezależne od hosta. - Plik manifestu określa wspólną stronę główną, a także Kalendarz, Dysk, Dokumenty Arkusze i strony główne specyficzne dla Prezentacji. Gmail używa domyślnej strony głównej.
- Przykładowe ustawienia pliku manifestu umożliwiają:
eventOpenieventUpdated.- (dotyczy tylko Apps Script) 2 rozwiązania do prowadzenia konferencji w Kalendarzu.
- 2 działania uniwersalne.
- Dysk
onItemsSelectedTrigger. - Akcja tworzenia wiadomości w Gmailu i jej kontekstowy wyzwalacz.
- Obiekt
linkPreviewTriggersDokumentów. Aby dowiedzieć się więcej o tym aktywatorze, zobacz Podgląd linków z elementami inteligentnymi. - Obiekt
createActionTriggersDokumentów. Aby dowiedzieć się więcej o tym aktywatorze, Więcej informacji znajdziesz w sekcji Tworzenie zasobów zewnętrznych za pomocą menu @. - Interfejsy API Dokumentów, Arkuszy, i Prezentacje.
- Pole
oauthScopesokreśla zakresy autoryzacji dla projektu (zwykle wymagane w przypadku dodatków). - (Tylko Apps Script)
urlFetchWhitelistpole to pole, które gwarantuje, że wszystkie pobrane punkty końcowe odpowiadają określonemu listę prefiksów adresów URL HTTPS. Więcej informacji: Lista dozwolonych adresów URL.
Linki w tym pliku kierują do opisów tego pola w odpowiedniej dokumentacji referencyjnej pliku manifestu dla Apps Script i HTTP Dodatków Google Workspace.
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"
}
}
},
"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" ] }
Adresy URL na liście dozwolonych
Za pomocą list dozwolonych możesz wyznaczać określone adresy URL, które są wstępnie zatwierdzone do dostępu za pomocą skryptu lub dodatku. Listy dozwolonych pomagają chronić użytkowników data; jeśli zdefiniujesz listę dozwolonych, projekty skryptów nie będą miały dostępu do adresów URL zawierających nie dodano do listy dozwolonych.
To pole jest opcjonalne podczas instalowania wdrożenia testowego, ale jest wymagane, gdy utworzysz wdrożenie z wersją.
Używasz list dozwolonych, gdy skrypt lub dodatek wykonuje te czynności:
- Pobiera lub pobiera informacje z zewnętrznego źródła (np. punktów końcowych HTTPS) za pomocą usługi Apps Script
UrlFetch. Aby dodać adresy URL do listy dozwolonych pobierania, umieść w pliku manifestu poleurlFetchWhitelist. - Otwiera lub wyświetla adres URL w odpowiedzi na działanie użytkownika (wymagane w przypadku
Dodatki do Google Workspace, które otwierają lub wyświetlają adresy URL spoza domeny
Google). Aby dodać adresy URL do listy dozwolonych, dodaj pole
addOns.common.openLinkUrlPrefixesdo pliku manifestu.
Dodawanie prefiksów do listy dozwolonych
Jeśli w pliku manifestu podasz listy dozwolonych adresów (za pomocą pola addOns.common.openLinkUrlPrefixes lub urlFetchWhitelist), musisz uwzględnić 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ć
https://, a niehttp://. - Każdy prefiks musi mieć pełną domenę.
- Każdy prefiks nie może mieć pustej ścieżki. Na przykład
https://www.google.com/jest prawidłowy, alehttps://www.google.comjuż nie. - Do prefiksów subdomen adresu URL możesz używać symboli wieloznacznych.
- W polu
addOns.common.openLinkUrlPrefixesmożna użyć pojedynczego symbolu wieloznacznego*, aby dopasować wszystkie linki, ale nie jest to zalecane, ponieważ może to narazić dane użytkownika na ryzyko i wydłużyć proces sprawdzania dodatku. Tylko użyj symbolu wieloznacznego, jeśli jest to wymagane przez Twój dodatek.
Podczas określania, czy adres URL pasuje do prefiksu na liście dozwolonych, obowiązują te reguły:
- W dopasowaniu ścieżki wielkość liter ma znaczenie.
- Jeśli prefiks jest identyczny z adresem URL, dopasowanie jest uznawane za prawidłowe.
- Jeśli adres URL jest taki sam lub jest podrzędnym adresem URL z prefiksem, dopasowanie jest uznawane za poprawne.
Na przykład prefiks https://example.com/foo pasuje do tych adresów URL:
https://example.com/foohttps://example.com/foo/https://example.com/foo/barhttps://example.com/foo?barhttps://example.com/foo#bar
Korzystanie z symboli wieloznacznych
Za pomocą jednego symbolu wieloznacznego (*) możesz dopasować subdomenę w przypadku
urlFetchWhitelist
i addOns.common.openLinkUrlPrefixes
. Nie możesz użyć więcej niż jednego symbolu wieloznacznego, aby dopasować wiele subdomen.
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/foohttps://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 prefiksu są wymuszane podczas zapisywania pliku manifestu. Dla: następujące prefiksy powodują błąd, jeśli występują w pliku manifestu przy próbie zapisania pliku:
https://*.*.example.com/foo(wielokrotne symbole zastępcze są niedozwolone)https://subdomain.*.example.com/foo(symbole wieloznaczne muszą być używane jako wiodący prefiks)