跳至主要內容
SheetForge

Google 試算表設定——服務帳戶與 JSON 金鑰

SheetForge 以兩種模式讀取 Google 試算表。

  • ExportUrl 不需要任何憑證：透過連結分享試算表、為每個分頁註冊其 #gid= 值後即可匯入。它僅供唯讀。
  • SheetsApi 會以 Google 服務帳戶 的身分進行驗證，並解鎖其餘的一切：私人試算表、寫回（反映），以及推送。

本頁將完整說明 SheetsApi 的設定流程——建立服務帳戶、下載其 JSON 金鑰、將你的試算表分享給它，並讓 SheetForge 指向該金鑰。不需要任何 Google Cloud 使用經驗；每個步驟都在網頁瀏覽器中完成，且完全免費。

整體流程：

  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 出現組織政策錯誤（請參閱下方「若發生問題」）。第一次造訪時，請先同意服務條款提示才能進入主控台。
  2. 在頂端列中，點按專案選擇器（Google Cloud 標誌旁的下拉選單），接著點選 New project。
  3. 輸入任意名稱（例如 sheetforge-sheets），然後點按 Create。組織與位置欄位維持預設值即可。
  4. 當「project created」通知出現時，請在選擇器中選取這個新專案。以下所有內容都會在這個專案內進行，請確保它維持在選取狀態。

專案只是 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）；帳戶 ID 會自動填入。點按 Create and continue。
  4. 「Grant this service account access to project」與「Grant users access」這兩個步驟都是選填——兩者皆可略過，直接點按 Done。對你試算表的存取權限是透過分享試算表（步驟 5）授予的，而非透過專案角色。
  5. 若主控台建議你設定 OAuth 同意畫面，可以忽略——服務帳戶不需要用到它。

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 試算表中開啟你的試算表，點按 Share。
  3. 貼上該地址並選擇一個角色：
    • Viewer 即可滿足匯入需求。
    • 寫回作業——編寫的反映與推送——則需要 Editor。
  4. 關閉「Notify people」（該地址沒有收件匣）並確認。
  5. 如果 Google 對「分享給組織外部」提出警告，請確認繼續——服務帳戶不屬於任何組織。

略過這個步驟是最常見的設定錯誤——無論金鑰多麼正確，之後的每一次請求都會因權限錯誤而失敗。

6. 讓 SheetForge 指向該金鑰

  1. 在你的匯入設定資源中，將來源設為 GoogleSheet，存取模式設為 SheetsApi。
  2. 在 spreadsheetId 中填入試算表網址中那一長串 ID：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 上：在你的 shell 設定檔中匯出該變數，並從該 shell 啟動 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 有誤——請精確複製試算表網址中 /d/ 與 /edit 之間的那一段。
  • 步驟 4 出現「Service account key creation is disabled」／組織政策錯誤： 你的 Google Workspace 組織強制套用了 iam.disableServiceAccountKeyCreation。請管理員允許此專案建立金鑰，或改用個人 Google 帳戶建立專案——無論試算表的擁有者是誰，都可以將它分享給該專案的服務帳戶。
  • 「Google Sheets API has not been used in project … or it is disabled」： 發出該金鑰的專案尚未啟用此 API（步驟 2）——請在那個專案中啟用，而不是其他專案。剛啟用的 API 可能需要幾分鐘才會生效。
  • 找不到金鑰檔案： 路徑有拼字錯誤，或是 Unity 在環境變數建立之前就已啟動——請先設定變數，再重新啟動 Unity 與 Unity Hub。
  • 金鑰外洩或遺失： 在服務帳戶的 Keys 分頁中刪除它，建立一支新的 JSON 金鑰，並替換檔案。其餘一切都不會改變——電子郵件地址與試算表分享設定依然有效。

相關頁面