Diese Seite wurde von der Cloud Translation API übersetzt.

Manifeste für Google Workspace-Add-ons

Ein Add-on verwendet eine Manifestdatei, um bestimmte Details zur App und ihrer Funktionsweise zu konfigurieren.

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

Manifeststruktur für Google Workspace-Add‑ons

In der Manifestdatei von Google Workspace-Add-ons werden verschiedene Aspekte des Erscheinungsbilds und Verhaltens des Add-ons definiert.

Die Manifestattribute 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 in der projects.deployments-Ressource.

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.

Häufige Manifestkonfigurationseinstellungen (einschließlich addons.common) werden in Chat ignoriert. Statt des Add‑on-Manifests verwenden Sie die Chat API, um die folgenden Chat-Einstellungen zu konfigurieren:

Name, Logo und Beschreibung der Chat-App, die nur in der Chat-Benutzeroberfläche angezeigt werden.
Chat-App-Trigger.

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 von Chateinstellungen für ein Add-on finden Sie unter Google Chat-App konfigurieren.

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

Die folgenden Manifestbeispiele zeigen 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. Gmail verwendet die Standardstartseite.
Die Beispielmanifesteinstellungen ermöglichen Folgendes:
- Kalender-Trigger eventOpen und eventUpdated.
- (Nur Apps Script) Zwei Konferenzlösungen für Kalender.
- Zwei universelle Aktionen
- Ein Laufwerk onItemsSelectedTrigger.
- Eine Gmail-Aktion zum Verfassen von Nachrichten und ein kontextbezogener Trigger.
- Ein Docs-linkPreviewTriggers-Objekt. Weitere Informationen zu diesem Trigger finden Sie unter Vorschaulinks mit Smartchips.
- Ein Docs-createActionTriggers-Objekt. Weitere Informationen zu diesem Trigger finden Sie unter Drittanbieterressourcen über das @-Menü erstellen.
- Dateispezifische Benutzeroberflächen für Google Docs, Google Sheets und Google Präsentationen
- (Nur HTTP) Zwei HttpOptions zum Senden eines Autorisierungsheaders und zur Unterstützung der detaillierten Einwilligung.
Im Feld oauthScopes werden Autorisierungsbereiche für das Projekt festgelegt (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 in den Manifestbeispielen leiten zur Beschreibung des jeweiligen Felds in der entsprechenden Manifestreferenzdokumentation für Apps Script- und HTTP-Google Workspace-Add-ons weiter.

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"
      }
    }
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN",
      "granularOauthPermissionSupport": "OPT_IN"
    }
  },
  "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 festlegen, die für den Zugriff durch Ihr Script oder Add‑on vorab genehmigt werden. Zulassungslisten tragen zum Schutz von Nutzerdaten bei. Wenn Sie eine Zulassungsliste definieren, können Scriptprojekte nicht auf URLs zugreifen, die nicht in der Zulassungsliste enthalten sind.

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

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

Ruft Informationen von einem externen Speicherort (z. B. HTTPS-Endpunkte) mithilfe des Apps Script-Dienstes UrlFetch ab. Wenn Sie URLs für das 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 ö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 von URL-Präfixen angeben. Die Präfixe, die Sie dem Manifest hinzufügen, müssen die folgenden Anforderungen erfüllen:

Jeder Präfix muss eine gültige URL sein.
Jedes Präfix muss https:// und nicht http:// verwenden.
Jeder 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-Subdomainpräfixe abzugleichen.
Im Feld addOns.common.openLinkUrlPrefixes kann ein einzelner Platzhalter * verwendet werden, um alle Links abzugleichen. Dies wird jedoch nicht empfohlen, da dadurch die Daten eines Nutzers gefährdet werden und sich der Add-on-Überprüfungsprozess verlängern kann. Verwenden Sie nur dann einen Platzhalter, wenn die Add-on-Funktionalität dies erfordert.

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

Beim Pfadabgleich wird zwischen Groß- und Kleinschreibung unterschieden.
Wenn das Präfix mit der URL identisch ist, liegt eine Übereinstimmung vor.
Wenn die URL mit dem Präfix übereinstimmt oder eine untergeordnete URL des Präfixes ist, liegt eine Übereinstimmung vor.

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 für die Felder urlFetchWhitelist und addOns.common.openLinkUrlPrefixes abzugleichen. Sie können nicht mehr als 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 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 stimmt nicht überein)
https://example.com/foo (mindestens eine Subdomain muss vorhanden sein)

Einige der Präfixregeln werden beim Speichern des 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 nicht zulässig)
https://subdomain.*.example.com/foo (Platzhalter müssen als führendes Präfix verwendet werden)