向Google Sheets API追加API_KEY时提示缺少认证凭证的问题

云上老周

2026-5-21

解决Google Sheets API通过API_KEY参数调用get/batchGet的报错问题

我之前帮不少开发者处理过自助终端场景下的Google Sheets API调用问题，你提到的用?key={API_KEY}的方式确实是无认证交互场景的最优解，下面我整理几个常见的报错原因和对应的修复方案，你可以逐一排查：

确认Google Sheets的共享权限设置
很多人会忽略这个核心点：即使你用了合法的API_KEY，表格必须设置为「任何人可查看」（或至少「知道链接的人可查看」）。如果是私有表格，API_KEY是无权访问的，会直接返回权限相关报错。你可以打开目标表格，点击右上角「共享」按钮，确认权限设置符合要求。
检查API_KEY的权限范围与启用状态
1. 登录Google Cloud控制台，找到你的API_KEY所属的项目
2. 确保已经启用了「Google Sheets API」：在API库中搜索该服务，确认状态为「已启用」
3. 检查API_KEY的限制规则：如果设置了HTTP referrer限制，要确保自助终端的访问域名/IP在允许列表内；如果暂时排查问题，可以先移除所有限制测试
4. 确认API_KEY未被禁用、配额未耗尽：在API_KEY详情页可以查看当前状态和配额使用情况
验证请求URL的格式正确性
对于get请求，正确的URL格式应该是：
```
https://sheets.googleapis.com/v4/spreadsheets/{SPREADSHEET_ID}/values/{RANGE}?key={API_KEY}
```
对于batchGet请求，格式是：
```
https://sheets.googleapis.com/v4/spreadsheets/{SPREADSHEET_ID}/values:batchGet?ranges={RANGE1}&ranges={RANGE2}&key={API_KEY}
```
注意细节：
- {SPREADSHEET_ID}是表格URL中d/后面的长字符串，比如https://docs.google.com/spreadsheets/d/abc123xyz/edit里的abc123xyz
- {RANGE}要严格遵循A1表示法，比如Sheet1!A1:B10，包含特殊字符时要做URL编码
- API_KEY必须作为URL参数追加，不能放在请求体中

jQuery请求的跨域与格式问题
自助终端如果是本地页面或跨域访问，要确保jQuery请求设置了正确的dataType：

$.get({
  url: 'https://sheets.googleapis.com/v4/spreadsheets/{SPREADSHEET_ID}/values/Sheet1!A1:B5?key={API_KEY}',
  dataType: 'json',
  success: function(data) {
    console.log('数据获取成功：', data);
  },
  error: function(xhr, status, error) {
    console.error('请求报错详情：', xhr.responseText);
  }
});

另外要注意：get和batchGet都是GET请求，不要用POST方式调用，否则会返回「方法不允许」的报错。

排查2016年"修复"相关的遗留限制
你提到2016年有帖子说该问题被修复，当时主要是解决了API_KEY访问公开表格的权限阻塞问题，但新的限制可能来自：
- 新创建的Google Cloud项目默认启用了API_KEY的安全限制，需要手动调整
- 若表格包含敏感内容，即使设置为公开，Google可能会自动限制API访问（这种情况少见，可以先创建一个仅含测试数据的表格验证）

最后建议你先直接用浏览器访问构造好的URL，查看返回的具体报错信息（比如403 Forbidden、API_KEY_INVALID、404 Not Found），根据提示针对性解决会更高效。

内容的提问来源于stack exchange，提问作者J. Martin