Pliki manifestu dodatków do Google Workspace

Projekt Apps Script używa pliku manifestu do skonfigurowania niektórych szczegółów skryptu i jego operacji. Aby dowiedzieć się, jak wyświetlić i edytować plik manifestu, przeczytaj artykuł Manifesty.

Ta dokumentacja zawiera szczegółowe informacje o konfigurowaniu 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 określić 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 pliku manifestu.

Przykładowa konfiguracja pliku manifestu dodatku do Google Workspace

Poniższy przykład pliku manifestu zawiera sekcję pliku manifestu, która określa dodatek do Google Workspace, w tym:

  • Sekcja addOns.common pliku manifestu określa nazwę, adres URL logo, kolory i inne ogólne ustawienia niezależne od hosta.
  • Plik manifestu definiuje wspólną stronę główną, a także stronę główną Kalendarza, Dysku, Dokumentów, Arkuszy i Prezentacji. Gmail używa domyślnej strony głównej.
  • Przykładowe ustawienia w pliku manifestu umożliwiają:
    • Kalendarz eventOpen i eventUpdated – aktywatory oraz 2 rozwiązania konferencyjne Kalendarza.
    • 2 działania uniwersalne.
    • Dysk onItemsSelectedTrigger.
    • Utworzenie działania i reguły kontekstowego Gmaila.
    • Interfejsy API dla plików Dokumentów, Arkuszy i Prezentacji.
  • Pole oauthScopes ustawia zakresy autoryzacji projektu (zwykle wymagane w przypadku dodatków).
  • Pole urlFetchWhitelist ustawia prefiks adresu URL HTTPS, który zapewnia, że wszystkie pobrane punkty końcowe są zgodne z prefiksem (zwykle wymagany w przypadku dodatków). 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 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

Czasami chcesz, aby skrypt lub dodatek otwierał adres URL w odpowiedzi na działanie użytkownika. W innych przypadkach może być konieczne, aby skrypt lub dodatek pobierał informacje z lokalizacji zewnętrznej przy użyciu usługi Apps Script UrlFetch. W obu przypadkach musisz dodać do listy dozwolonych adresy URL, które otwierasz lub pobierasz z pliku manifestu projektu.

Lista dozwolonych to proces, który wskazuje określone adresy URL, które są wstępnie zatwierdzone do użycia przez skrypt lub dodatek. Ten wymaganie pomaga chronić dane użytkowników. Jeśli zdefiniujesz listę dozwolonych, projekty skryptów nie będą miały dostępu do adresów URL, które nie znajdują się na liście dozwolonych. Google Workspace Dodatki wymagają dodania adresów URL do listy dozwolonych, aby można je było pobrać lub otworzyć.

Możesz zezwolić na pobieranie adresu URL, dodając go lub pasujący prefiks do pola pliku urlFetchWhitelist. W przypadku dodatków Google Workspace możesz dodawać adresy URL do listy dozwolonych osób, dodając go lub pasujący do niego prefiks w polu addOns.common.openLinkUrlPrefixes pliku manifestu.

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ć ciąg https://, a nie http://.
  • Każdy prefiks musi zawierać pełną domenę.
  • Każdy prefiks nie może być pusty. Na przykład reguła https://www.google.com/ jest prawidłowa, ale https://www.google.com nie.
  • Aby dopasować prefiksy subdomen adresu URL, możesz użyć 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 to narazić dane użytkownika na ryzyko i może wydłużyć proces dodatku. symbolu wieloznacznego używaj tylko wtedy, gdy wymaga tego funkcja dodatku.

Podczas określania, czy adres URL pasuje do prefiksu listy dozwolonych, obowiązują następujące reguły:

  • W dopasowaniu ścieżki rozróżniana jest wielkość liter.
  • Jeśli prefiks jest taki sam jak adres URL, jest to dopasowanie.
  • Jeśli adres URL jest taki sam lub jest prefiksem, 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 symbolu wieloznacznego (*), aby dopasować subdomenę do pól urlFetchWhitelist i addOns.common.openLinkUrlPrefixes. Do dopasowania wielu subdomen nie można używać więcej niż jednego symbolu wieloznacznego. Symbol wieloznaczny musi reprezentować prefiks domeny.

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ść przyrostka)
  • https://example.com/foo (musi istnieć co najmniej jedna subdomena)

Niektóre reguły prefiksu są wymuszane podczas próby zapisania pliku manifestu. Na przykład te prefiksy mogą powodować błędy, jeśli w pliku manifestu znajdują się błędy:

  • https://*.*.example.com/foo (zakaz używania wielu symboli wieloznacznych)
  • https://subdomain.*.example.com/foo (wilgotniki muszą być używane jako prefiks)