Pliki manifestu dodatków do Google Workspace

Dodatki korzystają z pliku manifest do konfigurowania określonych 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.

• Informacje o plikach manifestu Apps Script znajdziesz w sekcji Struktura pliku manifestu.
• Informacje o plikach manifestu dla dodatków utworzonych z punktami końcowymi HTTP znajdziesz w Zasobie REST: projects.deployments

Pliki manifestu Google Chat

Wersja dla deweloperów: dostępna w ramach programu Google Workspace Developer Preview, który zapewnia wcześniejszy dostęp do niektórych funkcji.

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ń:

• nazwę, logo i opis aplikacji Google Chat, które są widoczne tylko w interfejsie Google Chat;
• Wyzwalacze aplikacji Google Chat.

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

• addons.chat (wymagane)
• oauthScopes (wymagane, jeśli aplikacja Google Chat używa zakresów OAuth)

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ą:
  • eventOpen i eventUpdated.
  • (dotyczy tylko Apps Script) 2 rozwiązania do prowadzenia konferencji w Kalendarzu.
  • 2 działania uniwersalne.
  • Dysk onItemsSelectedTrigger.
  • Akcja tworzenia wiadomości w Gmailu i jej wyzwalacz kontekstowy.
  • Obiekt linkPreviewTriggers w Dokumentach Google. Więcej informacji o tym regułach znajdziesz w artykule Linki do podglądu z elementami inteligentnymi.
  • Obiekt createActionTriggers w Dokumentach Google. Więcej informacji o tym aktywatorze znajdziesz w artykule Tworzenie zasobów zewnętrznych w menu @.
  • interfejsy Dokumentów, Arkuszy i Prezentacji dostosowane do poszczególnych plików;
• 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 o umieszczaniu adresów URL na liście dozwolonych.

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

Uwaga: pliki manifestu zawierają inne komponenty. Pola w sekcji addOns dotyczą bezpośrednio dodatków Google Workspace. Ten przykład to tylko część pełnego pliku manifestu i nie jest to w pełni funkcjonalny manifest.

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 podczas instalowania wdrożenia testowego, ale jest wymagane podczas tworzenia wdrożenia z wersjami.

Używasz list dozwolonych, 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.

Uwaga: Biała lista, używana w urlFetchWhitelist, to termin, który został wycofany i zastąpiony przez listę dozwolonych. Więcej informacji znajdziesz w artykule Tworzenie dokumentacji uwzględniającej wszystkich użytkowników

.

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. 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ć 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)