Pliki manifestu dodatków do Google Workspace

Projekt Apps Script używa pliku manifestu do konfigurowania określonych szczegółów skryptu i jego działania. Aby dowiedzieć się, jak wyświetlić i edytować plik manifestu, przeczytaj artykuł Pliki manifestu.

Ta dokumentacja zawiera szczegółowe informacje o konfigurowaniu pliku manifestu dla dodatku do 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 określa dodatki do Google Workspace, w tym te 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ą, ale także strony główne związane z Kalendarzem, Dyskiem, Dokumentami, Arkuszami i Prezentacjami. Gmail używa domyślnej strony głównej.
• Przykładowe ustawienia pliku manifestu umożliwiają:
  • Wyzwalacze 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.
  • Plik Dokumentów linkPreviewTrigger. Więcej informacji o tej regule znajdziesz w artykule Wyświetlanie podglądu linków za pomocą elementów inteligentnych.
  • interfejsach plików Dokumentów, Arkuszy i Prezentacji.
• Pole oauthScopes określa zakresy autoryzacji projektu (zwykle wymagane w przypadku dodatków).
• Pole urlFetchWhitelist jest polem, które dba o to, aby wszystkie pobrane punkty końcowe pasują do określonej listy prefiksów adresów URL HTTPS. 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 referencyjnej pliku manifestu.

Uwaga: pliki manifestu zawierają inne komponenty, które odnoszą się do właściwości Apps Script. Pola w polu addOns odnoszą się bezpośrednio do dodatków do Google Workspace. Ten przykład jest tylko częścią pełnego pliku manifestu i nie jest w pełni funkcjonalny.

{
  "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 pozwalają wyznaczać konkretne adresy URL, do których skrypt lub dodatek ma dostęp wstępnie zatwierdzony. Listy dozwolonych pomagają chronić dane użytkowników. Gdy zdefiniujesz listę dozwolonych, projekty skryptów nie będą miały dostępu do adresów URL spoza tej listy.

To pole jest opcjonalne w przypadku instalowania wdrożenia testowego, ale wymagane podczas tworzenia wdrożenia z różnymi wersjami.

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

• Pobiera lub pobiera informacje z lokalizacji zewnętrznej (np. punktów końcowych HTTPS) za pomocą usługi Apps Script UrlFetch. Aby dodać adresy URL do listy dozwolonych na potrzeby pobierania, do pliku manifestu dołącz 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, umieść w pliku manifestu pole addOns.common.openLinkUrlPrefixes.

Uwaga: Biała lista (używana w urlFetchWhitelist) to wycofany termin, który jest synonimem słowa lista dozwolonych i jest zastąpiony przez listę dozwolonych. Więcej informacji znajdziesz w artykule na temat pisania dokumentacji promującej integrację społeczną.

Dodawanie prefiksów do listy dozwolonych

Gdy określisz listy dozwolonych w pliku manifestu (dołączając pole addOns.common.openLinkUrlPrefixes lub urlFetchWhitelist), musisz podać 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.
• Do dopasowywania prefiksów 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. Symbolu wieloznacznego 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 dopasowywaniu ścieżki wielkość liter ma znaczenie.
• Jeśli prefiks jest taki sam jak adres URL, zostaje dopasowany.
• Jeśli adres URL jest taki sam lub podrzędny wobec danego prefiksu, zostaje dopasowany.

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żesz użyć więcej niż 1 symbolu wieloznacznygo, aby dopasować wiele subdomen. 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 (musi istnieć co najmniej jedna subdomena)

Podczas zapisywania pliku manifestu wymuszane są niektóre z reguł prefiksu. Na przykład te prefiksy mogą powodować błąd, jeśli znajdują się one w pliku manifestu podczas próby zapisania:

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