Manifeste für Google Workspace-Add-ons

Ein Apps Script-Projekt verwendet eine Manifest-Datei, um bestimmte Details zum Skript und dessen Funktionsweise 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

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

Beispielkonfiguration für Add-ons für Google Workspace-Add-ons

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

• Im Abschnitt addOns.common des Manifests sind der Name, die Logo-URL, die Farben und andere allgemeine, hostunabhängige Einstellungen für das Add-on definiert.
• Das Manifest definiert eine allgemeine Startseite, aber auch bestimmte Startseiten für Google Kalender, Google Drive, Google Docs, Google Tabellen und Google Präsentationen. verwendet Gmail die Standardstartseite.
• Die Beispieleinstellungen für das Manifest ermöglichen Folgendes:
  • Kalender-eventOpen und eventUpdated-Trigger sowie Kalenderlösungen.
  • Zwei universelle Aktionen.
  • Ein Drive-onItemsSelectedTrigger.
  • Eine Gmail-Aktion zum Erstellen einer Nachricht und ein Kontexttrigger.
  • Dateispezifische Oberflächen für Google Docs, Google Tabellen und Google 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 URLs auf die Zulassungsliste setzen.

Die Links im Beispiel leiten direkt auf die Beschreibungen des jeweiligen Feldes in der Manifest-Referenzdokumentation weiter.

Hinweis: Manifeste enthalten weitere Komponenten, die sich auf Apps Script-Attribute beziehen. Die Felder unter dem 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"
      }
    },

    "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"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ],
}

URLs der Zulassungsliste

Mithilfe von Zulassungslisten können Sie bestimmte URLs angeben, die durch das Skript oder das Add-on vorab genehmigt werden dürfen. 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 Speicherort ab oder ruft sie ab, z. B. HTTPS-Endpunkte. Wenn Sie URLs auf die Zulassungsliste setzen möchten, schließen Sie das Feld urlFetchWhitelist in die Manifestdatei ein.
• Öffnet oder zeigt eine URL als Reaktion auf eine Nutzeraktion an (erforderlich für Google Workspace-Add-ons, die externe URLs öffnen oder anzeigen). Wenn du URLs zum Öffnen auf die Zulassungsliste setzen möchtest, nimm das Feld addOns.common.openLinkUrlPrefixes in die Manifestdatei auf.

Hinweis: Weiße Liste (wie in urlFetchWhitelist verwendet) ist ein verworfener Begriff, der durch Zulassungsliste ersetzt wird. Weitere Informationen finden Sie unter Inklusive Dokumentation erstellen.

Präfixe auf die Zulassungsliste setzen

Wenn Sie in der Manifestdatei Zulassungslisten (entweder im Feld 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.
• Für jedes Präfix muss https:// verwendet werden, nicht http://.
• Jedes Präfix muss eine vollständige Domain haben.
• Jedes Präfix muss einen nicht leeren Pfad haben. Beispiel: https://www.google.com/ ist gültig, https://www.google.com jedoch nicht.
• Sie können Platzhalter verwenden, um URL-Subdomain-Präfixen abzugleichen.
• Ein einzelner *-Platzhalter kann im Feld addOns.common.openLinkUrlPrefixes verwendet werden, um alle Verknüpfungen abzugleichen. Dies wird jedoch nicht empfohlen, da damit Daten eines Nutzers gefährdet werden und der Prozess der Add-on-Prüfung verlängert werden kann. Verwenden Sie einen Platzhalter nur, wenn dies für Ihre Add-on-Funktionalität erforderlich ist.

Bei der Bestimmung, 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, handelt es sich um eine Übereinstimmung.

Das Präfix https://example.com/foo entspricht beispielsweise 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. Sie können nicht mehr als einen Platzhalter zum Abgleich mehrerer Subdomains verwenden und der Platzhalter muss das führende Präfix der URL sein.

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 (nicht übereinstimmende Suffixe)
• https://example.com/foo (mindestens eine Subdomain vorhanden)

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

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