Diese Seite wurde von der Cloud Translation API übersetzt.

Manifeste für Google Workspace-Add-ons

In einem Add-on wird mithilfe einer manifest festgelegt, wie die App funktioniert.

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

Manifeststruktur für Google Workspace-Add-ons

In Google Workspace-Add-ons werden in der Manifestdatei mehrere Aspekte des Erscheinungsbildes und Verhaltens des Add-ons definiert.

Die Manifest-Eigenschaften für Google Workspace-Add-ons sind im Abschnitt addOns der Manifestobjektstruktur organisiert.

Informationen zu Apps Script-Manifestdateien finden Sie unter Manifeststruktur.
Informationen zu Manifestdateien für Add-ons, die mit HTTP-Endpunkten erstellt wurden, finden Sie unter REST-Ressource: projects.deployments .

Manifeste für Google Chat

Wenn Ihr Google Workspace-Add-on Google Chat erweitert, müssen Sie eine Google Chat-App konfigurieren, indem Sie die Google Chat API in der Google Cloud Console aktivieren und konfigurieren.

Gängige Manifestkonfigurationseinstellungen (einschließlich addons.common) werden in Google Chat ignoriert. Anstatt das Add-on-Manifest zu verwenden, konfigurieren Sie die folgenden Chat-Einstellungen mit der Chat API:

Der Name, das Logo und die Beschreibung der Chat-App, die nur in der Chat-Benutzeroberfläche angezeigt werden.
Trigger für Chat-Apps

Wenn Sie das Add-on in Apps Script erstellt haben, müssen Sie auch die folgenden Objekte in Ihrem Manifest hinzufügen oder aktualisieren:

addons.chat (erforderlich)
oauthScopes (erforderlich, wenn Ihre Google Chat-App OAuth-Bereiche verwendet)

Eine Anleitung zum Konfigurieren der Chateinstellungen für ein Add-on finden Sie unter Google Chat-App konfigurieren.

Beispiel für die Manifestkonfiguration eines Google Workspace-Add-ons

Das folgende Manifestbeispiel zeigt den Abschnitt einer Manifestdatei, in dem ein Google Workspace-Add-on definiert wird. Dazu gehören die folgenden Aspekte:

Im Abschnitt addOns.common des Manifests werden der Name, die Logo-URL, die Farben und andere allgemeine, hostunabhängige Einstellungen für das Add-on definiert.
Im Manifest wird eine gemeinsame Startseite definiert, aber auch spezifische Startseiten für Google Kalender, Google Drive, Google Docs, Google Tabellen und Google Präsentationen. In Gmail wird die Standardstartseite verwendet.
Mit den Beispielmanifesteinstellungen ist Folgendes möglich:
- Kalendertrigger eventOpen und eventUpdated
- (Nur Apps Script) Zwei Konferenzlösungen für Google Kalender
- Zwei universelle Aktionen.
- Eine Drive-onItemsSelectedTrigger.
- Eine Gmail-Aktivität zum Verfassen einer Nachricht und ein kontextbezogener Trigger.
- Ein Google Docs-linkPreviewTriggers-Objekt. Weitere Informationen zu diesem Trigger finden Sie unter Vorschaulinks mit Smartchips erstellen.
- Ein Google Docs-createActionTriggers-Objekt. Weitere Informationen zu diesem Trigger finden Sie unter Ressourcen von Drittanbietern über das Dreipunkt-Menü erstellen.
- Dateispezifische Benutzeroberflächen für Google Docs, Google Tabellen und Google Präsentationen
Im Feld oauthScopes werden Autorisierungsbereiche für das Projekt festgelegt. Das ist in der Regel für Add-ons erforderlich.
(Nur Apps Script) Das Feld urlFetchWhitelist sorgt dafür, 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 verweisen auf die Beschreibungen dieses Felds in der entsprechenden Manifest-Referenzdokumentation für Apps Script und HTTP-Google Workspace-Add-ons.

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

URLs auf die Zulassungsliste setzen

Mit Zulassungslisten können Sie bestimmte URLs angeben, die von Ihrem Script oder Add-on vorab für den Zugriff genehmigt werden. Mit Zulassungslisten können Sie Nutzerdaten schützen. Wenn Sie eine Zulassungsliste definieren, können Scriptprojekte nicht auf URLs zugreifen, die nicht der Zulassungsliste hinzugefügt wurden.

Dieses Feld ist optional, wenn Sie eine Testbereitstellung installieren. Es ist jedoch erforderlich, wenn Sie eine versionierte Bereitstellung erstellen.

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

Ruft Informationen über den Apps Script-Dienst UrlFetch von einem externen Speicherort (z. B. HTTPS-Endpunkte) ab. Wenn Sie URLs für das Abrufen auf die Zulassungsliste setzen möchten, fügen 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 URLs öffnen oder anzeigen, die nicht zu Google gehören. Wenn Sie URLs für das Öffnen auf die Zulassungsliste setzen möchten, fügen Sie das Feld addOns.common.openLinkUrlPrefixes in Ihre Manifestdatei ein.

Präfixe zur Zulassungsliste hinzufügen

Wenn Sie Zulassungslisten in Ihrer Manifestdatei angeben (indem Sie entweder das Feld addOns.common.openLinkUrlPrefixes oder urlFetchWhitelist einfügen), 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äfixe abzugleichen.
Im Feld addOns.common.openLinkUrlPrefixes kann ein einzelner Platzhalter * verwendet werden, um alle Links abzugleichen. Dies wird jedoch nicht empfohlen, da die Daten eines Nutzers dadurch gefährdet werden können und sich die Überprüfung des Add-ons dadurch verlängern kann. Verwenden Sie einen Platzhalter nur, wenn dies für die Add-on-Funktion erforderlich ist.

Bei der Bestimmung, ob eine URL mit einem Präfix in der Zulassungsliste übereinstimmt, gelten die folgenden Regeln:

Beim Pfadabgleich wird die Groß- und Kleinschreibung beachtet.
Wenn das Präfix mit der URL identisch ist, gibt es eine Übereinstimmung.
Wenn die URL mit dem Präfix übereinstimmt oder ein untergeordnetes Element davon ist, wird eine Übereinstimmung festgestellt.

Das Präfix https://example.com/foo stimmt beispielsweise 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 für das Feld urlFetchWhitelist als auch für das Feld addOns.common.openLinkUrlPrefixes abzugleichen. Sie können nicht mehrere Platzhalter verwenden, um mehrere Subdomains abzugleichen. Außerdem muss der Platzhalter das Präfix der URL sein.

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

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 (Suffix nicht übereinstimmend)
https://example.com/foo (mindestens eine Subdomain muss vorhanden sein)

Einige der Präfixregeln werden beim Speichern des Manifests erzwungen. Die folgenden Präfixe führen beispielsweise zu einem Fehler, wenn sie beim Speichern in Ihrem Manifest vorhanden sind:

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