clasp : CLI Apps Script

1. Introduction

L'interface de ligne de commande (CLI) Apps Script, également appelée clasp, est un outil qui permet de créer, modifier et déployer des projets Apps Script en local. Vous pouvez ainsi créer et publier à partir de la ligne de commande des applications Web et des modules complémentaires pour des produits tels que Sheets, Docs, Forms et Slides. Vous pouvez développer Apps Script de deux manières : à l'aide de script.google.com ou en local sur votre ordinateur. Dans le cadre de cet atelier, nous allons examiner la seconde méthode, qui consiste à utiliser clasp, l'outil de ligne de commande pour Apps Script.

Fonctionnalités

• Développez en local. clasp vous permet de coder sur votre propre ordinateur, puis d'importer le code dans Apps Script lorsque vous avez terminé. Vous pouvez également télécharger des projets Apps Script existants, puis les modifier en local. Une fois que le code est disponible en local, vous pouvez utiliser vos outils de développement favoris tels que git pour travailler sur des projets Apps Script.
• Gérez plusieurs versions de déploiement. Créez, mettez à jour et visualisez différents déploiements de votre projet.
• Code de structure. clasp convertit automatiquement votre projet à plat sur script.google.com en dossiers. Exemple :

# On script.google.com:
├── tests/slides.gs
└── tests/sheets.gs

# Locally:
├── tests/
│   ├─ slides.gs
│   └─ sheets.gs

Points abordés

Cet atelier de programmation vous indique comment effectuer trois opérations clés avec clasp :

• Création de projets Apps Script
• Clonage, transfert et récupération de projets existants
• Gestion des déploiements de vos scripts

2. Premiers pas

Télécharger la CLI

La CLI Apps Script (clasp) nécessite l'installation de Node.js. Installez Node.js ici.

Remarque : clasp nécessite Node.js >= 20.0.0. Mettez à jour Node.js à l'aide des commandes suivantes :

sudo npm install n -g

sudo n latest

Une fois Node installé, installez la CLI au niveau global (alias clasp) :

npm i @google/clasp -g

3. Activer l'API Apps Script

Avant de pouvoir utiliser Clasp, vous devez activer l'API Apps Script de Google dans l'IDE Apps Script.

4. Connexion

Connexion

Essayons clasp. La seule commande à mémoriser est clasp.

clasp

Nous avons installé clasp globalement sur notre ordinateur. La commande devrait donc fonctionner partout dans votre système de fichiers.

Avant de commencer à utiliser l'outil de ligne de commande, nous devons nous connecter. Exécutez cette commande :

clasp login

ou si vous utilisez SSH :

clasp login --no-localhost

Vous êtes alors invité à vous connecter à Google. Tous les projets que vous créerez avec la CLI seront associés à ce compte Google.

5. Créer un projet

Créer un projet autonome

Commencez par créer un projet Google Apps Script autonome à l'aide de la commande suivante :

mkdir clasp_codelab;
cd clasp_codelab;
clasp create --title "Clasp Codelab"  --type standalone;

Vous venez de créer un projet Apps Script dans le dossier "clasp_codelab".

Remarque : La commande clasp create a créé un script autonome. Cela signifie que le projet n'est pas connecté à une feuille de calcul Google Sheets, un document Google Docs, un formulaire Google Forms ou une présentation Google. Toutefois, nous allons voir à la section suivante comment créer un script lié.

(Facultatif) Cloner un projet existant

Essayons de créer un script lié à un conteneur pour obtenir un module complémentaire Google Slides.

Pour ce faire, accédez à slides.google.com et créez une présentation. Renommez la présentation clasp Codelab Test. Dans la barre de menu Slides, dans le menu Extensions, sélectionnez Apps Script.

Votre projet Apps Script s'ouvre sur script.google.com.

Créez un répertoire pour votre projet et accédez-y à l'aide de la commande cd.

mkdir clasp_codelab_test
cd clasp_codelab_test

Pour cloner un projet, nous avons besoin du Script ID. Vous trouverez cet ID dans l'URL du projet Apps Script après /projects/. Copiez la valeur et collez-la dans la commande suivante :

clasp clone <scriptID>

Le résultat doit se présenter comme suit :

Vous avez maintenant téléchargé le projet dans votre répertoire actuel. Utilisez votre éditeur favori pour visualiser le contenu de Code.gs (fonction vide).

6. Extraire et transférer des fichiers

Modifier le code sur script.google.com

Maintenant que vous avez appris à cloner un projet, examinons comment récupérer et transférer des fichiers. Nous allons vous expliquer comment effectuer des modifications sur le cloud par le biais de script.google.com et comment les récupérer en local sur votre ordinateur. Ouvrons le script dans le cloud :

clasp open-script

Maintenant que nous avons accédé à l'éditeur en ligne, nous allons modifier du code que nous récupérerons par la suite à l'aide de clasp.

Pour créer un fichier Apps Script, à gauche de l'éditeur, à côté de Fichiers, cliquez sur Ajouter un fichier  > Script. Saisissez le nom utils/strings. Dans le fichier utils/strings.gs que vous venez de créer, remplacez le code par ce qui suit :

var world = "世界";

Dans Code.gs, remplacez le code existant par ce qui suit :

function hello() {
  Logger.log("Hello, " + world);
}

En haut, cliquez sur (Enregistrer).

Pour exécuter la fonction, en haut de l'éditeur, sélectionnez hello dans la liste déroulante des fonctions, puis cliquez sur Exécuter.

Le message d'accueil s'affiche en bas du journal d'exécution.

Modifier le code en local

Revenons à la ligne de commande où nous avons cloné le dernier projet. Vous pouvez constater que notre code n'est plus synchronisé avec l'éditeur en ligne. Pour corriger cela, récupérons le code de notre projet en ligne.

clasp pull

À présent, revenez au code. Vous devriez remarquer la présence d'un dossier pour nos utilitaires. La CLI clasp convertit automatiquement le caractère barre oblique / en dossiers sur le système de fichiers local.

Dans votre éditeur de texte favori, accédez à util/strings.gs, puis remplacez le nom de variable world par mondo. Mettez également à jour le fichier Code.gs en remplaçant world par mondo. Pour actualiser le code mis à jour sur script.google.com, transférez le code modifié.

clasp push

Et voilà ! Votre code est désormais mis à jour sur script.google.com.

clasp push remplace le code figurant sur script.google.com, tandis que clasp pull remplace tous les fichiers en local. Par conséquent, suivez les consignes ci-dessous :

• Ne modifiez pas le code en local et sur script.google.com simultanément.
• Utilisez un système de contrôle des versions, tel que git.

7. Gestion des versions et déploiement

clasp vous permet de gérer les versions et les déploiements. Commençons par clarifier ces deux notions :

• Version : "instantané" d'un projet de script. Une version peut être considérée comme une branche en lecture seule utilisée pour les déploiements.
• Déploiement : version publiée d'un projet de script (généralement sous la forme d'un module complémentaire ou d'une application Web). Un déploiement nécessite un numéro de version.

Créons une version de notre script :

clasp create-version "First version"

Nous pouvons déployer le script en remplaçant [version] par la chaîne de version enregistrée que nous avons créée :

clasp create-deployment 1 "First deployment"

La commande clasp deploy examine votre fichier manifeste et crée un déploiement avec version. Votre code est à présent déployé en tant qu'exécutable. Pour en savoir plus, consultez le guide relatif aux déploiements.

8. Et voilà !

Nous espérons que la CLI Apps Script est un outil simple d'emploi vous permettant de gérer des projets Apps Script.

Points abordés

• Création de projets Apps Script
• Cloner, transférer et récupérer des projets existants
• Gestion des déploiements de vos scripts

Clasp est disponible sur GitHub et accepte les nouvelles fonctionnalités et les correctifs.

Nous avons hâte de découvrir vos créations !