clasp: a CLI do Apps Script

1. Introdução

A CLI do Apps Script (clasp, na sigla em inglês) é uma ferramenta para criar, editar e implantar projetos do Apps Script localmente. Com ela, você cria e publica apps da Web e complementos para produtos como o Planilhas, o Documentos, o Formulários e o Apresentações do Google diretamente na linha de comando. Há duas maneiras de desenvolver projetos com o Apps Script: acessando script.google.com ou localmente no computador. Você vai aprender a segunda opção, como usar a ferramenta de linha de comando do Apps Script clasp.

Recursos

Desenvolver localmente. clasp permite que você escreva o código no computador e faça upload para o Apps Script quando ele estiver pronto. Outra opção é fazer o download de projetos do Apps Script e editá-los localmente. Como o código está no computador, você pode usar suas ferramentas de desenvolvimento favoritas, como o git, para trabalhar em projetos do Apps Script.
Gerencie versões de implantação: crie, atualize e visualize várias implantações do projeto.
Estrutura do código. Oclasp converte automaticamente um projeto simples no script.google.com em pastas. Exemplo:

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

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

O que você vai aprender

Este codelab mostra como realizar três atividades principais com o clasp:

Como criar novos projetos do Apps Script
Como clonar, extrair e enviar projetos existentes
Como gerenciar implantações de scripts

2. Primeiros passos

Como fazer o download da CLI

A CLI do Apps Script (clasp) exige que o Node.js esteja instalado. Instale o Node.js aqui.

Depois de instalar o Node, instale a CLI globalmente (alias clasp):

npm i @google/clasp -g

3. Ativar a API Apps Script

Antes de usar o Clasp, ative a API Apps Script do Google no ambiente de desenvolvimento integrado do Apps Script.

4. Login

Vamos testar a clasp! O único comando que você precisa lembrar é clasp.

clasp

Antes de usar a ferramenta de linha de comando, você precisa fazer login. Execute este comando:

clasp login

ou, se estiver usando SSH:

clasp login --no-localhost

Nesse momento, você vai precisar fazer login no Google. Todos os projetos criados com a CLI estarão associados a essa Conta do Google.

5. Criar um novo projeto

Criar um projeto independente

Para começar, crie um projeto independente do Google Apps Script com o seguinte comando:

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

Você acabou de criar um projeto do Apps Script na pasta "clasp_codelab".

Clone um projeto (alternativa opcional)

Vamos tentar criar um script vinculado a um contêiner para um complemento do Apresentações Google.

Para fazer isso, acesse slides.google.com e crie uma apresentação. Mude o nome da apresentação para "clasp Codelab Test". Na barra de menus do Apresentações, no menu Extensões, escolha Apps Script.

Seu projeto do Apps Script será aberto em script.google.com.

Crie um novo diretório para seu projeto e cd até ele.

mkdir clasp_codelab_test
cd clasp_codelab_test

Para clonar um projeto, precisamos do Script ID. Você pode encontrar esse ID no URL do projeto do Apps Script depois de /projects/. Copie o valor e cole no seguinte comando:

clasp clone <scriptID>

A saída será semelhante a esta:

Agora você baixou o projeto no seu diretório atual. Use o editor de texto que você preferir para ver o conteúdo do arquivo Code.gs (uma função vazia).

6. Como extrair e enviar arquivos

Edite o código em script.google.com

Agora que você já sabe como clonar um projeto, é hora de aprender a extrair e enviar arquivos. Vamos mostrar as etapas necessárias para editar o código na nuvem em script.google.com e extraí-lo para uso local no seu computador. Abra o script na nuvem:

clasp open-script

Agora que estamos no editor on-line, vamos editar um código on-line que será extraído mais tarde usando clasp.

Para criar um arquivo do Apps Script, à esquerda do editor, ao lado de Arquivos, clique em Adicionar um arquivo > Script. Insira o nome utils/strings. No arquivo utils/strings.gs que você criou, substitua o código pelo seguinte:

var world = "世界";

Em Code.gs, substitua o código pelo seguinte:

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

Na parte superior, clique em Salvar salvar .

Para executar a função, na parte de cima do editor, selecione hello na lista suspensa de funções e clique em Executar.

A mensagem aparece na parte de baixo do registro de execução.

Edite o código localmente

Volte para a linha de comando onde você clonou o projeto. O código estará diferente do que aparece no editor on-line. Para consertar isso, extraia o código do projeto on-line.

clasp pull

Volte para o código. Você vai notar que há uma pasta para nossos utilitários. A CLI clasp converte automaticamente o caractere de barra / em pastas no sistema de arquivos local.

No editor de texto que você preferir, acesse util/strings.gs e substitua o nome da variável world por mondo. Além disso, atualize o Code.gs substituindo world por mondo. Para atualizar o código alterado em script.google.com, envie a versão editada.

clasp push

Pronto. Seu código foi atualizado em script.google.com.

7. Controle de versão e implantação

Com a clasp, você gerencia versões e implantações. Primeiro, conheça o vocabulário:

Versão: um "instantâneo" de um projeto de script. Uma versão pode ser considerada uma ramificação somente leitura usada para implantações.
Implantação: uma versão publicada de um projeto de script (geralmente como um complemento ou um app da Web). Requer um número de versão.

Vamos criar uma versão do script:

clasp create-version "First version"

Usando a string de versão registrada que criamos no lugar de [version], podemos implantar o script:

clasp create-deployment 1 "First deployment"

O comando clasp deploy examina o arquivo de manifesto e cria uma nova implantação com controle de versão. Agora o código está implantado como um executável. Leia o guia de implantações para saber mais.

8. Pronto!

Esperamos que a CLI do Apps Script seja uma ferramenta simples para ajudar você a gerenciar projetos do Apps Script.

O que aprendemos

Como criar novos projetos do Apps Script
Como clonar, enviar e extrair projetos atuais
Como gerenciar implantações de scripts

A clasp está disponível no GitHub e pode receber novos recursos e patches.

Mal podemos esperar para conhecer suas criações!