Pliki manifestu dodatków do Google Workspace

Projekt Apps Script korzysta z pliku pliku manifestu, aby skonfigurować określone szczegóły dotyczące skryptu i jego operacji. Aby dowiedzieć się, jak wyświetlić i edytować plik manifestu, przeczytaj artykuł Manifesty.

Ta dokumentacja zawiera szczegóły na temat konfigurowania pliku manifestu dodatku do Google Workspace.

Struktura pliku manifestu dodatków do Google Workspace

Dodatki do Google Workspace wykorzystują plik manifestu projektu Apps Script, aby definiować kilka 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 obiektów manifestu.

Przykładowa konfiguracja pliku manifestu dodatku Google Workspace

Poniżej znajdziesz przykładowy plik manifestu, w którym definiuje się dodatek Google Workspace, uwzględniając te aspekty:

  • Sekcja addOns.common pliku manifestu określa nazwę, adres URL logo, kolory i inne ogólne ustawienia niezależne od hosta dotyczące dodatku.
  • Plik manifestu określa wspólną stronę główną, ale zawiera też strony główne Kalendarza, Dysku, Dokumentów, Arkuszy i Prezentacji. Gmail używa domyślnej strony głównej.
  • Przykładowe ustawienia w pliku manifestu to:
    • aktywatory Kalendarza eventOpen i eventUpdated oraz 2 rozwiązania do prowadzenia wideokonferencji w Kalendarzu.
    • Dwa uniwersalne działania.
    • Dysk onItemsSelectedTrigger.
    • utworzenie działania w Gmailu i aktywatora kontekstowego,
    • interfejsy plików Dokumentów, Arkuszy i Prezentacji;
  • Pole oauthScopes ustawia zakresy autoryzacji projektu (zwykle wymagane w przypadku dodatków).
  • Pole urlFetchWhitelist to opcjonalne pole, które zapewnia, że wszystkie pobrane punkty końcowe odpowiadają określonej liście prefiksów adresów URL HTTPS. Więcej informacji znajdziesz w sekcji Lista dozwolonych adresów URL.

Linki w przykładzie kierują do opisów tych pól w dokumentacji pliku manifestu.

// Sample configuration of the addOns section in a manifest file:
{
  "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"
      }
    },

    "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"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ],
}

Lista dozwolonych adresów URL

Listy dozwolonych pozwalają wskazywać konkretne adresy URL, które są wstępnie zatwierdzone do użycia przez skrypt lub dodatek. Listy dozwolonych pomagają chronić dane użytkowników. Gdy zdefiniujesz listę dozwolonych, projekty skryptu nie będą miały dostępu do adresów URL, które nie znajdują się na liście dozwolonych.

Listy dozwolonych można użyć, gdy skrypt lub dodatek wykonuje te czynności:

  • Pobiera lub pobiera informacje z lokalizacji zewnętrznej (np. punktów końcowych HTTPS) przy użyciu usługi Apps Script UrlFetch. Aby pobrać adresy URL z listy dozwolonych, w pliku manifestu umieść 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 lista adresów URL otwierała się na liście dozwolonych, umieść w pliku manifestu pole addOns.common.openLinkUrlPrefixes.

Dodawanie prefiksów do listy dozwolonych

Określając listy dozwolonych w pliku manifestu (poprzez dodanie pola addOns.common.openLinkUrlPrefixes lub urlFetchWhitelist), musisz uwzględnić 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 zawierać https://, a nie http://.
  • 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, ale https://www.google.com nie.
  • Możesz użyć symboli wieloznacznych, aby dopasować prefiksy subdomen adresu URL.
  • W polu addOns.common.openLinkUrlPrefixes można użyć pojedynczego symbolu wieloznacznego * w celu dopasowania do wszystkich linków, ale nie jest to zalecane, ponieważ może narazić dane użytkownika na ryzyko oraz może wydłużyć proces dodawania dodatku. Symboli wieloznacznych 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 dopasowaniu ścieżki rozróżniana jest wielkość liter.
  • Jeśli prefiks jest identyczny z adresem URL, pasuje do niego.
  • Jeśli adres URL jest taki sam lub jest elementem podrzędnym prefiksu, jest zgodny.

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ć jednego znaku wieloznacznego (*), aby dopasować subdomenę w polach urlFetchWhitelist i addOns.common.openLinkUrlPrefixes. Nie można użyć więcej niż jednego symbolu wieloznacznego, aby dopasować wiele subdomen. Symbol wieloznaczny musi odpowiadać głównemu adresowi URL.

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

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

Prefiks https://*.example.com/foo nie jest zgodny z tymi adresami URL:

  • https://subdomain.example.com/bar (niezgodność sufiksu)
  • https://example.com/foo (przynajmniej jedna subdomena musi być obecna)

Niektóre reguły prefiksu są wymuszane podczas próby zapisania pliku manifestu. Jeśli na przykład w pliku manifestu występują błędy, oznacza to, że:

  • https://*.*.example.com/foo (wiele symboli wieloznacznych jest zabronione)
  • https://subdomain.*.example.com/foo (Symbole wieloznaczne muszą być na początku)