kintoneとスプレッドシートをGAS連携する設計方法｜API・権限・再実行まで

Google Apps Scriptを使うと、kintoneとGoogleスプレッドシートを比較的すぐにつなげます。

スプレッドシートの行をkintoneへ登録する。

kintoneの案件一覧を毎朝スプレッドシートへ取得する。

Googleフォームの回答をkintoneへ登録する。

スプレッドシートで入力された棚卸結果をkintoneへ戻す。

kintoneの更新候補をシートで確認して、承認後に一括更新する。

処理結果を別シートへ書き出す。

失敗した行だけを再実行する。

このような連携は、GASとkintone REST APIで作れます。

ただし、GAS連携で危ないのは、最初のコードが動くことです。

1件登録できた。

一覧を取得できた。

時間主導トリガーで毎日動いた。

ここまでは比較的早く到達できます。

本当に難しいのは、その後です。

同じ行が二重登録される。

誰の権限でGASが動いているか分からない。

APIトークンの権限が広すぎる。

編集時トリガーが予期しない列変更でも動く。

kintone側で更新済みのレコードを、古いシートから上書きする。

失敗した行と成功した行が混ざり、どこから再実行すればよいか分からない。

Apps Scriptの実行履歴を見ないと、連携が止まったことに気づけない。

API制限や実行時間に当たり、途中まで処理される。

kintoneとスプレッドシートのGAS連携で最初に決めるべきなのは、コードの書き方ではなく、「何を正本にして、どの方向に、どの条件で更新するか」です。

この記事では、Google Apps Scriptでkintoneとスプレッドシートを連携するときに、GASが向く業務、同期方向、APIトークン、UrlFetchApp、時間主導・編集時・フォーム送信時トリガー、二重登録、競合、LockService、ログ、失敗通知、再実行、API制限、GASから外部基盤へ移す判断まで整理します。

kintoneとスプレッドシート連携の設計方法はこちら
kintone API制限の設計方法はこちら
kintoneバックアップ設計はこちら

GAS連携が向く業務と向かない業務

GASは、小さく始めやすい連携に向いています。

Googleスプレッドシート、Googleフォーム、Gmail、Googleドライブなど、Google Workspace上のデータを起点にしやすいからです。

また、社内でスプレッドシートをすでに使っている場合、現場の画面を大きく変えずにkintoneへつなげられます。

GAS連携が向くケース	理由
毎日または毎時の一覧取得	時間主導トリガーで動かしやすい
Googleフォーム回答の登録	フォーム送信時トリガーと相性がよい
少量の更新候補をkintoneへ戻す	行単位で検証しやすい
社内向けの確認表	スプレッドシートをそのまま画面にできる
失敗しても手で追える連携	ログと再実行シートを作りやすい

一方で、GASに向かない連携もあります。

GASだけで抱えにくいケース	理由
大量件数の頻繁な同期	実行時間、API制限、再実行設計が重くなる
基幹システムとの重要連携	監視、リトライ、権限管理を厚くしたい
複数サービスをまたぐ処理	認証情報とエラー分岐が増える
外部顧客向けの常時処理	SLAや監視の考え方が必要になる
複雑な双方向同期	競合解決、差分管理、キュー処理が必要になる

GASは悪い選択肢ではありません。

ただし、GASは「簡単に書ける」ことと「業務システムとして運用できる」ことを分けて考える必要があります。

GAS連携は、少量・低頻度・社内運用から始めるには有効です。高頻度、大量件数、重要データの同期は、最初から外部基盤や連携サービスも候補に入れます。

同期方向と正本データを決める

GASを書く前に、同期方向を決めます。

同期方向が曖昧なままコードを書くと、スプレッドシートとkintoneの両方で同じ値を更新できる状態になります。

同期方向	例	設計すること
kintoneからシート	毎朝の案件一覧、月次集計	取得条件、列定義、更新頻度
シートからkintone	棚卸結果、フォーム回答、申請データ	更新キー、追加/更新の判定、エラー処理
シートで確認してkintoneへ戻す	修正候補、承認後の一括更新	差分、確認者、戻す項目
双方向	外部作業表として使う	競合、権限、更新責任

多くの場合、正本はkintone側に置きます。

スプレッドシートは、確認、入力補助、一時加工、集計の道具として使います。

データ	正本	スプレッドシート側の扱い
顧客マスタ	kintone	参照、確認
案件状態	kintone	一覧表示、コメント
棚卸数量	kintoneの棚卸履歴	入力元、検証後に登録
申請内容	kintone	フォーム回答の一時受け
月次集計	kintoneの元データ	集計表、ピボット
修正候補	kintoneへ反映前の一時値	確認者が承認後に戻す

kintoneを正本にするなら、スプレッドシートから戻せる項目は絞ります。

たとえば、作業メモや棚卸数量は戻してよい。

承認状態や請求済み金額は戻さない。

顧客マスタは、担当者だけが確認して戻す。

このように、項目単位で責任を分けます。

kintoneとスプレッドシート連携の設計方法はこちら

APIトークンと実行権限の管理

GASからkintone REST APIを呼び出す場合、認証情報を扱います。

Kintone Developer ProgramのREST API概要では、APIトークン認証を使う場合にX-Cybozu-API-TokenヘッダーへkintoneアプリのAPIトークンを指定することが説明されています。

Kintone Developer Program：Kintone REST API Overview

Googleフォーム回答をkintoneへ登録するチュートリアルでも、APIトークンにレコード追加権限を付け、GASからUrlFetchApp.fetchでkintoneへPOSTする例が示されています。

Kintone Developer Program：Post Google Forms Responses into Kintone

APIトークンは、必要な権限だけに絞ります。

連携内容	APIトークン権限の考え方
kintoneから取得するだけ	レコード閲覧
シートから新規登録する	レコード追加
既存レコードを更新する	レコード更新
ファイル添付も扱う	ファイルアップロードを含む設計
マスタ参照もする	参照先アプリの閲覧権限を確認

1つのAPIトークンに、閲覧、追加、更新、削除を全部持たせると危険です。

削除が不要なら付けない。

更新が不要なら付けない。

参照先アプリを増やすなら、何を読めるようになるかを確認する。

この粒度で設計します。

GAS側では、APIトークンをコードに直書きしない方がよいです。

Apps ScriptのPropertiesServiceを使えば、スクリプトやユーザー単位のプロパティを扱えます。

Google for Developers：PropertiesService

ただし、PropertiesServiceに置けば無条件に安全という意味ではありません。

スクリプトを編集できる人、実行できる人、デプロイできる人を分けて管理します。

観点	決めること
実行アカウント	個人か、管理用アカウントか
編集権限	GASコードを誰が変更できるか
実行権限	誰が手動実行できるか
トリガー作成者	誰の権限で定期実行されるか
トークン保管	コード直書きではなく設定として扱うか
退職・異動	作成者が使えなくなった時の引き継ぎ

GAS連携の権限は、kintoneのAPIトークンだけでは決まりません。Google側のスクリプト編集者、実行者、トリガー所有者まで含めて設計します。

時間主導・編集時・フォーム送信時トリガーの使い分け

GAS連携では、どのタイミングで処理を動かすかが重要です。

GoogleのApps Scriptドキュメントでは、インストール型トリガーとして、時間主導トリガーや、スプレッドシート、フォームなどのイベントに応じたトリガーを設定できることが説明されています。

Google for Developers：Installable Triggers

代表的な使い分けは次の通りです。

トリガー	向いている用途	注意点
時間主導	毎朝の取得、定期集計、夜間同期	失敗通知と再実行が必要
編集時	特定列の入力をきっかけに処理	意図しない編集でも動きやすい
フォーム送信時	回答をkintoneへ登録	重複送信、添付、必須項目を確認する
手動実行	管理者が確認後に処理	実行者と対象範囲を明確にする

編集時トリガーは便利ですが、扱いに注意します。

セルを貼り付けた。

行を並び替えた。

列名を直した。

関数が再計算された。

こうした操作をきっかけに、意図しない処理が動く可能性があります。

そのため、編集時トリガーを使う場合は、対象シート、対象列、対象値をかなり狭くします。

たとえば、送信列が実行待ちになった行だけ処理する。

処理後は処理済みへ変える。

エラー時はエラーへ変え、理由を別列へ書く。

このような状態列を持たせます。

二重登録・競合・ロックの設計

GAS連携でよく起きる事故は、二重登録です。

同じ行を複数回処理してしまう。

編集時トリガーが短時間に複数回動く。

手動実行と時間主導トリガーが重なる。

前回処理が終わる前に、次の処理が始まる。

この対策として、GAS側でロックを使うことがあります。

GoogleのLockServiceは、スクリプトの同時実行を防ぐためのロック機能として提供されています。

Google for Developers：LockService

ただし、ロックだけでは十分ではありません。

行ごとの処理状態も持たせます。

管理列	役割
recordId	kintoneのレコードID
更新キー	顧客番号、案件番号、対象月など
取得時更新日時	kintoneから取得した時点の更新日時
処理状態	未処理、処理中、処理済み、エラー
最終実行日時	いつ処理したか
エラー理由	何で失敗したか
再実行対象	再処理してよい行か

競合も見ます。

たとえば、スプレッドシートへ出力した後に、kintone側で同じレコードが更新されることがあります。

その古いシートから更新すると、kintone側の新しい値を上書きします。

これを避けるには、取得時点の更新日時や更新者をシートに持ち、登録前にkintone側の最新値と比較します。

競合パターン	対処
kintone側が後から更新済み	その行は止めて確認へ回す
シート側で同じ行を複数人が編集	状態列と確認者を置く
同じ更新キーが複数行ある	取込前にエラーにする
レコードが削除済み	新規登録せず確認に回す
承認済み・締め後	更新不可にする

GASで二重実行を防ぐには、ロックだけでなく、スプレッドシート側の状態列とkintone側の更新日時を組み合わせます。

ログ・失敗通知・再実行

GAS連携は、失敗したときに追える状態にしておく必要があります。

Kintone Developer ProgramのGoogleフォーム連携チュートリアルでも、登録できない場合はApps ScriptのExecutionsタブを確認し、ログを追加してデバッグすることが案内されています。

Kintone Developer Program：Post Google Forms Responses into Kintone

業務で使うなら、Apps Scriptの実行履歴を見るだけでなく、独自の同期ログを残します。

ログ項目	内容
実行ID	1回の処理を識別する番号
開始時刻、終了時刻	処理時間と停止位置を追う
実行者、トリガー	手動か自動か、誰の権限か
対象シート、対象範囲	どの行を処理したか
成功件数、失敗件数	結果の概要
失敗行	行番号、更新キー、理由
kintoneレスポンス	エラーコード、メッセージ
再実行可否	そのまま再実行できるか

失敗通知も必要です。

通知がないと、シート上の値が古いまま使われます。

通知先は、実装者ではなく業務担当者と運用責任者にします。

失敗内容	通知先
入力値エラー	入力担当者
API認証エラー	管理者、実装担当
API制限、実行時間	運用責任者、実装担当
競合検知	確認者、業務責任者
外部共有ファイル不備	ファイル管理者

再実行は、全件ではなく失敗行だけ処理できるようにします。

全件を再実行すると、すでに成功した行まで重複登録されることがあります。

そのため、スプレッドシートに処理状態と実行IDを持たせます。

エラー行だけを再実行待ちにし、修正後に対象行だけ処理します。

kintoneバックアップ設計はこちら

API制限と処理分割

GAS連携では、GAS側とkintone側の両方の制限を意識します。

kintone REST API概要では、REST APIのリクエストヘッダー、レスポンス、エラー形式に加えて、同時APIリクエスト数、1アプリあたりの日次APIリクエスト数、レコード操作APIで一度に追加・更新・削除できる件数などの制限が説明されています。

Kintone Developer Program：Kintone REST API Overview

制限を無視して全件を一気に処理すると、途中で止まります。

途中で止まったときに、どこまで成功したか分からないと危険です。

観点	設計すること
取得件数	必要なフィールドと条件に絞る
更新件数	一度に処理する行数を分割する
差分条件	前回同期日時以降だけ取得する
リトライ	すぐ再実行するか、時間を置くか
途中停止	最後に成功した行や実行IDを残す
APIレスポンス	エラーコードとメッセージをログへ残す
日次回数	何分ごとに動かすかを決める

Google Apps Script側でも、UrlFetchAppを使って外部サービスへリクエストできます。

Google for Developers：UrlFetchApp

しかし、外部リクエスト、実行時間、トリガー頻度、同時実行が増えるほど、GASだけで抱える負担は大きくなります。

小さく始める場合でも、最初から次のような分割を入れます。

100件ずつ処理する。

対象フィールドだけ取得する。

前回同期日時以降の差分だけ取得する。

成功行に処理済みを付ける。

失敗行は別に残す。

処理件数が増えたら、外部基盤へ移す判断をする。

kintone API制限の設計方法はこちら

GASから外部基盤へ移す判断

GASで作った連携を、いつまでもGASで運用すべきとは限りません。

次の条件が増えたら、外部基盤や連携サービスへの移行を検討します。

条件	移行を考える理由
処理件数が増えた	分割、再実行、監視が重くなる
実行頻度が高い	API制限や実行時間に当たりやすい
双方向同期が必要	競合解決が複雑になる
複数システムをまたぐ	認証情報と失敗パターンが増える
外部顧客向けに使う	可用性、監視、サポートが必要になる
会計・請求など重要データ	監査ログと復旧手順を厚くしたい
作成者に依存している	引き継ぎと保守が難しくなる

外部基盤に移す候補としては、Cloud Functions、Cloud Run、iPaaS、専用連携サービス、個別API連携があります。

どれを選ぶかは、件数、頻度、重要度、監視、保守体制で決めます。

GASを最初の検証に使い、運用が固まったら外部基盤へ移す、という進め方も現実的です。

ただし、その場合も、最初のGASからログ、状態列、更新キー、エラー一覧を持たせておくと移行しやすくなります。

連携パターン別の設計例

ここでは、よくある3つのGAS連携パターンで整理します。

毎朝kintoneの案件一覧をシートへ取得する

この場合、同期方向はkintoneからスプレッドシートへの片方向です。

項目	設計
トリガー	時間主導
kintone権限	レコード閲覧
取得条件	更新日、状態、担当部署など
シート処理	取得結果を一覧へ反映
ログ	取得件数、開始時刻、終了時刻
失敗通知	管理者、利用部門
戻し込み	原則なし

シート上で金額や状態を修正しない前提にします。

修正が必要なら、kintone側で直して次回取得します。

スプレッドシートの棚卸結果をkintoneへ登録する

この場合、同期方向はスプレッドシートからkintoneです。

項目	設計
トリガー	手動実行または時間主導
更新キー	商品コード、倉庫、対象日
検証	空欄、重複、数値、選択肢
kintone処理	棚卸履歴として追加、または在庫を更新
ログ	成功行、失敗行、実行ID
再実行	失敗行だけ対象
退避	更新前CSVを保存

棚卸では、同じ商品コードが複数行に出ることがあります。

倉庫や対象日まで含めて更新キーにするか、履歴として追加するかを決めます。

Googleフォーム回答をkintoneへ登録する

この場合、フォーム送信時トリガーを使えます。

項目	設計
トリガー	フォーム送信時
kintone処理	新規レコード追加
APIトークン	レコード追加権限
入力検証	必須、選択肢、添付ファイル
重複防止	回答IDやメールアドレス、日時を使う
失敗通知	フォーム管理者
後続処理	kintoneのプロセス管理へつなぐ

Kintone Developer Programのチュートリアルでも、Googleフォームの回答をGASで取得し、kintoneアプリへ登録する流れが紹介されています。

Kintone Developer Program：Post Google Forms Responses into Kintone

フォーム回答は入力元として便利ですが、登録後の対応、承認、コメント、権限管理はkintone側で設計します。

kintoneワークフロー設計はこちら

よくある失敗

kintoneとスプレッドシートのGAS連携でよくある失敗をまとめます。

失敗	起きること	対処
コード直書きのトークン	編集者に認証情報が見える	設定として管理し、編集権限を絞る
APIトークン権限が広い	不要な更新や削除ができる	必要な権限だけ付ける
編集時トリガーが広い	予期しない編集でも処理が走る	対象シート、列、状態を限定する
ロックがない	同時実行で二重登録される	LockServiceと状態列を使う
更新キーがない	重複登録や上書きが起きる	recordIdや業務番号を持たせる
ログがない	どこまで成功したか追えない	実行ID、行番号、結果を残す
全件再実行する	成功済み行まで重複処理する	失敗行だけ再実行する
個人アカウント依存	異動や退職で止まる	管理用アカウントと引き継ぎを決める
件数増加を放置	API制限や実行時間で止まる	分割処理と移行判断を持つ

特に危ないのは、動くサンプルコードをそのまま業務へ持ち込むことです。

サンプルは入口として有用です。

しかし、業務では失敗行、再実行、権限、ログ、担当者変更、API制限まで必要になります。

実装前チェックリスト

GAS連携を作る前に、次を確認します。

チェック	内容
目的	取得、登録、更新、通知のどれか
正本	kintoneか、スプレッドシートか、外部システムか
同期方向	片方向か、双方向か
トリガー	時間主導、編集時、フォーム送信時、手動実行
APIトークン	必要最小限の権限か
認証情報	コード直書きではないか
実行者	誰のGoogleアカウントで動くか
更新キー	既存更新と新規登録をどう分けるか
二重実行	LockServiceと状態列で防げるか
競合	kintone側更新後の上書きを止められるか
ログ	実行ID、件数、失敗理由が残るか
通知	失敗時に誰へ届くか
再実行	失敗行だけ処理できるか
制限	件数、頻度、API回数、実行時間を見積もったか
移行判断	GASで続ける条件と外部基盤へ移す条件を決めたか

このチェックが埋まらないままGASを書くと、動くけれど追えない連携になります。

逆に、このチェックを先に決めると、GASで十分な範囲と、最初から連携サービスや外部基盤を使うべき範囲を分けられます。

Bitlightに相談できること

Bitlightでは、kintoneとスプレッドシートのGAS連携を、サンプルコードではなく業務連携として設計できます。

たとえば、次のような支援ができます。

同期方向と正本データを整理する。

APIトークン、GAS実行者、トリガー所有者の権限を設計する。

時間主導、編集時、フォーム送信時、手動実行の使い分けを決める。

LockService、状態列、更新日時を使って二重登録と競合を防ぐ。

同期ログ、失敗通知、失敗行だけの再実行を作る。

API制限に合わせて、分割処理や差分取得を設計する。

GASで始める範囲と、Cloud Functions、Cloud Run、iPaaS、個別API連携へ移す範囲を分ける。

GASは、kintone連携の入口として有効です。

ただし、業務で使うなら「動いた」では終わりません。

止まったときに気づけること、どこまで成功したか分かること、失敗行だけ戻せること、誰の権限で何が更新されたか追えることまで含めて、はじめて現場で使える連携になります。