Apify API：从运行 Actor 到读取 Dataset 的最小安全闭环

证据口径：本页于 2026-07-30 按 Apify API v2 与 API getting started 核对。下面是占位符示例，没有真实 token，也没有为本站触发新 run。

API 接入的可靠路径不是“一次请求永远等到数据回来”，而是：

POST 启动 Actor/Task
  → 保存 Run ID
  → 查询状态
  → 从 Run 读取 defaultDatasetId
  → 分页读取 Dataset items

短任务可以使用同步 endpoint；耗时、结果量或失败重试不可预测时，优先异步流程。

第一步：把 token 放在 header

在 Apify Console 的 API & Integrations 页面创建或读取所需 token，把它放进服务器端秘密变量。官方仍允许 URL query token，但 URL 容易进入浏览历史、代理日志和监控记录，新代码应使用 Bearer header。

export APIFY_TOKEN="<YOUR_TOKEN>"

不要把真实 token 提交到仓库、前端 bundle、截图或聊天。

第二步：异步启动 Actor

下面以 Actor ID 占位符演示；请求体必须按该 Actor 当前 input schema 调整：

curl --request POST "https://api.apify.com/v2/actors/<ACTOR_ID>/runs" \
  --header "Authorization: Bearer $APIFY_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"queries":"coffee shops in Shanghai","maxCrawledPlacesPerSearch":10}'

把响应中的 Run id 保存下来。HTTP 请求成功只说明 run 被创建，不代表采集已成功，也不代表 Dataset 已有完整结果。

第三步：查询 Run 状态

curl "https://api.apify.com/v2/actor-runs/<RUN_ID>" \
  --header "Authorization: Bearer $APIFY_TOKEN"

只有状态进入成功终态后，才把对应 Dataset 交给下游。失败或超时先读日志，不要在没有退避和上限的循环里重新运行。

第四步：从 Run 读取 Dataset ID，再拉结果

从 Run 对象取 defaultDatasetId，不要永久写死一次测试的 Dataset ID：

curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?format=json&limit=100&offset=0" \
  --header "Authorization: Bearer $APIFY_TOKEN"

生产接入要循环 offset/分页直到完成，并保存 Run ID、Dataset ID、输入摘要和采集时间。

同步还是异步

上线前必须处理的失败条件

• 401/403：token 缺失、失效或权限不足；不要改成 query token“试试看”。
• 429/5xx：按响应与官方当前限制做有上限的指数退避，避免重试风暴。
• Run 失败：保存日志与输入，区分目标站、Actor 和调用方问题。
• Dataset 为空：成功状态也可能产生空结果；业务验收不能只看 HTTP 200。
• 重复结果：用 Run ID 和业务键设计幂等，不把网络重试变成重复写入。
• 费用失控：在提交前限制数量、超时和允许的 Actor；实际费用仍以 Console/Billing 为准。

Node.js 与 Python 可使用官方稳定 API 客户端减少轮询样板；无论用 REST 还是客户端，上面的 Run → status → Dataset 证据链不变。