元数据

目前适用于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"
  }
}

import requests

response = requests.post(
    "https://api.olostep.com/v1/batches",
    headers={"Authorization": "Bearer <your_token>"},
    json={
        "items": [{"custom_id": "1", "url": "https://example.com"}],
        "metadata": {
            "project": "q4-analysis",
            "team": "data-ops",
            "priority": "high"
        }
    }
)

const response = await fetch("https://api.olostep.com/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    items: [{ custom_id: "1", url: "https://example.com" }],
    metadata: {
      project: "q4-analysis",
      team: "data-ops",
      priority: "high"
    }
  })
});

元数据将在该资源的所有后续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": {}}`	无变化

常用

抓取

批次

抓取

地图

答案

搜索

显示器

文件

日程表

检索

反馈

余额与账单

使用场景

跟踪与组织

过滤与搜索

工作流上下文

审计追踪

在创建时添加元数据

验证规则

更新元数据（PATCH）

更新操作

PATCH行为总结

​使用场景

跟踪与组织

过滤与搜索

工作流上下文

审计追踪

​在创建时添加元数据

​验证规则

​更新元数据（PATCH）

​更新操作

​PATCH行为总结

使用场景

在创建时添加元数据

验证规则

更新元数据（PATCH）

更新操作

PATCH行为总结