Les annotations spéciales dans Google Apps Script

Google Apps Script propose plusieurs annotations spéciales qui permettent de contrôler et d’améliorer le comportement des scripts. Elles offrent des fonctionnalités de sécurité, de documentation, et facilitent la gestion des autorisations. Dans cet article, nous allons explorer ces annotations et comprendre comment elles peuvent être utiles dans vos projets.

1. Qu’est-ce qu’une annotation spéciale ?

Une annotation spéciale est un commentaire spécifique dans le code, introduit par un symbole @. Ces annotations sont traitées par Google Apps Script et influencent la manière dont le script se comporte. Certaines annotations sont directement liées aux permissions, tandis que d’autres sont utilisées pour la documentation ou la lisibilité du code.

Utiliser des annotations appropriées permet non seulement d’améliorer la sécurité et la performance de vos scripts, mais aussi de faciliter leur maintenance et leur compréhension par d’autres développeurs.

2. Les annotations les plus courantes

@OnlyCurrentDoc

Cette annotation limite l’accès du script au document ou à la feuille de calcul en cours. Elle empêche le script d’interagir avec d’autres fichiers dans Google Drive.

Exemple :

/**
 * @OnlyCurrentDoc
 */
function monScript() {
  const feuille = SpreadsheetApp.getActiveSpreadsheet();
  // Le script est limité à cette feuille de calcul.
}

@NotOnlyCurrentDoc

Contrairement à @OnlyCurrentDoc, cette annotation permet au script d’accéder à d’autres documents ou fichiers Google Drive. Elle est nécessaire si vous devez manipuler plusieurs documents.

Exemple :

/**
 * @NotOnlyCurrentDoc
 */
function accederAutresDocuments() {
  const fichiers = DriveApp.getFiles();
  // Le script peut accéder à d'autres fichiers dans Google Drive.
}

@SuppressWarnings

Cette annotation sert à ignorer certains avertissements générés par l’éditeur. Elle peut être utilisée pour suspendre les avertissements liés à des pratiques de codage spécifiques, que vous jugez sans danger dans votre cas.

Exemple :

/**
 * @SuppressWarnings("UnreachableCode")
 */
function ignorerAvertissements() {
  return;
  Logger.log("Cette ligne ne sera jamais atteinte.");
}

@CustomFunction

Cette annotation permet de définir une fonction personnalisée que l’utilisateur pourra appeler directement depuis une cellule dans Google Sheets, comme une fonction standard telle que =SOMME().

Exemple :

/**
 * @CustomFunction
 */
function sommePersonnalisee(a, b) {
  return a + b;
}

3. Pourquoi utiliser des annotations ?

Les annotations sont essentielles pour rendre vos scripts plus robustes, sécurisés et compréhensibles. Elles apportent plusieurs avantages :

1. Sécurité : Grâce à @OnlyCurrentDoc, vous pouvez empêcher le script d’accéder à des fichiers sensibles en dehors du document en cours.

2. Documentation : Avec des annotations comme @Param et @Return, vous facilitez la compréhension de vos fonctions pour les autres développeurs.

3. Gestion des avertissements : @SuppressWarnings permet d’ignorer certains avertissements lorsque vous savez que le code est correct mais que l’éditeur de script l’interprète comme risqué.

4. Améliorations avec des annotations

Optimiser la sécurité avec @OnlyCurrentDoc

Lorsque votre script est destiné à n’interagir qu’avec un seul document, l’annotation @OnlyCurrentDoc devient indispensable. Elle garantit que le script n’aura pas accès à d’autres ressources, ce qui réduit considérablement le risque de fuites de données.

Simplifier l’intégration avec @CustomFunction

En utilisant @CustomFunction, vous pouvez enrichir Google Sheets avec des fonctions personnalisées. Cela offre plus de flexibilité aux utilisateurs, car ils peuvent exécuter des calculs complexes directement depuis une cellule.

5. Autres annotations utiles

@Deprecated

L’annotation @Deprecated est utilisée pour marquer une fonction comme obsolète. Elle indique qu’une fonction ne doit plus être utilisée et qu’elle pourrait être retirée dans une future version du script. Cela est utile lorsque vous souhaitez maintenir la compatibilité avec de vieux scripts tout en signalant aux utilisateurs et aux développeurs que cette partie du code est à éviter.

@Param et @Return

Ces annotations permettent de documenter les paramètres et les valeurs de retour des fonctions. Cela améliore la lisibilité et aide les autres développeurs à comprendre rapidement le rôle de chaque paramètre.

Exemple :

/**
 * Ajoute deux nombres.
 * @param {number} a Le premier nombre.
 * @param {number} b Le second nombre.
 * @return {number} La somme des deux nombres.
 */
function additionner(a, b) {
  return a + b;
}

Les annotations spéciales dans Google Apps Script sont des outils puissants pour optimiser vos scripts et en assurer la sécurité. Utilisées correctement, elles peuvent non seulement faciliter la gestion des autorisations et des avertissements, mais aussi améliorer la lisibilité et la maintenabilité de votre code.

Que vous développiez des scripts pour un usage personnel ou pour d’autres utilisateurs, prendre le temps d’ajouter des annotations vous aidera à écrire un code plus propre, sécurisé et facile à comprendre. Expérimentez avec ces annotations pour améliorer vos projets Google Apps Script !

---

Soutenez mon travail

Si cet article vous a été utile et que vous souhaitez soutenir mon travail, vous pouvez me remercier en faisant un don via PayPal. Chaque contribution est grandement appréciée et m’aide à continuer à partager des astuces et conseils sur ce blog. Merci pour votre soutien !

L’Atelier Informatique vous accompagne dans vos projets technologiques en vous proposant des tutoriels et des solutions pour optimiser vos tâches quotidiennes