Apify

运行 Apify Store 上 17,000 多个 Actors 中的任意一个，并通过 REST API 获取结构化结果。

完整 OpenAPI 规范：openapi.json

身份验证

所有请求都需要 APIFY_TOKEN 环境变量。将其用作 Bearer 令牌：

bash
-H Authorization: Bearer $APIFY_TOKEN

基础 URL：https://api.apify.com

核心工作流程

1. 找到合适的 Actor

通过关键词搜索 Apify Store：

bash
curl -s https://api.apify.com/v2/store?search=web+scraper&limit=5 \
-H Authorization: Bearer $APIFY_TOKEN | jq .data.items[] | {name: (.username + / + .name), title, description}

在 API 路径中，Actors 由 username~name（波浪号）标识，例如 apify~web-scraper。

2. 获取 Actor README 和输入模式

在运行 Actor 之前，获取其默认构建版本以获取 README（使用文档）和输入模式（预期的 JSON 字段）：

bash
curl -s https://api.apify.com/v2/acts/apify~web-scraper/builds/default \
-H Authorization: Bearer $APIFY_TOKEN | jq .data | {readme, inputSchema}

inputSchema 是一个 JSON 字符串化对象——解析它以查看必填/可选字段、类型、默认值和描述。使用它来构建运行的有效输入。

您还可以获取 Actor 的每个构建版本的 OpenAPI 规范（无需身份验证）：

bash
curl -s https://api.apify.com/v2/acts/apify~web-scraper/builds/default/openapi.json

3. 运行 Actor（异步——大多数情况下推荐）

启动 Actor 并立即获取运行对象：

bash
curl -s -X POST https://api.apify.com/v2/acts/apify~web-scraper/runs \
-H Authorization: Bearer $APIFY_TOKEN \
-H Content-Type: application/json \
-d {startUrls:[{url:https://example.com}],maxPagesPerCrawl:10}

响应包含 data.id（运行 ID）、data.defaultDatasetId、data.status。

可选查询参数：?timeout=300&memory=4096&maxItems=100&waitForFinish=60

• - waitForFinish（0-60）：API 在返回前等待的秒数。对于短时间运行，有助于避免轮询。

4. 轮询运行状态

bash
curl -s https://api.apify.com/v2/actor-runs/RUN_ID?waitForFinish=60 \
-H Authorization: Bearer $APIFY_TOKEN | jq .data | {status, defaultDatasetId}

最终状态：SUCCEEDED、FAILED、ABORTED、TIMED-OUT。

5. 获取结果

数据集项（最常见——结构化抓取数据）：

bash
curl -s https://api.apify.com/v2/datasets/DATASET_ID/items?clean=true&limit=100 \
-H Authorization: Bearer $APIFY_TOKEN

或直接从运行中获取（快捷方式——相同参数）：

bash
curl -s https://api.apify.com/v2/actor-runs/RUN_ID/dataset/items?clean=true&limit=100 \
-H Authorization: Bearer $APIFY_TOKEN

参数：format（json|csv|jsonl|xml|xlsx|rss）、fields、omit、limit、offset、clean、desc。

键值存储记录（截图、HTML、OUTPUT）：

bash
curl -s https://api.apify.com/v2/key-value-stores/STORE_ID/records/OUTPUT \
-H Authorization: Bearer $APIFY_TOKEN

运行日志：

bash
curl -s https://api.apify.com/v2/logs/RUN_ID \
-H Authorization: Bearer $APIFY_TOKEN

6. 同步运行 Actor（仅限短时间运行的 Actor）

对于在 300 秒内完成的 Actor，通过一次调用获取数据集项：

bash
curl -s -X POST https://api.apify.com/v2/acts/apify~web-scraper/run-sync-get-dataset-items?timeout=120 \
-H Authorization: Bearer $APIFY_TOKEN \
-H Content-Type: application/json \
-d {startUrls:[{url:https://example.com}],maxPagesPerCrawl:5}

直接返回数据集项数组（不包装在 data 中）。如果运行超过 300 秒，则返回 408。

替代方案：/run-sync 返回 KVS OUTPUT 记录而不是数据集项。

快速配方

抓取网站

bash
curl -s -X POST https://api.apify.com/v2/acts/apify~web-scraper/run-sync-get-dataset-items?timeout=120 \
-H Authorization: Bearer $APIFY_TOKEN \
-H Content-Type: application/json \
-d {startUrls:[{url:https://example.com}],maxPagesPerCrawl:20}

Google 搜索

bash
curl -s -X POST https://api.apify.com/v2/acts/apify~google-search-scraper/run-sync-get-dataset-items?timeout=120 \
-H Authorization: Bearer $APIFY_TOKEN \
-H Content-Type: application/json \
-d {queries:site:example.com openai,maxPagesPerQuery:1}

长时间运行的 Actor（带轮询的异步）

bash

1. 启动

RUN=$(curl -s -X POST https://api.apify.com/v2/acts/apify~web-scraper/runs?waitForFinish=60 \
-H Authorization: Bearer $APIFY_TOKEN \
-H Content-Type: application/json \
-d {startUrls:[{url:https://example.com}],maxPagesPerCrawl:500})
RUN_ID=$(echo $RUN | jq -r .data.id)

2. 轮询直到完成

while true; do STATUS=$(curl -s https://api.apify.com/v2/actor-runs/$RUN_ID?waitForFinish=60 \ -H Authorization: Bearer $APIFY_TOKEN | jq -r .data.status) echo 状态：$STATUS case $STATUS in SUCCEEDED|FAILED|ABORTED|TIMED-OUT) break;; esac done

3. 获取结果

curl -s https://api.apify.com/v2/actor-runs/$RUN_ID/dataset/items?clean=true \ -H Authorization: Bearer $APIFY_TOKEN

中止运行

bash
curl -s -X POST https://api.apify.com/v2/actor-runs/RUN_ID/abort \
-H Authorization: Bearer $APIFY_TOKEN

付费/租赁 Actors

某些 Actors 需要每月订阅才能运行。如果 API 返回 Actors 的权限或付款错误，请要求用户通过 Apify 控制台手动订阅：

https://console.apify.com/actors/ACTOR_ID

将 ACTOR_ID 替换为 Actor 的 ID（例如 AhEsMsQyLfHyMLaxz）。用户需要在该页面上点击 开始 以激活订阅。大多数租赁 Actors 提供由开发者设置的免费试用期。

您可以从商店搜索响应（data.items[].id）或从 GET /v2/acts/username~name（data.id）获取 Actor ID。

错误处理

• - 401：APIFYTOKEN 缺失或无效。
• 404 Actor 未找到：检查 username~name 格式（波浪号，不是斜杠）。浏览 https://apify.com/store。
• 400 运行失败：检查 GET /v2/logs/RUNID 以获取详细信息。
• 402/403 需要付款：Actor 可能需要订阅。请参阅上面的“付费/租赁 Actors”。
• 408 运行超时：同步端点有 300 秒限制。请改用异步工作流程。
• 429 速率限制超出：使用指数退避重试（从 500 毫秒开始，每次加倍）。

其他资源

• - API 文档