调用HubSpot API拉取Deals同步Google Sheets出现列数不匹配错误求助

报错根因 #

你遇到的列数不匹配错误，核心是getStages()函数没有拿到有效返回数据，导致写入表格时数组结构异常，主要有3个触发原因：

1. 授权范围配置错误：你当前的SCOPE仅设置了contacts，没有交易、销售管道的访问权限，HubSpot API会拒绝你的数据请求，导致getStages()执行异常返回非数组值
2. 管道ID配置错误：你写死的pipeline_id = "default"不适用于新版HubSpot，实际默认管道ID为数字字符串，找不到匹配管道时stages会返回空数组
3. 缺少容错处理：代码没有对API请求失败、数据为空的情况做校验，异常数据传入写入函数后就会触发列数不匹配报错

修复方案 #

1. 修正授权范围 #

将SCOPE配置替换为包含交易和管道访问权限的配置：

var SCOPE = 'deals contacts crm.pipelines.deals.read';

修改后需要重新走一次授权流程，确保权限生效。

2. 替换为实际管道ID #

登录HubSpot后台，依次进入「设置」→「对象」→「交易」→「管道」，选择你要同步的管道后，地址栏中pipelineId=后的数字字符串就是实际ID，替换代码中的"default"。

3. 增加容错处理 #

给写入函数增加数据校验、表格存在性判断，避免异常数据导致报错，修改后的writeStages参考：

function writeStages(stages) {
   // 校验数据有效性
   if(!stages || !Array.isArray(stages)) {
      stages = [];
      Logger.log("未获取到有效阶段数据，请检查权限和管道ID配置");
   }
   var ss = SpreadsheetApp.getActiveSpreadsheet();
   // 自动创建不存在的工作表
   var sheet = ss.getSheetByName(sheetNameStages) || ss.insertSheet(sheetNameStages);
   var matrix = [["StageID","Label"]];
   matrix = matrix.concat(stages);
   var range = sheet.getRange(1,1,matrix.length,matrix[0].length);
   range.setValues(matrix);
}

同样可以给writeDeals函数也加上相同的容错逻辑，另外可以在refresh函数中增加异常捕获，方便排查问题：

function refresh() {
   var service = getService();
   if (service.hasAccess()) {
      try {
         var stages = getStages();
         writeStages(stages);
         var deals = getDeals();
         writeDeals(deals);
         Logger.log("数据同步完成");
      } catch (e) {
         Logger.log("同步出错：" + e.toString());
      }
   } else {
      var authorizationUrl = service.getAuthorizationUrl();
      Logger.log('请打开以下地址授权后重新运行脚本：%s', authorizationUrl);
   }
}

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