コマンドラインで、手元のCSV一式からGoogleスプレッドシートを作成・更新する #Node.js

ローカル環境にあるCSVファイルをディレクトリ単位で一式、Google Drive内の指定したフォルダにGoogleスプレッドシートとして変換・アップロードするCLIツール「csv2gsheets」を作成しました。

指定したDriveフォルダ内に、同じファイル名の既存スプレッドシートがあれば、それを上書き更新する（ファイルIDを変更することなく内容を更新する）こともできるので、Googleスプレッドシートを簡易データベースとして使いたい場合など、データの流れを自動化することができます。

こんな感じ：

c2g convert --config-file-path /Users/username/path/to/c2g.config.json --browse --dry-run

Node.js/npm環境での動作なので、バージョン管理も簡単です。以下ではcsv2gsheets v1.1.0をベースにその初期設定と使用方法をご紹介します。

インストールなどの初期設定

Node.js

Node.jsのActive以上のリリース（2023年9月末時点ではv18.x.xまたはv20.x.x）がインストールされていることを確認してください。

node -v

csv2gsheetsのインストール

npm install -g csv2gsheets

以下ではグローバル環境での実行を想定していますので、インストールにあたって-gフラグをつけています。

試しに実行してみます：

c2g --help

実行コマンドは短縮形c2gでも実行できるようにしてあります。以下、全てc2gで記載していますがcsv2gsheetsに置き換え可能です。

Google Cloudプロジェクトの作成

Google Cloudプロジェクトを立てたことがない人にとっては、ここが面倒に感じるかもしれません...が、一度だけやればいいものなので、ご辛抱ください！分かりにくい記述があれば遠慮なくコメントでお知らせください。

csv2gsheetsでGoogle Drive APIを使うためには、Google Cloudプロジェクトを作成し、Drive APIを有効にした上で、そのプロジェクトに紐づく認証情報（Credentials）をJSON形式のファイルとしてローカル環境に保存する必要があります。無料のGmailアカウントでも進めることができます。

以下その手順を、Google for Developersの公式案内「Node.js クイックスタート」に沿って、スクリーンショットを交えながらご紹介します。

Google Cloudプロジェクトを作成する

公式の「Google Cloud プロジェクトを作成する」のとおりに新規プロジェクトを作成します。プロジェクト名は以下のスクショのとおりMy Projectでも何でも大丈夫です：

プロジェクト作成が完了すれば、Node.js クイックスタートの「Prerequisites（前提）」が準備できたことになりますので、次の項目に移ります。

Drive APIを有効にする

クイックスタートの「APIの有効化」ボタンを押して、Drive APIを有効にします。

OAuth同意画面を設定

APIを有効にしたGoogle Cloud Consoleからそのまま「OAuth同意画面」に移動して、必須項目を設定していきます。

ユーザの種類（User Type）には「内部（Internal）」（＝組織内での利用に限る）または「外部（External）」（＝組織外のユーザも使用できるようにする）の選択肢があります。Google Workspaceのアカウントを使っているのであれば「内部」としておくのがおすすめです。後述のテストユーザを設定せずに済みます。

無料のGmailアカウントを使用しているのであれば「外部」しか選択できないようになっています。

OAuthのスコープではhttps://www.googleapis.com/auth/driveを選択してください。

もしOAuth画面作成時に「外部」を選んだのであれば、テストユーザとしてご自身のアカウント（例：hogehoge@gmail.com）を登録しておいてください。

OAuthクライアント認証情報を作成

「認証情報」ページに移動して「認証情報を作成」>「OAuthクライアントID」をクリックします.

「アプリケーションの種類」では「デスクトップアプリ」を選択します
「名前」は、このコンソール内で自分が理解できるものにすればいいです（例：csv2gsheets）

認証情報を作成すると以下のような画面が出てきます：

「DOWNLOAD JSON」から認証情報のJSONファイルをc2g.creds.jsonとして端末のホームディレクトリに保存してください。

「ホームディレクトリに保存」...

Windows端末ではC:\Users\ユーザ名\c2g.creds.json
macOS端末では/Users/ユーザ名/c2g.creds.json

c2g.creds.jsonはGitにコミットしたり、不用意に他人と共有しないようにしてください！
Drive APIへのリクエスト回数制限など、Googleによる各種制約はGoogle Cloudプロジェクト単位で適用されます。先のOAuth同意画面の設定でユーザの種類を「内部」としていても、この制約含めて共有して問題の無い同僚（同じ部署の人、など）限りとするのがいいでしょう。

以上で「Google Cloudプロジェクトの作成」が完了です！

実行してみる

Googleにログインする

Google Drive内でGoogleスプレッドシートを作成・更新するために、まずはGoogleにログインします：

c2g login

前項のGoogle Cloudプロジェクト作成がうまくいっていれば、いつものGoogleのログイン画面に続いて、先ほど設定したOAuth同意画面が出てきます。

同意が完了するとホームディレクトリに.c2grc.jsonというファイルが生成されます。いわゆるOAuth tokenです。

.c2grc.jsonは誰とも共有しないでください！ ログインしたGoogleアカウントのID/パスワードと同義です。

一度ログインすれば、

c2g logout

でログアウトするか、OAuth token内のrefresh tokenが無効になるまで有効であり続けます。「あれ？いまどのアカウントでログインしていたっけ？」というときはloginコマンドに--status（-s）オプションをつけてください：

c2g login --status

余談ですが、GoogleのOAuth tokenの失効に関しては、こちら↓の記事がわかりやすいです：
https://qiita.com/croquette0212/items/8da7ccaa09abf89d4f51

設定ファイルの作成

csv2gsheetsは、必要な変数を設定ファイル（c2g.config.json）に格納して、実行時にはその設定ファイルを見にいくようにしています。

設定項目やそのデフォルト値について詳しく知る（クリックして展開）

プロパティ	型	意味	デフォルト値
`sourceDir`	`string`	Googleスプレッドシートに変換したいCSVファイル一式が保存されているディレクトリ。ここで指定したディレクトリ直下にあるCSVファイルが全て、csv2gsheetsの対象となる。サブディレクトリ以下は対象とならない。	csv2gsheetsを実行している作業ディレクトリ
`targetDriveFolderId`	`string`	CSVごとのGoogleスプレッドシートを作成するGoogle DriveフォルダID。フォルダIDとは、URL「`https://drive.google.com/drive/folders/***`」の`***`の部分。マイドライブ直下を指定したい場合は、IDの代わりに`root`とする。	`root`
`targetIsSharedDrive`	`boolean`	`targetDriveFolderId`で指定したDriveフォルダが共有ドライブ内のものである場合は`true`とする。（参考：共有ドライブとは - Google Workspace ラーニングセンター）	`false`
`updateExistingGoogleSheets`	`boolean`	`targetDriveFolderId`で指定したDriveフォルダ内に、変換するCSVと同じ名前のスプレッドシートが既に存在する時に、それを上書きする場合は`true`とする。`false`であれば、同じファイル名のスプレッドシートが新規作成される。（Google Driveの場合、ひとつのフォルダ内に同じファイル名がいくつも共存できる）	`false`
`saveOriginalFilesToDrive`	`boolean`	元のCSVファイルもGoogle Driveに保存したい場合は`true`にする。`true`とした場合、`targetDriveFolderId`で指定したDriveフォルダ内の子フォルダ「csv」内に、そのCSVがアップロードされる。子フォルダ「csv」が存在しなければ、新規作成される。	`false`

設定ファイルもコマンドラインで作成できます。

cd <設定ファイルを作成したいディレクトリ>
c2g init

設定値を入力するようプロンプトされますので、順に値を指定していきます。何も指定せずにEnterを押すとデフォルト値となります。

この時点でログインがまだでしたら--login（-l）オプションを使用して、設定ファイルの作成とGoogleへのログイン・承認を同時に済ませられます：

c2g init --login

これは

c2g init

# 各種設定後
c2g login

と順に実行するのと同じことです。

CSVをGoogleスプレッドシートに変換する

一番シンプルなパターンが

c2g convert

です。csv2gsheetsは作業ディレクトリ内にある設定ファイルc2g.config.jsonを見つけて、その内容に従ってDrive内でのスプレッドシート作成・更新を行います。

CSVファイルと、設定ファイルc2g.config.jsonは別々のディレクトリにあっても問題ありません。Windowsのバッチ処理で、「ネットワークドライブ割り当て」などで設定した別ドライブ内のCSVファイル一式を取り扱いたい時に、設定ファイルがC:\hoge\hogeに、CSVファイルが Z:\fuga\fugaにある、という状況にも対応可能ということです。

c2g.config.jsonの場所を明示したい場合は--config-file-path（-c）オプションを使います：

c2g convert -c /Users/foo/bar/c2g.config.json

本番実行前には--dry-run（-d）オプションで、実際のファイル操作を行うことなく、対象ファイルや設定値を確認することができます：

c2g convert --dry-run

--dry-runでは基本的にファイル・フォルダに対する実際の操作は行われませんが、一点だけ例外があります。Driveフォルダ内の「csv」フォルダの作成です。

詳しく知る

元のCSVファイルもDriveにアップロードする設定となっている場合（つまりc2g.config.jsonでsaveOriginalFilesToDriveがtrueとなっている場合）、convert実行中に、CSVアップロード先である「csv」フォルダのURLもconsole.infoで出力されるようになっています。

このようにアップロード先がユーザ側にも明示されることを優先させている都合上、「もし対象Driveフォルダ内に『csv』サブフォルダが存在しない場合は、作成して、そのURLを返す」という処理は--dry-runが有効であっても実行される、という事情です。

convert実行後にGoogle Driveの対象フォルダをブラウザで開きたい場合は--browse（-b）オプションをつけます：

c2g convert --browse

オプションは組み合わせることができます：

c2g convert -c /Users/foo/bar/c2g.config.json -d -b

留意点

Drive APIの使用量上限

csv2gsheetsの処理には、Googleが定めるDrive APIの使用量上限が適用されます

既存スプレッドシート更新であっても、シートIDは変わる

本ツールでは、既存スプレッドシートの更新にあたってDrive APIのfiles.updateを使っていますが、このメソッドは

ファイルIDを変更せずに、内容を完全に上書き更新
シートIDは変わる

という仕様になっています。取り扱っている元データがCSVファイルなので、更新後のスプレッドシートは必然的に1ファイル1シートとなります。つまり定期的に更新されることが前提のスプレッドシートについては、下流での処理を進めるにあたって次の点に留意する必要があります：

編集や集計は別のスプレッドシートで行う

変換されたスプレッドシートを直接編集してしまうと、更新時にその作業が消えてしまいます。

例えば「別シートでちょっとした集計」などはExcel感覚でやりたくなりますが、集計を含めて表計算として残していきたい場合はスプレッドシートのIMPORTRANGE関数などの利用をお勧めします。

シートは名前で参照する

更新時にシートIDが変わってしまうので、Google Apps Scriptなど参照方法を選べる場合は極力、シート名での参照としたほうが手数を少なくできます。

GASの例

// ファイルIDは変わらないので、ID指定できる：
const targetSpreadsheet = SpreadsheetApp.openById('ファイルID'); 

// シートを取得するときは、シート名で指定する：
const targetSheet = targetSpreadsheet.getSheetByName('シート名');

// 1ファイル1シートとなるので、これでも一意の指定ができる：
const targetSheet2 = targetSpreadsheet.getSheets()[0];

csv2gsheetsで作成・更新されるスプレッドシートのシート名は、ファイル名と同じになります。例えば元ファイルがtest.csvであれば、ファイル名・シート名ともにtestとなります。

現時点ではDrive APIのみを使っているcsv2gsheetsですが、Sheets APIも組み合わせればシートIDが変わらない形での上書き更新が可能な気がしています。その辺はAPIリクエスト回数や処理速度とのトレードオフになりそうなので、追々。機能追加のご要望などはぜひGitHubのIssuesを立てていただければと思います。もちろん日本語で大丈夫です。

終わりに

CSVをGoogleスプレッドシートに変換するためのツールや方法は検索すれば色々ありますが、

コマンドラインで完結する
業務で展開するためにバージョン管理が容易＝パッケージ化してdistributeされている
必要最小限の機能（CSV→Sheetsは欲しいけれど、別にSheetsから情報を取得して色々したいわけではない）

といった要件を満たすものが見当たらなかったため、今回csv2gsheetsを作ってみました。

これが個人開発でのコマンドラインツール2作目ということで、まだまだ至らぬ点も多いかと思います。よろしければ本記事へのコメントや、GitHubレポジトリへのIssue立てを通じてご指摘ください。GitHubのほうが英語で書きましたが、日本語での投稿ももちろん大丈夫です