Fichiers manifestes pour les modules complémentaires Google Workspace

Un projet Apps Script utilise un fichier manifeste pour configurer certains détails du script et de son fonctionnement. Pour savoir comment afficher et modifier un fichier manifeste, consultez la section Fichiers manifestes.

Cette documentation décrit en détail la configuration d'un fichier manifeste pour un module complémentaire Google Workspace.

Structure du fichier manifeste des modules complémentaires Google Workspace

Les modules complémentaires Google Workspace utilisent le fichier manifeste du projet Apps Script pour définir plusieurs aspects de leur apparence et de leur comportement. Les propriétés du fichier manifeste des modules complémentaires Google Workspace sont organisées dans la section addOns de la structure des objets manifeste.

Exemple de configuration de fichier manifeste d'un 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, avec les aspects suivants:

• La section addOns.common du fichier manifeste définit le nom, l'URL du logo, les couleurs et d'autres 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 définit également les pages d'accueil spécifiques à Agenda, Drive, Docs, Sheets et Slides. Gmail utilise la page d'accueil par défaut.
• Les paramètres de l'exemple de fichier manifeste activent les éléments suivants :
  • Déclencheurs eventOpen et eventUpdated d'Agenda, et deux solutions de conférence Agenda.
  • Deux actions universelles.
  • Un onItemsSelectedTrigger Drive.
  • Une action de rédaction Gmail et un déclencheur contextuel.
  • Un fichier linkPreviewTrigger Docs. Pour en savoir plus sur ce déclencheur, consultez Prévisualiser les liens avec des chips intelligents.
  • Interfaces spécifiques aux fichiers pour Docs, Sheets et Slides
• Le champ oauthScopes définit les champs d'application des autorisations pour le projet (généralement requis pour les modules complémentaires).
• Le champ urlFetchWhitelist est un champ qui garantit que tous les points de terminaison récupérés correspondent à une liste spécifiée de préfixes d'URL HTTPS. Ce champ est facultatif pour les déploiements de test, mais obligatoire pour les déploiements. Pour en savoir plus, consultez Ajouter des URL à la liste d'autorisation.

Les liens figurant dans l'exemple permettent d'accéder aux descriptions de ce champ dans la documentation de référence sur les fichiers manifestes.

Remarque :Les fichiers manifestes incluent d'autres composants liés aux propriétés Apps Script. Les champs situés sous le champ addOns sont directement liés aux modules complémentaires Google Workspace. Cet exemple n'est qu'une partie d'un fichier manifeste complet. Il ne s'agit pas d'un fichier manifeste entièrement fonctionnel.

// 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/"
  ],
}

Ajouter des URL à la liste d'autorisation

Les listes d'autorisation vous permettent de désigner des URL spécifiques dont l'accès via votre script ou votre module complémentaire est pré-approuvé. Les listes d'autorisation contribuent à 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.

Les listes d'autorisation sont utilisées lorsque votre script ou votre module complémentaire effectue les actions suivantes:

• Récupère ou récupère des informations à partir d'un emplacement externe (tel que les points de terminaison HTTPS) à l'aide du service Apps Script UrlFetch. Pour ajouter des URL à la liste d'autorisation pour l'extraction, incluez le champ urlFetchWhitelist dans votre fichier manifeste.
• Ouvre ou affiche une URL en réponse à une action de l'utilisateur (obligatoire pour les modules complémentaires Google Workspace qui ouvrent ou affichent des URL externes à Google). Pour ajouter des URL à la liste d'autorisation, incluez le champ addOns.common.openLinkUrlPrefixes dans votre fichier manifeste.

Remarque :La liste blanche, telle qu'elle est utilisée dans urlFetchWhitelist, est un terme obsolète qui est synonyme de liste d'autorisation et est remplacé par celui-ci. Pour en savoir plus, consultez la section Écrire une documentation inclusive.

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 doivent répondre aux exigences suivantes:

• Chaque préfixe doit être une URL valide.
• Chaque préfixe doit utiliser https://, et non http://.
• Chaque préfixe doit correspondre à un domaine complet.
• Chaque préfixe doit comporter un chemin d'accès non vide. Par exemple, https://www.google.com/ est valide, mais pas https://www.google.com.
• Vous pouvez utiliser des caractères génériques pour établir une correspondance avec les préfixes de sous-domaine d'URL.
• Vous pouvez utiliser un seul caractère générique * dans le champ addOns.common.openLinkUrlPrefixes pour établir une correspondance avec tous les liens. Toutefois, cela n'est pas recommandé, car cela peut exposer les données d'un utilisateur à des risques et prolonger le processus d'examen des modules complémentaires. N'utilisez un caractère générique que si votre module complémentaire le nécessite.

Pour déterminer si une URL correspond à un préfixe de la liste d'autorisation, les règles suivantes s'appliquent:

• La mise en correspondance des chemins 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 qu'il s'agit d'un enfant du préfixe, il s'agit d'une 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 établir une correspondance avec un sous-domaine dans les champs urlFetchWhitelist et addOns.common.openLinkUrlPrefixes. Vous ne pouvez pas utiliser plusieurs caractères génériques pour établir une correspondance avec plusieurs sous-domaines. Le caractère générique doit représenter le préfixe de début de l'URL.

Par exemple, le préfixe https://*.example.com/foo correspond aux URL suivantes:

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

Le préfixe https://*.example.com/foo ne correspond pas aux URL suivantes:

• https://subdomain.example.com/bar (non-concordance du suffixe)
• https://example.com/foo (au moins un sous-domaine doit être présent)

Certaines règles de préfixe sont appliquées lorsque vous essayez d'enregistrer votre fichier manifeste. Par exemple, les préfixes suivants génèrent une erreur s'ils sont présents dans le fichier manifeste lorsque vous tentez d'enregistrer:

• https://*.*.example.com/foo (les caractères génériques multiples sont interdits)
• https://subdomain.*.example.com/foo (les caractères génériques doivent être utilisés comme préfixes)