本文へスキップ
SheetForge

Googleシートの設定 — サービスアカウントと JSON キー

SheetForge は、Googleシートを二つのモードで読み取ります。

  • ExportUrl は認証情報を必要としません: シートをリンクで共有し、各タブの #gid= の値を登録してインポートするだけです。読み取り専用です。
  • SheetsApi は Google の サービスアカウント として認証し、それ以外のすべて(プライベートなシート、書き戻し(反映)、Push)を解放します。

このページでは、SheetsApi のセットアップを最初から最後まで説明します——サービスアカウントの作成、その JSON キーのダウンロード、スプレッドシートをそのアカウントと共有すること、そして SheetForge にそのキーの場所を指定することです。Google Cloud の事前知識は前提としません。すべての手順は Web ブラウザーの中で完結し、費用は一切かかりません。

全体の流れ:

  1. Google Cloud プロジェクトを作成する。
  2. その中で Google Sheets API を有効化する。
  3. サービスアカウントを作成する。
  4. そのアカウントの JSON キーをダウンロードする。
  5. そのアカウントのメールアドレスとスプレッドシートを共有する。
  6. SheetForge にそのキーの場所を指定する。

1. Google Cloud プロジェクトを作成する

  1. console.cloud.google.com を開き、Google アカウントでサインインしてください——スプレッドシートの所有者と同じアカウントである必要はありません。個人アカウントであれば常に機能します。会社の Google Workspace 組織の中には、ポリシーによってサービスアカウントキーのダウンロードを無効化しているところもあり、その場合は手順4が組織ポリシーのエラーで失敗します(下記「うまくいかない場合」を参照)。初回アクセス時は、利用規約(Terms of Service)のプロンプトに同意するとコンソールに到達します。
  2. 上部のバーで project picker(Google Cloud のロゴの隣にあるドロップダウン)をクリックし、続いて New project をクリックしてください。
  3. 任意の名前(例: sheetforge-sheets)を入力し、Create をクリックしてください。organization と location はデフォルトのままにしておきます。
  4. 「project created」の通知が表示されたら、picker で新しいプロジェクトを選択してください。これ以降の手順はすべて、このプロジェクトの 内側で 行われるため、選択されたままになっていることを確認してください。

プロジェクトは、API 設定を入れるための単なる入れ物です。作成は無料であり、このガイドで行う Sheets API の利用にも費用はかかりません。

2. Google Sheets API を有効化する

  1. 左側のメニュー(☰)を開き、APIs & Services ▸ Library に進んでください。
  2. Google Sheets API を検索し、その結果を開いてください。
  3. Enable をクリックしてください。ボタンが Manage と表示されている場合、API はすでに有効化されています——何もする必要はありません。

3. サービスアカウントを作成する

サービスアカウントとは、独自のメールアドレスを持つ、機械のためのアイデンティティです。SheetForge は、このアイデンティティとしてサインインします——あなた個人の Google パスワードが関わることは一切ありません。

  1. APIs & Services ▸ Credentials に進んでください。
  2. + Create credentials ▸ Service account をクリックしてください。
  3. 名前(例: sheetforge-reader)を入力してください。account ID は自動的に入力されます。Create and continue をクリックしてください。
  4. 「Grant this service account access to project」と「Grant users access」の手順は 任意です——両方とも読み飛ばして Done をクリックしてください。スプレッドシートへのアクセス権は、プロジェクトのロールではなく、シートを共有すること(手順5)によって与えられます。
  5. コンソールが OAuth consent screen の設定を提案してきた場合は、無視して構いません——サービスアカウントはそれを使用しません。

4. JSON キーをダウンロードする

  1. Credentials ページに戻り、たった今作成したサービスアカウントをクリックしてください(「Service accounts」の下にあります)。
  2. Keys タブを開いてください。
  3. Add key ▸ Create new key をクリックし、JSON を選んで Create をクリックしてください。
  4. ブラウザーが sheetforge-sheets-1a2b3c.json のような名前のファイルをダウンロードします。これが唯一のコピーです——Google は再ダウンロード用にこれを保持しません。紛失した場合は、Keys タブでそのキーを削除し、新しいものを作成してください。

このファイルは、パスワードと同じように扱ってください:

  • Unity プロジェクトとリポジトリの 外側 のどこかに移動してください。例: C:/keys/sheetforge.json。
  • 絶対に Assets/ の下には置かないでください——そこにあるものはすべてプロジェクトと一緒にコミットされ、迷い込んだ参照(あるいは Resources/StreamingAssets フォルダー)が、それをビルドの中に持ち込んでしまう可能性があります。
  • もしキーが漏洩した場合は、Keys タブでそれを削除し(これにより即座に失効します)、新しいものを作成してください。

5. スプレッドシートをサービスアカウントと共有する

キーだけでは何の権限も得られません。サービスアカウントが読み取れるのは、明示的に共有されたシートだけです——人間の共同編集者とまったく同じです。

  1. ダウンロードした JSON ファイルを任意のテキストエディターで開き、client_email の値をコピーしてください。これは sheetforge-reader@sheetforge-sheets.iam.gserviceaccount.com のような形をしています。
  2. Google Sheets でスプレッドシートを開き、Share をクリックしてください。
  3. そのアドレスを貼り付け、ロールを選んでください:
    • インポートだけなら Viewer で十分です。
    • 書き戻し——オーサリングの反映と Push——には Editor が必要です。
  4. 「Notify people」をオフにして(このアドレスに受信箱はありません)、確定してください。
  5. Google が組織外との共有について警告してきた場合は、確定してください——サービスアカウントはどの組織にも属していません。

この手順を飛ばすことが、最もよくあるセットアップのミスです——それをしないと、キーがどれほど正しくても、すべてのリクエストが権限エラーで失敗します。

6. SheetForge にそのキーの場所を指定する

  1. インポート設定アセットで、source を GoogleSheet に、access mode を SheetsApi に設定してください。
  2. シートの URL に含まれる長い ID を spreadsheetId に入力してください: https://docs.google.com/spreadsheets/d/<this part>/edit。
  3. キーファイルの場所を、次の二つのどちらかの方法で SheetForge に伝えてください:
    • 推奨 — 環境変数。 SHEETFORGE_SHEETS_KEY に、JSON ファイルの絶対パスを設定してください。各開発者が自分自身のものを設定するため、パスがリポジトリに入り込むことは一切なく、設定フィールドよりも優先されます。
      • Windows の場合: ターミナルで setx SHEETFORGE_SHEETS_KEY "C:\keys\sheetforge.json" を実行し、Unity と Unity Hub の両方を再起動してください(すでに実行中のプロセスは、古い環境をそのまま保持します)。
      • macOS/Linux の場合: シェルのプロファイルでエクスポートし、そのシェルから Unity を起動するか、macOS では launchctl setenv を使ってください。
    • または — 設定フィールド。 serviceAccountKeyPath にパスを入力し、リポジトリの 外側 を指すようにしてください。
  4. Tools ▸ SheetForge ▸ Data Studio で ↓ Pull from source を押してください。レポートが成功していれば、プロジェクト・API・アカウント・共有・キーという連鎖全体が機能していることを意味します。

うまくいかない場合

  • 権限エラー(PERMISSION_DENIED / 403): シートが client_email アドレスと共有されていません(手順5)——ID は実在するスプレッドシートを指していますが、サービスアカウントからはそれが見えません。
  • Requested entity was not found(404): spreadsheetId が間違っています——シートの URL の /d/ と /edit の間の部分を、そのまま正確にコピーしてください。
  • 「Service account key creation is disabled」/ 手順4での組織ポリシーエラー: あなたの Google Workspace 組織が iam.disableServiceAccountKeyCreation を強制しています。管理者にこのプロジェクトでのキー作成を許可してもらうか、個人の Google アカウントの下でプロジェクトを作成してください——スプレッドシートは、シートの所有者が誰であっても、そのプロジェクトのサービスアカウントと共有できます。
  • 「Google Sheets API has not been used in project … or it is disabled」: キーを発行したプロジェクトで API が有効化されていません(手順2)——別のプロジェクトではなく、そのプロジェクトで有効化してください。有効化した直後の API が反映されるまで、数分かかることがあります。
  • Key file not found: パスにタイプミスがあるか、環境変数が存在するようになる前に Unity が起動されています——変数を設定してから、Unity と Unity Hub を再起動してください。
  • キーが漏洩した、または紛失した場合: サービスアカウントの Keys タブでそれを削除し、新しい JSON キーを作成して、ファイルを置き換えてください。それ以外は何も変わりません——メールアドレスとシートの共有は有効なままです。

関連ページ