ノードの使い方 — Google Sheetsノード

この文書では、AgentriaのGoogle Sheetsノードの使い方を説明します。Google Sheetsノードは、Googleスプレッドシートのファイルを作成・取得したり、シートを追加したり、セルの値を読み書き・削除したりするノードです。作業（Task）項目で何を選ぶかによって、ノードエディターに表示される入力項目が変わります。

Google Sheetsノードは作業1つにつきノード1つで動作します。この文書では、7つの作業それぞれの機能と使い方を、ノード1つだけを使った例で案内します。

事前準備

Agentriaキャンバスへの進入方法については、🔗3ステップコアガイドをご参照ください。

Google Sheetsノードを使用するには、まずGoogleクレデンシャル（Credential）を登録し、Googleアカウントを連携する必要があります。登録方法については、🔗Googleクレデンシャル設定ガイドをご参照ください。Client ID / Client Secret方式で連携する場合は、データアクセス範囲でGoogle Sheets APIを検索して有効化します。

• 連携したGoogleアカウントがアクセスできるスプレッドシートのみを扱えます。他の人のシートを扱うには、そのシートが連携したアカウントに共有されている必要があります。

ノードエディターの共通構造

Google Sheetsノードをキャンバスに配置してダブルクリックすると、ノードエディターが開きます。どの作業を選んでも、以下の2つのルールが共通して適用されます。

• ノードエディターには最初、クレデンシャルと作業のみが表示されます。 それ以外の入力項目（スプレッドシートID、範囲、値など）は画面にすぐには表示されず、変数追加ボタンをクリックしてモーダルで必要な項目にチェックを入れ、保存することでノードエディターに表示されます。必須項目も例外ではないため、各作業に必要な項目を漏れなくチェックする必要があります。

• どの作業でも、出力はresultというObject（オブジェクト）値1つだけです。 Googleスプレッドシート APIのレスポンス形式をそのまま保持しているため、作業によって中身が異なります。ノードテストを実行した後、出力パネルの結果タブでresultを展開して中身を確認するのが最も確実です。

作業一覧

作業ドロップダウンで、以下の7つの中から1つを選択します。

Append to SheetとUpdate Sheetは混同しやすいです。Append to Sheetはどこに書き込むかを自動的に探し、既存データの一番下の空行から追加します。Update Sheetは指定した位置に正確に書き込み、その場所にあった値は上書きされます。

スプレッドシートID

Create Spreadsheetを除くすべての作業で、スプレッドシートID（spreadsheet_id）を入力する必要があります。扱うGoogleスプレッドシートファイルを区別する固有の文字列で、アドレスバーのURLに含まれています。

たとえばアドレスがhttps://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit#gid=0であれば、/d/とその次の/の間にある1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upmsの部分だけをコピーします。

スプレッドシートID項目の説明文には「IDまたはURL」と書かれていますが、実際にはURL全体ではなくID部分のみを入力する必要があります。URLをそのまま入力すると、ノードの実行が失敗します。

• 正しい値：1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms

• 誤った値：https://docs.google.com/spreadsheets/d/1BxiMVs.../edit

Create Spreadsheetでファイルを作成した直後であれば、その結果であるresult.spreadsheetIdの値をそのまま使用できます。

1. Create Spreadsheet — スプレッドシートの作成

新しいGoogleスプレッドシートファイルを作成します。

作業でCreate Spreadsheetを選択し、変数追加で以下の項目を出します。

スプレッドシートタイトルを空にすると、New Spreadsheetという名前で作成されます。

ノードテストを実行すると、結果タブでresultを展開して以下の値を確認できます。シートのプロパティや書式などの詳細情報も一緒に返されますが、実際に活用する値は以下の2つです。

この作業で作成したファイルに値を書き込んだり読み取ったりするには、他の作業のスプレッドシートID項目にresult.spreadsheetIdの値をそのまま入力します。

2. Get Spreadsheet — ファイル情報の取得

ファイルのタイトルと、その中に含まれるシート（タブ）一覧を取得します。セルの内容は取得しません。 セルの値を読み取るにはGet Sheet Dataを使用します。

作業でGet Spreadsheetを選択し、変数追加で以下の項目を出します。新しく登場するオプションはなく、どちらも先述のスプレッドシートID、タイムアウトで扱った項目です。

結果はCreate Spreadsheetと同じ形式です。結果タブでresultを展開すると、ファイルのタイトルはresult.properties.title、シート（タブ）一覧はresult.sheets配列で確認できます。シートが複数ある場合は配列にもその数だけ項目が入り、各シートの名前はresult.sheets[番号].properties.titleに格納されています。

3. Create Sheet — シート（タブ）の追加

既存のファイルに新しいシート（タブ）を追加します。

作業でCreate Sheetを選択し、変数追加で以下の項目を出します。新しく登場するオプションはシート名（sheet_name）です。

シート名を空にすると、Sheet + 番号の形式（例：Sheet3）で自動生成されます。この番号は、ファイル内でこれまでに実際に作成されたシート数を基準に増え続け、途中でシートを削除しても減りません。たとえばSheet14まで作成した後すべて削除しても、次に作成される名前はSheet1ではなくSheet15になります。

同じ名前のシートがすでにある場合は、API operation failed: Failed to create sheet (HTTP 400)エラーが発生します。日付のように毎回変わる名前を使うか、Get Spreadsheetで先にシート一覧を確認してください。

ノードテストを実行すると、結果タブでresult → replies → [0] → addSheet → propertiesの順に展開して以下の値を確認できます。

4. Get Sheet Data — シートデータの読み取り

指定した範囲のセルの値を読み取ります。

作業でGet Sheet Dataを選択し、変数追加で以下の項目を出します。

シート範囲を空にするとエラーが発生します。シート名を省略してA:Zのように列範囲だけを入力すると、Sheet1タブが対象になります。データ解釈方法（major_dimension）はRows、Columnsのいずれかを選びます。Rows（デフォルト）は人が見る表の形そのまま行単位で受け取り、Columnsは同じ列の値をまとめて受け取ります。特別な理由がなければRowsをそのまま使用します。

ノードテストを実行すると、結果タブでresultを展開して以下の値を確認できます。

シートが以下のようになっている場合、

result.valuesは[["名前", "年齢", "都市"], ["John", 30, "ソウル"]]のように、行ごとに配列で格納されます。

範囲に値が1つもない場合、resultにはrange、majorDimensionのみが含まれ、values自体が存在しません。後に続くノードが「valuesに配列がある」と前提にしていると失敗する可能性があるため、値がない場合に備えておいてください。

5. Append to Sheet — データの追加

既存データの一番下に新しい行を追加します。どこが最後の行かはGoogleが自動的に判断します。

作業でAppend to Sheetを選択し、変数追加で以下の項目を出します。フィールド構成は6. Update Sheetと同じです。

Update Sheetと決定的に異なるのは、シート範囲が意味するところです。Append to Sheetでは「ここに書き込め」ではなく、**「ここから表を探せ」**という意味です。Sheet1!A:Cのように列範囲を広く指定すると、すでに値が入っている行の次から自動的に追加されます。

シート範囲で指定した列幅より値の列数が多い場合、範囲を超えた列にもそのまま書き込まれます。たとえばシート範囲をSheet1!A:B（2列）にしても、値が3列であればC列まで書き込まれます。つまりシート範囲の列幅は「ここまでしか書き込むな」という制限ではなく、既存の表を探すための基準にすぎません。Sheet1!A2:B3のような狭い範囲を指定しても、Sheet1のようにシート名だけを指定しても、同じように動作します。

値には一度に複数の行を入れることもできます。たとえば[["Alice", 28, "Incheon"], ["Bob", 34, "Daegu"]]のように2行を入れると、2行がまとめて追加されます。

ノードテストを実行すると、結果タブでresultを展開して以下の値を確認できます。

6. Update Sheet — データの上書き

指定した位置に値を正確にそのまま書き込みます。元々あった値は消えます。

作業でUpdate Sheetを選択し、変数追加で以下の項目を出します。

シート範囲と値のサイズを合わせる必要があります。範囲が3行なのに値が5行だとエラーになり、範囲が3行なのに値が2行だと、残りの3行目は消去されずそのまま残ります。消去してから新しく書き込みたい場合は、先にClear Sheetで空にしてから書き込む方が安全です。

ノードテストを実行すると、結果タブでresultを展開して以下の値を確認できます。

Append to Sheetとは異なり、これらの値はupdatesでさらに1段階包まれることなく、resultの直下にあります。

7. Clear Sheet — データの削除

指定した範囲の値のみを削除します。シート自体や書式（色、罫線など）はそのまま残ります。

作業でClear Sheetを選択し、変数追加で以下の項目を出します。新しく登場するオプションはありません。

タイトル行は残してデータだけを空にしたい場合は、2行目から範囲を指定します。Sheet1!A2:Z1000のように指定すると、1行目のタイトルは残り、2行目以降の値だけが削除されます。

ノードテストを実行すると、結果タブでresultを展開して以下の値を確認できます。

値だけが削除され、セルの書式（色、罫線など）やシート自体はそのまま残ります。

範囲の表記法

シート範囲（range_name）項目は、Excelで使うセルアドレス方式と同じです。シート名!開始セル:終了セルの形式で入力します。

シート名にスペースが含まれる場合は、シングルクォートで囲むことを推奨します。囲まなくても内部的に処理されて問題なく動作しますが、表記を明確にするために囲んで書く方が良いでしょう。

• 推奨：'売上サマリー'!A1:D100

• クォートなしでも動作：売上サマリー!A1:D100

値（表データ）の入力方法

値（values）項目は、表を1枚まるごと二次元配列で書くとイメージすると分かりやすいです。

1. 1行は角括弧[ ]で囲みます。例：["John", 30, "ソウル"]

2. 複数行は、その角括弧をさらに外側の角括弧で囲みます。例：[行1, 行2, 行3]

以下の表を入力したい場合、

次のように書きます。

[
  ["名前", "年齢", "都市"],
  ["John", 30, "ソウル"],
  ["Jane", 25, "釜山"]
]

[
  ["名前", "年齢", "都市"],
  ["John", 30, "ソウル"],
  ["Jane", 25, "釜山"]
]

[
  ["名前", "年齢", "都市"],
  ["John", 30, "ソウル"],
  ["Jane", 25, "釜山"]
]

1行だけを入力する場合でも、外側の角括弧が必要です。

• 正しい例：[["Alice", 28, "Incheon"]]

• 誤った例：["Alice", 28, "Incheon"] — 縦方向に誤って入るか、エラーが発生する可能性があります

文字は二重引用符" "で囲み、数字は引用符なしで書きます。空のセルは""にします。

1つのセルに入力できる値の種類は以下のとおりです。

日付・パーセント・金額・数式は、値入力オプションがUser Enteredのときのみ解釈されます。Rawにすると、すべて文字としてそのまま入力されます。リンクは例外で、User Entered・RawどちらであってもURL形式の文字列であれば自動的にクリック可能なリンクになります。詳しい比較は値入力オプションをご参照ください。

文字の中に二重引用符や改行を入れる場合は、前に円記号（バックスラッシュ）\を付けます。

シングルクォート'とカンマ,は、文字の中にそのまま書いても問題ありません。

値入力オプション

値入力オプション（value_input_option）は、Append to Sheet、Update Sheet作業で入力した値をGoogleが解釈するか、文字としてそのまま扱うかを決める項目です。

Rawを選ぶべき代表的なケースは、電話番号・郵便番号・社員番号のように先頭の0が消えては困る値を扱うときです。それ以外は、デフォルトのUser Enteredをそのまま使用します。

同じ値（日付・パーセント・数値・数式など）を、1行はUser Enteredで、1行はRawでそれぞれ書いて比較すると、違いがはっきり分かります。User Enteredの行は日付・パーセント・数値がすべて右揃えで表示され、実際に日付・数値の型として認識されたことが分かり、=SUM(1,2,3)のような数式も計算されて結果値になります。Rawの行は左揃えの文字列としてそのまま保存され、数式も文字のまま残ります。

リンク（https://example.comのようなURL文字列）は、どちらのオプションでもクリック可能なリンクとして表示されます。Google Sheetsは、URL形式の文字列を値入力オプションに関係なく自動的にリンク化するようです。

応答に更新された値を含める

応答に更新された値を含める（include_values_in_response）は、Append to Sheet、Update Sheet作業で変数追加から出せるチェックボックスです。

オンにすると、result.updatesの中にupdatedDataが追加され、結果タブで展開すると、その中に実際に書き込まれた範囲（updatedData.range）と値（updatedData.values）が格納されているのを確認できます。

値入力オプションがUser EnteredでGoogleが値を変換して保存した可能性があるとき（例："0123"を入力したのに123として保存された場合）、実際に何が入力されたかを確認したい場合にオンにします。データが多いと結果もその分大きくなるため、通常はオフのままにしておくことを推奨します。

タイムアウト

Googleの応答を待つ最大時間です。

• 単位：秒（デフォルト60秒）

• 小数点なしの整数で入力

広い範囲を読み取ったり、多くの行を一度に書き込んだりする際にタイムアウトエラーが発生する場合は、この値を増やします。それでも失敗する場合は、範囲を分割して複数回に分けて処理することを検討してください。

複数のノードで連携するには

この文書の例は、ノード1つだけを使って各作業の入力・出力を確認する方式です。実際のワークフローでは、「新しいファイルを作成 → そのIDで値を書き込む」のように、複数のGoogle Sheetsノードを連携させて値を自動的に受け渡す必要がある場合が多くあります。

各作業の出力はresultというObject 1つの中にネストされているため、spreadsheetIdのようにその中の値1つだけを次のノードのString項目（例：spreadsheet_id）に直接ドラッグ＆ドロップで接続することはできません。このような場合は、PythonノードでGoogle Sheetsノードを関数ノードとして接続して呼び出し、result.get("spreadsheetId")のように必要な値だけを取り出して使う方法を用います。この構成はPythonコードの作成が必要な上級者向けの活用方法のため、この文書では扱いません。

このノードでできないこと

Google Sheetsノードは、以下の作業には対応していません。必要な場合はGoogleスプレッドシートで直接行うか、別の方法を探す必要があります。

• シート（タブ）の削除、名前変更、順序の入れ替え

• スプレッドシートファイルの削除、共有設定の変更

• セルの書式指定（フォント、色、罫線、条件付き書式）

• 行／列の挿入・削除、列幅の調整

• グラフ・ピボットテーブルの作成

• フィルター・並べ替えの適用

よくある間違い

次のステップ

🎉 おめでとうございます！ AgentriaのGoogle Sheetsノードで7つの作業をそれぞれ実行してみました。

Create Spreadsheetで作成したファイルにUpdate Sheetでタイトル行を書き込み、Append to Sheetでデータを蓄積するように、複数の作業を連携させるワークフローも作ってみてください。

Agentriaは、アイデアを現実に変える可能性の空間です。

あなたのアイデア次第で、ワークフローは無限に広がります。

• より多くのアビリティ例が気になる方は 🔗アビリティガイド をご確認ください。

• エージェント例を見たい方は 🔗エージェントガイド をご確認ください。

よくある質問

Google Sheetsノードとは何ですか？

Google Sheetsノードは、AgentriaでGoogleスプレッドシートのファイルを作成・取得したり、シートを追加したり、セルの値を読み書き・削除したりするノードです。「ユーティリティ・生産性」カテゴリに属し、作業項目でCreate Spreadsheet、Get Spreadsheet、Create Sheet、Get Sheet Data、Append to Sheet、Update Sheet、Clear Sheetのいずれかを選択して動作を決めます。

Google Sheetsノードを使用するには何を準備すればよいですか？

Googleクレデンシャルを登録し、Googleアカウントを連携する必要があります。連携方法については、🔗Googleクレデンシャル設定ガイドをご参照ください。連携したアカウントがアクセスできるスプレッドシートのみを扱えるため、他の人のシートを扱うには事前に共有してもらう必要があります。

ノードエディターにスプレッドシートIDなどの項目が表示されません。

Google Sheetsノードはクレデンシャルと作業のみがデフォルトで表示され、それ以外の入力項目はすべて変数追加ボタンでチェックを入れて出す必要があります。必須項目も例外ではないため、使用する作業に必要な項目を変数追加モーダルで漏れなくチェックしてください。

Append to SheetとUpdate Sheetはどう違いますか？

Append to Sheetは既存データの一番下の空行を自動的に探して新しい行を追加します。一方Update Sheetは指定した範囲に正確に値を書き込み、その場所にあった値は消えます。ログや受付内容のように継続的に蓄積すべきデータにはAppend to Sheetを、特定のセルや領域を更新する必要がある場合はUpdate Sheetを使用します。

値項目には表データをどのような形式で入力しますか？

各行の値を角括弧で囲み、その行をさらに外側の角括弧で囲む二次元配列形式で入力します。たとえば2行分の表は[["John", 30, "ソウル"], ["Jane", 25, "釜山"]]のように書きます。1行だけを入力する場合でも、外側の角括弧を省略できません。詳しい表記ルールは値（表データ）の入力方法をご参照ください。

1つのノードで複数の作業を処理できますか？

いいえ。Google Sheetsノード1つは、作業項目で選択した動作1つだけを実行します。複数の作業を連続して処理するには、Google Sheetsノードを複数配置し、ノードごとに異なる作業を選択して順番に接続する必要があります。