Manifeste für Google Workspace-Add-ons

In einem Apps Script-Projekt werden mithilfe einer Manifestdatei bestimmte Details zum Skript und seinem Betrieb konfiguriert. Informationen zum Anzeigen und Bearbeiten eines Manifests finden Sie unter Manifeste.

In dieser Dokumentation wird die Konfiguration eines Manifests für ein Google Workspace-Add-on im Detail beschrieben.

Manifeststruktur für Google Workspace-Add-ons

Für Google Workspace-Add-ons wird die Manifestdatei des Apps Script-Projekts verwendet, um verschiedene Aspekte der Darstellung und des Verhaltens des Add-ons zu definieren. Die Manifesteigenschaften für Google Workspace-Add-ons sind im Abschnitt addOns der Manifestobjektstruktur organisiert.

Beispielkonfiguration für ein Google Workspace-Add-on-Manifest

Das folgende Manifestbeispiel zeigt den Abschnitt einer Manifestdatei, in dem ein Google Workspace-Add-on definiert wird. Es enthält folgende Aspekte:

  • Im Abschnitt addOns.common des Manifests werden der Name, die Logo-URL, Farben und andere allgemeine, hostunabhängige Einstellungen für das Add-on definiert.
  • Das Manifest definiert eine gemeinsame Startseite, aber auch Startseiten für Kalender, Drive, Docs, Tabellen und Präsentationen. Gmail verwendet die Standardstartseite.
  • Mit den Einstellungen für das Beispielmanifest wird Folgendes aktiviert:
    • eventOpen- und eventUpdated-Trigger für Kalender sowie zwei Kalender-Konferenzlösungen
    • Zwei universelle Aktionen.
    • Ein Drive-onItemsSelectedTrigger.
    • Eine Gmail-Schreibaktion und einen kontextbezogenen Trigger.
    • Ein Docs-linkPreviewTrigger. Weitere Informationen zu diesem Trigger finden Sie unter Vorschaulinks mit Smartchips anzeigen.
    • Dateispezifische Oberflächen für Google Docs, Google Tabellen und Google Präsentationen.
  • Im Feld oauthScopes werden Autorisierungsbereiche für das Projekt festgelegt. Dies ist normalerweise für Add-ons erforderlich.
  • Mit dem Feld urlFetchWhitelist wird dafür gesorgt, dass alle abgerufenen Endpunkte mit einer angegebenen Liste von HTTPS-URL-Präfixen übereinstimmen. Weitere Informationen finden Sie unter URLs auf die Zulassungsliste setzen.

Die Links im Beispiel leiten zu den Beschreibungen des jeweiligen Felds in der Manifest-Referenzdokumentation weiter.

{
  "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/"
  ]
}

URLs auf die Zulassungsliste setzen

Sie verwenden Zulassungslisten, um bestimmte URLs anzugeben, für die Ihr Script oder Add-on vorab den Zugriff gewährt hat. Zulassungslisten schützen Nutzerdaten. Wenn Sie eine Zulassungsliste definieren, können Script-Projekte nicht auf URLs zugreifen, die nicht auf der Zulassungsliste stehen.

Dieses Feld ist optional, wenn Sie eine Testbereitstellung installieren, aber es ist erforderlich, wenn Sie eine versionierte Bereitstellung erstellen.

Sie verwenden Zulassungslisten, wenn Ihr Script oder Add-on die folgenden Aktionen ausführt:

  • Mit dem Apps Script-Dienst UrlFetch werden Informationen von einem externen Speicherort (z. B. HTTPS-Endpunkte) abgerufen oder abgerufen. Wenn Sie abrufende URLs auf die Zulassungsliste setzen möchten, fügen Sie in die Manifestdatei das Feld urlFetchWhitelist ein.
  • Öffnet oder zeigt eine URL als Reaktion auf eine Nutzeraktion an (erforderlich für Google Workspace-Add-ons, mit denen URLs außerhalb von Google geöffnet oder angezeigt werden). Wenn Sie URLs zum Öffnen auf die Zulassungsliste setzen möchten, fügen Sie in die Manifestdatei das Feld addOns.common.openLinkUrlPrefixes ein.

Präfixe zur Zulassungsliste hinzufügen

Wenn Sie in Ihrer Manifestdatei Zulassungslisten durch Eingabe des Felds addOns.common.openLinkUrlPrefixes oder urlFetchWhitelist angeben, müssen Sie eine Liste mit URL-Präfixen angeben. Die Präfixe, die Sie dem Manifest hinzufügen, müssen die folgenden Anforderungen erfüllen:

  • Jedes Präfix muss eine gültige URL sein.
  • Jedes Präfix muss https:// verwenden, nicht http://.
  • Jedes Präfix muss eine vollständige Domain haben.
  • Jedes Präfix muss einen nicht leeren Pfad haben. https://www.google.com/ ist beispielsweise gültig, https://www.google.com jedoch nicht.
  • Sie können Platzhalter verwenden, um URL-Subdomainpräfixe abzugleichen.
  • Im Feld addOns.common.openLinkUrlPrefixes kann ein einzelner Platzhalter * verwendet werden, um alle Verknüpfungen abzugleichen. Dies wird jedoch nicht empfohlen, da die Daten eines Nutzers dadurch Risiken ausgesetzt sein und die Add-on-Überprüfung länger dauern kann. Verwenden Sie einen Platzhalter nur, wenn dies für Ihre Add-on-Funktionen erforderlich ist.

Wenn festgestellt wird, ob eine URL mit einem Präfix auf der Zulassungsliste übereinstimmt, gelten die folgenden Regeln:

  • Beim Pfadabgleich wird zwischen Groß- und Kleinschreibung unterschieden.
  • Wenn das Präfix mit der URL identisch ist, gilt eine Übereinstimmung.
  • Wenn die URL dem Präfix identisch oder diesem untergeordnet ist, gilt die URL als Übereinstimmung.

Beispielsweise stimmt das Präfix https://example.com/foo mit den folgenden URLs überein:

  • https://example.com/foo
  • https://example.com/foo/
  • https://example.com/foo/bar
  • https://example.com/foo?bar
  • https://example.com/foo#bar

Platzhalter verwenden

Sie können ein einzelnes Platzhalterzeichen (*) verwenden, um eine Subdomain sowohl in den Feldern urlFetchWhitelist als auch in addOns.common.openLinkUrlPrefixes abzugleichen. Sie können nur einen Platzhalter verwenden, um mehrere Subdomains abzugleichen. Der Platzhalter muss das führende Präfix der URL darstellen.

Das Präfix https://*.example.com/foo entspricht beispielsweise folgenden URLs:

  • https://subdomain.example.com/foo
  • https://any.number.of.subdomains.example.com/foo

Das Präfix https://*.example.com/foo stimmt nicht mit den folgenden URLs überein:

  • https://subdomain.example.com/bar (nicht übereinstimmendes Suffix)
  • https://example.com/foo (Es muss mindestens eine Subdomain vorhanden sein)

Einige der Präfixregeln werden erzwungen, wenn Sie versuchen, Ihr Manifest zu speichern. Die folgenden Präfixe verursachen beispielsweise einen Fehler, wenn sie beim Speichern in Ihrem Manifest vorhanden sind:

  • https://*.*.example.com/foo (mehrere Platzhalter sind unzulässig)
  • https://subdomain.*.example.com/foo (Platzhalter müssen als vorangestelltes Präfix verwendet werden)