Node.js中@hubspot/api-client如何用after实现联系人分页

基于after游标的标准分页实现 #

首先纠正一个常见误区：v3版本@hubspot/api-client的getPage方法after入参不支持直接传入联系人ID，传联系人ID是旧版v1 API的规则，v3版本该参数需要传入接口返回的分页游标，正确实现逻辑如下：

• 第一页请求时，after参数传undefined即可，无需赋值
• 每一页请求完成后，检查响应结果中的paging?.next?.after字段：
  • 如果该字段存在有效值，将该值作为下一次请求的after入参，继续拉取下一页
  • 如果该字段不存在，说明已经拉取完所有数据，终止分页流程
• 单页limit参数最大值为100，传入超过100的值接口会自动截断，不生效
• 禁止手动构造after值，必须使用接口返回的游标，否则会出现400报错、数据重复/遗漏问题

可直接复用的分页代码示例：

async function fetchAllContacts() {
  const contactList = []
  let afterCursor = undefined
  // 按需配置以下参数
  const pageSize = 100
  const properties = ['email', 'firstname', 'lastname', 'phone']
  const propertiesWithHistory = []
  const associations = []
  const includeArchived = false

  do {
    const resp = await hubspotClient.crm.contacts.basicApi.getPage(
      pageSize,
      afterCursor,
      properties,
      propertiesWithHistory,
      associations,
      includeArchived
    )
    contactList.push(...resp.results)
    // 更新下一页游标
    afterCursor = resp.paging?.next?.after
  } while (afterCursor)

  return contactList
}

// 调用示例
fetchAllContacts()
  .then(contacts => console.log(`拉取到${contacts.length}个联系人`))
  .catch(err => console.error('拉取失败', err))

其他可选分页方案 #

• SDK内置自动分页方法
  如果不需要自定义分页逻辑，可以直接调用SDK封装的getAll方法，内部会自动处理游标翻页，代码更简洁，适合数据量不大的场景：

  // 自动翻页拉取所有联系人，无需手动处理after参数
  const allContacts = await hubspotClient.crm.contacts.basicApi.getAll(
    100,
    ['email', 'firstname', 'lastname'],
    [],
    []
  )
  

  注意：该方法会一次性拉取全量符合条件的数据，联系人量级超过10w时不建议使用，避免内存占用过高。
• 搜索接口分页
  如果需要带筛选条件、排序规则拉取联系人，可以使用crm.contacts.searchApi.doSearch方法，分页逻辑和getPage完全一致，同样通过响应中的paging.next.after游标实现翻页，支持更灵活的查询规则。
• Webhook增量同步
  如果是做数据双向同步场景，不要用定时全量翻页拉取的方案，直接配置联系人变更Webhook，监听创建、更新、删除事件做增量同步，实时性和性能远高于定时分页拉取。

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