google-sheets

Google Sheets の作成

意図的に使い分ける 2 つの座標系

• VALUE ツール（read_range、write_range、append_rows、clear_range）は、タブのタイトルと A1 形式のセルを指定します：{sheet: "Data", cells: "A1:B4"}。
• STRUCTURE/FORMAT ツール（format_cells、set_borders、merge_cells、add_chart、add_conditional_formatting、insert_rows_or_columns、delete_rows_or_columns、freeze_rows_or_columns、sort_range、set_data_validation、set_basic_filter、add_banding、set_column_width、rename_sheet_tab、delete_sheet_tab）は、数値の sheetId を指定します。

get_spreadsheet はセルデータを含まずに、各タブのタイトルと sheetId の両方を返します。最初に呼び出し、対応関係を保持してください。新しいタブの sheetId は、add_sheet_tab の応答（replies[0].addSheet.properties.sheetId）に含まれます。

スタイル付きシートの作成順序：値を先に入力し、その後書式を設定し、最後にグラフを追加する

1. create_spreadsheet を実行します（名前付きタブを指定することもできます。フォルダーを指定することはできません。作成後に google-drive の google_drive_move_or_rename で移動してください）。
2. データを write_range で入力します。値に数値、日付、数式が含まれる場合は parseInput: true を指定してください（デフォルトの false ではすべてリテラルテキストとして保存されるため、「グラフが空」の不具合が起きる主な原因になります）。
3. 裸のグリッドではなく、実際のダッシュボードのように書式を設定します。
   • format_cells でヘッダーを太字にし、塗りつぶし色と白いテキストを設定します。値の列には数値書式（$#,##0、0.0%）を設定します。
   • freeze_rows_or_columns でヘッダー行を固定します。
   • テーブル範囲に set_basic_filter を設定します。フィルターのドロップダウンがあることで、データテーブルとして見やすくなります。
   • set_borders（外枠を内側の罫線より太くする）または add_banding で行に交互の色を付け、set_column_width で内容が切れないようにします。
   • ひと目で確認すべきしきい値には add_conditional_formatting を設定します。
4. データが揃ってから、最後に add_chart を実行します。

グラフ

• add_chart では、最初の範囲がドメイン（x 軸／円グラフのラベル）で、後続の範囲が系列（各 1 列）です。誤った範囲や逆順の範囲をグラフに設定することが、最もよくあるグラフの不具合です。すべての範囲はグラフと同じタブに属している必要があります。headerCount: 1 を指定すると最初のセルが系列ラベルとして使われるため、指定する場合は各範囲にヘッダー行を含めてください。
• グラフは、プロットするデータの上ではなく、テーブルの横または下にある空のセル上に配置します。
• 間違ったグラフはその場で修正し、回避策を取らないでください。get_spreadsheet には各タブのグラフ（chartId、タイトル）が一覧表示されます。update_chart は位置を維持したままグラフの仕様を置き換え、delete_chart はグラフを削除します。最初のグラフの不備を覆い隠すために、2 つ目のグラフを追加してはいけません。

名前付き範囲と保護された範囲

• add_named_range を使うと、数式を自己説明的にできます（=SUM(B2:B13) ではなく =SUM(Budget)）。数式は parseInput: true を指定して入力してください。名前にセル参照のような形式は使えません。
• protect_range でヘッダーや数式セルを保護できます（デフォルトの warningOnly: true では編集者に警告し、false では編集をロックします）。保護と競合する自分の書き込みを避けるため、対象範囲への最後の書き込みが終わった後に保護してください。
• get_spreadsheet には両方が一覧表示され、それぞれに delete_named_range と unprotect_range で必要となる ID が含まれます。

注意点

• リビジョンガードはありません。最後に書き込んだ内容が優先されます。共同編集者が編集している可能性がある場合は、書き込む前に読み取ってください。
• merge_cells では左上の値だけが保持されます。結合後にテキストを書き込んでください。
• sort_range はセルの位置を書き換えます。その範囲を参照する数式を追加する前に並べ替え、並べ替え対象の範囲からヘッダー行を除外してください。
• insert_rows_or_columns／delete_rows_or_columns の位置は 1 始まりです（A=1）。削除は即時に実行され、API では元に戻せません。
• find_replace_sheet はリテラル検索です（ここでは正規表現は使いません）。searchFormulas: true を指定すると数式内も検索できます。
• タブ全体を読み取るとバイト数の上限を超える場合があります。サイズが不明なタブでは cells（例：「1:2000」）の範囲を限定し、切り詰められた場合は nextCells を使用してください。

作業を確認する

値の確認にはread_rangeを使用します（FORMATTED_VALUEはユーザーに表示される値を示し、UNFORMATTED_VALUEは生の数値を示します。数値がテキストではなく数値として認識されていることを確認するには、こちらを使用します）。構造（タブ、グラフ、名前付き範囲、保護）の確認にはget_spreadsheetを使用します。見た目が重要な場合は、google-driveのgoogle_drive_export_fileを使用します（PDFでは、すべてのタブがグラフや書式も含めてレンダリングされます）。