Manifeste für Google Workspace-Add-ons

Add-ons verwenden eine Manifestdatei, um bestimmte Details über die App und ihren Betrieb zu konfigurieren.

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

Manifeststruktur für Google Workspace-Add-ons

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

Die Manifesteigenschaften 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

Beispielkonfiguration für das Google Workspace-Add-on

Das folgende Manifest zeigt den Abschnitt einer Manifestdatei, in dem Google Workspace-Add-ons definiert werden, einschließlich der 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.
• Das Manifest definiert 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 Beispieleinstellungen für das Manifest ermöglichen Folgendes:
  • Kalender-Trigger eventOpen und eventUpdated.
  • (Nur Apps Script) Zwei Konferenzlösungen in Google Kalender
  • Zwei universelle Aktionen.
  • onItemsSelectedTrigger für Drive.
  • Eine Gmail-Schreibaktion und einen kontextbezogenen Trigger.
  • Ein linkPreviewTriggers-Objekt für Docs. Informationen zu diesem Trigger finden Sie unter Vorschaulinks mit Smartchips.
  • Ein createActionTriggers-Objekt von Google Docs. Weitere Informationen zu diesem Trigger finden Sie unter Ressourcen von Drittanbietern über das @-Menü erstellen.
  • Dateispezifische Oberflächen für Google Docs, Google Tabellen und Google Präsentationen.
• Mit dem 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 im Beispiel führen zu den Beschreibungen dieses Felds in der zugehörigen Manifest-Referenzdokumentation für Apps Script- und HTTP-Add-ons für Google Workspace.

Hinweis: Manifeste enthalten weitere Komponenten. Die Felder unter dem Feld addOns beziehen sich direkt auf Google Workspace-Add-ons. Dieses Beispiel ist nur ein Teil einer vollständigen Manifestdatei, aber kein voll funktionsfähiges Manifest.

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 der Zulassungsliste

Mit Zulassungslisten können Sie bestimmte URLs festlegen, denen der Zugriff durch Ihr Script oder Add-on vorab genehmigt wird. Zulassungslisten tragen zum Schutz von Nutzerdaten bei. Wenn Sie eine Zulassungsliste definieren, können Scriptprojekte nicht auf URLs zugreifen, die nicht auf der Zulassungsliste stehen.

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

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

• Ruft mithilfe des Apps Script-Dienstes UrlFetch Informationen von einem externen Speicherort (z. B. HTTPS-Endpunkten) ab. Wenn du URLs zum Abrufen auf die Zulassungsliste setzen möchtest, füge das Feld urlFetchWhitelist in die Manifestdatei ein.
• Öffnet oder zeigt als Reaktion auf eine Nutzeraktion eine URL an (erforderlich für Google Workspace-Add-ons, die URLs außerhalb von Google öffnen oder anzeigen). Füge das Feld addOns.common.openLinkUrlPrefixes in die Manifestdatei ein, um URLs zum Öffnen auf die Zulassungsliste zu setzen.

Hinweis: Zulassungsliste, wie in urlFetchWhitelist verwendet, ist ein eingestellter Begriff, der gleichbedeutend mit Zulassungsliste und ersetzt wurde. Weitere Informationen finden Sie unter Dokumentation für eine inklusive Sprache schreiben.

Präfixe auf die Zulassungsliste setzen

Wenn Sie in Ihrer Manifestdatei Zulassungslisten angeben (indem Sie 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.
• Jedes Präfix muss https:// verwenden, nicht http://.
• 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 nur ein Platzhalter * verwendet werden, um alle Links abzugleichen. Dies wird jedoch nicht empfohlen, da dies die Daten eines Nutzers gefährden und die Überprüfung des Add-ons verzögern kann. Verwenden Sie einen Platzhalter nur, wenn dies für Ihre Add-on-Funktion erforderlich ist.

Wenn festgestellt wird, 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 mit dem Präfix identisch oder ein untergeordnetes Element ist, handelt es sich um eine Übereinstimmung.

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 in den Feldern urlFetchWhitelist und addOns.common.openLinkUrlPrefixes abzugleichen. Sie können nur einen Platzhalter verwenden, um mehrere Subdomains abzugleichen. Er muss das führende Präfix der URL darstellen.

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 entspricht nicht den folgenden URLs:

• 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 unzulässig)
• https://subdomain.*.example.com/foo (Platzhalter müssen als Präfix vorangestellt werden)