Pliki manifestu dodatków do Google Workspace

Dodatek używa pliku manifestu do skonfigurowania określonych szczegółów aplikacji i jej działania.

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

Struktura pliku manifestu dla dodatków do Google Workspace

Dodatki do Google Workspace używają pliku manifestu do określenia kilku aspektów wyglądu i działania dodatku.

Właściwości dodatku do Google Workspace w pliku manifestu znajdują się w sekcji addOns struktury obiektów manifestu.

• Informacje o plikach manifestu Apps Script znajdziesz w artykule Struktura pliku manifestu.
• Informacje o plikach manifestu dodatków utworzonych z użyciem punktów końcowych HTTP znajdziesz w zasobie REST: projects.deployments .

Przykładowa konfiguracja pliku manifestu dodatku do Google Workspace

Poniższy przykładowy plik manifestu przedstawia sekcję pliku manifestu, który definiuje dodatki do 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 dla dodatku.
• Plik manifestu definiuje wspólną stronę główną oraz strony główne Kalendarza, Dysku, Dokumentów, Arkuszy i Prezentacji. Gmail używa domyślnej strony głównej.
• Przykładowe ustawienia pliku manifestu umożliwiają:
  • Wyzwalacze kalendarza eventOpen i eventUpdated.
  • (Tylko Apps Script) Dwa rozwiązania do obsługi konferencji Kalendarza.
  • Dwa uniwersalne działania.
  • Dysk onItemsSelectedTrigger.
  • Działanie tworzenia wiadomości w Gmailu i reguła kontekstowa.
  • Obiekt linkPreviewTriggersDokumentów. Więcej informacji o tym aktywatorze znajdziesz w artykule Podgląd linków z elementami inteligentnymi.
  • Obiekt createActionTriggers Dokumentów. Więcej informacji o tym aktywatorze znajdziesz w artykule Tworzenie zasobów innych firm za pomocą menu @.
  • Interfejsy do obsługi plików Dokumentów, Arkuszy i Prezentacji.
• Pole oauthScopes określa zakresy autoryzacji dla projektu (zwykle wymagane w przypadku dodatków).
• (Tylko Apps Script) Pole urlFetchWhitelist to pole, które sprawdza, czy wszystkie pobrane punkty końcowe pasują do określonej listy prefiksów adresów URL HTTPS. Więcej informacji znajdziesz w artykule o dodawaniu adresów URL do listy dozwolonych.

Linki w przykładzie prowadzą do opisów tych pól w odpowiedniej dokumentacji referencyjnej dotyczącej manifestu Apps Script i dodatków HTTP do Google Workspace.

Uwaga: pliki manifestu zawierają inne komponenty. Pola pod polem addOns odnoszą się bezpośrednio do dodatków do Google Workspace. Ten przykład to tylko część pełnego pliku manifestu, a nie w pełni funkcjonalny plik manifestu.

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

Za pomocą list dozwolonych możesz wskazać określone adresy URL, które są wstępnie zatwierdzone przez skrypt lub dodatek. 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, które nie znajdują się na tej liście.

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

Z list dozwolonych możesz korzystać, gdy skrypt lub dodatek wykonuje te działania:

• 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 pobierania, umieść w pliku manifestu 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, które można otwierać, umieść w pliku manifestu pole addOns.common.openLinkUrlPrefixes.

Uwaga: biała lista (używana w urlFetchWhitelist) to wycofana termin, która jest synonimem i zastąpiona listą dozwolonych. Więcej informacji znajdziesz w artykule Pisanie dokumentacji promującej integrację społeczną.

Dodawanie prefiksów do listy dozwolonych

Gdy określasz listy dozwolonych w pliku manifestu (za pomocą pola addOns.common.openLinkUrlPrefixes lub urlFetchWhitelist), musisz uwzględnić 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.
• W każdym prefiksie musi znajdować się https://, a nie http://.
• Każdy prefiks musi zawierać 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 już nie.
• Do prefiksów subdomen adresu URL możesz używać symboli wieloznacznych.
• W polu addOns.common.openLinkUrlPrefixes można użyć jednego 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 jest to wymagane przez Twój dodatek.

Podczas określania, czy adres URL pasuje do prefiksu na liście dozwolonych, obowiązują te reguły:

• W dopasowywaniu ścieżki wielkość liter ma znaczenie.
• Jeśli prefiks jest identyczny z adresem URL, zostaje dopasowany.
• Jeśli URL jest taki sam lub podrzędny względem 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

Za pomocą jednego symbolu wieloznacznego (*) możesz dopasować subdomenę w polach urlFetchWhitelist i addOns.common.openLinkUrlPrefixes. Nie można użyć więcej niż jednego symbolu wieloznacznego, aby dopasować wiele subdomen, i musi on odzwierciedlać początkowy 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)

Niektóre reguły prefiksu są wymuszane podczas zapisywania pliku manifestu. Na przykład te prefiksy powodują błąd, jeśli występują w manifeście podczas próby zapisania:

• https://*.*.example.com/foo (nie można używać wielu symboli wieloznacznych)
• https://subdomain.*.example.com/foo (symbol wieloznaczny musi być na początku prefiksu)