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 werden die Details der Konfiguration eines Manifests für ein Google Workspace-Add‑on behandelt.

Manifeststruktur für Google Workspace-Add‑ons

Google Workspace-Add‑ons verwenden die Manifestdatei, um verschiedene Aspekte des Erscheinungsbilds und des Verhaltens zu definieren.

Manifesteigenschaften für Google Workspace-Add‑ons sind im Abschnitt addOns organisiert.

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

Manifeste für Google Chat

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

Allgemeine Manifestkonfigurationseinstellungen (einschließlich addons.common) werden in Chat ignoriert. Verwenden Sie die Chat API, um die folgenden Chat-Einstellungen zu konfigurieren:

Name, Logo und Beschreibung der Chat-App für die Chat-UI.
Chat-App Trigger.

Wenn Sie das Add‑on in Apps Script erstellt haben, fügen Sie die folgenden Objekte in Ihrem Manifest hinzu oder aktualisieren Sie sie:

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

Informationen zum Konfigurieren von Chat-Einstellungen für ein Add‑on finden Sie unter Google Chat-App konfigurieren.

Beispiel für eine Manifestkonfiguration für ein Google Workspace-Add‑on

In den folgenden Beispielen wird der Teil eines Manifests gezeigt, der ein Google Workspace-Add‑on definiert, einschließlich der folgenden Aspekte:

addOns.common definiert den Namen, das Logo, die Farben und andere allgemeine Einstellungen für das Add‑on.
Das Manifest definiert eine gemeinsame Startseite, aber auch spezifische Startseiten für Google Kalender, Google Drive, Google Docs, Google Sheets und Google Präsentationen. In Gmail wird die Standardstartseite verwendet.
Die Beispielmanifesteinstellungen ermöglichen Folgendes:
- Kalender-Trigger eventOpen und eventUpdated.
- (Nur Apps Script) Zwei Kalender Konferenzlösungen.
- Zwei universelle Aktionen.
- Ein Drive-Trigger onItemsSelectedTrigger.
- Eine Gmail-Aktion zum Verfassen von Nachrichten und ein kontextbezogener Trigger.
- Ein Docs-Objekt linkPreviewTriggers. Weitere Informationen finden Sie unter Vorschaulinks mit Smartchips.
- Ein Docs-Objekt createActionTriggers. Weitere Informationen finden Sie unter Ressourcen von Drittanbietern über das @-Menü erstellen.
- Dateispezifische Oberflächen für Google Docs, Google Sheets und Google Präsentationen.
- Eine Google Meet-Option sidePanelUri und addOnOrigins.
- (Nur HTTP) Zwei HttpOptions zum Senden eines Autorisierungsheaders und zur Unterstützung der detaillierten Einwilligung.
Im Feld oauthScopes werden die Autorisierungsbereiche des Projekts festgelegt.
(Nur Apps Script) Mit urlFetchWhitelist wird sichergestellt, dass die abgerufenen Endpunkte mit den angegebenen HTTPS-URL-Präfixen übereinstimmen. Weitere Informationen finden Sie unter URLs auf die Zulassungsliste setzen.

Die Links in den Beispielen führen zu Feldbeschreibungen in der Manifest referenz für Apps Script und HTTP Google Workspace-Add‑ons.

Manifeste enthalten weitere Komponenten. Felder unter addOns beziehen sich direkt auf Google Workspace-Add‑ons. Dieses Beispiel zeigt nur einen Teil einer vollständigen Manifestdatei und ist allein nicht funktionsfähig.

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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/logoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
    },
  },
  "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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/meetWebLogoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
      ]
    },
    "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 Skript oder Add‑on vorab genehmigt wurden. Zulassungslisten tragen zum Schutz von Nutzerdaten bei. Wenn Sie eine Zulassungsliste definieren, können Skriptprojekte nicht auf URLs zugreifen, die nicht der Zulassungsliste hinzugefügt wurden.

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:

Informationen von einem externen Speicherort (z. B. HTTPS Endpunkten) mit dem Apps Script UrlFetch Dienst abrufen oder abrufen. Wenn Sie URLs für den Abruf auf die Zulassungsliste setzen möchten, fügen Sie das urlFetchWhitelist Feld in Ihre Manifestdatei ein.
Eine URL als Reaktion auf eine Nutzeraktion öffnen oder anzeigen (erforderlich für Google Workspace-Add‑ons, die URLs öffnen oder anzeigen, die sich außerhalb von Google befinden). Wenn Sie URLs zum Öffnen auf die Zulassungsliste setzen möchten, fügen Sie das addOns.common.openLinkUrlPrefixes Feld 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:

Jedes Präfix muss eine gültige URL sein.
Jedes Präfix muss https:// und nicht http:// verwenden.
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-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 dadurch die Daten eines Nutzers gefährdet werden und sich der Überprüfungsprozess für Add‑ons verlängern kann. Verwenden Sie nur einen Platzhalter, wenn dies für die Funktion Ihres Add‑ons erforderlich ist.

Bei der Bestimmung, 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 identisch ist oder ein untergeordnetes Element 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 einen einzelnen Platzhalter (*) verwenden, um eine Subdomain sowohl für die urlFetchWhitelist als auch für die addOns.common.openLinkUrlPrefixes Felder 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 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 nicht zulässig)
https://subdomain.*.example.com/foo (Platzhalter müssen als führendes Präfix verwendet werden)