clasp: La CLI de Apps Script

1. Introducción

Apps Script CLI, o clasp, es una herramienta que te permite crear, editar e implementar proyectos de Apps Script de manera local. Le permite crear y publicar aplicaciones web y complementos para productos, como Hojas de cálculo, Documentos, Formularios y Presentaciones desde la línea de comandos. Existen dos formas de desarrollar Apps Script: usando script.google.com o de manera local en su computadora. Aprenderemos esto último, cómo usar clasp, la herramienta de línea de comandos para Apps Script.

Funciones

• Desarrollo a nivel local. clasp te permite escribir código en tu propia computadora y subirlo a Apps Script cuando termines. También puede descargar proyectos existentes de Apps Script y, luego, editarlos de forma local. Una vez que el código sea local, podrá usar sus herramientas de desarrollo favoritas, como git, para trabajar en proyectos de Apps Script.
• Administración de versiones de implementación: Cree, actualice y visualice varias implementaciones de su proyecto.
• Estructuración del código. clasp convierte automáticamente tu proyecto plano en carpetas en script.google.com. Por ejemplo:

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

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

Qué aprenderás

En este codelab, te mostraremos cómo realizar 3 actividades clave con clasp:

• Cómo crear nuevos proyectos de Apps Script
• Cómo clonar, extraer y enviar proyectos existentes
• Cómo administrar las implementaciones de sus secuencias de comandos

2. Comenzar

Descarga la CLI

Apps Script CLI (clasp) requiere que se instale Node.js >= v6.0.0. Instala Node.js aquí.

Nota: El uso de clasp requiere Node.js >= v6.0.0. Actualiza Node.js con estos comandos:

sudo npm install n -g

sudo n latest

Una vez que tengas Node, instala la CLI a nivel global (alias clasp):

npm i @google/clasp -g

3. Acceder

Acceder

Probemos clasp. El único comando que debes recordar es clasp.

clasp

Instalamos clasp de forma global en nuestra computadora, por lo que el comando debería funcionar en todas partes del sistema de archivos.

Antes de comenzar a usar la herramienta de línea de comandos, debemos acceder. Ejecuta este comando:

clasp login

o si usas SSH:

clasp login --no-localhost

En este punto, se te solicitará que accedas a Google. Todos los proyectos que cree con la CLI estarán asociados con esta Cuenta de Google.

4. Crear un proyecto nuevo

Cómo crear un proyecto independiente

Para comenzar, crea un proyecto independiente de Google Apps Script con el siguiente comando:

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

Acabas de crear un proyecto de Apps Script en la carpeta "clasp_codelab".

Nota: El comando clasp create creó una secuencia de comandos independiente. Esto significa que el proyecto no está conectado a archivos de Hojas de cálculo, Documentos, Formularios ni Presentaciones de Google. Sin embargo, veremos cómo crear una secuencia de comandos vinculada en la siguiente sección.

(Alternativa opcional) Clone un proyecto existente

Intentemos crear una secuencia de comandos vinculada al contenedor para un complemento de Presentaciones de Google.

Para ello, vaya a slides.google.com y cree una nueva presentación. Cambia el nombre de la presentación a "clasp Codelab Test". En el encabezado, en Herramientas, presiona Editor de secuencias de comandos....

Esto abrirá tu proyecto de Apps Script en script.google.com. Para clonar un proyecto, necesitamos Script ID. Puedes encontrar este ID en la URL del proyecto de Apps Script después de /projects/. Copia el valor y pégalo en el siguiente comando:

clasp clone <scriptID>

El resultado debería verse de la siguiente manera:

Ya descargaste el proyecto en tu directorio actual. Usa tu editor favorito para ver el contenido de Code.gs (una función vacía).

5. Extracción y Envía archivos

Edite el código en script.google.com

Ahora que puede clonar un proyecto, veamos cómo extraer y enviar archivos. Te guiaremos a través de los pasos para editar en la nube a través de script.google.com y extraer datos de forma local a tu computadora. Abramos la secuencia de comandos en la nube:

clasp open

Ahora que estamos en el editor en línea, editaremos código que, luego, recuperaremos con clasp.

Para crear un nuevo archivo de Apps Script, a la izquierda del editor, junto a Archivos, haz clic en Agregar un archivo > Secuencia de comandos Ingresa el nombre utils/strings. En el archivo recién creado, utils/strings.gs, reemplaza el código por lo siguiente:

var world = "世界";

En Code.gs, reemplaza el código existente por lo siguiente:

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

En la parte superior, haz clic en Guardar .

Para ejecutar la función, en la parte superior del editor, selecciona hello en la lista desplegable de funciones y haz clic en Ejecutar.

El saludo aparece en la parte inferior del registro de ejecución.

Edite código de forma local

Volvamos a la línea de comandos donde clonamos el proyecto por última vez. Puede notar que, ahora, nuestro código no está sincronizado con el editor en línea. Para solucionar esto, extraigamos el código de nuestro proyecto en línea.

clasp pull

Regrese al código. Deberías ver que hay una carpeta para nuestras utilidades. La CLI de clasp convierte automáticamente el carácter de barra / en carpetas del sistema de archivos local.

En tu editor de texto favorito, navega a util/strings.gs y reemplaza el nombre de variable world por mondo. Además, actualiza Code.gs y reemplaza world por mondo. Para actualizar el código actualizado en script.google.com, envía el código editado.

clasp push

Eso es todo. Tu código se actualizó el script.google.com.

clasp push reemplaza el código que está en script.google.com y clasp pull reemplaza todos los archivos de forma local. Por eso, siga estas pautas:

• No edites el código de forma simultánea de forma local y en script.google.com.
• Usa un sistema de control de versiones, como git.

6. Implementación y control de versiones

clasp te permite administrar implementaciones y versiones. Antes que nada, veamos algo de vocabulario:

• Versión: Una "instantánea" de un proyecto de secuencia de comandos. Una versión puede considerarse una rama de solo lectura utilizada para implementaciones.
• Implementación: Una actualización publicada de un proyecto de secuencia de comandos (a menudo en la forma de complemento o aplicación web). Requiere un número de versión.

Creemos una versión de nuestra secuencia de comandos:

clasp version "First version"

Podemos implementar la secuencia de comandos con la cadena de versión registrada que creamos en lugar de [version]:

clasp deploy 1 "First deployment"

El comando clasp deploy examina tu manifiesto y crea una nueva implementación con control de versiones. Ahora, se implementará su código como un elemento ejecutable. Obtén más información sobre esto en la guía de implementaciones.

7. Eso es todo.

Esperamos que Apps Script CLI sea una herramienta simple para ayudarte a administrar proyectos de Apps Script.

Temas abordados

• Cómo crear nuevos proyectos de Apps Script
• Cómo clonar, enviar y extraer proyectos existentes
• Cómo administrar las implementaciones de sus secuencias de comandos

Clasp está disponible en GitHub y te damos la bienvenida a las nuevas funciones y parches.

Ya queremos ver tus ideas en acción.