Bibliothèques

Une bibliothèque est un projet de script dont les fonctions peuvent être réutilisées dans d'autres scripts.

Accéder à une bibliothèque

Pour inclure une bibliothèque dans votre projet, vous devez y avoir au moins accès au niveau de la vue. Si vous n'êtes pas l'auteur de la bibliothèque que vous souhaitez inclure, contactez-le et demandez-lui de vous accorder l'accès.

Vous avez besoin de l'ID de script de la bibliothèque que vous souhaitez inclure. Une fois que vous avez accès à la bibliothèque, vous pouvez trouver l'ID de script sur la page Paramètres du projet .

Ajouter une bibliothèque à votre projet de script

  1. À gauche de l'éditeur Apps Script, à côté de"Bibliothèques", cliquez sur Ajouter une bibliothèque .
  2. Dans le champ "ID du script", collez l'ID de script de la bibliothèque.
  3. Cliquez sur Rechercher.
  4. Cliquez sur le menu déroulant Version, puis sélectionnez la version de la bibliothèque à utiliser.
  5. Vérifiez si le nom par défaut est celui que vous souhaitez utiliser avec cette bibliothèque. Il s'agit du nom que votre script utilise pour référencer la bibliothèque. Par exemple, si vous la définissez sur Test, vous pouvez appeler une méthode de cette bibliothèque comme suit: Test.libraryMethod().
  6. Cliquez sur Ajouter.

Utiliser une bibliothèque

Utilisez votre bibliothèque incluse comme vous le feriez avec un service par défaut. Par exemple, si Test est l'identifiant de votre bibliothèque, saisissez Test suivi d'un point pour afficher la liste des méthodes dans la bibliothèque.

Pour accéder à la documentation de référence d'une bibliothèque incluse, procédez comme suit:

À gauche de l'éditeur de script, à côté du nom de la bibliothèque, cliquez sur More > Open in a new tab (Plus > Ouvrir dans un nouvel onglet).

Supprimer une bibliothèque

À gauche de l'éditeur de scripts, à côté du nom de la bibliothèque, cliquez sur Plus > Supprimer > Supprimer la bibliothèque.

Mettre à jour une bibliothèque

Vous pouvez modifier la version de la bibliothèque ou mettre à jour son identifiant.

  1. À gauche de l'éditeur, sous "Bibliothèques", cliquez sur le nom de la bibliothèque.
  2. Apportez les modifications nécessaires, puis cliquez sur Enregistrer.

Créer et partager une bibliothèque

Pour utiliser et partager votre projet de script en tant que bibliothèque, procédez comme suit :

  1. Créez un déploiement avec versions gérées de votre script.
  2. Partagez au moins l'accès au niveau de la vue avec tous les utilisateurs potentiels de la bibliothèque.
  3. Attribuez à ces utilisateurs l'ID de script, disponible sur la page Paramètres du projet .

Bonnes pratiques

Voici quelques consignes à suivre lors de l'écriture d'une bibliothèque:

  1. Choisissez un nom explicite pour votre projet, car il sera utilisé comme identifiant par défaut lorsque votre bibliothèque sera incluse par d'autres utilisateurs.
  2. Si vous souhaitez que les utilisateurs de votre bibliothèque n'aient pas accès à une ou plusieurs méthodes de votre script, vous pouvez terminer le nom de la méthode par un trait de soulignement. Par exemple, myPrivateMethod_().
  3. Seules les propriétés globales énumérables sont visibles pour les utilisateurs de la bibliothèque. Cela inclut les déclarations de fonction, les variables créées en dehors d'une fonction avec var et les propriétés définies explicitement sur l'objet global. Par exemple, Object.defineProperty() avec enumerable défini sur false crée un symbole que vous pouvez utiliser dans votre bibliothèque, mais vos utilisateurs ne peuvent pas y accéder.
  4. Si vous souhaitez que les utilisateurs de votre bibliothèque utilisent la saisie semi-automatique de l'éditeur de scripts et la documentation générée automatiquement, vous devez disposer d'une documentation de type JSDoc pour toutes vos fonctions. Exemple :

    /**
     * Raises a number to the given power, and returns the result.
     *
     * @param {number} base the number we're raising to a power
     * @param {number} exp the exponent we're raising the base to
     * @return {number} the result of the exponential calculation
     */
    function power(base, exp) { ... }
    

Portée des ressources

Il existe deux types de ressources lorsque vous utilisez des bibliothèques: partagées et non partagées. Une ressource partagée signifie que la bibliothèque et le script d'inclusion ont un accès intégré à la même instance de la ressource. Le schéma suivant illustre une ressource partagée utilisant l'exemple de propriétés utilisateur:

Ressource partagée

Une ressource non partagée signifie que la bibliothèque et le script inclus n'ont un accès intégré qu'à leur instance de la ressource. Cependant, une bibliothèque peut fournir l'accès à ses ressources non partagées en utilisant des fonctions explicites. Voici un exemple de fonction que vous pouvez inclure dans votre bibliothèque pour exposer ses propriétés de script:

  function getLibraryProperty(key) {
    return ScriptProperties.getProperty(key);
  }

Le schéma suivant illustre une ressource non partagée utilisant l'exemple de propriétés de script:

Ressource non partagée

Ce tableau présente les ressources partagées et non partagées à titre d'information:

Ressource Partagé* Non partagé** Remarques
Verrouiller La même instance est visible par tous les scripts, y compris lorsqu'ils sont créés dans la bibliothèque.
Propriétés du script La même instance est visible par tous les scripts, y compris lorsqu'ils sont créés dans la bibliothèque.
Cache La même instance est visible par tous les scripts, y compris lorsqu'ils sont créés dans la bibliothèque.
Déclencheurs Les déclencheurs simples créés dans la bibliothèque ne sont pas déclenchés par le script "Inclure".
Application de script
UI
Propriétés utilisateur
Enregistreur et transcription d'exécution
Sites, feuilles de calcul et autres conteneurs Un appel à getActive() renvoie le conteneur du script "include".
MailApp et GmailApp
* Cela signifie que la bibliothèque ne dispose pas de sa propre instance de la fonctionnalité/ressource, mais utilise celle créée par le script qui l'a appelée.
** Cela signifie que la bibliothèque possède sa propre instance de la ressource/fonctionnalité, et que tous les scripts qui l'utilisent partagent la même instance.

Tester une bibliothèque

Pour tester votre bibliothèque, utilisez le déploiement "Head". Toute personne disposant d'un accès de niveau éditeur au script peut utiliser le déploiement "Head".

Déboguer une bibliothèque

Lorsque vous utilisez le débogueur dans un projet qui inclut une bibliothèque, vous pouvez accéder à une fonction de la bibliothèque incluse. Le code s'affiche dans le débogueur en mode lecture seule et dans la version appropriée.