> ## 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.
# 创建批处理
> 开始一个新的批处理。你会收到一个 `id`，可以用来跟踪批处理的进度，如[此处](/api-reference/batches/info)所示。注意：处理时间与批处理大小无关，是恒定的。
**完成时获取通知：** 传递 `webhook` 参数以及你的端点 URL，以便在批处理完成时接收一个 HTTP POST。详情请参阅 [Webhooks](/api-reference/common/webhooks)。
**附加自定义数据：** 使用 `metadata` 参数存储键值对。支持两个级别：
* **批处理级别** — 在请求体中
* **项目级别** — 在 `items` 数组中的每个项目上
详情请参阅 [Metadata](/api-reference/common/metadata)。
## OpenAPI
````yaml zh/openapi/batches.json POST /v1/batches
openapi: 3.0.3
info:
title: 批处理 API
version: 1.0.0
servers:
- url: https://api.olostep.com
security: []
paths:
/v1/batches:
post:
summary: 启动新批处理
description: 使用指定的参数启动新的批处理过程。
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
custom_id:
type: string
description: URL 的内部唯一标识符。
url:
type: string
format: uri
description: 项目的 URL。
metadata:
allOf:
- $ref: '#/components/schemas/Metadata'
description: 项目级元数据。为单个项目附加键值对，以便跟踪、过滤或与内部系统关联。
required:
- custom_id
- url
description: 要在批处理中处理的项目数组。
country:
type: string
description: 批处理执行的国家。请使用 ISO 3166-1 alpha-2 代码，如 US（美国）、IN（印度）等。
parser:
type: object
properties:
id:
type: string
description: 用于批处理的解析器。
required:
- id
description: >-
你可以使用这个参数来指定要使用的解析器。解析器对于从网页中提取结构化内容非常有用。Olostep
内置了一些常见网页的解析器，你也可以创建自己的解析器。
links_on_page:
type: object
properties:
include_links:
type: array
items:
type: string
description: >-
使用 glob 模式过滤提取的链接。模式与链接的 URL 路径匹配。注意：单个 `*` 不会跨越 `/`，所以
"/blog/*" 匹配 "/blog/post-1"，但不匹配索引 "/blog" 本身（或
"/blog?tag=x"，因为查询字符串不是路径的一部分）。要包括索引，请使用 "/blog*" 或
"{/blog,/blog/**}"。
exclude_links:
type: array
items:
type: string
description: >-
使用 glob 模式过滤提取的链接。模式与链接的 URL 路径匹配。注意：单个 `*` 不会跨越 `/`，所以
"/blog/*" 匹配 "/blog/post-1"，但不匹配索引 "/blog" 本身。
description: 获取批处理中每个页面上存在的所有链接。链接始终以绝对 URL 返回。
metadata:
$ref: '#/components/schemas/Metadata'
webhook:
type: string
format: uri
description: >-
当批处理完成时接收 POST 请求的 HTTPS URL。必须是使用 `http://` 或 `https://`
协议的公开可访问 URL。不能指向 localhost 或私有 IP 地址。有关负载格式和重试行为，请参见
[Webhooks](/api-reference/common/webhooks)。
required:
- items
example:
items:
- custom_id: product-123
url: https://example.com/product/123
metadata:
source: catalog_sync
priority: high
- custom_id: product-456
url: https://example.com/product/456
country: US
metadata:
batch_name: Q1 Product Sync
initiated_by: automation
responses:
'200':
description: 批处理启动成功。
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: 批处理 ID
object:
type: string
description: 对象的类型。此端点为 "batch"。
status:
type: string
description: '`in_progress` 或 `completed`'
created:
type: number
description: 创建的纪元时间
total_urls:
type: number
description: 批处理中 URL 的数量
completed_urls:
type: number
description: 已完成的 URL 数量
parser:
type: string
country:
type: string
metadata:
$ref: '#/components/schemas/Metadata'
webhook:
type: string
description: 用于接收完成通知的 Webhook URL
credits_consumed:
type: integer
nullable: true
description: 此请求消耗的积分数量。在执行完成后填充。积分是计费的真实来源。
cost_usd:
type: number
nullable: true
description: >-
此请求的估计成本（以美元计）。在执行完成后填充。根据消耗的积分和你的计划费率计算——99% 准确，但
credits_consumed 是权威值。
example:
id: batch_abc123def456
object: batch
status: in_progress
created: 1704067200
total_urls: 2
completed_urls: 0
country: US
metadata:
batch_name: Q1 Product Sync
initiated_by: automation
'400':
description: >-
由于参数不正确或缺失导致的错误请求。详情请参见 [Bad
Request](/api-reference/errors/bad_request)。
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: validation_error
type: https://docs.olostep.com/api-reference/errors/bad_request
status: 400
title: 错误请求
detail: >-
The 'items' array is required and must contain at least one
item.
created: 1704067200
metadata: {}
'401':
description: >-
身份验证凭据缺失或无效。详情请参阅
[Unauthorized](/api-reference/errors/unauthorized)。
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: invalid_api_key
type: https://docs.olostep.com/api-reference/errors/unauthorized
status: 401
title: 未授权
detail: >-
Your API key is invalid. Try double-checking it or reaching
out to info@olostep.com if you're facing issues.
created: 1704067200
metadata: {}
'402':
description: >-
需要付款 - 积分已用尽。详情请参见 [Payment
Required](/api-reference/errors/payment_required)。
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: credits_exhausted
type: https://docs.olostep.com/api-reference/errors/payment_required
status: 402
title: 需要付款
detail: >-
You have consumed all available credits. Please upgrade your
plan from the dashboard: https://www.olostep.com/auth/
created: 1704067200
metadata: {}
'403':
description: 禁止 - 拒绝访问此功能。详情请参见 [Forbidden](/api-reference/errors/forbidden)。
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: access_denied
type: https://docs.olostep.com/api-reference/errors/forbidden
status: 403
title: 禁止
detail: >-
You don't have access to this feature. Please reach out to
info@olostep.com to get approved
created: 1704067200
metadata: {}
'409':
description: >-
幂等性冲突 - 此键的请求正在进行中。详情请参见
[幂等性错误](/api-reference/errors/idempotency_error)。
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: idempotency_key_in_progress
type: >-
https://docs.olostep.com/api-reference/errors/idempotency_error
status: 409
title: 幂等性错误
detail: >-
A request with this idempotency key is currently being
processed. Please wait and retry.
created: 1704067200
metadata: {}
'422':
description: >-
无法处理的实体 - 违反业务规则。详情请参见
[无法处理的实体](/api-reference/errors/unprocessable_entity)。
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: idempotency_key_reuse
type: >-
https://docs.olostep.com/api-reference/errors/unprocessable_entity
status: 422
title: 无法处理的实体
detail: >-
A request with this idempotency key was already made with
different parameters. Idempotency keys must be unique per
request.
created: 1704067200
metadata: {}
'500':
description: >-
内部服务器错误。详情请参阅 [Internal
Error](/api-reference/errors/internal_error)。
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: internal_server_error
type: https://docs.olostep.com/api-reference/errors/internal_error
status: 500
title: 内部服务器错误
detail: An unexpected error occurred
created: 1704067200
metadata: {}
security:
- Authorization: []
components:
schemas:
Metadata:
type: object
description: >-
用于存储对象附加信息的键值对集合。遵循Stripe的验证规则：最多50个键，键最多40个字符（不含方括号），值最多500个字符，所有值以字符串形式存储。
additionalProperties:
type: string
maxLength: 500
description: 元数据值（最多500个字符）。数字和布尔值会自动转换为字符串。
maxProperties: 50
example:
order_id: '12345'
customer_name: John Doe
priority: high
processed: 'true'
x-validation-rules:
max_keys: 50
key_max_length: 40
key_forbidden_chars:
- '['
- ']'
value_max_length: 500
value_types:
- string
- number (coerced)
- boolean (coerced)
Error:
type: object
description: RFC 7807 问题详情错误响应
properties:
id:
type: string
description: 唯一错误标识符
object:
type: string
enum:
- error
description: 始终为 'error'
code:
type: string
description: 机器可读的错误代码
type:
type: string
format: uri
description: 标识问题类型的URI引用
status:
type: integer
description: HTTP状态码
title:
type: string
description: 简短的、可读的摘要
detail:
type: string
description: 可读的解释
created:
type: integer
description: Unix时间戳
metadata:
$ref: '#/components/schemas/Metadata'
errors:
type: array
description: 可选的附加错误详情数组
items: {}
required:
- id
- object
- code
- type
- status
- title
- detail
- created
securitySchemes:
Authorization:
type: http
scheme: bearer
description: Bearer认证头格式为Bearer ，其中是你的认证令牌。
````