clasp : CLI Apps Script

1. Introduction

La CLI Apps Script, ou clasp, est un outil qui vous permet de créer, de modifier et de 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. Nous allons découvrir la deuxième option, qui consiste à utiliser clasp, l'outil de ligne de commande pour Apps Script.

Fonctionnalités

• Développement local. clasp vous permet d'écrire du code sur votre propre ordinateur et de l'importer vers 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.
• Structurez le code. 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 explique comment effectuer trois activités 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 6.0.0 ou version ultérieure. Installez Node.js ici.

Remarque: clasp utilise Node.js v6.0.0 ou version ultérieure. Mettez à jour Node.js à l'aide des commandes suivantes:

sudo npm install n -g

sudo n latest

Une fois que vous disposez de Node, installez la CLI de manière globale (alias clasp):

npm i @google/clasp -g

3. Connexion

Connexion

Essayons clasp ! La seule commande à retenir est clasp.

clasp

Nous avons installé clasp de manière globale 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.

4. 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 associé à une feuille de calcul Google Sheets, un document Google Docs, un formulaire ou une présentation. 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é au conteneur pour un module complémentaire Google Slides.

Pour ce faire, accédez à la page slides.google.com et créez une présentation. Remplacez le nom de la présentation par clasp Codelab Test (Test de l'atelier de programmation clasp). Dans l'en-tête, sous Tools (Outils), appuyez sur Script Editor (Éditeur de scripts).

Votre projet Apps Script s'ouvre alors sur script.google.com. Pour cloner un projet, nous avons besoin de 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 l'éditeur de votre choix pour afficher le contenu de Code.gs (une fonction vide).

5. Extraction et Transfert de 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 dans le cloud via script.google.com et les récupérer en local sur votre ordinateur. Ouvrons le script dans le cloud :

clasp open

Maintenant que nous sommes dans l'éditeur en ligne, nous allons modifier du code en ligne que nous récupérerons plus tard à l'aide de clasp.

Pour créer un fichier Apps Script, à gauche de l'éditeur, à côté de Fichiers, cliquez sur Ajouter un fichier > d'application. 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, sélectionnez hello dans la liste déroulante des fonctions en haut de l'éditeur, 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 projet pour la dernière fois. 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 l'existence 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 préféré, accédez à util/strings.gs et remplacez le nom de variable world par mondo. Mettez également à jour Code.gs en remplaçant world par mondo. Pour mettre à jour le code mis à jour sur script.google.com, transférez le code modifié.

clasp push

Et voilà ! Votre code a été mis à jour le script.google.com.

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

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

6. 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 version "First version"

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

clasp deploy 1 "First deployment"

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

7. Et voilà !

Nous espérons que la CLI Apps Script est un outil simple qui vous aidera à gérer les projets Apps Script.

Points abordés

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

Fermoir est disponible sur GitHub, et n'hésitez pas à découvrir les nouvelles fonctionnalités et les nouveaux correctifs.

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