# 首次获取已授权数据


你可以从已有订阅开始，不需要先创建活动。本指南使用正式环境的 HTTP API，先从头读取最多五条记录。这次请求不会推进组织共享的增量读取位置。

## 开始前

准备安装了 curl 和 Python 3 的终端，以及：

- 目标订阅所属 Organization（组织）中的账户。
- 有效的 **Subscription ID**（订阅 ID）和覆盖该订阅的完整组织 **API Key**（接口密钥）。
- 允许你按预定目的获取和使用数据的适用条款。
- 至少一条符合条件的已交付记录。收费订阅只能重读此前已取得的范围。

Subscription ID 指定数据，API Key 证明组织和访问范围。Campaign ID 不能代替 Subscription ID。在网页看到数据，也不等于已经取得下载、转发或训练用途的授权；发送请求前，请与你的组织确认适用条款。

## 1. 找到订阅

打开[正式环境 Developer 端的 API Keys 页面](https://developer.humanbased.ai/api-keys)，先确认左下角的组织名称。然后在 **Pull data with your API key**（用你的 API 密钥拉取数据）区域找到 **Pull from**（拉取来源），选择目标来源并复制 `subscription_id`。只有一个来源时，页面可能直接显示名称，不出现下拉框。

如果显示 **No subscription yet**（尚无订阅），先不要执行示例命令。本组织自己的活动可由组织成员在创建 Key 时选择符合条件的活动，系统会建立或复用订阅。外部数据则需要先取得相应订阅和使用条件。创建 Key 本身不会购买访问权。

## 2. 取得适用的 Key

组织内任何成员都可以在该页面创建 Key。撤销时，创建者可以撤销自己创建的 Key，Owner 或 Admin 可以撤销组织内所有 Key。已有完整 Key 时，核对列表中的 **Scope**（范围）、**Status**（状态）和 **Expires**（有效期）；Active 状态不覆盖已过的到期日。

需要创建时：

1. 选择 **Create API Key**（创建 API 密钥），填写能辨认用途的 **Name**（名称）。
2. 选择 **Expires**，并在 **Permissions → Data**（权限中的数据访问）开启数据读取。不选择具体来源时，这把 Key 可读取组织目前及以后拥有的全部订阅。
3. 要缩小范围，展开 **Limit this key to specific subscriptions or campaigns**，在 **Subscription access**（订阅访问权限）中选择目标来源；读取自有活动时也可在 **Campaign access**（活动访问权限）中选择符合条件的活动。
4. 确认组织和范围，按页面要求完成协议步骤，再选择 **Create key**。
5. 在 **Your new API key**（你的新 API 密钥）弹窗中复制完整 Key，存入组织认可的密钥保管位置。完整值只显示这一次。

活动标记为 **partial**（部分）时，新 Key 会复用现有订阅的较窄范围，不会自动扩权。范围不符时，请组织管理员检查订阅条件。

## 3. 准备小范围请求

在 bash 或 zsh 中执行以下命令。Key 在输入时不回显，也不会以明文直接出现在命令历史中。不要把它贴进智能体对话、截图、源码或浏览器地址。设置从 `unset HB_API_KEY` 开始：如果该变量此前已被导出，`read` 不会清除它的导出属性，Key 仍会传给你之后在这个终端启动的所有进程。

```sh
export HB_API_URL='https://api.humanbased.ai'
unset HB_API_KEY
printf 'API Key: '
read -rs HB_API_KEY
printf '\nSubscription ID: '
read -r HB_SUBSCRIPTION_ID
```

API 地址、订阅和凭证必须属于同一环境。测试环境使用 `https://api.staging.humanbased.ai` 及该环境签发的凭证。

## 4. 保存第一页

这次请求最多取五条记录，把响应保存到新的本地目录，并打印 HTTP 状态。请妥善保管输出目录中的数据。

```sh
HB_DOWNLOAD_DIR="$(mktemp -d)"
printf 'Response directory: %s\n' "$HB_DOWNLOAD_DIR"
curl --silent --show-error --get "$HB_API_URL/v1/live/pull" \
  --header "Authorization: Bearer $HB_API_KEY" \
  --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
  --data-urlencode 'from=beginning' \
  --data-urlencode 'limit=5' \
  --output "$HB_DOWNLOAD_DIR/first-page.json" \
  --write-out 'HTTP %{http_code}\n'
```

保留 `from=beginning`。去掉它会切换为增量读取：增量位置由同一订阅的所有消费者共享，且可能产生费用。不要为了让空结果变成非空而直接切换模式。

## 5. 检查实际返回

在本地打开保存的 JSON：

```sh
python3 -m json.tool "$HB_DOWNLOAD_DIR/first-page.json"
```

成功响应的 `success` 为 `true`，`errorCode` 为 `0`；本页记录在 `data.items`，`data.count` 是本页数量。

| 字段 | 检查什么 |
| --- | --- |
| `submission_id`、`task_id`、`campaign_id` | 来源记录和任务；保留字符串形式的 ID。 |
| `template_id` | 交付内容对应的模板；空值表示未知。 |
| `data` | 已按交付结构提供的 JSON 内容，不必再次按 JSON 字符串解析。 |
| `quality_grade`、`quality_score` | 记录的等级及映射分数；不能据此证明模型性能提升。 |
| `created_at` | 原提交时间，不是本次请求完成时间。 |

交付字段可能来自对原提交的映射。按约定的输出结构读取，不要假定审核表单与 `data` 使用相同字段名。

一次请求只是一页。`data.has_more=true` 表示还有下一页；最后一页也仅完成当前订阅可读范围的遍历，不代表取得活动全部提交或一个永不变化的数据快照。

## 6. 需要更多时继续分页

复制最近一页 `data.next_cursor` 的字符串值，不带 JSON 引号。保持相同订阅、读取模式和筛选条件。

```sh
printf 'Next cursor: '
read -r HB_CURSOR
HB_NEXT_PAGE="$(mktemp "$HB_DOWNLOAD_DIR/page.XXXXXX")"
printf 'Response file: %s\n' "$HB_NEXT_PAGE"
curl --silent --show-error --get "$HB_API_URL/v1/live/pull" \
  --header "Authorization: Bearer $HB_API_KEY" \
  --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
  --data-urlencode 'from=beginning' \
  --data-urlencode 'limit=5' \
  --data-urlencode "cursor=$HB_CURSOR" \
  --output "$HB_NEXT_PAGE" \
  --write-out 'HTTP %{http_code}\n'
```

每页保存成功后再继续，直到 `has_more=false`。游标是不透明的返回值，不能用 Submission ID 或自己生成的数字替代。如果显示还有下一页却没有 `next_cursor`，停止并保留响应以便排查。

需要用 hb CLI 一次导出某个活动的全部交付记录时，见[导出全部交付记录](/zh/api/cli#导出全部交付记录)。

## 没有取到记录时

| 结果 | 下一步 |
| --- | --- |
| `401` | 核对完整 Key、有效期、撤销状态和 `Bearer ` 前缀。 |
| `403` | 核对 Key 的数据交付权限和订阅范围；不要改用其他组织的 Key 绕过权限。 |
| `404` 或找不到订阅 | 请管理员核对订阅、组织和环境；Campaign ID 不能代填。 |
| `success: true`，但 `items: []` | 检查交付状态、筛选条件，以及收费订阅此前已取得的范围。已接受的工作可能仍待奖励授予或交付。 |
| `400` 或 `422` | 对照[接口参考](/zh/api/api-fields)检查参数、页大小和模式。 |
| `503` 或网络中断 | 稍后重试这次从头读取；只保留完整的成功响应作为有效页。 |

零价订阅可从头读取符合条件、已交付而增量尚未读取的记录；收费订阅只能重读已经取得的范围。重读时 `receipt` 为空，不表示底层数据免费或没有使用限制。

需要支持时，向 [hello@humanbased.ai](mailto:hello@humanbased.ai) 提供环境、请求时间、HTTP 状态和脱敏错误，不要发送完整 Key 或私有数据内容。

## 完成标准

完成本指南时，你应已保存至少一条成功返回的记录，能识别它的来源和交付字段，并确认预定用途的条款。空的成功响应只说明请求成功，至少有一条记录才算取得了数据。

把读取时间、订阅、适用条款和来源标识与本地副本一起记录，并按数据要求妥善保存。响应本身不包含完整许可，也不固定某个数据集版本；订阅只说明你按哪个范围取得数据。数据集的 **Snapshot & license**（快照与授权）目前尚未开放，见[数据使用范围](/zh/data/rights)。

下一步可读[接口参考](/zh/api/api-fields)了解增量读取，或[让智能体执行限定范围的读取](/zh/api/agent-access)。