Pliki manifestu dodatków do Google Workspace

Dodatek używa pliku manifestu do konfigurowania niektórych szczegółów dotyczących aplikacji i jej działania.

W tym dokumencie znajdziesz szczegółowe informacje o konfigurowaniu pliku manifestu dodatku do Google Workspace.

Struktura pliku 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 dodatku.

Właściwości manifestu dodatków do Google Workspace są uporządkowane w sekcji addOns struktury obiektu manifestu.

• Więcej informacji o plikach manifestu Apps Script znajdziesz w artykule Struktura manifestu.

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

Pliki manifestu Google Chat

Jeśli dodatek do Google Workspace rozszerza Google Chat, musisz skonfigurować aplikację Google Chat, włączając i konfigurując interfejs Google Chat API w konsoli Google Cloud.

W Chat ignorowane są typowe ustawienia konfiguracji pliku manifestu (w tym addons.common). Zamiast manifestu dodatku używasz interfejsu Chat API do konfigurowania tych ustawień Chatu:

• Nazwa, logo i opis aplikacji Google Chat, które są widoczne tylko w interfejsie Google Chat.
• wyzwalacze aplikacji do obsługi czatu.

Jeśli dodatek został utworzony w Apps Script, musisz też dodać lub zaktualizować te obiekty w pliku manifestu:

• addons.chat (wymagane)
• oauthScopes (wymagane, jeśli aplikacja Google Chat korzysta z zakresów OAuth)

Instrukcje konfigurowania ustawień Google Chat dla dodatku znajdziesz w artykule Konfigurowanie aplikacji Google Chat.

Przykładowa konfiguracja pliku manifestu dodatku do Google Workspace

Poniższe przykłady manifestu pokazują sekcję pliku manifestu, która definiuje dodatek do Google Workspace, w tym te aspekty:

• Sekcja addOns.common w manifeście określa 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 dla Kalendarza, Dysku, Dokumentów, Arkuszy i Prezentacji. Gmail używa domyślnej strony głównej.

• Przykładowe ustawienia pliku manifestu umożliwiają:

  • wyzwalacze Kalendarz eventOpen i eventUpdated;

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

  • 2 działania uniwersalne.

  • A Dysk onItemsSelectedTrigger.

  • działanie tworzenia wiadomości w Gmailu i wyzwalacz kontekstowy;

  • Obiekt linkPreviewTriggers Dokumentów Google. Więcej informacji o tym wyzwalaczu znajdziesz w artykule Wyświetlanie podglądu linków za pomocą elementów inteligentnych.

  • Obiekt createActionTriggers w Dokumentach Google. Więcej informacji o tym wyzwalaczu znajdziesz w artykule Tworzenie zasobów innych firm za pomocą menu @.

  • Interfejsy specyficzne dla plików w Dokumentach, Arkuszach i Prezentacjach.

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

• Pole oauthScopes określa zakresy autoryzacji projektu (zwykle wymagane w przypadku dodatków).

• (Tylko Apps Script) Pole urlFetchWhitelist zapewnia, że 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ładowych plikach manifestu przekierowują do opisów danego pola w odpowiedniej dokumentacji referencyjnej pliku manifestu dla dodatków do Apps Script i HTTP w Google Workspace.

Uwaga: pliki manifestu zawierają inne komponenty. Pola w sekcji addOns są bezpośrednio powiązane z dodatkami do Google Workspace. Ten przykład to tylko fragment pełnego pliku manifestu, który nie jest w pełni funkcjonalny.

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

Adresy URL na liście dozwolonych

Listy dozwolonych służą do wyznaczania konkretnych 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ą mieć 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 wersją.

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

• Pobiera informacje z zewnętrznej lokalizacji (np. punktów końcowych HTTPS) za pomocą 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 zewnętrzne w stosunku do Google). Aby dodać adresy URL do listy dozwolonych w celu otwierania, uwzględnij w pliku manifestu pole addOns.common.openLinkUrlPrefixes.

Uwaga: termin biała lista używany w urlFetchWhitelist jest przestarzały i został zastąpiony terminem lista dozwolonych. Więcej informacji znajdziesz w artykule Tworzenie dokumentacji z myślą o różnorodności.

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 dodane do pliku manifestu muszą spełniać te wymagania:

• Każdy prefiks musi być prawidłowym adresem URL.
• Każdy prefiks musi używać znaku https://, a nie http://.
• Każdy prefiks musi zawierać pełną domenę.
• Każdy prefiks musi mieć niepustą ścieżkę. Na przykład klucz 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ż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 weryfikacji dodatku. Symbolu wieloznacznego używaj tylko wtedy, gdy jest to wymagane przez funkcje 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, następuje dopasowanie.
• Jeśli adres URL jest taki sam jak prefiks lub jest jego elementem podrzędnym, następuje 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

Aby dopasować subdomenę w polach urlFetchWhitelist i addOns.common.openLinkUrlPrefixes, możesz użyć pojedynczego symbolu wieloznacznego (*). Nie możesz używać więcej niż jednego symbolu wieloznacznego do dopasowywania wielu 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ć co najmniej 1 subdomena)

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

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