Java Spring后端使用Google服务账户访问Sheets遇403权限问题

嘿，我之前也踩过一模一样的坑！用服务账户替换3-legged OAuth访问Sheets时，403权限错误是最常见的问题，咱们一步步来排查解决：

1. 最容易忽略的关键：给服务账户共享目标Sheet权限 #

服务账户本质是一个「虚拟用户」，你必须像给普通同事共享Sheet一样，把它添加到目标表格的共享列表里：

• 打开你的Google Sheet，点击右上角的「共享」按钮
• 输入服务账户的client_email（在你下载的服务账户JSON密钥文件里能找到）
• 根据需求给它分配「编辑者」或「查看者」权限，然后发送邀请

这一步没做的话，哪怕代码和配置全对，也会直接报403。

2. 确认Google Sheets API已在GCP控制台启用 #

很多人重构代码时会漏掉这一步：

• 登录GCP控制台，找到你的项目
• 进入「API和服务」→「库」
• 搜索「Google Sheets API」，如果显示「启用」按钮就点击启用；如果已经是「管理」状态就没问题

API未启用时，任何调用都会返回权限错误。

3. 检查服务账户认证代码的正确性 #

替换AuthCodeFlow后，服务账户的认证逻辑要对应调整，这里给你一个标准的示例：

import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.auth.oauth2.ServiceAccountCredentials;

import java.io.FileInputStream;
import java.util.Collections;

public class SheetsServiceHelper {
    public static Sheets getSheetsService() throws Exception {
        // 加载服务账户密钥文件（替换成你的密钥路径）
        ServiceAccountCredentials credentials = ServiceAccountCredentials.fromStream(
                new FileInputStream("src/main/resources/service-account-key.json"))
                .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));

        // 构建Sheets服务实例
        return new Sheets.Builder(GoogleNetHttpTransport.newTrustedTransport(),
                JacksonFactory.getDefaultInstance(), credentials)
                .setApplicationName("你的应用名称")
                .build();
    }
}

这里要注意两个关键点：

• 确保使用的Scope正确：如果只是读取数据，用SheetsScopes.SPREADSHEETS_READONLY；需要编辑的话用SheetsScopes.SPREADSHEETS
• 密钥文件路径要正确，避免因找不到文件导致的隐性认证失败

4. 排查完整的错误信息 #

你提到错误提示是「The cal...」，完整的应该是「The caller does not have permission」。如果上面三步都做了还是报错，可以：

• 检查服务账户的IAM角色（在GCP控制台「IAM与管理员」→「IAM」里），确保它有必要的权限（比如Editor或更细粒度的Sheets权限）
• 用GCP的「API测试工具」直接调用Sheets API的spreadsheets.get接口，测试服务账户的权限是否正常

按照这个流程走下来，90%的403问题都能解决！

内容的提问来源于stack exchange，提问作者Thstd