はじめに

Google Apps Script（GAS）は通常、ブラウザ上のスクリプトエディタで開発・実行されますが、claspを使うとVSCodeなどのローカル環境で開発し、さらにコマンドラインから直接実行することが可能になります。この文書では、現時点（2025/5/11）の最新版のclasp 3.0.4-alpha版を使用してVSCodeからGASスクリプトを実行するための設定手順を説明します。

参考

VSCodeを使ったGoogle Apps Script開発の環境構築
 GAS用のCLIツール clasp を使ってGASをローカルで開発して実行するの巻。
公式Github：clasp/README.md
公式Github：clasp/docs/run.md

前提条件

この手順を始める前に、以下のものが必要です。

Node.js（バージョン22.0.0以上）
VSCode or Cursor
Google Cloud Platformのプロジェクト
Google アカウント

1. プロジェクトの準備

まず、GASプロジェクトをローカル環境に作成します。既存のプロジェクトがある場合は、それをクローンすることもできます。

新しいプロジェクトを作成する場合は、ディレクトリを作成し、そこで以下のコマンドを実行します。

> npm init -y
> npm i -g @google/clasp
> clasp login
> clasp create-script --type standalone

これにより、新しいGASプロジェクトが作成され、.clasp.json ファイルが生成されます。このファイルには、スクリプトIDなどの重要な情報が含まれています。

各コマンドの役割は以下の通りです：

npm init -y：
Node.jsプロジェクトを初期化します。-yオプションは全ての質問に自動的に「はい」と答え、デフォルト設定でpackage.jsonファイルを生成します。このファイルはプロジェクトの依存関係や設定を管理します。
npm i -g @google/clasp：
Google提供のCommand Line Apps Script Projects（clasp）ツールをグローバルにインストールします。-gオプションによりシステム全体でclaspコマンドが使えるようになります。このツールがGASプロジェクトのローカル開発を可能にします。
ちなみに、npm iはnpm installの省略形であり、どちらも機能は同じです。
clasp login：
GoogleアカウントでClaspを認証します。ブラウザが開き、Googleアカウントへのアクセス許可を求められます。許可すると、ローカルに.clasprc.jsonファイルが作成され、認証情報が保存されます。これにより、以降のコマンドでGoogleアカウントの認証が不要になります。
clasp create-script --type standalone：
新しいスタンドアロン（独立した）GASプロジェクトを作成します。このコマンドは以下の処理を行います：
- Google Drive上に新しいApps Scriptプロジェクトを作成
- ローカルに.clasp.jsonファイルを作成（スクリプトIDなどの情報を含む）
- 基本的なappsscript.jsonマニフェストファイルを作成
--type standalone オプションは、特定のGoogleドキュメントに紐づかない独立したスクリプトを作成することを指定します。他のオプションとしてはdocs、sheets、slides、formsなどがあり、それぞれ対応するGoogleアプリケーションに紐づいたスクリプトを作成します。

これにより、ローカル環境とGoogle Apps Script環境の間の連携が設定され、VSCodeなどのエディタでGASプロジェクトの開発を始める準備が整います。

claspプロジェクトの削除方法

claspプロジェクトを削除するには、以下の手順を実行します：

ローカルのプロジェクトファイルを削除します：
```
> rm .clasp.json appsscript.json
```
必要に応じて、生成されたスクリプトファイルも削除します：
```
rm *.js *.html
```
Google Drive上のリモートプロジェクトは自動的には削除されないため、必要に応じてscript.google.comから手動で削除します。
認証情報も削除したい場合は、以下のコマンドを実行します：
```
clasp logout
```

これで、claspプロジェクトが完全に削除されます。

2. プロジェクトIDの設定

GASスクリプトをコマンドラインから実行するには、Google Cloud Platform のプロジェクトと関連付ける必要があります。.clasp.jsonファイルを開き、プロジェクトIDを追加します。

.clasp.json

{
  "scriptId": "あなたのスクリプトID",
  "rootDir": ".",
  "projectId": "あなたのGCPプロジェクトID"
}

プロジェクトIDは、Google Cloud Console で新しいプロジェクトを作成するか、既存のプロジェクトを使用して取得できます。

3. OAuth認証情報の設定

GASスクリプトをコマンドラインから実行するには、OAuth認証情報が必要です。以下の手順で設定します。

まず、Google Cloud Console で認証情報を作成します。
Google Cloud Consoleで先ほど .clasp.json で登録したプロジェクトを開き、「固定されたプロダクト」 → 「APIとサービス」 → 「認証情報」を選択します。

または、ブラウザで以下のURLを開きます。

https://console.cloud.google.com/apis/credentials?project=プロジェクトID

プロジェクトの認証情報の画面では、「＋認証情報を作成」→「OAuthクライアントID」を選択します。

OAuthの設定を行っていない場合（初回の場合）

以下のような画面になり、同意画面の構成を行うようにと促されるので、指示に従います。

同意画面の構成の処理が最後まで終わると以下の画面になります。

ここから再度、「認証情報」→ 「＋認証情報を作成」 → 「OAuthクライアントID」を選択します。

アプリケーションタイプとして「デスクトップアプリ」を選びます。名前を入力して「作成」をクリックします。作成後、JSONファイルをダウンロードし、プロジェクトディレクトリに client_secret.json という名前で保存します。

ちなみに、以下の 'Starting in June 2025, you will no longer be able to view or download the client secret once you close this dialog.'の内容はダウンロードされるJSONに入っています。

次に、この認証情報を使ってclaspにログインします。

clasp login --user gasuser --creds client_secret.json --use-project-scopes

gasuserは任意の名前で、複数のアカウントを管理する際に識別子として使用されます。

GCPプロジェクトとOAuth認証情報の再利用について

同じOAuth認証情報の使いまわし:

一度作成したGCPプロジェクトとそのOAuth認証情報（client_secret.json）は、複数のGASプロジェクトで再利用できます。
各GASプロジェクトごとに新しいOAuth認証情報を作成する必要はありません。

使いまわしの方法:

既存の client_secret.json ファイルを新しいGASプロジェクトのディレクトリにコピーするだけです。
新しいプロジェクトでも同じコマンドでログインできます：

clasp login --user gasuser --creds client_secret.json --use-project-scopes

GASプロジェクトごとに.clasp.jsonファイルの内容（特にscriptIdの値）は異なります。しかし、OAuth認証情報（client_secret.json）は同じものを使用できます。

メリット:

複数のGASプロジェクトを管理する場合、認証プロセスを簡素化できます。この方法で、一つのGCPプロジェクトとOAuth認証情報を使って、複数のGASプロジェクトを効率的に管理できます。

4. 必要なAPIの有効化

GASスクリプトが使用するAPIを有効にする必要があります。最低限、Apps Script APIを有効にする必要があります。

https://console.cloud.google.com/marketplace/product/google/script.googleapis.com?project=プロジェクトID

スクリプトが他のGoogleサービス（Sheets、Drive、Gmailなど）を使用する場合は、それらのAPIも有効にする必要があります。claspコマンドを使って有効にできます。

> clasp enable-api sheets
> clasp enable-api drive

5. 実行APIの設定

スクリプトをコマンドラインから実行できるようにするには、appsscript.jsonファイルに実行APIの設定を追加する必要があります。このファイルがない場合は作成し、以下の内容を追加します。

appsscript.json


{
  "timeZone": "Asia/Tokyo",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "executionApi": {
    "access": "ANYONE"
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

スクリプトが特定のGoogleサービスを使用する場合は、oauthScopes配列に適切なスコープを追加します。例えば、Spreadsheetsを使用する場合は https://www.googleapis.com/auth/spreadsheets を追加します。

6. スクリプトのデプロイ

スクリプトをAPI実行可能な形でデプロイする必要があります。まず、ローカルの変更をプッシュします。

> clasp push

次に、ブラウザでスクリプトエディタを開きます。

> clasp list-scripts

表示されたURLをブラウザで開き、「デプロイ」→「新しいデプロイ」を選択します。デプロイタイプとして「API実行可能」を選び、説明を入力して「デプロイ」をクリックします。

7. スクリプトの実行

これで、VSCodeのターミナルから直接GAS関数を実行できるようになります。

clasp run-function --user gasuser 関数名

引数を渡す場合は、--paramsまたは-pオプションを使用します。引数はJSON形式の配列として指定します。

clasp run-function --user gasuser addMemo -p '["2023-05-12", "これはテストメモです"]'

8. デバッグとログの確認

実行結果やエラーを確認するには、ログを確認します。

clasp logs

特定のパターンでフィルタリングしたり、最新のログのみを表示したりするには、以下のようにします。

clasp logs --simplified
clasp logs --watch

注意点

初回デプロイ時には、アクセス権限の承認が必要になる場合があります
clasp deployコマンドは新しいバージョンを自動的に作成してデプロイします
特定のバージョンをデプロイしたい場合は、--versionNumberオプションを使用します

これで、VSCodeのターミナルからGASアプリを完全にデプロイできるようになり、ブラウザでスクリプトエディタを開く手間が省けます。

注意点と制限事項

関数の戻り値は基本的なデータ型（文字列、数値、真偽値）や単純な配列・オブジェクトに限られます。複雑なオブジェクトを返す場合は、JSON文字列に変換することを検討してください。
VSCodeでの本格的なインタラクティブデバッグ（ブレークポイントの設定など）は直接サポートされていません。デバッグには主にログ出力を活用します。
初回実行時や権限が変更された場合は、追加の認証が必要になることがあります。
スクリプトの実行はGoogle Cloud Platform上で行われるため、ネットワーク遅延が発生します。

まとめ

claspを使用することで、VSCodeなどの使い慣れたエディタでGASスクリプトを開発し、コマンドラインから直接実行することが可能になります。これにより、バージョン管理やチーム開発がしやすくなり、開発効率が向上します。初期設定は少し複雑ですが、一度設定すれば快適な開発環境が整います。

付録

claspプロジェクトの管理について

claspプロジェクトの単位と管理方法

claspは、Google Apps Script（GAS）プロジェクトをローカルとリモートの両方で管理するツールです。

プロジェクトの構成：

ローカル側: .clasp.jsonファイルを含むディレクトリ
リモート側: Google Drive上の対応するApps Scriptプロジェクト
この二重構造により、開発者は使い慣れたエディタでコードを編集しながら、Google Apps Scriptの機能を活用できます。プロジェクトの紐付けは.clasp.jsonファイル内のscriptIdによって行われています。

同期の仕組み：

clasp push: ローカルファイルをリモートに反映
clasp pull: リモートの変更をローカルに反映

プロジェクトの削除に関する注意点

claspプロジェクトの削除には以下の点に注意が必要です：

二重管理の性質
ローカルファイルを削除しても、Google Drive上のプロジェクトは自動的には削除されません。完全に削除するには両方の場所で操作が必要です。
認証とプロジェクト情報の分離
.clasp.json（プロジェクト情報）と.clasprc.json（認証情報）は別々に管理されています。プロジェクトを削除しても認証情報は残るため、完全にクリーンアップするにはclasp logoutも必要です。
複数プロジェクトの管理
異なるディレクトリに異なる.clasp.jsonファイルを配置することで、複数のGASプロジェクトを並行して管理できます。

claspを使いこなすことで、バージョン管理やチーム開発など、従来のGAS開発では難しかった作業が可能になります。ローカル環境とGASプラットフォームの両方を適切に管理することが、効率的な開発の鍵となります。