Fichiers manifestes pour les modules complémentaires Google Workspace

Un module complémentaire utilise un fichier manifest 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.

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 des modules complémentaires 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 activent les éléments suivants: <ph type="x-smartling-placeholder">
  • Le champ oauthScopes définit les champs d'application des autorisations pour le projet (généralement requis pour des 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 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"
  ]
}

Ajouter des URL à la liste d'autorisation

Les listes d'autorisation vous permettent de désigner des URL spécifiques préapprouvées par votre script ou module complémentaire. Les listes d'autorisation contribuent à protéger les utilisateurs data; lorsque vous définissez une liste d'autorisation, les projets de script ne peuvent pas accéder aux URL comportant ne figure pas sur la liste d'autorisation.

Ce champ est facultatif lorsque vous installez un déploiement test, mais obligatoire si vous créez un déploiement avec versions gérées.

Vous utilisez des listes d'autorisation lorsque votre script ou module complémentaire exécute les actions suivantes:

  • Récupère ou récupère des informations à partir d'un emplacement externe (HTTPS, par exemple). points de terminaison) à l'aide d'Apps Script UrlFetch Google Cloud. 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 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 vos 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 paramètre 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 non http://.
  • Chaque préfixe doit comporter un domaine complet.
  • Le chemin d'accès de chaque préfixe doit être renseigné. 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 des URL.
  • Un seul caractère générique * peut être utilisé dans le addOns.common.openLinkUrlPrefixes pour correspondre à tous les liens, mais cela n'est pas recommandé, car cela peut exposer une les données de l'utilisateur et peut prolonger 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 figurant sur la liste d'autorisation, les règles suivantes appliquer:

  • La 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 établir une correspondance avec un sous-domaine à la fois pour les urlFetchWhitelist et addOns.common.openLinkUrlPrefixes . Vous ne pouvez pas utiliser plus d'un caractère générique pour correspondre à plusieurs sous-domaines. Le caractère générique doit représenter le préfixe 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 (non-concordance du suffixe)
  • https://example.com/foo (au moins un sous-domaine doit être présent)

Certaines règles de préfixe s'appliquent 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)