Un module complémentaire utilise un fichier fichier manifeste pour configurer certains détails sur l'application et son fonctionnement.
Cette documentation décrit en détail la configuration d'un fichier manifeste pour du module complémentaire Google Workspace.
Structure du fichier manifeste pour les modules complémentaires Google Workspace
Les modules complémentaires Google Workspace utilisent le fichier manifeste pour définir plusieurs aspects modules complémentaires leur apparence et leur comportement.
Les propriétés du fichier manifeste pour les modules complémentaires Google Workspace sont les suivantes :
organisées dans la section addOns
de la structure de l'objet du fichier manifeste.
- Pour en savoir plus sur les fichiers manifestes Apps Script, consultez la section Structure du fichier manifeste.
- Pour en savoir plus sur les fichiers manifestes des modules complémentaires créés avec
Pour les points de terminaison HTTP, reportez-vous à la ressource REST:
projects.deployments
.
Exemple de configuration du fichier manifeste du module complémentaire Google Workspace
L'exemple de fichier manifeste suivant montre la section d'un fichier manifeste qui définit un module complémentaire Google Workspace, y compris les aspects suivants :
addOns.common
du fichier manifeste définit le nom, l'URL du logo, les couleurs paramètres généraux indépendants de l'hôte pour le module complémentaire.- Le fichier manifeste définit une page d'accueil commune, mais aussi Agenda, Drive, Docs, Sheets et Slides. Gmail utilise la page d'accueil par défaut.
- Les paramètres de l'exemple de fichier manifeste permettent les éléments suivants :
- Déclencheurs d'agenda
eventOpen
eteventUpdated
. - (Apps Script uniquement) Deux solutions de conférence Agenda.
- Deux actions universelles.
- Un
onItemsSelectedTrigger
Drive. - Action de rédaction Gmail et déclencheur contextuel.
- Objet
linkPreviewTriggers
Docs. Pour en savoir plus sur ce déclencheur, consultez Prévisualiser les liens avec des chips intelligents. - Objet
createActionTriggers
Docs. Pour en savoir plus sur ce déclencheur, consultez Créer des ressources tierces à partir du menu @. - Des interfaces spécifiques aux fichiers pour Docs, Sheets, et Slides.
- Déclencheurs d'agenda
- Le champ
oauthScopes
définit les champs d'autorisation du projet (généralement requis pour les modules complémentaires). - (Apps Script uniquement)
urlFetchWhitelist
est un champ qui garantit que tous les points de terminaison récupérés correspondent à liste des préfixes d'URL HTTPS. Pour en savoir plus, consultez la section Ajouter des URL à la liste d'autorisation.
Les liens de l'exemple pointent vers les descriptions de ce champ dans les champs Documentation de référence du fichier manifeste pour Apps Script et HTTP Modules complémentaires Google Workspace.
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" ] }
URL de la liste d'autorisation
Vous utilisez des listes d'autorisation pour désigner des URL spécifiques qui sont préapprouvées pour l'accès par votre script ou votre module complémentaire. Les listes d'autorisation aident à protéger les données utilisateur. Lorsque vous définissez une liste d'autorisation, les projets de script ne peuvent pas accéder aux URL qui n'ont pas été ajoutées à la liste d'autorisation.
Ce champ est facultatif lorsque vous installez un déploiement test, mais obligatoire lorsque vous créez un déploiement avec versions gérées.
Vous utilisez des listes d'autorisation lorsque votre script ou votre module complémentaire effectue les actions suivantes :
- Récupère ou extrait des informations à partir d'un emplacement externe (tels que des points de terminaison HTTPS) à l'aide du service
UrlFetch
d'Apps Script. Pour ajouter des URL à la liste d'autorisation pour l'extraction, incluez le champurlFetchWhitelist
dans votre fichier manifeste. - Ouvre ou affiche une URL en réponse à une action de l'utilisateur (obligatoire pour
Modules complémentaires Google Workspace qui ouvrent ou affichent des URL externes à
Google). Pour ajouter des URL à la liste d'autorisation d'ouverture, incluez le champ
addOns.common.openLinkUrlPrefixes
dans votre fichier manifeste.
Ajouter des préfixes à votre liste d'autorisation
Lorsque vous spécifiez des listes d'autorisation dans votre fichier manifeste (en incluant le champ addOns.common.openLinkUrlPrefixes
ou urlFetchWhitelist
), vous devez inclure une liste de préfixes d'URL. Les préfixes que vous ajoutez au fichier manifeste
Vous devez remplir les conditions suivantes:
- Chaque préfixe doit correspondre à une URL valide.
- Chaque préfixe doit utiliser
https://
, et nonhttp://
. - Chaque préfixe doit comporter un domaine complet.
- Chaque préfixe doit avoir un chemin non vide. Exemple :
https://www.google.com/
est valide, mais pashttps://www.google.com
. - Vous pouvez utiliser des caractères génériques pour établir une correspondance avec les préfixes de sous-domaine des URL.
- Un seul caractère générique
*
peut être utilisé dans leaddOns.common.openLinkUrlPrefixes
pour correspondre à tous les liens, mais cela n'est pas recommandé, car cela peut exposer une les données de l'utilisateur à risque et peut d'examen des modules complémentaires. Uniquement utilisez un caractère générique si la fonctionnalité du module complémentaire l'exige.
Pour déterminer si une URL correspond à un préfixe de la liste d'autorisation, les règles suivantes appliquer:
- La correspondance de chemin d'accès est sensible à la casse.
- Si le préfixe est identique à l'URL, il s'agit d'une correspondance.
- Si l'URL est identique ou un enfant du préfixe, il y a correspondance.
Par exemple, le préfixe https://example.com/foo
correspond aux URL suivantes :
https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar
Utiliser des caractères génériques
Vous pouvez utiliser un seul caractère générique (*
) pour faire correspondre un sous-domaine pour les champs urlFetchWhitelist
et addOns.common.openLinkUrlPrefixes
. Vous ne pouvez pas utiliser plusieurs caractères génériques pour faire correspondre plusieurs sous-domaines. Le caractère générique doit représenter le préfixe initial de l'URL.
Par exemple, le préfixe https://*.example.com/foo
correspond à ce qui suit :
URL:
https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo
Le préfixe https://*.example.com/foo
ne correspond pas à ce qui suit
URL:
https://subdomain.example.com/bar
(incompatibilité de suffixe)https://example.com/foo
(au moins un sous-domaine doit être présent)
Certaines des règles de préfixe sont appliquées lorsque vous essayez d'enregistrer votre fichier manifeste. Pour exemple, les préfixes suivants provoquent une erreur s'ils sont présents dans votre manifeste lorsque vous tentez d'enregistrer:
https://*.*.example.com/foo
(plusieurs caractères génériques sont interdits)https://subdomain.*.example.com/foo
(vous devez utiliser des caractères génériques comme préfixe)