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

# Olostep + Apify 集成

> 使用 Olostep 和 Apify Actors 自动化网页搜索、抓取和爬取——搜索、提取和结构化网页数据的 API。

Olostep 是一个网页搜索、抓取和爬取的 API——用于搜索、提取和结构化网页数据的 API。本指南展示了如何使用 Olostep 和 Apify Actors 构建可靠的端到端网页数据管道。

## 你可以构建的内容

<CardGroup cols={2}>
  <Card title="抓取网站" icon="file-lines">
    从任何单个 URL 提取内容，支持 Markdown、HTML、JSON 或文本格式
  </Card>

  <Card title="批量抓取 URL" icon="layer-group">
    并行处理大量 URL 列表，输出结构化数据
  </Card>

  <Card title="创建爬取" icon="spider-web">
    发现并抓取链接页面以构建完整的数据集
  </Card>

  <Card title="创建地图" icon="map">
    从网站中提取所有 URL（类似网站地图的发现）
  </Card>

  <Card title="AI 驱动的答案" icon="robot">
    提问并获得带有来源的结构化 JSON 答案
  </Card>
</CardGroup>

## 快速开始

### 1) 安装 Apify CLI

```bash theme={null}
npm install -g apify-cli
apify --version
```

### 2) 获取你的 Olostep API 密钥

从 Olostep 仪表板 → API 密钥。

### 3) 本地运行 Olostep Actor

```bash theme={null}
cd olostep-tools/integrations/apify
apify run
```

默认的本地输入文件位于：
`olostep-tools/integrations/apify/storage/key_value_stores/default/INPUT.json`

示例输入：

```json theme={null}
{
  "operation": "scrape",
  "apiKey": "YOUR_OLostep_API_KEY",
  "url_to_scrape": "https://example.com",
  "formats": "markdown"
}
```

### 4) 部署到 Apify（云端）

```bash theme={null}
apify login
apify push
```

然后打开 Apify 控制台 → Actors → 使用你想要的输入运行 actor。

### 在 Apify 控制台中运行（逐步）

1. 在 Apify 控制台中打开你的 Actor → 源码 → 输入。
2. 在手动选项卡中，你会看到一个可见的“Olostep API 密钥”字段。从 Olostep 仪表板粘贴你的密钥。
3. 选择一个操作（默认为“scrape”）。
4. 填写相关字段（对于“scrape”，设置“URL to Scrape”）。
5. 点击保存 → 开始。
6. 运行结束后，打开数据集选项卡下载结果（JSON/CSV/Excel）。

注意：

* 对于“URL to Scrape”，你可以粘贴带或不带协议的 URL。如果缺失，actor 会自动添加 `https://`。
* 如果网站使用大量 JavaScript 并且你看到超时，请将“Wait Before Scraping”设置为 2000–5000 毫秒，然后再次运行。

## 可用操作

### 抓取网站

从单个 URL 提取内容。非常适合页面级自动化。

<ParamField path="operation" type="constant" default="scrape">
  必须为 "scrape"
</ParamField>

<ParamField path="apiKey" type="string" required>
  你的 Olostep API 密钥（Bearer）
</ParamField>

<ParamField path="url_to_scrape" type="string" required>
  要抓取的 URL（必须包含 http\:// 或 https\://）
</ParamField>

<ParamField path="formats" type="dropdown" default="markdown">
  选项之一：Markdown、HTML、JSON、Text
</ParamField>

<ParamField path="country" type="string">
  可选国家代码（例如 "US", "GB", "CA"）
</ParamField>

<ParamField path="wait_before_scraping" type="integer">
  JavaScript 渲染的可选等待时间（0–10000 毫秒）
</ParamField>

<ParamField path="parser" type="string">
  可选解析器 ID（例如 "@olostep/amazon-product"）
</ParamField>

输出字段：

* id, url, status, formats
* markdown\_content / html\_content / json\_content / text\_content
* 托管 URL（如果可用），页面元数据

### 批量抓取 URL

同时处理多个 URL，保持一致的格式和结构。

<ParamField path="operation" type="constant" default="batch">
  必须为 "batch"
</ParamField>

<ParamField path="apiKey" type="string" required>
  你的 Olostep API 密钥
</ParamField>

<ParamField path="batch_array" type="text" required>
  包含 `url` 和可选 `custom_id` 的对象的 JSON 数组\
  示例：`[{"url":"https://example.com","custom_id":"site1"}]`
</ParamField>

<ParamField path="formats" type="dropdown" default="markdown">
  选项之一：Markdown、HTML、JSON、Text
</ParamField>

<ParamField path="country" type="string">
  可选国家代码
</ParamField>

<ParamField path="wait_before_scraping" type="integer">
  JS 网站的可选等待时间
</ParamField>

<ParamField path="parser" type="string">
  可选解析器 ID
</ParamField>

输出字段：

* batch\_id, status, total\_urls, created\_at, formats, country, parser, urls\[]

### 创建爬取

从起始 URL 跟随链接并抓取多个页面。

<ParamField path="operation" type="constant" default="crawl">
  必须为 "crawl"
</ParamField>

<ParamField path="apiKey" type="string" required>
  你的 Olostep API 密钥
</ParamField>

<ParamField path="start_url" type="string" required>
  爬取的起始 URL
</ParamField>

<ParamField path="max_pages" type="integer" default="10">
  要爬取的最大页面数。设置为 `1` 仅抓取起始 URL。
</ParamField>

<ParamField path="formats" type="dropdown" default="markdown">
  选项之一：Markdown、HTML、JSON、Text
</ParamField>

<ParamField path="country" type="string">
  可选国家代码
</ParamField>

<ParamField path="parser" type="string">
  可选解析器 ID
</ParamField>

输出字段：

* crawl\_id, object, status, start\_url, max\_pages, created, formats

### 创建地图

发现网站上的所有 URL，为后续批量抓取做准备。

<ParamField path="operation" type="constant" default="map">
  必须为 "map"
</ParamField>

<ParamField path="apiKey" type="string" required>
  你的 Olostep API 密钥
</ParamField>

<ParamField path="website_url" type="string" required>
  要映射的网站
</ParamField>

<ParamField path="search_query" type="string">
  可选查询过滤器
</ParamField>

<ParamField path="top_n" type="integer">
  限制 URL 数量
</ParamField>

<ParamField path="include_patterns" type="string">
  包含的 glob(s)，例如 "/products/\*\*"
</ParamField>

<ParamField path="exclude_patterns" type="string">
  排除的 glob(s)，例如 "/admin/\*\*"
</ParamField>

输出字段：

* map\_id, object, website\_url, total\_urls, urls\[], search\_query, top\_n

## 复制粘贴 JSON 示例（控制台 → 输入 → JSON）

### 抓取

```json theme={null}
{
  "operation": "scrape",
  "apiKey": "YOUR_OLOSTEP_API_KEY",
  "url_to_scrape": "https://www.wikipedia.org",
  "formats": "markdown",
  "wait_before_scraping": 2000
}
```

### 批量

```json theme={null}
{
  "operation": "batch",
  "apiKey": "YOUR_OLOSTEP_API_KEY",
  "batch_array": "[{\"url\":\"https://example.com\",\"custom_id\":\"site1\"},{\"url\":\"https://olostep.com\",\"custom_id\":\"site2\"}]",
  "formats": "json"
}
```

### 爬取

```json theme={null}
{
  "operation": "crawl",
  "apiKey": "YOUR_OLOSTEP_API_KEY",
  "start_url": "https://docs.example.com",
  "max_pages": 50,
  "formats": "markdown"
}
```

### 地图

```json theme={null}
{
  "operation": "map",
  "apiKey": "YOUR_OLOSTEP_API_KEY",
  "website_url": "https://example.com",
  "include_patterns": "/blog/**",
  "top_n": 200
}
```

### 答案

```json theme={null}
{
  "operation": "answers",
  "apiKey": "YOUR_OLOSTEP_API_KEY",
  "task": "What is the latest funding round of Olostep? Provide company, round, date, amount.",
  "json": "{\"company\":\"\",\"round\":\"\",\"date\":\"\",\"amount\":\"\"}"
}
```

## 示例工作流

<AccordionGroup>
  <Accordion title="发现并抓取产品">
    1. 创建地图 → 包含 "/products/\*\*"
    2. 解析 URL → 构建批量数组
    3. 批量抓取 URL → 格式：JSON
    4. 发送到 Google Sheets / Airtable
  </Accordion>

  <Accordion title="每日内容监控">
    1. 定时运行 actor（每日）
    2. 抓取网站 → 格式：Markdown
    3. 使用 LLM 总结
    4. 在 Slack 上通知
  </Accordion>

  <Accordion title="竞争对手知识库">
    1. 创建爬取（博客/文档）
    2. 将输出存储在 Notion 中
    3. 每周定时刷新
  </Accordion>
</AccordionGroup>

## 专用解析器

Olostep 支持解析器以结构化流行网站的数据。

<CardGroup cols={2}>
  <Card title="亚马逊产品" icon="amazon">
    `@olostep/amazon-product` → 标题、价格、评分、评论、图片、变体
  </Card>

  <Card title="谷歌搜索" icon="google">
    `@olostep/google-search` → 结果、标题、摘要、URL
  </Card>

  <Card title="谷歌地图" icon="map">
    `@olostep/google-maps` → 商业信息、评论、评分、位置
  </Card>

  <Card title="更多解析器" icon="cart-shopping" href="https://www.olostep.com/store">
    探索电子邮件提取器、社交账号查找器、日历链接提取器等
  </Card>
</CardGroup>

## 最佳实践

<AccordionGroup>
  <Accordion title="3 个以上 URL 优先批量处理">
    更快、更便宜、更易于监控和遵守速率限制。
  </Accordion>

  <Accordion title="使用适当的等待时间">
    JS 重的网站：增加 `wait_before_scraping`（例如 2000–5000 毫秒）。
  </Accordion>

  <Accordion title="在抓取前进行过滤">
    避免不必要的任务——先检查更改，保持去重状态。
  </Accordion>

  <Accordion title="通过托管 URL 存储大内容">
    使用托管输出绕过 Apify 流程中的负载大小限制。
  </Accordion>

  <Accordion title="将异步操作视为长时间运行">
    批量/爬取/地图返回 ID；稍后检索或延迟链式操作。
  </Accordion>

  <Accordion title="干净地处理瞬时超时">
    如果你看到 504 或瞬时超时，actor 会自动重试一次并短暂等待。\
    你也可以为 JS 重的页面设置“Wait Before Scraping”为 2000–5000 毫秒。
  </Accordion>
</AccordionGroup>

## 故障排除

<AccordionGroup>
  <Accordion title="身份验证失败">
    * 检查仪表板中的 API 密钥
    * 删除尾随空格
    * 在 Apify 输入表单中重新输入
  </Accordion>

  <Accordion title="内容为空">
    * 增加等待时间
    * 验证 URL 是否公开/不需要登录
    * 尝试不同的输出格式
  </Accordion>

  <Accordion title="超出速率限制">
    * 通过计划安排运行
    * 对于多个 URL 优先批量处理
    * 如有需要，升级 Olostep 计划
  </Accordion>

  <Accordion title="被阻止或动态网站">
    * 尝试国家参数
    * 调整等待时间和解析器
    * 联系支持以获得指导
  </Accordion>
</AccordionGroup>

## 定价

Olostep 按 API 使用量收费（独立于 Apify）：

* 抓取 → 每次抓取
* 批量 → 每个 URL
* 爬取 → 每个页面
* 地图 → 每次操作

参见 `https://www.olostep.com/pricing`。

## 安全

* 你的 API 密钥在运行时作为 Bearer 令牌发送。
* 不要将密钥提交到版本控制；Apify 将输入存储在键值存储中。
* 在本地开发中，将密钥保存在 `storage/key_value_stores/default/INPUT.json`（已 gitignore）。

## 相关资源

<CardGroup cols={2}>
  <Card title="抓取 API" icon="file-lines" href="/features/scrapes">
    从任何 URL 提取 LLM 友好的 Markdown、HTML、文本或结构化 JSON。
  </Card>

  <Card title="批量 API" icon="layer-group" href="/features/batches">
    同时处理多达 10k 个 URL，并稍后检索结果。
  </Card>

  <Card title="爬取 API" icon="spider-web" href="/features/crawls">
    递归发现并抓取网站的内容。
  </Card>

  <Card title="地图 API" icon="map" href="/features/maps">
    获取网站上的所有 URL，以准备批量抓取。
  </Card>
</CardGroup>

## 支持

<CardGroup cols={2}>
  <Card title="Apify 网站" icon="link" href="https://apify.com">
    Apify 平台
  </Card>

  <Card title="Apify 文档" icon="book" href="https://docs.apify.com">
    Apify 平台和 SDK 文档
  </Card>

  <Card title="文档" icon="book" href="https://docs.olostep.com">
    完整的 API 文档
  </Card>

  <Card title="支持邮箱" icon="envelope" href="mailto:info@olostep.com">
    [info@olostep.com](mailto:info@olostep.com)
  </Card>
</CardGroup>