Manifeste für Google Workspace-Add-ons

Für ein Add-on wird eine Manifestdatei verwendet. um bestimmte Details über die App und ihren Betrieb zu konfigurieren.

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

Manifeststruktur für Google Workspace-Add-ons

Für Google Workspace-Add-ons wird die Manifestdatei verwendet, um verschiedene Aspekte des Add-ons Erscheinungsbild und Verhalten.

Die Manifesteigenschaften für Google Workspace-Add-ons sind im Abschnitt addOns der Manifest-Objektstruktur aufgeführt.

Beispielkonfiguration für das Google Workspace-Add-on

Das folgende Manifest-Beispiel zeigt den Abschnitt einer Manifestdatei, in dem ein Google Workspace-Add-on, einschließlich der folgenden Aspekte:

  • Das addOns.common des Manifests den Namen, die Logo-URL, Farben und andere allgemeinen, hostunabhängigen Einstellungen für das Add-on festlegen.
  • Das Manifest definiert eine allgemeine Startseite, definiert aber auch Kalender, Drive, Docs, Startseiten für Google Tabellen und Google Präsentationen. Gmail verwendet die Standardstartseite.
  • Die Beispieleinstellungen für das Manifest ermöglichen Folgendes: <ph type="x-smartling-placeholder">
      </ph>
    • Kalender-Trigger eventOpen und eventUpdated.
    • (Nur Apps Script) Zwei Kalender Konferenzlösungen.
    • Zwei universelle Aktionen.
    • onItemsSelectedTrigger für Drive.
    • Eine Gmail-Schreibaktion und einen kontextbezogenen Trigger.
    • Ein linkPreviewTriggers-Objekt für Docs. Weitere Informationen zu diesem Trigger Weitere Informationen finden Sie unter Vorschaulinks mit Smartchips.
    • Ein createActionTriggers-Objekt von Google Docs. Weitere Informationen zu diesem Trigger Siehe Drittanbieterressourcen über das @-Menü erstellen.
    • Dateispezifische Oberflächen für Google Docs, Google Tabellen, und Google Präsentationen.
  • Das Feld oauthScopes legt Autorisierungsbereiche für das Projekt fest (in der Regel erforderlich für Add-ons).
  • (Nur Apps Script) urlFetchWhitelist Feld ist ein Feld, das sicherstellt, dass alle abgerufenen Endpunkte mit einem Liste der HTTPS-URL-Präfixe. Weitere Informationen finden Sie unter URLs auf die Zulassungsliste setzen:

Die Links im Beispiel führen zu den Beschreibungen. in das entsprechende Feld 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 der Zulassungsliste

Sie verwenden Zulassungslisten, um bestimmte URLs anzugeben, für die der Zugriff vorab genehmigt wurde Skript oder Add-on einfügen. Zulassungslisten tragen zum Schutz von Nutzern bei data; Wenn Sie eine Zulassungsliste definieren, können Scriptprojekte nicht auf URLs zugreifen, nicht auf der Zulassungsliste stehen.

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

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

  • Ruft Informationen von einem externen Speicherort (z. B. HTTPS) ab bzw. daraus. Endpunkte) mithilfe von Apps Script UrlFetch Service. 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 externe URLs öffnen oder anzeigen Google. Wenn Sie URLs zum Öffnen auf die Zulassungsliste setzen möchten, fügen Sie das Feld addOns.common.openLinkUrlPrefixes in die Manifestdatei.

Präfixe auf die Zulassungsliste setzen

Wenn Sie in Ihrer Manifestdatei Zulassungslisten angeben (durch Einfügen des addOns.common.openLinkUrlPrefixes oder urlFetchWhitelist), müssen Sie eine Liste mit URL-Präfixen enthalten. Die Präfixe, die du dem Manifest hinzufügst, müssen folgende 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. 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.
  • Ein einzelner *-Platzhalter kann in der addOns.common.openLinkUrlPrefixes für alle Links übernommen. Dies wird jedoch nicht empfohlen, da dadurch des Nutzers gefährden und die Überprüfung des Add-ons. Nur verwenden Sie einen Platzhalter, wenn dies für Ihre Add-on-Funktion erforderlich ist.

Für die Feststellung, ob eine URL mit einem Präfix auf der Zulassungsliste übereinstimmt, gelten folgende Regeln: Anwenden:

  • 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 für die beiden urlFetchWhitelist und addOns.common.openLinkUrlPrefixes . Sie können nur 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 Folgendem überein: URLs:

  • https://subdomain.example.com/foo
  • https://any.number.of.subdomains.example.com/foo

Das Präfix https://*.example.com/foo entspricht nicht dem folgenden Präfix 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. Für Beispiel: Die folgenden Präfixe verursachen einen Fehler, wenn sie in Ihrem wenn Sie versuchen, Folgendes zu speichern:

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