跳转到主要内容
目前可用于 批次。 对于抓取、爬网、地图和答案的支持即将推出。
元数据允许您为 Olostep 资源附加自定义键值对。这对于跟踪、过滤、组织和在您的 API 请求中存储上下文非常有用。 元数据遵循 Stripe 的方法 ——简单、灵活且在所有端点上保持一致。

​
使用案例

跟踪与组织

使用订单 ID、客户 ID 或项目名称将资源链接到内部系统。

过滤与搜索

标记资源以便在您的应用程序中轻松检索和过滤。

工作流上下文

存储流水线阶段、优先级或处理指令。

审计追踪

记录谁发起了请求、时间戳或版本信息。

​
在创建时添加元数据

在创建资源时包含 metadata 参数： 
{
  "url": "https://example.com",
  "metadata": {
    "order_id": "12345",
    "customer_name": "John Doe",
    "priority": "high",
    "internal_ref": "proj-2024-001"
  }
}
元数据将在该资源的所有后续 GET 响应中返回。

​
验证规则

限制限制值错误示例
最大键数50"元数据最多可以有 50 个键。您提供了 51 个键。"
键长度40 个字符"元数据键 \"my_very_long_key_name...\" 超过了 40 个字符的限制。"
键格式无方括号"元数据键 \"items[0]\" 不能包含方括号 ([ 或 ])。"
值长度500 个字符"键 \"description\" 的元数据值超过了 500 个字符的限制。"
值类型仅限字符串"键 \"count\" 的元数据值必须是字符串。得到的是对象。"
类型转换：数字和布尔值会自动转换为字符串。
  • 42 → "42"
  • true → "true"
  • 3.14 → "3.14"
对象和数组会被拒绝。

​
更新元数据 (PATCH)

目前可用于： 仅限 批次。爬网、抓取、地图和答案尚不支持在创建后更新元数据。
您可以使用 PATCH 端点 更新现有批次的元数据。更新使用合并行为。

​
更新操作

在保留现有键的同时添加新键。
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"new_key": "new_value"}}'
之前： {"project": "alpha"}
之后： {"project": "alpha", "new_key": "new_value"}
用新值覆盖现有键。
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"project": "beta"}}'
之前： {"project": "alpha", "priority": "high"}
之后： {"project": "beta", "priority": "high"}
将键设置为 null 或 ""（空字符串）以删除它。
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"priority": null}}'
之前： {"project": "alpha", "priority": "high"}
之后： {"project": "alpha"}
将整个元数据字段设置为 null 或 "" 以删除所有键。
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": null}'
之前： {"project": "alpha", "priority": "high"}
之后： {}
在一次请求中添加、更新和删除键。
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"project": "gamma", "new_field": "value", "old_field": null}}'
之前： {"project": "alpha", "old_field": "remove_me"}
之后： {"project": "gamma", "new_field": "value"}

​
PATCH 行为总结

操作请求结果
添加键{"metadata": {"new": "value"}}键已添加，其他保持
更新键{"metadata": {"existing": "new_value"}}键已更新，其他保持
删除键{"metadata": {"key": null}}键已删除，其他保持
删除键{"metadata": {"key": ""}}键已删除，其他保持
清除所有{"metadata": null}所有键已删除
清除所有{"metadata": ""}所有键已删除
无操作{"metadata": {}}无更改