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 で記述され、npm ツールを使用して配布されます。clasp を使用する前に、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 login を使用して再度ログインし、Google で再認証してから clasp の使用を続行します。

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 アカウントで作成するか、Google アカウントと共有する必要があります。クローンを作成するスクリプト プロジェクトは、スクリプト ID を指定して指定します。スタンドアロン プロジェクトとコンテナ バインド プロジェクトの両方を複製できます。

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

1. Apps Script プロジェクトを開きます。
2. 左側の [プロジェクト設定] 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 Secrets として保存します。

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

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

3. CI ワークフロー - PR での Lint とテスト

.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 プロジェクトを作成し、構成を個別の Secret（CLASP_JSON_DEV、CLASP_JSON_STAGING、CLASP_JSON_PROD）として保存します。ワークフローで、デプロイするブランチに基づいて適切な Secret を .clasp.json に書き込みます。

トラブルシューティング

関連情報

• GitHub Actions のドキュメント