Manifeste für Google Workspace-Add-ons

In einem Apps Script-Projekt wird eine Manifestdatei verwendet, um bestimmte Details zum Skript und seinem Vorgang zu konfigurieren. Informationen zum Aufrufen und Bearbeiten eines Manifests finden Sie unter Manifeste.

In dieser Dokumentation wird beschrieben, wie Sie ein Manifest für ein Google Workspace-Add-on konfigurieren.

Manifeststruktur für Google Workspace-Add-ons

Mit 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 Manifestattribute für Google Workspace-Add-ons finden Sie im Abschnitt addOns der Manifestobjektstruktur.

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

Das folgende Manifestbeispiel zeigt den Abschnitt einer Manifestdatei, der ein Google Workspace-Add-on definiert, einschließlich der folgenden Aspekte:

• Der Abschnitt addOns.common des Manifests definiert den Namen, die Logo-URL, Farben und andere allgemeine, hostunabhängige Einstellungen für das Add-on.
• Mit dem Manifest wird eine gemeinsame Startseite definiert, aber auch die Startseiten für Google Kalender, Google Drive, Google Docs, Google Tabellen und Google Präsentationen. Gmail verwendet die Standardstartseite.
• Mit den Beispieleinstellungen für das Manifest wird Folgendes ermöglicht:
  • Die Trigger eventOpen und eventUpdated sowie zwei Konferenzlösungen für Google Kalender
  • Zwei universelle Aktionen.
  • Einen Drive-onItemsSelectedTrigger.
  • Eine Gmail-Nachricht zum Schreiben einer Aktion und einen kontextbezogenen Trigger.
  • Ein Google Docs-linkPreviewTrigger Weitere Informationen zu diesem Trigger finden Sie unter Vorschaulinks mit Smartchips.
  • Dateispezifische Schnittstellen für Docs, Tabellen und Präsentationen.
• Im Feld oauthScopes werden Autorisierungsbereiche für das Projekt festgelegt (in der Regel für Add-ons erforderlich).
• Das Feld urlFetchWhitelist stellt sicher, dass alle abgerufenen Endpunkte mit einer angegebenen Liste von HTTPS-URL-Präfixen übereinstimmen. Dieses Feld ist für Testbereitstellungen optional, für Bereitstellungen jedoch erforderlich. Weitere Informationen finden Sie unter Zulassungslisten-URLs.

Die Links im Beispiel leiten direkt zu den Beschreibungen dieses Feldes in der Manifest-Referenzdokumentation.

Hinweis: Manifeste enthalten andere Komponenten, die sich auf Apps Script-Attribute beziehen. Die Felder im Feld addOns beziehen sich direkt auf Google Workspace-Add-ons. Dieses Beispiel ist nur ein Teil einer vollständigen Manifestdatei und kein voll funktionsfähiges Manifest.

// Sample configuration of the addOns section in a manifest file:
{
  "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/"
  ],
}

Zulassungslisten-URLs

Mit Zulassungslisten können Sie bestimmte URLs angeben, die für das Skript oder das Add-on vorab genehmigt werden. Zulassungslisten tragen zum Schutz von Nutzerdaten bei. Wenn Sie eine Zulassungsliste definieren, können Skriptprojekte nicht auf URLs zugreifen, die nicht auf der Zulassungsliste stehen.

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

• Ruft mit dem Apps Script-Dienst UrlFetch Informationen von einem externen Standort (z. B. HTTPS-Endpunkten) ab oder ruft sie ab. Wenn Sie URLs zum Abrufen auf die Zulassungsliste setzen möchten, fügen Sie das Feld urlFetchWhitelist in Ihre Manifestdatei ein.
• Öffnet oder zeigt eine URL als Reaktion auf eine Nutzeraktion an (erforderlich für Google Workspace-Add-ons, die URLs außerhalb von Google öffnen oder anzeigen). Wenn Sie URLs zum Öffnen auf die Zulassungsliste setzen möchten, fügen Sie in die Manifestdatei das Feld addOns.common.openLinkUrlPrefixes ein.

Hinweis: Die weiße Liste, wie in urlFetchWhitelist verwendet, ist ein veralteter Begriff, der durch allowlist ersetzt wird. Weitere Informationen finden Sie unter Inklusive Dokumentation erstellen.

Präfixe zur Zulassungsliste hinzufügen

Wenn Sie Zulassungslisten in der Manifestdatei angeben (entweder durch das Feld addOns.common.openLinkUrlPrefixes oder urlFetchWhitelist), 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 darf nicht leer sein. 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 für * verwendet werden, um alle Links abzugleichen. Dies wird jedoch nicht empfohlen, da bei ihm möglicherweise Daten gefährdet werden und die Add-on-Überprüfung verlängert wird. Verwenden Sie einen Platzhalter nur, wenn dies durch die Add-on-Funktionalität erforderlich ist.

Bei der Entscheidung, 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, handelt es sich um eine Übereinstimmung.
• Wenn die URL identisch oder ein untergeordnetes Präfix des Präfixes ist, ist es eine Übereinstimmung.

Beispielsweise entspricht das Präfix https://example.com/foo den folgenden URLs:

• 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 für die Felder urlFetchWhitelist und addOns.common.openLinkUrlPrefixes abzugleichen. Der Platzhalter kann nur für mehrere Subdomains verwendet werden und muss das vorangestellte Präfix der URL darstellen.

Das Präfix https://*.example.com/foo entspricht beispielsweise den 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 (Abweichung bei Suffix)
• https://example.com/foo (Es muss mindestens eine Subdomain vorhanden sein)

Einige Präfixregeln werden beim Speichern Ihres Manifests erzwungen. Die folgenden Präfixe verursachen beispielsweise einen Fehler, wenn sie beim Speichern im 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)