Usar a interface de linha de comando com o clasp

Para desenvolver e gerenciar projetos do Google Apps Script no terminal em vez do editor de script do Apps Script, use a ferramenta de código aberto clasp.

O clasp codelab oferece uma visão geral de todos os clasp recursos.

Recursos

O clasp inclui os seguintes recursos:

Desenvolver localmente

O clasp permite desenvolver projetos do Apps Script localmente. Escreva o código no seu computador e faça upload para o Apps Script quando terminar. Você também pode fazer o download de projetos do Apps Script para editá-los off-line. Use suas ferramentas de desenvolvimento favoritas, como git ao criar projetos do Apps Script.

Gerenciar versões de implantação

Crie, atualize e visualize várias implantações do projeto.

Estruturar o código

O clasp permite organizar o código em diretórios, que são preservados quando você faz upload deles para script.google.com. Por exemplo:

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

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

Tipos de projeto

Você pode usar o clasp para gerenciar projetos de script autônomos e vinculados a contêineres.

Projetos autônomos

Um projeto autônomo aparece como um arquivo separado no Google Drive. Você pode criar um novo script autônomo usando o comando clasp create.

Projetos vinculados a contêineres

Um projeto vinculado a contêineres é anexado a um arquivo do Google Docs, Planilhas, Apresentações ou Google Formulários. Você pode criar um novo script vinculado a contêineres anexado a um novo arquivo usando o comando clasp create. Você também pode anexar um novo script a um arquivo usando a flag --parentId.

Outros tipos de projeto

O clasp também oferece suporte à criação de scripts para APIs e apps da Web.

Requisitos

clasp é escrito em Node.js e distribuído usando a ferramenta npm. Antes de usar o clasp, é necessário ter o Node.js versão 20.0.0 ou mais recente instalado. A instalação do Node.js exige privilégios administrativos.

Instalação

Depois de instalar o Node.js, use o seguinte comando npm para instalar o clasp:

npm install @google/clasp -g

Após a instalação, use o comando clasp em qualquer diretório do seu computador.

Usar clasp

Use o clasp para lidar com várias tarefas na linha de comando. Esta seção descreve operações comuns a serem usadas ao desenvolver com clasp.

Login

Esse comando faz login e autoriza o gerenciamento dos projetos do Apps Script da sua Conta do Google. Depois de executado, você precisa fazer login em uma Conta do Google em que os projetos do Apps Script estão armazenados.

clasp login

Sair

Esse comando faz logout da ferramenta de linha de comando. Faça login novamente usando clasp login para se autenticar novamente com o Google antes de continuar usando clasp.

clasp logout

Criar um novo projeto do Apps Script

Esse comando cria um novo script no diretório atual com um título de script opcional.

clasp create [scriptTitle] [--type <projectType>] [--parentId <parentId>]

Esse comando usa os seguintes parâmetros opcionais:

• scriptTitle: o título do projeto de script.
• --type <projectType>: o tipo de projeto a ser criado. Os valores permitidos são standalone, docs, sheets, slides, forms, webapp e api.
• --parentId <parentId>: o ID do arquivo do Google Drive (Documentos, Planilhas, Apresentações ou Formulários) ao qual o novo projeto de script precisa ser vinculado.

Esse comando também cria dois arquivos no diretório atual:

• Um arquivo .clasp.json que armazena o ID do script.
• Um arquivo de manifesto do projeto appsscript.json que contém metadados do projeto.

Clonar um projeto

Esse comando clona um projeto existente no diretório atual. O script precisa ser criado ou compartilhado com sua Conta do Google. Especifique o projeto de script a ser clonado fornecendo o ID do script. Você pode clonar projetos autônomos e vinculados a contêineres.

Para encontrar o ID do script do projeto:

1. Abra o projeto do Apps Script.
2. À esquerda, clique em Configurações do projeto settings.

3. Em IDs, copie o ID do script.

   clasp clone

Fazer o download de um projeto de script

Esse comando faz o download do projeto do Apps Script do Google Drive para o sistema de arquivos do seu computador.

clasp pull

Fazer upload de um projeto de script

Esse comando faz upload de todos os arquivos de um projeto de script do seu computador para o Drive.

clasp push

Listar versões do projeto

Esse comando lista o número e a descrição de cada uma das versões de um projeto de script.

clasp versions

Implantar um projeto publicado

Implante projetos de script como apps da Web, complementos do Google Workspace ou executáveis. Crie implantações no editor de scripts, no manifesto do projeto ou usando clasp.

Para implantar um projeto com clasp, primeiro crie uma versão imutável do projeto do Apps Script. Uma versão é um "instantâneo" de um projeto de script e é semelhante a uma versão ramificada somente leitura.

clasp version [description]

Esse comando mostra o número da versão recém-criada. Use esse número para implantar e cancelar a implantação de instâncias do projeto:

clasp deploy [version] [description]
clasp undeploy <deploymentId>

Esse comando atualiza uma implantação com uma nova versão e descrição:

clasp redeploy <deploymentId> <version> <description>

Listar implantações

Esse comando lista os IDs de implantação, as versões e as descrições do projeto de script.

clasp deployments

Abrir o projeto no editor de script do Apps Script

Esse comando abre um projeto de script no editor do Apps Script. O editor é aberto como uma nova guia no navegador da Web padrão.

clasp open-script

Contribuir para o projeto de código aberto clasp

Contribua para o clasp no GitHub.

CI/CD para o Apps Script com clasp e GitHub Actions

Este guia aborda a configuração de linting, testes e implantação automatizados para projetos do Google Apps Script usando clasp e GitHub Actions.

1. Pré-requisitos

Antes de começar, conclua as etapas de configuração em Requisitos.

Os seguintes itens também são necessários:

• Um repositório do GitHub.
• A API Apps Script ativada em script.google.com/home/usersettings.

2. Autenticação em CI

Como os executores de CI não podem abrir um navegador para OAuth, você armazena as credenciais como secrets do GitHub:

O token de atualização em .clasprc.json concede acesso aos projetos do Apps Script. Trate-o como uma credencial sensível e faça a rotação dele periodicamente.

Adicione .clasprc.json e .clasp.json ao seu .gitignore. Eles contêm credenciais e nunca devem ser confirmados.

3. Fluxo de trabalho de CI: lint e teste em PRs

.github/workflows/ci.yml:

name: CI
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6.3
      - uses: actions/setup-node@v6.3
        with:
          node-version: "20"
          cache: npm
      - run: npm ci
      - run: npm run lint

4. Fluxo de trabalho de CD: implantação na mesclagem

.github/workflows/deploy.yml:

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm
      - run: npm ci
      - run: npm run lint && npm test
      - name: Setup clasp credentials
        run: |

          echo '${{ secrets.CLASPRC_JSON }}' > ~/.clasprc.json
          echo '${{ secrets.CLASP_JSON }}' > .clasp.json

      - name: Push and version
        run: |
          npx @google/clasp push --force
          npx @google/clasp version "$(git rev-parse --short HEAD)"

A flag --force substitui o código remoto sem confirmação. Depois que esse pipeline estiver em vigor, evite edições manuais no editor de script do Apps Script. O repositório se torna a única fonte de verdade.

5. Implantação em vários ambientes

Para ambientes de desenvolvimento/preparação/produção separados, crie um projeto do Apps Script distinto para cada um e armazene as configurações como Secrets separados (CLASP_JSON_DEV, CLASP_JSON_STAGING, CLASP_JSON_PROD). No fluxo de trabalho, grave o Secret apropriado em .clasp.json com base na ramificação que está sendo implantada.

Solução de problemas

Leitura adicional

• Documentação do GitHub Actions (em inglês)