Bibliothèques

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

Un script qui utilise une bibliothèque ne s'exécute pas aussi rapidement que si tout le code était contenu dans un seul projet de script. Bien que les bibliothèques puissent faciliter le développement et la maintenance, utilisez-les avec parcimonie dans les projets où la vitesse est essentielle. Pour cette raison, l'utilisation de bibliothèques doit être limitée dans les modules complémentaires Google Workspace.

Accéder à une bibliothèque

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

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

Ajouter une bibliothèque à votre projet de script

À gauche de l'éditeur Apps Script, à côté de "Bibliothèques", cliquez sur Ajouter une bibliothèque .
Dans le champ "ID de script", collez l'ID de script de la bibliothèque.
Cliquez sur Rechercher.
Si une erreur s'affiche, assurez-vous d'avoir au moins accès en lecture seule au projet que vous essayez d'inclure.
Cliquez sur la liste déroulante Version et sélectionnez la version de la bibliothèque à utiliser.
Vérifiez si le nom d'identifiant par défaut est celui que vous souhaitez utiliser avec cette bibliothèque. Il s'agit du nom que votre script utilise pour faire référence à la bibliothèque. Par exemple, si vous le définissez sur Test, appelez une méthode de cette bibliothèque comme suit : Test.libraryMethod.
Si vous utilisez un nom d'identifiant qui correspond au nom d' un service déjà existant, tel que MailApp, ou d'une bibliothèque précédemment ajoutée, la bibliothèque que vous avez ajoutée le plus récemment remplace le service ou la bibliothèque existant.
Cliquez sur Ajouter.

Utiliser une bibliothèque

Utilisez la 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 immédiatement suivi d'un point pour afficher la liste des méthodes de la bibliothèque.

Ouvrez la documentation de référence d'une bibliothèque incluse en procédant comme suit :

À gauche de l'éditeur de script, à côté du nom de la bibliothèque, cliquez sur Plus > Ouvrir dans un nouvel onglet.

Supprimer une bibliothèque

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

Si une bibliothèque est supprimée par l'auteur, vous devez toujours la supprimer de votre liste de bibliothèques incluses.

Mettre à jour une bibliothèque

Modifiez la version de la bibliothèque ou mettez à jour son identifiant.

À gauche de l'éditeur, sous "Bibliothèques", cliquez sur le nom de la bibliothèque.
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 :

Créez un déploiement versionné de votre script.
Partagez au moins l'accès en lecture seule avec tous les utilisateurs potentiels de la bibliothèque.
Communiquez à ces utilisateurs l'ID de script, que vous trouverez sur la page Projet Paramètres .

Bonnes pratiques

Voici quelques consignes à suivre lorsque vous écrivez une bibliothèque :

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.
Pour que les utilisateurs de votre bibliothèque ne puissent pas voir (ni utiliser) une ou plusieurs méthodes de votre script, terminez le nom de la méthode par un trait de soulignement. Par exemple, myPrivateMethod_.
Seules les propriétés globales énumérables sont visibles par les utilisateurs de la bibliothèque. Cela inclut les déclarations de fonctions, les variables créées en dehors d'une fonction avec var et les propriétés explicitement définies 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 qui n'est pas accessible à vos utilisateurs.

Pour vous assurer que les utilisateurs de votre bibliothèque peuvent utiliser la saisie semi-automatique de l'éditeur de script et la documentation générée automatiquement, incluez une documentation de style 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) { ... }

Délimitation des ressources

Lorsque vous travaillez avec des bibliothèques, il existe deux types de ressources : partagées et non partagées. Une ressource partagée signifie que la bibliothèque et le script incluant ont un accès intégré à la même instance de la ressource. Le schéma suivant illustre une ressource partagée à l'aide de l'exemple des propriétés utilisateur :

Ressource partagée

Une ressource non partagée signifie que la bibliothèque et le script incluant n'ont accès intégré qu'à leur instance de la ressource. Toutefois, une bibliothèque peut fournir un accès à ses ressources non partagées en disposant de fonctions explicites qui fonctionnent sur celles-ci. Voici un exemple de fonction que vous incluez dans votre bibliothèque pour exposer ses propriétés de script :

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

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

Exemple de ressource non partagée

Ce tableau répertorie les ressources partagées et non partagées à titre de référence :

Ressource	Partagée*	Non partagée**	Remarques
Verrouiller			La même instance est visible pour tous les scripts incluant lorsqu'elle est créée dans la bibliothèque.
Propriétés du script			La même instance est visible pour tous les scripts incluant lorsqu'elle est créée dans la bibliothèque.
Cache			La même instance est visible pour tous les scripts incluant lorsqu'elle est créée 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 incluant script.
ScriptApp
UiApp
Propriétés utilisateur
Journalisation et transcription d'exécution
Sites, feuilles de calcul et autres conteneurs			Un appel à `getActive` renvoie le conteneur du script incluant.
MailApp et GmailApp
* Cela signifie que la bibliothèque ne possède pas sa propre instance de la fonctionnalité/ressource et utilise plutôt 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 utilisent la bibliothèque partagent et ont accès à cette même instance.

Tester une bibliothèque

Pour tester votre bibliothèque, utilisez le déploiement principal. Toute personne ayant accès en tant qu'éditeur au script peut utiliser le déploiement principal.

Vous devez toujours avoir au moins une version de la bibliothèque enregistrée.

Déboguer une bibliothèque

Lorsque vous déboguez un script qui inclut une bibliothèque, vous ne pouvez pas accéder au code de la bibliothèque ni y définir de points d'arrêt. Si vous essayez d'accéder à une fonction de bibliothèque en mode débogage, le débogueur ignore la fonction et passe à la ligne suivante du script appelant.

L'utilisation de HEAD (mode développement) pour la version de la bibliothèque n'active pas l'accès à la bibliothèque ni l'atteinte de points d'arrêt dans celle-ci.

Pour déboguer le code de la bibliothèque, utilisez l'une des méthodes suivantes :

Déboguer à partir du projet de bibliothèque : ouvrez le projet de script de la bibliothèque dans l'éditeur Apps Script. Pour tester les fonctions de la bibliothèque avec des arguments spécifiques, créez une fonction de "test" temporaire dans le projet de bibliothèque qui appelle vos fonctions de bibliothèque, puis exécutez cette fonction de test en mode débogage.
Journalisation : utilisez console.log() dans vos fonctions de bibliothèque pour générer des informations dans les journaux d'exécution. Lorsque la bibliothèque est appelée par un autre script, ces journaux s'affichent dans les journaux d'exécution du script appelant.