clasp - Interfaccia a riga di comando di Apps Script

1. Introduzione

L'interfaccia a riga di comando di Apps Script, o clasp, è uno strumento che consente di creare, modificare ed eseguire il deployment dei progetti Apps Script a livello locale. Consente di creare e pubblicare applicazioni web e componenti aggiuntivi per prodotti quali Fogli, Documenti, Moduli e Presentazioni dalla riga di comando. Esistono due modi per sviluppare Apps Script: utilizzando script.google.com o localmente sul computer. Impareremo a utilizzare clasp, lo strumento a riga di comando per Apps Script.

Funzionalità

• Sviluppa a livello locale. clasp ti consente di scrivere codice sul tuo computer e caricarlo su Apps Script al termine. Puoi anche scaricare i progetti Apps Script esistenti e modificarli localmente. Una volta che il codice è locale, puoi utilizzare i tuoi strumenti di sviluppo preferiti, come git, per lavorare sui progetti Apps Script.
• Gestisci le versioni di deployment. Crea, aggiorna e visualizza più deployment del tuo progetto.
• Structure Code. clasp converte automaticamente il tuo progetto piatto su script.google.com in cartelle. Ad esempio:

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

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

Obiettivi didattici

Questo codelab ti mostrerà come svolgere tre attività chiave con clasp:

• Come creare nuovi progetti Apps Script
• Come clonare, estrarre e inviare progetti esistenti
• Come gestire i deployment degli script

2. Per iniziare

Download dell'interfaccia a riga di comando

La CLI di Apps Script (clasp) richiede l'installazione di Node.js. Installa Node.js qui.

Nota: clasp richiede Node.js >= 20.0.0. Aggiorna Node.js con questi comandi:

sudo npm install n -g

sudo n latest

Una volta installato Node, installa la CLI a livello globale (alias clasp):

npm i @google/clasp -g

3. Abilita l'API Apps Script

Prima di poter utilizzare Clasp, devi abilitare l'API Apps Script nell'IDE Apps Script.

4. Accedi

Accedi

Proviamo chiusura. L'unico comando che devi ricordare è clasp.

clasp

Abbiamo installato clasp a livello globale sul nostro computer, quindi il comando dovrebbe funzionare ovunque nel file system.

Prima di iniziare a utilizzare lo strumento a riga di comando, dobbiamo accedere. Esegui questo comando:

clasp login

o se utilizzi SSH:

clasp login --no-localhost

A questo punto, ti viene chiesto di accedere a Google. Tutti i progetti che crei con la CLI sono associati a questo Account Google.

5. Crea un nuovo progetto

Crea un progetto autonomo

Inizia creando un progetto Google Apps Script autonomo con il seguente comando:

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

Hai appena creato un progetto Apps Script nella cartella "clasp_codelab".

Nota: il comando clasp create ha creato uno script autonomo. Ciò significa che il progetto non è collegato a un foglio, un documento, un modulo o una presentazione Google. Tuttavia, vedremo come creare uno script associato nella sezione successiva.

(Alternativa facoltativa) Clona un progetto esistente

Proviamo a creare uno script associato al contenitore per un componente aggiuntivo di Presentazioni Google.

A tale scopo, vai alla pagina slides.google.com e crea una nuova presentazione. Modifica il nome della presentazione in "clasp Codelab Test". Nella barra dei menu di Presentazioni, nel menu Estensioni, scegli "Apps Script".

Si aprirà il progetto Apps Script all'indirizzo script.google.com.

Crea una nuova directory per il tuo progetto e cd.

mkdir clasp_codelab_test
cd clasp_codelab_test

Per clonare un progetto, abbiamo bisogno di Script ID. Puoi trovare questo ID nell'URL del progetto Apps Script dopo /projects/. Copia il valore e incollalo nel seguente comando:

clasp clone <scriptID>

L'output dovrebbe essere simile al seguente:

Ora hai scaricato il progetto nella directory corrente. Utilizza il tuo editor preferito per visualizzare i contenuti di Code.gs (una funzione vuota).

6. Recuperare e inviare file

Modificare il codice su script.google.com

Ora che puoi clonare un progetto, vediamo come estrarre e inviare file. Ti guideremo attraverso i passaggi per modificare i file sul cloud tramite script.google.com e scaricarli in locale sul tuo computer. Apriamo lo script nel cloud:

clasp open-script

Ora che ci troviamo nell'editor online, modificheremo online un codice che recupereremo in un secondo momento utilizzando clasp.

Per creare un nuovo file Apps Script, fai clic su Aggiungi un file > Script a sinistra dell'editor accanto a File. Inserisci il nome utils/strings. Nel file appena creato, utils/strings.gs, sostituisci il codice con il seguente:

var world = "世界";

In Code.gs, sostituisci il codice esistente con il seguente:

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

In alto, fai clic su Salva .

Per eseguire la funzione, seleziona hello dall'elenco a discesa delle funzioni nella parte superiore dell'editor e fai clic su Esegui.

Il saluto viene visualizzato in basso nel log di esecuzione.

Modificare il codice localmente

Torniamo alla riga di comando in cui abbiamo clonato il progetto l'ultima volta. Potresti notare che il nostro codice non è più sincronizzato con l'editor online. Per risolvere il problema, estraiamo il codice dal nostro progetto online.

clasp pull

Ora torna al codice. Dovresti notare una cartella per le nostre utilità. L'interfaccia a riga di comando clasp converte automaticamente il carattere barra / in cartelle sul file system locale.

Nel tuo editor di testo preferito, vai a util/strings.gs e sostituisci il nome della variabile world con mondo. Inoltre, aggiorna Code.gs sostituendo world con mondo. Per aggiornare il codice aggiornato su script.google.com, esegui il push del codice modificato.

clasp push

È tutto. Il codice è stato aggiornato il giorno script.google.com.

clasp push sostituisce il codice presente su script.google.com e clasp pull sostituisce tutti i file localmente. Per questo motivo, segui queste linee guida:

• Non modificare contemporaneamente il codice in locale e su script.google.com.
• Utilizza un sistema di controllo della versione, come git.

7. Controllo delle versioni e deployment

clasp ti consente di gestire versioni e deployment. Innanzitutto, un po' di vocabolario:

• Versione: uno "snapshot" di un progetto di script. Una versione può essere considerata un ramo di sola lettura utilizzato per le implementazioni.
• Deployment: una release pubblicata di un progetto di script (spesso come componente aggiuntivo o app web). Richiede un numero di versione.

Creiamo una versione del nostro script:

clasp create-version "First version"

Utilizzando la stringa della versione registrata che abbiamo creato al posto di [version], possiamo eseguire il deployment dello script:

clasp create-deployment 1 "First deployment"

Il comando clasp deploy esamina il manifest e crea un nuovo deployment con controllo delle versioni. Il codice è ora implementato come eseguibile. Scopri di più in questa guida ai deployment.

8. È tutto.

Ci auguriamo che l'interfaccia a riga di comando di Apps Script sia uno strumento semplice per aiutarti a gestire i progetti Apps Script.

Argomenti trattati

• Come creare nuovi progetti Apps Script
• Come clonare, eseguire il push e il pull di progetti esistenti
• Come gestire i deployment degli script

Clasp è disponibile su GitHub e accoglie con favore nuove funzionalità e patch.

Non vediamo l'ora di vedere le tue creazioni.