認証とセットアップ
Google Sheetsの統合は、Sheets APIが有効化されたGoogle Cloud Platformを通じたOAuth 2.0認証を使用します。エージェントは、スプレッドシートデータをプログラムで読み取り、書き込み、操作でき、強力なデータ自動化ワークフローを実現します。パーソナルGoogleアカウントと、共有スプレッドシートを使用するGoogle Workspaceエンタープライズアカウントの両方をサポートしています。必要なAPIスコープ
- spreadsheets: スプレッドシートの作成、読み取り、更新、削除へのフルアクセスです。
- spreadsheets.readonly: データの取得と分析のための読み取り専用アクセスです。
- drive: Google Drive内のスプレッドシートの一覧表示と管理へのアクセスです。
- drive.file: アプリが作成または開いたファイルのみにアクセスします。
利用可能な操作
すべての必要な権限を設定すると、ツールキットは以下の操作を可能にします。読み取り操作
- Read Range: 指定された範囲（例：「Sheet1!A1:D10」）からセルの値を取得します。A1表記と名前付き範囲をサポートしています。
- Read Multiple Ranges: 単一のリクエストで複数の非連続範囲からバッチ読み取りを行います。
- Get Cell Value: 特定の単一セルから値を取得します。
- Get Row: 行番号で行全体を読み取ります。
- Get Column: 列文字で列全体を読み取ります。
- Find Cell: 特定の値を検索し、その位置を返します。
書き込み操作
- Write Range: 2次元配列データで指定された範囲の値を更新します。生の入力またはユーザー入力形式をサポートしています。
- Append Row: 既存のデータを上書きせずに、シートの最後に新しい行を追加します。
- Insert Row: 特定の位置に新しい行を挿入し、既存の行を下にシフトします。
- Update Cell: 数式または静的データで単一セルの値を変更します。
- Clear Range: 書式設定を保持したまま、指定された範囲のコンテンツを削除します。
- Delete Row/Column: シートから行または列全体を削除します。
スプレッドシート管理
- Create Spreadsheet: カスタムタイトルと初期シート構造で新しいGoogle Sheetを作成します。
- Copy Spreadsheet: すべてのデータと書式設定を含む既存のスプレッドシートを複製します。
- Get Spreadsheet Metadata: シート名、寸法、保護範囲、プロパティを取得します。
- Update Spreadsheet Properties: タイトル、ロケール、タイムゾーン、デフォルト形式を変更します。
シート操作
- Add Sheet: 既存のスプレッドシート内に新しいシート（タブ）を作成します。
- Delete Sheet: スプレッドシートからシートを削除します。
- Rename Sheet: シートの名前/タイトルを変更します。
- Copy Sheet: 同じまたは異なるスプレッドシート内でシートを複製します。
- Hide/Unhide Sheet: シートの表示/非表示を制御します。
- Reorder Sheets: スプレッドシート内のタブの順序を変更します。
書式設定操作
- Batch Update: 単一のAPIコールで複数の書式設定変更（色、フォント、罫線、配置）を適用します。
- Set Cell Format: 数値形式、通貨、日付、パーカンテージ、またはカスタム形式を適用します。
- Merge Cells: 複数のセルを単一のセルに結合します。
- Unmerge Cells: 以前に結合されたセルを分割します。
- Set Column Width: 列幅をピクセルで調整または自動リサイズします。
- Set Row Height: より良いレイアウトのために行の高さを変更します。
- Freeze Rows/Columns: ナビゲーションを容易にするためにヘッダー行または列をロックします。
高度な操作
- Sort Range: 列でデータを昇順または降順に並べ替えます。
- Filter Data: データのサブセットを表示するフィルタ基準を適用します。
- Create Pivot Table: データ分析用のピボットテーブルを生成します。
- Add Chart: データ範囲に基づいてチャート（棒、折れ線、円、散布）を挿入します。
- Create Named Range: より簡単な参照のために名前付き範囲を定義します。
- Data Validation: ドロップダウンリスト、数値範囲、またはカスタムバリデーションルールを設定します。
- Conditional Formatting: ルールベースのセル書式設定を適用します。
設定オプション
- Value Input Option: RAW（正確な入力を保持）またはUSER_ENTERED（入力されたように解析）を選択します。
- Value Render Option: 値の返し方を制御します（FORMATTED_VALUE、UNFORMATTED_VALUE、FORMULA）。
- Default Spreadsheet ID: 繰り返しのID指定を避けるために、操作用のデフォルトスプレッドシートを設定します。
- Date Time Render Option: 日付/時刻のシリアル番号またはフォーマットされた文字列を選択します。
- Dimension: 操作がROWSまたはCOLUMNSのどちらに適用されるかを指定します。
ユースケース
- 自動レポート: データベースを照会し、Pythonで結果を処理し、チャート付きのフォーマットされたレポートをSheetsに書き込みます。
- データ入力自動化: メール、ドキュメント、またはフォームからデータを抽出し、スプレッドシートの行に投入します。
- リアルタイムダッシュボード: ステークホルダーダッシュボードを支える指標シートを継続的に更新します。
- 在庫管理: ERPシステムとコラボレーションSheetsトラッカー間で製品データを同期します。
- 予算追跡: 複数のソースから経費データを集約し、統合された予算シートにまとめます。
- アンケート回答処理: フォーム回答を収集し、Pythonで分析し、概要シートにインサイトを書き込みます。
- プロジェクトステータスレポート: Jira/Asanaからタスクデータを取得し、フォーマットし、ステークホルダーがアクセスできるSheetsに公開します。
- 営業パイプラインの可視化: 計算フィールドと条件付き書式設定付きでCRMデータをSheetsにエクスポートします。
ベストプラクティス
- スプレッドシートIDの使用: 安定性のために、名前ではなくスプレッドシートID（URLから取得）で参照してください。
- バッチ操作: パフォーマンスを向上させるために、複数の更新を単一のbatchUpdateコールに統合してください。
- メタデータのキャッシュ: メタデータAPIコールを最小限にするために、シート構造情報を保存してください。
- 名前付き範囲: コードの保守性を高めるために、重要なデータ領域に名前付き範囲を使用してください。
- 追加と挿入の使い分け: 新しいデータの追加には追加を使用してください。最後の行を見つけるより速く安全です。
- 大きなデータセットの読み取り: 10,000行以上のシートには、タイムアウトとメモリの問題を避けるためにチャンクで読み取ってください。
- 数式の処理: 数式を書く際には、RAW値入力オプションを使用し、「=」を先頭に付けてください。
パフォーマンスのヒント
- 操作をバッチ処理し、一度に大きな範囲を読み取ることでAPIコールを最小限に抑えてください。
- 適切な値レンダリングオプションを使用してください - 書式設定が不要な場合はUNFORMATTED_VALUEの方が高速です。
- リソースを消費する過度な書式設定操作は避けてください。
- 大規模なデータセットには、APIを繰り返し読み取る代わりにSheets内のIMPORTRANGEの使用を検討してください。
よくある問題と対処法
- 権限が拒否されました: スプレッドシートがエージェントのサービスアカウントと共有されているか、ユーザーがアクセスを付与したことを確認してください。
- 無効な範囲: A1表記の構文を確認してください（例：「Sheet1!A1:B10」）。複数シートのファイルにはシート名を含めてください。
- レート制限を超過しました: 指数バックオフを実装してください。コール数を削減するためにバッチ操作の使用を検討してください。
- データ型の不一致: データ型が期待される形式と一致するようにしてください（文字列ではなく数値として）。