@d-zero/google-sheets
v0.13.1
Published
Google Sheets API Toolkit
Readme
@d-zero/google-sheets
Google Sheets API を型安全にラップしたライブラリ。SheetTableで「ヘッダー定義済みのテーブル」として読み書きする。
Installation
yarn add @d-zero/google-sheets @d-zero/google-authUsage
import { authentication } from '@d-zero/google-auth';
import { SheetTable } from '@d-zero/google-sheets';
const auth = await authentication(null, ['https://www.googleapis.com/auth/spreadsheets']);
const table = await SheetTable.create(
'https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit',
'Users',
auth,
{
define: {
name: '名前',
email: 'メールアドレス',
age: '年齢',
registered: '登録日',
},
},
);
await table.addRecords([
{ name: '田中太郎', email: '[email protected]', age: { value: 25 } },
]);Drive フォルダ URL から新規作成
createSpreadsheetは Drive フォルダ URL を受け取り、そのフォルダ内にスプレッドシートを新規作成する。parseGoogleUrlで URL 種別を判別すれば、「フォルダ URL なら新規作成、スプレッドシート URL なら既存に書き込み」と分岐できる。フォルダ URL はhttps://drive.google.com/drive/folders/<id>形式のみ受理する(open?id=はフォルダとファイルを URL から区別できないため非対応)。
import { authentication } from '@d-zero/google-auth';
import { createSpreadsheet, parseGoogleUrl, Sheets } from '@d-zero/google-sheets';
// Drive scope が必要(spreadsheets scope だけではフォルダに配置できない)
const auth = await authentication(null, [
'https://www.googleapis.com/auth/spreadsheets',
'https://www.googleapis.com/auth/drive.file',
]);
const target = parseGoogleUrl(input);
const sheetUrl =
target?.kind === 'drive-folder'
? (await createSpreadsheet(input, '集計結果', auth)).url
: input;
const sheets = new Sheets(sheetUrl, auth);シートの構造操作
Sheets.createで得たSheetに対して、名前変更・保護・削除・並び替え・非表示ができる。再表示(unhide)と保護解除(unprotect)の API は提供しない。
const sheet = await sheets.create('集計');
await sheet.rename('集計 v2');
await sheet.move(0);
await sheet.hide();
// editors を渡す(推奨)
await sheet.protect({
editors: ['[email protected]', '[email protected]'],
description: '自動生成の集計シート',
});
await sheet.delete();protectのeditors(期待とずれやすい)
- 省略または空配列にすると、シートを編集できるのはスプレッドシートの所有者だけになる。ファイルの編集権限があってもシートは編集できない
- 実行者が所有者でないのに自分のメールを入れ忘れると、自分も編集できなくなる
- セルを編集できる人と、UI の「シートと範囲を保護」からその保護を変更・削除できる人は同じ集合。所有者は常に両方できる。「誰もセルを触れない」と「ファイル編集者の誰でも解除できる」は分けられない
- セキュリティ境界ではない。印刷・コピー・貼り付け・書き出しで内容は持ち出せる。ブックのコピーにこの保護は残らない
warningOnly: trueは確認ダイアログだけで誰でも編集できる。ダイアログの文言は固定で、任意の文は定義できない。このときeditorsは送らないdescriptionは右パネル「シートと範囲を保護」の見出しになるだけ。権限とダイアログ本文は変わらない- 対象はセルの値だけではない。書式だけをロックして値の入力は許す分け方はできない。全員に見えるフィルタは、保護された範囲にかかると作成・変更できない。自分だけのフィルタ表示は作れる
書式・条件付き書式・読み取り API はsrc/sheet-table.tsの JSDoc を参照。
重要な制約
- 大量行のストリーミング送信は 2500 行チャンクで自動分割される(Sheets API のメモリ・タイムアウト制約への対応)
- 遅延セル(
{ value: thunk })は flush 中に自動展開される。展開中に新たな遅延セルが見つかった場合は早期 flush を停止して整合性を保つ onProgressコールバック内でaddRecordsを再入呼びしてはならない — buffer mutation 破壊で行順が壊れるcreateSpreadsheetはリトライしない・同名ファイルを検索しない —files.createは非冪等で、リトライすると二重作成し得るため。呼ぶたびに新規作成する- 同一インスタンスへの並列呼び出し禁止 — 行順・送信件数の保証は逐次呼び出し前提
理由・実装はsrc/sheet-table.tsおよびsrc/sheet.tsの JSDoc を参照。
