Fichiers manifestes pour les modules complémentaires Google Workspace

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Un projet Apps Script utilise un fichier manifest pour configurer certains détails sur le script et son fonctionnement. Pour savoir comment afficher et modifier un fichier manifeste, consultez la section 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 pour les 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 l'apparence et du comportement des modules complémentaires. Les propriétés de manifeste des modules complémentaires Google Workspace sont organisées dans la section addOns de la structure d'objet de fichier manifeste.

Exemple de configuration du fichier manifeste d'un module complémentaire Google Workspace

L'exemple de fichier manifeste ci-dessous présente la section d'un fichier manifeste qui définit un module complémentaire Google Workspace, y compris 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 du module complémentaire.
  • Le fichier manifeste définit une page d'accueil commune, mais aussi des pages d'accueil spécifiques à Agenda, Drive, Docs, Sheets et Slides. Gmail utilise la page d'accueil par défaut.
  • Les exemples de paramètres de fichier manifeste permettent les opérations suivantes :
    • Déclencheurs eventOpenet eventUpdatedGoogle Agenda, et deuxsolutions de conférenceGoogle Agenda.
    • Deux actions universelles.
    • Un Drive onItemsSelectedTrigger.
    • Action de rédaction Gmail et déclencheur contextuel.
    • 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 définit un préfixe d'URL HTTPS, qui garantit que tous les points de terminaison récupérés correspondent au préfixe (généralement requis pour les modules complémentaires). Pour en savoir plus, consultez URL à la liste d'autorisation.

Les liens de l'exemple redirigent les utilisateurs vers les descriptions de ce champ dans la documentation du fichier manifeste de référence.

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

    "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"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ],
}

Ajouter des URL à la liste d'autorisation

Vous pouvez avoir besoin que votre script ou votre module complémentaire ouvre une URL en réponse à une action de l'utilisateur. Vous pouvez également avoir besoin que votre script ou votre module complémentaire récupère des informations à partir d'un emplacement externe à l'aide du service UrlFetch Apps Script. Dans les deux cas, vous devez ajouter à la liste d'autorisation les URL que vous ouvrez ou récupérez dans le fichier manifeste du projet.

La liste d'autorisation est le processus dans lequel vous désignez des URL spécifiques dont l'accès est autorisé par votre script ou votre module complémentaire. Cette exigence permet de protéger les données utilisateur. Si 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. Google Workspace Les modules complémentaires exigent que les URL soient ajoutées à la liste d'autorisation avant de pouvoir être récupérées ou ouvertes.

Vous pouvez ajouter une URL à la liste d'autorisation pour l'extraction en l'ajoutant ou en ajoutant un préfixe correspondant au champ manifeste urlFetchWhitelist. Pour Google Workspaceles projets complémentaires, vous pouvez ajouter une URL à la liste d'autorisation pour l'ouverture en l'ajoutant ou en ajoutant un préfixe correspondant au champ manifeste addOns.common.openLinkUrlPrefixes.

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 être associé à un domaine complet.
  • Un préfixe doit être renseigné pour chaque préfixe. Par exemple, https://www.google.com/ est valide, mais https://www.google.com ne l'est pas.
  • Vous pouvez utiliser des caractères génériques pour établir une correspondance avec les préfixes de sous-domaines des URL.
  • Un seul caractère générique * peut être utilisé dans le champ addOns.common.openLinkUrlPrefixes pour correspondre à tous les liens, mais 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 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 faire correspondre un sous-domaine à la fois pour 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. Il doit représenter le préfixe 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-correspondance 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 votre fichier manifeste lorsque vous tentez d'enregistrer:

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