执行前先查操作开放范围与兼容性。
hbd campaign records pull 读取一个活动Developer 组织的一组数据工作及其相关设置交付到某项订阅的记录。它固定从第一条开始读,订阅的增量读取位置保持原位。活动筛选只会在订阅已授权的范围内缩小结果:收费订阅的范围仍是此前已取得的那一段,读到的始终是已交付记录,而非活动的全部提交。先确认 hbd --help --json 列出了这条命令;你的版本没有它时,改用 HTTP 数据接口逐页读取。
凭证与第一页
这条命令需要一把对该订阅有数据读取权限的完整组织 API Key,hbd auth login 的登录会话会被拒绝。只有 Data 授权的 Key 也可以运行 hbd capabilities;它会显示 Campaign API 目录不可用,这对本命令没有影响。按首次获取已授权数据设置 HB_API_KEY 和 HB_SUBSCRIPTION_ID,再把 Key 只交给这一条命令:
printf 'Campaign ID: '
read -r HB_CAMPAIGN_ID
HB_API_KEY="$HB_API_KEY" hbd campaign records pull "$HB_CAMPAIGN_ID" \
--subscription "$HB_SUBSCRIPTION_ID" \
--limit 5 --json不加 --all 时只读一页,并返回 data.next_cursor。--limit 是每页条数,默认 50,最多 200。命令只接受一个 Campaign ID。
这把 Key 只通过一个订阅读取该活动时,可以不写 --subscription:命令会找到这个订阅,在附注里写明用的是哪一个,并在 data.subscription_id 中返回。有多个订阅时,命令什么也不读,返回 SUBSCRIPTION_AMBIGUOUS;hbd campaign subscription list <campaign-id> 按创建时间从新到旧列出它们。带 --cursor 续读时,每次都要写明订阅。
导出所有页
--all 沿游标继续读取,直到服务端报告没有更多记录。把结果写进私有目录:
HB_EXPORT_DIR="$(mktemp -d)"
printf 'Export directory: %s\n' "$HB_EXPORT_DIR"
HB_API_KEY="$HB_API_KEY" hbd campaign records pull "$HB_CAMPAIGN_ID" \
--subscription "$HB_SUBSCRIPTION_ID" \
--limit 200 --all --json > "$HB_EXPORT_DIR/campaign-records.json"
printf 'Exit code: %s\n' "$?"记录在 data.items。两项检查都通过,才把这个文件当作完整导出:退出码为 0,且 data.complete 为 true。
data 字段 | 含义 |
|---|---|
items | 本次命令读到的记录,顺序与服务端返回一致。 |
count | items 中的记录数。 |
pages_read | 本次命令请求的页数。 |
has_more | 命令停止时,服务端是否仍报告还有记录。 |
next_cursor | 之后可以续读的位置,或 null。 |
complete | 只有未传 --cursor、从第一条读到最后一页时才是 true。 |
pagination_stop_reason | null,或 --all 提前停止的原因。 |
每行导出一个 JSON 对象
如果 hbd campaign records pull --help 列出 --jsonl,可用它将每条交付记录写成标准输出中的一行。把上方导出命令中的 --json 换成 --jsonl,将输出保存为 campaign-records.jsonl。每行字段与 JSON 封套中 data.items 的一条记录相同。加 --quiet 可隐藏进度计数。
写完记录后,命令会在标准错误输出中写出以 records-checkpoint 开头的一行。解析前缀后的 JSON 对象,可读取 count、pages_read、complete、has_more、next_cursor、pagination_stop_reason、campaign_id 和 subscription_id。只有退出码为 0 且 complete: true 时,文件才是完整导出。从 --cursor 开始的读取即使到了末页,也只是其中一段。
--all 因分页上限或无效游标提前停止时,退出码为 1,已读取的记录和部分导出的检查点仍会输出。如果检查点给出游标,用其中的 next_cursor 和 subscription_id 续读。读取途中发生请求错误时,标准输出为空。请随导出文件保留退出码和检查点。
完整结果与部分结果
以下示例使用 HB_CLI_ENVELOPE_VERSION=v1 选择旧版 v1 输出。新的默认版本 v2 还会返回顶层 nextAction 字段。示例省略了 data.items、context 和 notices,标识符仅供示意。
{
"apiVersion": "humanbased.cli/v1",
"command": "campaign.records.pull",
"requestId": "e9dc2862-d165-44ce-b54a-42111284bd40",
"context": {
"profile": null,
"apiOrigin": "https://api.humanbased.ai",
"organizationId": "10571000020000000001"
},
"data": {
"subscription_id": "784210003001",
"campaign_id": "784210001001",
"count": 1342,
"pages_read": 7,
"has_more": false,
"next_cursor": null,
"complete": true,
"pagination_stop_reason": null
},
"notices": [],
"error": null
}部分导出以 1 退出。文件里仍保留已读到的记录,并说明停在哪里:
{
"apiVersion": "humanbased.cli/v1",
"command": "campaign.records.pull",
"requestId": "e9dc2862-d165-44ce-b54a-42111284bd40",
"context": {
"profile": null,
"apiOrigin": "https://api.humanbased.ai",
"organizationId": "10571000020000000001"
},
"data": {
"subscription_id": "784210003001",
"campaign_id": "784210001001",
"count": 100000,
"pages_read": 500,
"has_more": true,
"next_cursor": "example-opaque-cursor",
"complete": false,
"pagination_stop_reason": "item_limit"
},
"notices": [],
"error": {
"code": "PAGINATION_INCOMPLETE",
"httpStatus": null,
"message": "The --all walk stopped while the server still reported more pages. The partial data and a continuation cursor, when available, are included.",
"retryable": false,
"nextAction": null,
"details": null
}
}pagination_stop_reason | 发生了什么 | 你现在做什么 |
|---|---|---|
page_limit | 命令已读 1,000 页。按默认每页 50 条,就是 50,000 条记录。 | 从 next_cursor 续读。加 --limit 200 可让单次命令读到更多记录。 |
item_limit | 命令已读 100,000 条记录。 | 从 next_cursor 续读。 |
missing_cursor | 服务端报告还有记录,却没有返回游标。 | next_cursor 为 null,这个文件没有安全的续读位置。保留它供排查,再从第一条重新导出。 |
repeated_cursor | 服务端返回了本次命令已经用过的游标。 | next_cursor 为 null。重复的游标只会回到同一页,请从第一条或你此前保存的更早游标重新导出;再次出现时联系 support@humanbased.ai。 |
续读部分导出
只有 data.next_cursor 是字符串时才续读。复制它的值,去掉 JSON 引号:
printf 'Part number, 2 for the first continuation: '
read -r HB_PART
printf 'Next cursor: '
read -r HB_CURSOR
HB_API_KEY="$HB_API_KEY" hbd campaign records pull "$HB_CAMPAIGN_ID" \
--subscription "$HB_SUBSCRIPTION_ID" \
--cursor "$HB_CURSOR" \
--limit 200 --all --json > "$HB_EXPORT_DIR/campaign-records-$HB_PART.json"
printf 'Exit code: %s\n' "$?"一次运行最多读取 100,000 条记录,较大的导出需要续读多次。每次续读保存为单独的文件:第 2 部分、第 3 部分,依此类推。续读结果覆盖了之前的文件,那一部分记录就丢失了。
续读文件只包含游标之后的记录。即使它读到最后一页并以 0 退出,data.complete 仍是 false。完整导出等于第一个文件的 data.items 依次接上每个续读文件的 data.items,各次命令使用同一个活动和订阅。
保护输出
| 导出的哪一部分 | 对你意味着什么 |
|---|---|
| 记录内容 | data.items[].data 按交付时的原样写出,外形像凭证的值也照样保留。按源数据的要求保管这个文件。 |
| 数字 | 记录内容里的数字保留原有位数,包括超出 JavaScript 安全整数范围的整数和长小数。数值需要这种精度时,用能保留它的解析器读取。 |
| 临时文件 | 读取期间,CLI 把记录暂存在系统临时目录里仅当前用户可读的文件中,命令结束时删除。请在那里留出整份导出所需的空间。 |
| 输出中断 | 管道关闭或目标位置写满时,命令以非零退出码结束,并在标准错误输出报告原因。已经写出一部分的 JSON 文件是残缺的:丢弃它,重新导出。 |
错误
退出码与 error.code | 原因 | 你现在做什么 |
|---|---|---|
1,PAGINATION_INCOMPLETE | --all 在还有记录时停止。 | 查看 data.pagination_stop_reason,按上文续读。 |
2,INVALID_ARGUMENT | Campaign ID 为空或是逗号分隔的列表,某个 ID、游标外形像凭证,或带了 --cursor 却没写 --subscription。请求没有发出。 | 只传一个 Campaign ID 和真实的标识符。Key 只通过 HB_API_KEY 或 --token-stdin 提供。 |
2,SUBSCRIPTION_AMBIGUOUS | 没写 --subscription,而这把 Key 通过多个订阅读取该活动。没有读取任何记录。 | 用 hbd campaign subscription list <campaign-id> 选定一个,再用 --subscription 传入。 |
3 | 没有可用凭证:Key 缺失、格式有误、过期或已撤销,或者用了登录会话。 | 提供完整的组织 API Key。 |
4 | Key 没有数据读取权限,或订阅在它的范围或组织之外。 | 按创建和使用 API Key检查 Key 的 Data 授权。 |
4,SUBSCRIPTION_NOT_BOUND | 没写 --subscription,而这把 Key 不通过任何订阅读取该活动。没有读取任何记录。 | 核对 Campaign ID。本组织自己的活动,可在 Campaign access(活动访问权限)中选中它,创建一把 Key。 |
6 | 服务暂时不可用,或输出没有送达。 | 重新执行同一条命令;从头读取既不计费,也不移动读取位置。 |
接口操作和权限见 Campaign API。把一次限定范围的读取交给智能体,见通过智能体使用 Humanbased。