跳至主要内容
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. 把表格 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 上：在你的 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 填错了——请精确复制表格 URL 中 /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 密钥，并替换掉旧文件。其他一切都不需要改动——邮箱地址和表格共享关系依然有效。

相关页面