clasp でコマンドライン インターフェースを使用する

Apps Script エディタではなくターミナルから Google Apps Script プロジェクトを開発、管理するには、オープンソース ツール clasp を使用します。

clasp Codelab では、 clasp のすべての機能の概要を説明しています。

機能

clasp には以下の機能があります。

ローカルで開発

clasp を使用すると、Apps Script プロジェクトをローカルで開発できます。コンピュータ上でコードを記述して、完成後に Apps Script にアップロードします。既存の Apps Script プロジェクトをダウンロードして、オフラインで編集することも可能です。Apps Script プロジェクトをビルドするときは、 gitなど、お好みの開発ツールを使用します。

デプロイ バージョンを管理する

プロジェクトで複数のデプロイ の作成、更新、表示を行うことができます。

コードを構成する

clasp を使用すると、コードをディレクトリに整理できます。ディレクトリは、script.google.com にアップロードしても保持されます。例:

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

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

プロジェクトの種類

clasp を使用すると、スタンドアロン スクリプト プロジェクトとコンテナ バインド スクリプト プロジェクトの両方を管理できます。

スタンドアロン プロジェクト

スタンドアロン プロジェクトは、Google ドライブに個別のファイルとして表示されます。clasp create コマンドを使用して、新しいスタンドアロン スクリプトを作成できます。

コンテナ バインド プロジェクト

コンテナ バインド プロジェクトは、Google ドキュメント、スプレッドシート、スライド、Google フォームのファイルに添付されます。clasp create コマンドを使用して、新しいファイルに添付された新しいコンテナ バインド スクリプトを作成できます。--parentId フラグを使用して、既存のファイルに新しいスクリプトを添付することもできます。

その他のプロジェクト タイプ

clasp では、ウェブアプリと API のスクリプトの作成もサポートしています。

要件

clasp は Node.js で記述され、 ツールを使用して配布されます。npmclasp を使用する前に、 Node.js バージョン 20.0.0 以降 をインストールする必要があります。Node.js をインストールするには、管理者権限が必要です。

インストール

Node.js をインストールしたら、次の npm コマンドを使用して clasp をインストールします。

npm install @google/clasp -g

インストールしたら、パソコンの任意のディレクトリから clasp コマンドを使用します。

clasp を使用する

clasp を使用すると、コマンドラインからさまざまなタスクを処理できます。このセクションでは、clasp を使用して開発する際に使用する一般的なオペレーションについて説明します。

ログイン

このコマンドは、Google アカウントの Apps Script プロジェクトの管理にログインして承認します。実行すると、Apps Script プロジェクトが保存されている Google アカウントにログインするように求められます。

clasp login

ログアウト

このコマンドは、コマンドライン ツールからログアウトします。clasp の使用を続行する前に、clasp login を使用して再ログインし、Google で 再認証します。

clasp logout

新しい Apps Script プロジェクトを作成する

このコマンドは、現在のディレクトリに新しいスクリプトを作成します。スクリプト タイトルは省略可能です。

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

このコマンドは、次の省略可能なパラメータを使用します。

• scriptTitle: スクリプト プロジェクトのタイトル。
• --type <projectType>: 作成するプロジェクトのタイプ。指定できる値は、standalone、docs、sheets、slides、forms、webapp、api です。
• --parentId <parentId>: 新しいスクリプト プロジェクトをバインドする既存の Google ドライブ ファイル （ドキュメント、スプレッドシート、スライド、 フォーム）の ID。

このコマンドは、現在のディレクトリに次の 2 つのファイルも作成します。

• スクリプト ID を保存する .clasp.json ファイル。
• プロジェクト メタデータを含む appsscript.json プロジェクト マニフェスト ファイル。

既存のプロジェクトのクローンを作成する

このコマンドは、現在のディレクトリにある既存のプロジェクトのクローンを作成します。スクリプト は、Google アカウントで作成または共有する必要があります。クローンを作成するスクリプト プロジェクトを指定するには、スクリプト ID を指定します。スタンドアロン プロジェクトと コンテナ バインド プロジェクトの両方のクローンを作成できます。

プロジェクトのスクリプト ID を確認するには:

1. Apps Script プロジェクトを開きます。
2. 左側の [Project Settings] settings をクリックします。

3. [ID] で、スクリプト ID をコピーします。

   clasp clone

スクリプト プロジェクトをダウンロードする

このコマンドは、Google ドライブからパソコンのファイル システムに Apps Script プロジェクトをダウンロードします。

clasp pull

スクリプト プロジェクトをアップロードする

このコマンドは、スクリプト プロジェクトのすべてのファイルをパソコンからドライブにアップロードします。

clasp push

プロジェクト バージョンを一覧表示する

このコマンドは、スクリプト プロジェクトの各バージョンの番号と説明を一覧表示します。

clasp versions

公開されたプロジェクトをデプロイする

スクリプト プロジェクトをウェブアプリ、Google Workspace アドオン、実行可能ファイルとしてデプロイします。スクリプト エディタ、 プロジェクト マニフェスト、または clasp を使用して デプロイを作成します。

clasp でプロジェクトをデプロイするには、まず Apps Script プロジェクトの不変バージョンを作成します。バージョンはスクリプト プロジェクトの「スナップショット」であり、読み取り専用のブランチ リリースに似ています。

clasp version [description]

このコマンドは、新しく作成されたバージョン番号を表示します。この番号を使用して、プロジェクトのインスタンスをデプロイおよびデプロイ解除します。

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

このコマンドは、新しいバージョンと説明で既存のデプロイを更新します。

clasp redeploy <deploymentId> <version> <description>

デプロイのリスト表示

このコマンドは、スクリプト プロジェクトのデプロイ ID、バージョン、説明を一覧表示します。

clasp deployments

Apps Script エディタでプロジェクトを開く

このコマンドは、Apps Script エディタでスクリプト プロジェクトを開きます。エディタは、デフォルトのウェブブラウザで新しいタブとして起動します。

clasp open-script

clasp オープンソース プロジェクトに投稿する

GitHub で clasp に投稿します。

clasp と GitHub Actions を使用した Apps Script の CI/CD

このガイドでは、clasp と GitHub Actions を使用して、Google Apps Script プロジェクトの自動リンティング、テスト、デプロイを設定する方法について説明します。

1. 前提条件

始める前に、要件の手順を完了してください。

上記に加え、以下が必要です。

• GitHub リポジトリ。
• script.google.com/home/usersettings で有効になっている Apps Script API。

2. CI での認証

CI ランナーは OAuth のブラウザを開くことができないため、認証情報をGitHub シークレットとして保存します。

.clasprc.json の更新トークンは、Apps Script プロジェクトへのアクセスを許可します。機密性の高い認証情報として扱い、定期的にローテーションします。

.clasprc.json と .clasp.json を .gitignore に追加します。これらには認証情報が含まれているため、コミットしないでください。

3. CI ワークフロー - PR でのリンティングとテスト

.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. CD ワークフロー - マージ時にデプロイ

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

--force フラグを指定すると、確認なしでリモートコードが上書きされます。このパイプラインが設定されたら、Apps Script スクリプト エディタで手動で編集しないでください。リポジトリが信頼できる唯一の情報源になります。

5. マルチ環境のデプロイ

開発環境、ステージング環境、本番環境を分離するには、それぞれに個別の Apps Script プロジェクトを作成し、構成を個別のシークレット（CLASP_JSON_DEV、CLASP_JSON_STAGING、CLASP_JSON_PROD）として保存します。ワークフローで、デプロイするブランチに基づいて適切なシークレットを .clasp.json に書き込みます。

トラブルシューティング

関連情報

• GitHub Actions のドキュメント