Google App Script中如何迭代API的paged参数自动获取全量数据

核心逻辑是通过循环自动递增paged参数，逐页拉取数据直到判定到最后一页，合并所有结果后一次性返回给表格，全程无需手动修改页码参数。

前置提醒：你当前使用的请求URL存在两处格式错误，会直接导致请求异常，需要先修正：

• date参数混入了注释文字(Date start - yyyy-mm-dd)、(Date end - yyyy-mm-dd)，参数值只需要保留符合格式的日期字符串即可
• status=1,2,3,4 末尾带有多余空格，会导致服务端参数解析失败

具体实现步骤 #

• 打开Google电子表格，点击顶部菜单栏「扩展程序」→「App 脚本」，打开脚本编辑器
• 删除编辑器里默认的空函数，粘贴下面的代码，根据自己的API实际返回结构调整字段映射后保存

function IMPORT_ALL_MATCHES(startDate, endDate, statusList = "1,2,3,4", perPage = 2000) {
  // 替换为你自己的API token
  const API_TOKEN = "xxx-xxx-xxxx-xx";
  // 存储所有拉取到的数据，第一行是表头，根据API实际返回字段修改
  const totalResult = [
    ["比赛ID", "开赛时间", "主队", "客队", "比赛状态", "最终比分"]
  ];
  let currentPage = 1;
  let isLastPage = false;

  while (!isLastPage) {
    // 按API要求拼接请求URL，如果日期区间不是用下划线分隔，替换为对应分隔符即可
    const reqUrl = `https://rest.yyy.com/v2/matches?date=${startDate}_${endDate}&per_page=${perPage}&token=${API_TOKEN}&status=${statusList}&paged=${currentPage}`;
    
    const resp = UrlFetchApp.fetch(reqUrl, {
      method: "GET",
      muteHttpExceptions: true
    });

    // 异常捕获
    if (resp.getResponseCode() !== 200) {
      throw new Error(`第${currentPage}页请求失败，状态码：${resp.getResponseCode()}，错误信息：${resp.getContentText()}`);
    }

    const respData = JSON.parse(resp.getContentText());
    // 按API实际返回结构调整列表提取逻辑：多数接口会把数据列表存在data字段下，部分接口直接返回列表
    const pageList = Array.isArray(respData.data) ? respData.data : respData;

    // 当前页无数据，直接终止循环
    if (pageList.length === 0) {
      isLastPage = true;
      break;
    }

    // 逐行提取字段，映射到表格行，字段名需要和API返回的键名完全对应
    pageList.forEach(item => {
      totalResult.push([
        item.id,
        item.match_time,
        item.home_team,
        item.away_team,
        item.status,
        item.final_score
      ]);
    });

    // 判断是否为最后一页
    // 方法1：当前页返回数据量小于每页设置的最大值，说明没有下一页
    if (pageList.length < perPage) {
      isLastPage = true;
    } 
    // 方法2：如果API返回总页数字段（比如respData.meta.total_pages），可以直接用页码判断，准确率更高
    // else if (currentPage >= respData.meta.total_pages) {
    //   isLastPage = true;
    // }
    else {
      currentPage++;
      // 加200ms请求间隔，避免触发API频率限制，可根据接口规则调整间隔时长
      Utilities.sleep(200);
    }
  }

  return totalResult;
}

• 回到电子表格，直接在空白单元格输入公式即可自动拉取全量数据，无需手动传paged参数：

=IMPORT_ALL_MATCHES("2022-06-01", "2022-07-02")

如果需要自定义筛选状态、单页数据量，直接在公式里传对应参数即可，例如：

=IMPORT_ALL_MATCHES("2022-06-01", "2022-07-02", "1,3", 1000)

注意事项 #

• 代码中的日期拼接规则、响应列表提取逻辑、字段映射都需要根据你所用API的实际文档、返回结构调整，否则会出现取数为空的问题
• 如果API有严格的请求频率限制，可以调大Utilities.sleep()里的数值，单位是毫秒
• 自定义函数单次执行最长时限为30秒，如果拉取数据量过大，建议改成定时触发脚本把数据写入表格，不要用单元格公式触发

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