> ## 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.

# 面向对象的 API

> 了解 Olostep API 对象如何协同工作

Olostep 的 API 是围绕对象设计的。理解这种设计可以帮助你构建更有效的集成。

***

## 一切都是对象

Olostep 中的每个资源都是一个具有唯一标识符的对象。无论你通过 API、SDK 还是仪表板创建它，你都会得到一个可以引用、更新和查询的对象。

| 资源       | 对象 ID 格式     | 示例                |
| -------- | ------------ | ----------------- |
| Scrape   | `scrape_*`   | `scrape_abc123`   |
| Batch    | `batch_*`    | `batch_xyz789`    |
| Crawl    | `crawl_*`    | `crawl_def456`    |
| Map      | `map_*`      | `map_ghi012`      |
| Answer   | `answer_*`   | `answer_jkl345`   |
| Search   | `search_*`   | `search_mno678`   |
| Monitor  | `monitor_*`  | `monitor_mno678`  |
| File     | `file_*`     | `file_mno678`     |
| Schedule | `schedule_*` | `schedule_pqr901` |

***

## 对象可以有生命周期

一些 Olostep 对象通过 `status` 字段跟踪状态。这种状态机模式让你确切知道每个资源在其生命周期中的位置。

### 批次

批次有两个级别的状态：**批次**本身和单个**项目**。

**批次状态：**

```
in_progress → completed
```

| 状态            | 描述       |
| ------------- | -------- |
| `in_progress` | 正在抓取 URL |
| `completed`   | 处理完成     |

<Note>
  **批次级别的失败极为罕见。** 批次几乎总是完成的——即使某些 URL 失败，批次本身也会达到 `completed` 状态。在极少数情况下，基础设施出现灾难性故障（例如，在丰富过程中 LLM 服务中断），批次可能会失败。这影响不到 0.01% 的批次。
</Note>

**项目状态：**

批次中的每个 URL 都被跟踪为一个具有自身状态的单独项目：

| 状态        | 描述       |
| --------- | -------- |
| `success` | URL 抓取成功 |
| `failed`  | URL 无法抓取 |

项目可能因以下原因失败：

* URL 被阻止或返回错误
* 解析器输出缺失
* 网络/获取错误

失败的项目包含一个带有 `code` 和 `message` 的 `error` 对象来解释失败原因。批次仍然会完成——在处理结果时检查每个项目的状态。

### 爬网

```
in_progress → completed
```

| 状态            | 描述            |
| ------------- | ------------- |
| `in_progress` | 正在积极发现和处理 URL |
| `completed`   | 爬网完成          |

<Note>
  **爬网总是完成的。** 即使爬网找到 0 个 URL（由于 robots.txt 阻止或起始 URL 无效），爬网状态也将是 `completed`。检查 `pages_count` 字段以验证结果。
</Note>

### 监控器

监控器是具有比一次性资源更丰富生命周期的长寿命对象：

```
provisioning → active ⇄ paused
            ↘ failed
```

| 状态             | 描述                                             |
| -------------- | ---------------------------------------------- |
| `provisioning` | 正在设置代理、规格、计划和时间表                               |
| `active`       | 启用时间表；运行在 `schedule.frequency` 上执行             |
| `paused`       | 通过 `POST /v1/monitors/:monitor_id/pause` 禁用时间表 |
| `failed`       | 设置或时间表更新失败（`error_message` 已设置）                |
| `deleted`      | 通过 `DELETE /v1/monitors/:monitor_id` 软删除       |

创建监控器返回 HTTP `202`，状态为 `provisioning`。一旦计划解决其跟踪目标，监控器将变为 `active`——轮询 `GET /v1/monitors/:monitor_id` 或使用 `?stream=1` 流式传输设置事件。只有 `active` 的监控器可以暂停，只有 `paused` 的监控器可以恢复。更新在监控器仍然 `provisioning` 时返回 `409`。

***

## 检索模式

许多对象生成的内容可以稍后检索。`retrieve_id` 模式允许你在不重新处理的情况下获取内容。

```bash theme={null}
# 使用 retrieve_id 获取内容
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
  -H "Authorization: Bearer <your_token>"
```

此模式用于：

* **批次项目** — 每个处理的 URL 都会获得一个 `retrieve_id`
* **爬网页面** — 每个爬网页面都获得一个 `retrieve_id`

`/v1/retrieve` 端点接受 `formats` 参数以指定返回哪些内容类型（`html`、`markdown`、`json`、`text`）。

***

## Webhooks：事件驱动的更新

与其轮询状态变化，不如配置 [webhooks](/api-reference/common/webhooks) 以在对象状态更改时接收事件。

```json theme={null}
{
  "event": "batch.completed",
  "data": {
    "id": "batch_xyz789",
    "status": "completed",
    "items_total": 100,
    "items_completed": 100
  }
}
```

***

## 元数据：你的数据与我们的数据一起

使用 [metadata](/api-reference/common/metadata) 将自定义键值对附加到对象。这让你可以将 Olostep 资源链接到你的内部系统。

```json theme={null}
{
  "items": [{"url": "https://example.com"}],
  "metadata": {
    "order_id": "12345",
    "customer": "acme-corp"
  }
}
```

***

## 总结

| 概念           | 描述                      |
| ------------ | ----------------------- |
| **对象**       | 每个资源都有唯一 ID 并且可查询       |
| **生命周期**     | 通过 `status` 字段跟踪进度      |
| **检索**       | 使用 `retrieve_id` 稍后获取内容 |
| **Webhooks** | 在状态更改时收到通知              |
| **元数据**      | 将你自己的数据附加到任何对象          |