Pliki manifestu dodatków do Google Workspace

Dodatki używają pliku manifestu do konfigurowania pewnych szczegółów dotyczących aplikacji i jej działania.

Ta dokumentacja zawiera szczegółowe informacje o konfigurowaniu pliku manifestu dla dodatku Google Workspace.

Struktura pliku manifestu dla dodatków do Google Workspace

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

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

Pliki manifestu Google Chat

Jeśli Twój 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 usłudze Chat ignorowane są typowe ustawienia konfiguracji pliku manifestu (w tym addons.common). Zamiast pliku manifestu dodatku możesz użyć interfejsu Chat API do skonfigurowania tych ustawień:

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

Aby dowiedzieć się, jak skonfigurować ustawienia Google Chat dla danego dodatku, zapoznaj się z artykułem Konfigurowanie aplikacji Google Chat.

Przykładowa konfiguracja pliku manifestu dodatku do Google Workspace

Poniższy przykład pliku manifestu pokazuje sekcję pliku manifestu, która definiuje dodatek Google Workspace, w tym:

  • Sekcja addOns.common pliku manifestu definiuje nazwę, adres URL logo, kolory i inne ogólne ustawienia niezależne od hosta.
  • Manifest definiuje 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ą:
  • Pole oauthScopesokreśla zakresy autoryzacji dla projektu (zwykle wymagane w przypadku dodatków).
  • (Dotyczy 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 Lista adresów URL, które mogą używać protokołu HTTP.

Linki w tym pliku kierują do opisów tego pola w odpowiedniej dokumentacji pliku manifestu dotyczącej Apps Script i HTTP – dodatków Google Workspace.

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

Listy dozwolonych adresów URL służą do oznaczania konkretnych adresów URL, które są wstępnie zatwierdzone do dostępu przez skrypt lub dodatek. Listy dozwolonych adresów pomagają chronić dane użytkownika. Gdy zdefiniujesz listę dozwolonych adresów, projekty skryptów nie będą mogły uzyskiwać dostępu do adresów URL, które nie zostały dodane do listy dozwolonych.

To pole jest opcjonalne, gdy instalujesz wdrożenie testowe, ale jest wymagane, gdy tworzysz wdrożenie z wersjami.

Listy dozwolonych adresów używasz, gdy skrypt lub dodatek wykonuje te czynności:

  • Pobiera lub pobiera informacje z zewnętrznego źródła (np. punktów końcowych HTTPS) za pomocą usługi Apps Script UrlFetch. Aby dodać adresy URL do listy dozwolonych, dodaj pole urlFetchWhitelist do pliku manifestu.
  • Otwiera lub wyświetla adres URL w odpowiedzi na działanie użytkownika (wymagane w przypadku dodatków Google Workspace, które otwierają lub wyświetlają adresy URL zewnętrzne w stosunku do Google). Aby dodać adresy URL do listy dozwolonych, dodaj pole addOns.common.openLinkUrlPrefixes w pliku manifestu.
.

Dodawanie prefiksów do listy dozwolonych

Jeśli w pliku manifestu podasz listy dozwolonych adresów (za pomocą pola addOns.common.openLinkUrlPrefixes lub urlFetchWhitelist), musisz uwzględnić listę prefiksów adresów URL. W pliku manifestu dodawane prefiksy 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 mieć pełną domenę.
  • Każdy prefiks musi mieć niepustą ścieżkę. Na przykład https://www.google.com/ jest prawidłowy, 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 to narazić dane użytkownika na ryzyko i wydłużyć proces sprawdzania dodatku. Używaj symboli wieloznacznych tylko wtedy, gdy wymaga tego funkcjonalność dodatku.

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

  • W dopasowaniu ścieżki wielkość liter ma znaczenie.
  • Jeśli prefiks jest identyczny z adresem URL, jest to dopasowanie.
  • Jeśli adres URL jest taki sam lub jest podrzędnym adresem URL z prefiksem, dopasowanie jest uznawane za poprawne.

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ć pojedynczego symbolu wieloznacznego (*), aby dopasować subdomenę w obu polach urlFetchWhitelist i addOns.common.openLinkUrlPrefixes. Nie można użyć więcej niż jednego symbolu wieloznacznego do dopasowania wielu subdomen, a symbol wieloznaczny musi reprezentować 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 (niepasujący sufiks)
  • https://example.com/foo (musi być co najmniej 1 subdomena)

Niektóre reguły dotyczące prefiksów są egzekwowane, gdy próbujesz zapisać plik manifestu. Na przykład, jeśli w pliku manifestu znajdują się te prefiksy, podczas próby zapisywania wystąpi błąd:

  • https://*.*.example.com/foo (wielokrotne symbole zastępcze są niedozwolone)
  • https://subdomain.*.example.com/foo(symbole wieloznaczne muszą być używane jako wiodący prefiks)