Korzystanie z interfejsu wiersza poleceń za pomocą narzędzia clasp

Aby tworzyć projekty Google Apps Script i zarządzać nimi z poziomu terminala, a nie edytora skryptów Apps Script, użyj narzędzia open source clasp.

W claspcodelabie znajdziesz omówienie wszystkich funkcji clasp.

Funkcje

clasp zawiera następujące funkcje:

Opracowywanie lokalne

clasp umożliwia tworzenie projektów Apps Script lokalnie. Pisz kod na własnym komputerze i przesyłaj go do Apps Script po zakończeniu. Możesz też pobrać istniejące projekty Apps Script, aby edytować je offline. Podczas tworzenia projektów Apps Script możesz korzystać z ulubionych narzędzi programistycznych, takich jak git.

Zarządzanie wersjami wdrożenia

Tworzenie, aktualizowanie i wyświetlanie wielu wdrożeń projektu.

Kod struktury

clasp umożliwia porządkowanie kodu w katalogach, które są zachowywane po przesłaniu go na stronę script.google.com. Przykład:

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

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

Typy projektów

Za pomocą clasp możesz zarządzać zarówno samodzielnymi projektami skryptów, jak i projektami skryptów powiązanymi z kontenerem.

Projekty samodzielne

Samodzielny projekt jest wyświetlany jako osobny plik na Dysku Google. Nowy samodzielny skrypt możesz utworzyć za pomocą polecenia clasp create.

Projekty powiązane z kontenerem

Projekt powiązany z kontenerem jest dołączony do pliku Dokumentów Google, Arkuszy, Prezentacji lub Formularzy Google. Możesz utworzyć nowy skrypt powiązany z kontenerem, który będzie dołączony do nowego pliku, za pomocą polecenia clasp create. Możesz też dołączyć nowy skrypt do istniejącego pliku za pomocą flagi --parentId.

Inne typy projektów

clasp umożliwia też tworzenie skryptów do aplikacji internetowych i interfejsów API.

Wymagania

clasp jest napisany w Node.js i dystrybuowany za pomocą narzędzia npm. Zanim zaczniesz korzystać z clasp, musisz mieć zainstalowaną wersję 20.0.0 lub nowszą środowiska Node.js. Instalacja Node.js wymaga uprawnień administracyjnych.

Instalacja

Po zainstalowaniu Node.js użyj tego polecenia npm, aby zainstalować clasp:

npm install @google/clasp -g

Po zainstalowaniu użyj polecenia clasp z dowolnego katalogu na komputerze.

Używaj funkcji clasp

Używaj clasp do wykonywania różnych zadań z poziomu wiersza poleceń. W tej sekcji opisujemy typowe operacje, które można wykonywać podczas tworzenia aplikacji z użyciem clasp.

Zaloguj się

To polecenie loguje Cię i autoryzuje zarządzanie projektami Apps Script na Twoim koncie Google. Po uruchomieniu pojawi się prośba o zalogowanie się na konto Google, na którym są przechowywane projekty Apps Script.

clasp login

Wyloguj się

To polecenie powoduje wylogowanie z narzędzia wiersza poleceń. Zaloguj się ponownie za pomocą clasp login, aby ponownie uwierzytelnić się w Google, zanim zaczniesz dalej korzystać z clasp.

clasp logout

Tworzenie nowego projektu Apps Script

To polecenie tworzy w bieżącym katalogu nowy skrypt z opcjonalnym tytułem.

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

To polecenie używa tych opcjonalnych parametrów:

• scriptTitle: tytuł projektu skryptu.
• --type <projectType>: typ projektu do utworzenia. Dozwolone wartości to standalone, docs, sheets, slides, forms, webapp i api.
• --parentId <parentId>: identyfikator istniejącego pliku na Dysku Google (Dokumentów, Arkuszy, Prezentacji lub Formularzy), z którym ma być powiązany nowy projekt skryptu.

To polecenie tworzy też w bieżącym katalogu 2 pliki:

• Plik .clasp.json zawierający identyfikator skryptu.
• appsscript.json plik manifestu projektu zawierający metadane projektu;

Klonowanie istniejącego projektu

To polecenie klonuje istniejący projekt w bieżącym katalogu. Skrypt musi zostać utworzony lub udostępniony na Twoim koncie Google. Projekt skryptu do sklonowania określa się, podając jego identyfikator. Możesz klonować zarówno samodzielne projekty, jak i projekty powiązane z kontenerem.

Aby znaleźć identyfikator skryptu projektu:

1. Otwórz projekt Apps Script.
2. Po lewej stronie kliknij Ustawienia projektu settings.

3. W sekcji Identyfikatory skopiuj Identyfikator skryptu.

   klon zapięcia

Pobieranie projektu skryptu

To polecenie pobiera projekt Apps Script z Dysku Google do systemu plików komputera.

clasp pull

Przesyłanie projektu skryptu

To polecenie przesyła wszystkie pliki projektu skryptu z komputera na Dysk.

clasp push

Wyświetlanie listy wersji projektu

To polecenie wyświetla numer i opis każdej wersji projektu skryptu.

clasp versions

Wdrażanie opublikowanego projektu

Wdrażanie projektów skryptów jako aplikacji internetowych, dodatków do Google Workspace lub plików wykonywalnych. Twórz wdrożenia w edytorze skryptów, w pliku manifestu projektu lub za pomocą clasp.

Aby wdrożyć projekt za pomocą clasp, najpierw utwórz niezmienną wersję projektu Apps Script. Wersja to „migawka” projektu skryptu, która jest podobna do rozgałęzionego wydania tylko do odczytu.

clasp version [description]

To polecenie wyświetla numer nowo utworzonej wersji. Użyj tego numeru, aby wdrażać i wycofywać instancje projektu:

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

To polecenie aktualizuje istniejące wdrożenie o nową wersję i opis:

clasp redeploy <deploymentId> <version> <description>

Wyświetlenie listy wdrożeń

To polecenie wyświetla identyfikatory wdrożeń, wersje i opisy projektu skryptu.

clasp deployments

Otwieranie projektu w edytorze skryptów Apps Script

To polecenie otwiera projekt skryptu w edytorze skryptów Apps Script. Edytor otworzy się w nowej karcie w domyślnej przeglądarce.

clasp open-script

Współtworzenie projektu open source clasp

Współtwórz clasp na GitHub.

CI/CD w Apps Script z clasp i działaniami na GitHubie

Ten przewodnik zawiera informacje o konfigurowaniu automatycznego sprawdzania kodu, testowania i wdrażania projektów Google Apps Script za pomocą clasp i GitHub Actions.

1. Wymagania wstępne

Zanim zaczniesz, wykonaj czynności konfiguracyjne opisane w sekcji Wymagania.

Potrzebujesz też:

• Repozytorium GitHub.
• Interfejs Apps Script API włączony w domenie script.google.com/home/usersettings.

2. Uwierzytelnianie w CI

Ponieważ narzędzia CI nie mogą otwierać przeglądarki na potrzeby protokołu OAuth, dane logowania są przechowywane jako obiekty tajne GitHub:

Token odświeżania w .clasprc.json przyznaje dostęp do Twoich projektów Apps Script. Traktuj go jako poufne dane logowania i okresowo go zmieniaj.

Dodaj .clasprc.json i .clasp.json do .gitignore. Zawierają one dane logowania i nigdy nie powinny być zatwierdzane.

3. Przepływ pracy CI – sprawdzanie i testowanie w przypadku żądań scalenia

.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. Przepływ pracy CD – wdrażanie po scaleniu

.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)"

Flaga --force zastępuje kod zdalny bez potwierdzenia. Po skonfigurowaniu tego potoku unikaj ręcznych zmian w edytorze skryptów Apps Script – repozytorium stanie się jedynym źródłem wiarygodnych danych.

5. Wdrażanie w wielu środowiskach

W przypadku oddzielnych środowisk deweloperskich, testowych i produkcyjnych utwórz osobne projekty Apps Script i przechowuj ich konfiguracje jako osobne wpisy tajne (CLASP_JSON_DEV, CLASP_JSON_STAGING, CLASP_JSON_PROD). W przepływie pracy zapisz odpowiedni wpis tajny w .clasp.json na podstawie wdrażanej gałęzi.

Rozwiązywanie problemów

Więcej informacji

• Dokumentacja GitHub Actions