跳转到正文
Docs
下载 Markdown
文章目录

导出全部交付记录

按步骤完成一项 CLI 工作,开始前核对凭证与环境。

下载 Markdown

执行前先查操作开放范围与兼容性。

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本次命令读到的记录,顺序与服务端返回一致。
countitems 中的记录数。
pages_read本次命令请求的页数。
has_more命令停止时,服务端是否仍报告还有记录。
next_cursor之后可以续读的位置,或 null。
complete只有未传 --cursor、从第一条读到最后一页时才是 true。
pagination_stop_reasonnull,或 --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_ARGUMENTCampaign 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。
4Key 没有数据读取权限,或订阅在它的范围或组织之外。按创建和使用 API Key检查 Key 的 Data 授权。
4,SUBSCRIPTION_NOT_BOUND没写 --subscription,而这把 Key 不通过任何订阅读取该活动。没有读取任何记录。核对 Campaign ID。本组织自己的活动,可在 Campaign access(活动访问权限)中选中它,创建一把 Key。
6服务暂时不可用,或输出没有送达。重新执行同一条命令;从头读取既不计费,也不移动读取位置。

接口操作和权限见 Campaign API。把一次限定范围的读取交给智能体,见通过智能体使用 Humanbased。