跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.olostep.com/llms.txt

Use this file to discover all available pages before exploring further.

目前适用于Batches。 对于scrapes、crawls、maps和answers的支持即将推出。
元数据允许你为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）

目前适用于： 仅限Batches。Crawls、Scrapes、Maps和Answers尚不支持在创建后更新元数据。
你可以使用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": {}}无变化