Cette page a été traduite par l'API Cloud Translation.

Fichiers manifestes pour les modules complémentaires Google Workspace

Un module complémentaire utilise un fichier manifeste pour configurer certains détails sur l'application et son fonctionnement.

Cette documentation explique en détail comment configurer 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 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 d'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 des points de terminaison HTTP, consultez la page 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:

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 également des 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 d'agenda eventOpen et eventUpdated.
- (Apps Script uniquement) Deux solutions de conférence Agenda.
- Deux actions universelles.
- Un onItemsSelectedTrigger Drive.
- Action de rédaction Gmail et déclencheur contextuel.
- Un objet linkPreviewTriggersDocs. Pour en savoir plus sur ce déclencheur, consultez Prévisualiser les liens avec des chips intelligents.
- Un objet createActionTriggers Docs. Pour en savoir plus sur ce déclencheur, consultez la section Créer des ressources tierces à partir du menu @.
- Interfaces spécifiques aux fichiers pour Docs, Sheets et Slides
Le champ oauthScopes définit les niveaux d'autorisation pour le projet (généralement requis pour les modules complémentaires).
(Apps Script uniquement) 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. Pour en savoir plus, consultez Ajouter des URL à la liste d'autorisation.

Les liens de l'exemple redirigent vers les descriptions de ce champ dans la documentation de référence du fichier manifeste correspondant pour les modules complémentaires Apps Script et HTTP 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 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 lors de la création d'un déploiement avec versions gérées.

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

Récupère ou récupère des informations à partir d'un emplacement externe (par exemple, 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 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 le 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 doivent répondre aux exigences 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é. 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-domaine des 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, mais cela n'est pas recommandé, car cela peut exposer les données d'un utilisateur à un risque et prolonger le processus d'examen complémentaire. N'utilisez un caractère générique que 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 s'appliquent:

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 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 l'URL au début.

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 s'appliquent 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 (utilisez des caractères génériques comme préfixe)