Ta strona została przetłumaczona przez Cloud Translation API.

Pliki manifestu dodatków do Google Workspace

Projekt Apps Script używa pliku manifest do konfigurowania określonych informacji o skrypcie i jego działaniu. Aby dowiedzieć się, jak wyświetlić i edytować plik manifestu, przeczytaj artykuł o plikach manifestu.

Ta dokumentacja zawiera szczegółowe informacje na temat konfigurowania pliku manifestu dla dodatku 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 definiuje dodatki do Google Workspace, w tym następujące 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ą, a także strony główne Kalendarza, Dysku, Dokumentów, Arkuszy i Prezentacji. Gmail używa domyślnej strony głównej.
Przykładowe ustawienia pliku manifestu pozwalają na:
- Aktywatory eventOpen i eventUpdated 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.
- Dokumenty linkPreviewTrigger. Więcej informacji o tej regule znajdziesz w artykule Wyświetlanie podglądu linków za pomocą elementów inteligentnych.
- interfejsy plików Dokumentów, Arkuszy i Prezentacji;
Pole oauthScopes określa zakresy autoryzacji w projekcie (zwykle wymagane w przypadku dodatków).
Pole urlFetchWhitelist jest polem, które zapewnia, że wszystkie pobrane punkty końcowe pasują do określonej listy prefiksów adresów URL HTTPS. To pole jest opcjonalne w przypadku wdrożeń testowych, ale jest wymagane na potrzeby wdrożeń. Więcej informacji znajdziesz w artykule Umieszczanie adresów URL na liście dozwolonych.

Linki w przykładzie kierują do opisów tego pola w dokumentacji referencyjnej 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"
      },
      "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 służą do oznaczania adresów URL wstępnie zatwierdzonych do dostępu przez skrypt lub dodatek. Listy dozwolonych pomagają chronić dane użytkownika. Gdy zdefiniujesz listę dozwolonych, projekty skryptu nie mają dostępu do adresów URL, które nie zostały dodane do tej listy.

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

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

Dodawanie prefiksów do listy dozwolonych

Określając listy dozwolonych w pliku manifestu (dołączając pole 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 używać https://, a nie http://.
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, ale https://www.google.com już nie.
Aby dopasować prefiksy 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. Używaj symbolu wieloznacznego 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 rozróżniana jest wielkość liter.
Jeśli prefiks jest taki sam jak adres URL, oznacza to, że się zgadza.
Jeśli adres URL jest taki sam jak adres podrzędny prefiksu lub jego element podrzędny jest dopasowaniem.

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żna dopasować więcej niż jednego symbolu wieloznacznego, aby dopasować wiele subdomen, a 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 (wymagana jest co najmniej jedna subdomena)

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

https://*.*.example.com/foo (nie można używać wielu symboli wieloznacznych)
https://subdomain.*.example.com/foo (Symbole wieloznaczne muszą być używane jako prefiks wiodący)