In Apps Script-Projekten werden mithilfe einer Manifestdatei bestimmte Details zum Skript und zu dessen Betrieb konfiguriert. Informationen zum Anzeigen und Bearbeiten eines Manifests finden Sie unter Manifeste.
In dieser Dokumentation wird die Konfiguration eines Manifests für ein Google Workspace-Add-on beschrieben.
Manifeststruktur für Google Workspace-Add-ons
Add-ons für Google Workspace verwenden die Apps Script-Projektmanifestdatei, um verschiedene Aspekte der Darstellung und des Verhaltens des Add-ons zu definieren. Die Manifestattribute für Google Workspace-Add-ons sind im Abschnitt addOns der Manifestobjektstruktur aufgeführt.
Beispielkonfiguration für das Google Workspace-Add-on als Manifestkonfiguration
Das folgende Manifestbeispiel zeigt den Abschnitt einer Manifestdatei, in dem ein Google Workspace-Add-on definiert wird. Dabei werden folgende Aspekte berücksichtigt:
- Im Abschnitt
addOns.commondes Manifests werden der Name, die Logo-URL, die Farben und andere allgemeine, hostunabhängige Einstellungen für das Add-on festgelegt. - Das Manifest definiert eine gemeinsame Startseite sowie spezifische Startseiten für Google Kalender, Google Drive, Google Docs, Google Tabellen und Google Präsentationen. Gmail verwendet die Standardstartseite.
- Mit den Einstellungen für das Beispielmanifest wird Folgendes aktiviert:
- Kalender-
eventOpen- und -eventUpdated-Trigger sowie zwei Kalender-Konferenzlösungen. - Zwei universelle Aktionen.
- Ein Drive-
onItemsSelectedTrigger. - Eine Aktion zum Schreiben einer E-Mail in Gmail und einen kontextabhängigen Trigger.
- Ein Docs-
linkPreviewTrigger. Weitere Informationen zu diesem Trigger finden Sie unter Vorschaulinks mit Smartchips. - Dateispezifische Oberflächen für Google Docs, Google Tabellen und Google Präsentationen
- Kalender-
- Mit dem Feld
oauthScopeswerden Autorisierungsbereiche für das Projekt festgelegt (in der Regel für Add-ons erforderlich). - Mit dem Feld
urlFetchWhitelistwird dafür gesorgt, dass alle abgerufenen Endpunkte mit einer bestimmten 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 der Zulassungsliste.
Die Links im Beispiel führen zu den Beschreibungen des jeweiligen Feldes in der Manifest-Referenzdokumentation.
// 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/"
],
}
URLs auf die Zulassungsliste setzen
Sie verwenden Zulassungslisten, um bestimmte URLs festzulegen, die von Ihrem Skript oder Add-on vorab für den Zugriff zugelassen sind. 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
UrlFetchInformationen von einem externen Speicherort (z. B. HTTPS-Endpunkten) ab. Wenn du URLs zum Abrufen auf die Zulassungsliste setzen möchtest, füge deiner Manifestdatei das FeldurlFetchWhitelisthinzu. - Öffnet oder zeigt eine URL als Reaktion auf eine Nutzeraktion an (erforderlich für Google Workspace-Add-ons, mit denen URLs außerhalb von Google geöffnet oder angezeigt werden). Wenn du URLs zum Öffnen auf die Zulassungsliste setzen möchtest, füge deiner Manifestdatei das Feld
addOns.common.openLinkUrlPrefixeshinzu.
Präfixe zur Zulassungsliste hinzufügen
Wenn Sie in Ihrer Manifestdatei Zulassungslisten angeben (entweder durch Einbinden des Felds 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, nichthttp://. - Jedes Präfix muss eine vollständige Domain haben.
- Jedes Präfix muss einen Pfad enthalten.
https://www.google.com/ist beispielsweise gültig,https://www.google.comjedoch nicht. - Sie können Platzhalter verwenden, um URL-Subdomain-Präfixe abzugleichen.
- Im Feld
addOns.common.openLinkUrlPrefixeskann ein einzelner Platzhalter*verwendet werden, um alle Links abzugleichen. Dies wird jedoch nicht empfohlen, da die Daten eines Nutzers dadurch Risiken gefährdet und die Add-on-Überprüfung verlängert werden kann. Verwenden Sie einen Platzhalter nur, wenn dies für Ihre Add-on-Funktionalität erforderlich ist.
Wenn festgestellt wird, ob eine URL mit einem Präfix aus der Zulassungsliste übereinstimmt, gelten die folgenden Regeln:
- Beim Pfadabgleich wird zwischen Groß- und Kleinschreibung unterschieden.
- Wenn das Präfix mit der URL identisch ist, gilt eine Übereinstimmung.
- Wenn die URL mit dem Präfix identisch oder diesem untergeordnet ist, gilt eine Übereinstimmung.
Beispielsweise entspricht das Präfix https://example.com/foo den folgenden URLs:
https://example.com/foohttps://example.com/foo/https://example.com/foo/barhttps://example.com/foo?barhttps://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 vorangestellte Präfix der URL darstellen.
Das Präfix https://*.example.com/foo stimmt beispielsweise mit folgenden URLs überein:
https://subdomain.example.com/foohttps://any.number.of.subdomains.example.com/foo
Das Präfix https://*.example.com/foo stimmt nicht mit folgenden URLs überein:
https://subdomain.example.com/bar(nicht übereinstimmendes Suffix)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 vorangestelltes Präfix verwendet werden)