Claude Code から Connected Sheets のデータコネクタを繋ぐ

はじめに

Claude Codeに「このBigQueryクエリを、スプレッドシートにConnected Sheetsのデータソースとして挿して」と頼めるようにしたい。そう思って自動化を試みたところ、API自体は単純な一方で、認証まわりに引っかかりどころが多くありました。

本記事では、Connected SheetsのデータソースをAPIで追加する手順と、前提となるADC（Application Default Credentials）の仕組みを紹介します。

やりたかったこと

Connected Sheetsは、スプレッドシートからBigQueryを直接参照できる機能です。データソースの追加は普段UIで行いますが、これをClaude Codeから一言で実行できるようにしたい。

記事執筆時点（2026年8月）では、Google Workspace系のCLI（gogcli / Google Workspace CLI）はデータコネクタの追加に対応しておらず、生のSheets API（spreadsheets.batchUpdateのaddDataSource）を叩く必要があります。

そしてこのAPIは、spreadsheetsとbigquery.readonlyの両スコープを持ったトークンを要求します。この「トークンを用意する」が本記事の本題です。

前提知識：gcloudのcredentialは2セットある

手順に入る前に、前提を整理します。gcloudにはloginコマンドが2つあります。

	gcloud CLI認証	ADC (Application Default Credentials)
コマンド	gcloud auth login	gcloud auth application-default login
保存先	~/.config/gcloud/credentials.db	~/.config/gcloud/application_default_credentials.json
使うのは誰	gcloudコマンド自身	ライブラリ経由の自作コード
スコープ	GCP管理系で固定	--scopesで変更可能

この2つは完全に独立したファイルです。片方を再発行しても、もう片方には一切触れません。

「gcloudは通ってるのにスクリプトが401」「スクリプトは動くのにgcloudがReauthentication required」という一見矛盾した状態は、この分離のせいで普通に起きます。

今回Sheets APIを叩くのは自作コード側なので、必要なのはADCの方です。

ライブラリはADCをどう見つけるか

Pythonのgoogle.auth.default()は次の順でcredentialを探します。

① 環境変数 GOOGLE_APPLICATION_CREDENTIALS が指すファイル
② ~/.config/gcloud/application_default_credentials.json  ← ADC loginが書く場所
③ GCE / Cloud Run等のメタデータサーバー

①が設定されていると②は無視されます。「loginし直したのに古いサービスアカウントで動く」ときは、まず①の環境変数を疑ってください。

認可は3つの軸で決まる

もう1つ、トラブルシューティングに効く知識です。OAuthの認可は独立した3層で決まります。

• client_id — どのアプリとして頼むか
• scope — 何の権限を頼むか
• account — 誰のデータに対してか

そして重要なのがこれです。

refresh_tokenは「account × client × scope」の組に対して発行される

スコープを1つ足しただけでも、クライアントを差し替えただけでも、ブラウザでの再認可が必要になります。「前にログインしたのになぜまた認可画面？」の答えは常にここです。

手順

1. 自前のOAuthクライアントを作る

ADCのデフォルトはgcloud標準のOAuthクライアントですが、このクライアントでSheets系のスコープを要求すると、Googleが「このアプリはブロックされます」で拒否します。

gcloudは全世界に配布されるCLIなので、client secretも中身を見れば取り出せます。つまり誰でも「gcloudです」と名乗って認可画面を出せる状態です。もしこのclient_idにSheetsやGmailのスコープが許されると、Google Cloud SDKを装ったアプリがWorkspaceデータへの同意画面を正規の見た目で出せてしまいます。そのためGoogleは、このclient_idに対してGCP外のスコープをブロックしています。

なので自前のOAuthクライアントを作ります。作成にはGCPプロジェクトが必要です（個人アカウントの無料プロジェクトでも可）。

• GCP Console →「APIとサービス」→「認証情報」→「OAuthクライアントIDを作成」
• アプリケーションの種類はデスクトップアプリ
• 作成したらJSONをダウンロード（以下client_secret.json）

OAuth同意画面が未設定なら先に設定が必要です。注意点として、公開ステータスが「テスト中」のままだとrefresh_tokenが7日で強制失効します。Google Workspace組織なら「内部」タイプにしておくのが楽です。

また、対象プロジェクトでSheets APIとBigQuery APIの有効化も忘れずに。

2. ADCを発行する

gcloud auth application-default login \
  --client-id-file=client_secret.json \
  --scopes=https://www.googleapis.com/auth/cloud-platform,\
https://www.googleapis.com/auth/spreadsheets,\
https://www.googleapis.com/auth/bigquery.readonly

ポイントはスコープです。前述の通りaddDataSourceはspreadsheetsとbigquery.readonlyの両方を持ったトークンを要求します。cloud-platformスコープでは代替されず、bigquery.readonlyの明示が必要です。

ブラウザが開くので認可すれば、application_default_credentials.jsonが書き換わって完了です。

3. quota projectを設定する

ユーザーcredentialのADCは「APIのクォータをどのプロジェクトに付けるか」が曖昧になりがちで、Cannot find a quota project系の警告が出ることがあります。出たらこれで解消します。

gcloud auth application-default set-quota-project YOUR_PROJECT_ID

4. addDataSourceを叩く

Pythonだとこうなります。

import google.auth
from googleapiclient.discovery import build

SCOPES = [
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/bigquery.readonly",
]

creds, _ = google.auth.default(scopes=SCOPES)
service = build("sheets", "v4", credentials=creds)

body = {
    "requests": [{
        "addDataSource": {
            "dataSource": {
                "spec": {
                    "bigQuery": {
                        "projectId": "YOUR_GCP_PROJECT",
                        "querySpec": {
                            "rawQuery": "SELECT * FROM `dataset.table` LIMIT 1000"
                        }
                    }
                }
            }
        }
    }]
}

service.spreadsheets().batchUpdate(
    spreadsheetId="YOUR_SPREADSHEET_ID", body=body
).execute()

実行すると、スプレッドシートにDATA_SOURCEタブが自動で作られ、Connected SheetsのデータソースとしてBigQueryクエリが追加されます。UIから追加した場合と同じ状態です。

5. Claude Codeに覚えさせる

ここまでの知見をCLAUDE.mdに書いておくと、以降は「このクエリをスプシにConnected Sheetsで挿して」の一言でClaude Codeが再現してくれます。

## Connected Sheetsのデータソース追加
- Sheets API `spreadsheets.batchUpdate` の `addDataSource` で追加できる（CLI不可）
- トークンは spreadsheets + bigquery.readonly の両スコープ必須
- ADCは自前OAuthクライアントで発行済み（gcloud標準クライアントはSheets系スコープ不可）
- 定期更新スケジュールだけはAPI不可、UIで設定する

認証は一度セットアップすればrefresh_tokenが生き続けるので、日常運用でやることはありません。

できないこと

APIでできないことも書いておきます。

• 定期更新スケジュールの設定はAPI不可。ここだけUIで設定する必要があります
• DATA_SOURCEタブはvalues APIで参照不可（Unable to parse rangeになります）。他タブの数式からも参照できないので、通常タブとして使いたい場合はUIで「抽出」タブ化が必要です

さいごに

いかがだったでしょうか。

スコープの揃ったADCさえ用意できれば、Connected Sheetsのデータソース追加はaddDataSource一発です。ぜひ試してみてください！