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 tej dokumentacji znajdziesz szczegółowe informacje o konfigurowaniu manifestu dodatku do Google Workspace.

Struktura 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 manifestu dodatków do Google Workspace są uporządkowane w sekcji addOns.

  • Informacje o plikach manifestu Google Apps Script znajdziesz w artykule Struktura manifestu.

  • Informacje o plikach manifestu dodatków utworzonych za pomocą punktów końcowych HTTP znajdziesz w sekcji projects.deployments.

Manifesty Google Chat

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

W Google Chat ignorowane są typowe ustawienia konfiguracji manifestu (w tym addons.common). Aby skonfigurować te ustawienia Google Chat, użyj interfejsu Chat API:

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

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

Przykładowa konfiguracja manifestu dodatku do Google Workspace

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

  • addOns.common określa nazwę, logo, kolory i inne ustawienia ogólne dodatku.

  • Manifest definiuje wspólną stronę główną, ale także strony główne specyficzne dla Kalendarza Google, Dysku Google, Dokumentów Google, Arkuszy Google i Prezentacji Google. Gmail używa domyślnej strony głównej.

  • Przykładowe ustawienia manifestu umożliwiają:

    • wyzwalacze Kalendarza eventOpen i eventUpdated;

    • (tylko Apps Script) 2 rozwiązania do konferencji w Kalendarzu .

    • 2 działania uniwersalne;

    • onItemsSelectedTrigger na Dysku;

    • działanie tworzenia i wyzwalacz kontekstowy w Gmailu;

    • obiekt linkPreviewTriggers w Dokumentach. Zobacz Wyświetlanie podglądu linku za pomocą elementów inteligentnych.

    • obiekt createActionTriggers w Dokumentach. Zobacz Tworzenie zasobów innych firm z menu @.

    • interfejsy specyficzne dla plików w Dokumentach, Arkuszach i Prezentacjach;

    • opcje sidePanelUri i addOnOrigins w Google Meet;

    • (tylko HTTP) 2 HttpOptions do wysyłania nagłówka autoryzacji i obsługi szczegółowej zgody.

  • Pole oauthScopes ustawia zakresy autoryzacji projektu.

  • (tylko Apps Script) urlFetchWhitelist zapewnia, że pobrane punkty końcowe pasują do określonych prefiksów adresów URL HTTPS. Zobacz Dodawanie adresów URL do listy dozwolonych.

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

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

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

Dodawanie adresów URL do listy dozwolonych

Listy dozwolonych służą do określania 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ą mogły uzyskiwać 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 wymagane podczas tworzenia wdrożenia z numerem wersji.

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

  • Pobiera informacje z lokalizacji zewnętrznej (np. z 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 spoza Google). Aby dodać adresy URL do listy dozwolonych na potrzeby otwierania, dodaj do pliku manifestu pole addOns.common.openLinkUrlPrefixes.

Dodawanie prefiksów do listy dozwolonych

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

  • Każdy prefiks musi być prawidłowym adresem URL.
  • Każdy prefiks musi używać protokołu https://, a nie http://.
  • Każdy prefiks musi mieć pełną domenę.
  • Każdy prefiks musi mieć niepustą ścieżkę. Na przykład https://www.google.com/ jest prawidłowy, 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żesz 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 dodatku. Używaj symbolu wieloznacznego tylko wtedy, gdy jest to wymagane przez funkcję dodatku.

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

  • W dopasowaniu ścieżki jest rozróżniana wielkość liter.
  • Jeśli prefiks jest identyczny z adresem URL, jest to dopasowanie.
  • Jeśli adres URL jest taki sam jak prefiks lub jest jego elementem podrzędnym, jest to 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

Używanie 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ż jednego symbolu wieloznacznego, aby dopasować wiele subdomen, a symbol wieloznaczny musi reprezentować 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ć obecna co najmniej 1 subdomena).

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

  • https://*.*.example.com/foo (używanie wielu symboli wieloznacznych jest zabronione);
  • https://subdomain.*.example.com/foo (symbole wieloznaczne muszą być używane jako prefiks).