{ "openapi": "3.1.0", "info": { "title": "Brightdata API", "description": "用于与数据集市场交互的 API", "version": "1.0.0" }, "servers": [ { "url": "https://api.brightdata.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/dca/dataset": { "get": { "description": "接收批量数据", "parameters": [ { "name": "dataset_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "要获取的数据集 ID。" } ], "responses": { "200": { "description": "数据集（已就绪）", "content": { "application/json": { "examples": { "response": { "value": [ { "Image": "https://targetwebsite.com/product_id.png", "Title": "product_name", "Price": "product_price", "input": { "url": "https://targetwebsite.com/product_id/" } } ] } } } } }, "202": { "description": "等待数据集", "content": { "application/json": { "examples": { "response": { "value": { "status": "building", "message": "数据集尚未就绪，请在 XX 秒后重试" } } } } } } } } }, "/dca/get_result": { "get": { "description": "获取实时工作 scraper 的数据", "parameters": [ { "name": "response_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "响应的唯一标识" }, { "name": "timeout", "in": "query", "required": false, "schema": { "type": "string", "example": "50s" }, "description": "启用长轮询。请求会等待结果可用，最长等待该时长，而不是立即返回 `202`。格式为 `Xs`，其中 X 为 25 到 50 之间的整数（例如 `25s`、`30s`、`50s`）。如果在超时时间内仍无结果可用，则照常返回 `202`。使用该参数可减少轮询调用次数并避免触及速率限制。" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "examples": { "Sample (old scrapers)": { "value": { "input": { "url": "https://targetwebsite.com/product_id/" }, "line_1": "Lorem ipsum dolor sit amet", "line_2": "consectetur adipisicing elit" } }, "Sample (new scrapers)": { "value": [ { "line_1": "Lorem ipsum dolor sit amet", "line_2": "consectetur adipisicing elit" } ] } } } } }, "202": { "description": "结果尚未就绪。当没有可用结果时返回，包括设置了 `timeout` 但在超时时间内结果仍未就绪的情况。请使用相同的 `response_id` 再次轮询。" } } } }, "/dca/log/{job_id}": { "get": { "description": "通过 job ID 获取任务数据", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "要获取的任务 ID。" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "examples": { "response": { "value": { "Id": "j_ma13y9ay1piehrso8r", "Status": "done", "Collector": "c_m9im5n7v82p2y35la", "Template": "t_m9jty150kxgwtzcgi.3", "Inputs": 1, "dup_inputs": 0, "Lines": 60, "Fails": 0, "Pages": 1, "Pages_left": 0, "Success": 1, "Navigations": 2, "created": "2025-04-28T13:22:16.857Z", "started": "2025-04-28T13:22:17.502Z", "finished": "2025-04-28T13:23:28.961Z", "trigger": "amite@brightdata.com", "Success_rate": 1, "Job_time": 71459, "Queue_time": 645 } } } } } } } } }, "/dca/trigger_immediate": { "post": { "description": "触发 scraper 以进行实时采集", "parameters": [ { "name": "collector", "in": "query", "required": true, "schema": { "type": "string" }, "description": "scraper 的唯一标识" }, { "name": "version", "in": "query", "schema": { "type": "string" }, "description": "设置为 `dev` 以触发 scraper 的开发版本" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "`human_name` - 批处理的可读名称" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } }, "examples": { "request": { "value": { "url": "https://targetwebsite.com/product_id/" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "examples": { "response": { "value": { "response_id": "" } } } } } } } } }, "/dca/trigger": { "post": { "description": "触发 scraper 以进行批量采集", "parameters": [ { "name": "collector", "in": "query", "required": true, "schema": { "type": "string" }, "description": "scraper 的唯一标识" }, { "name": "version", "in": "query", "schema": { "type": "string" }, "description": "设置为 `dev` 以触发 scraper 的开发版本" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "`human_name` - 批处理的可读名称" }, { "name": "queue_next", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "如果抓取队列中已有任务，将此任务加入队列" }, { "name": "queue", "in": "query", "schema": { "type": "string" }, "description": "发送另一个批次的请求，该批次将在上一个完成后启动" }, { "name": "confirm_cancel", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "取消正在运行的任务并替换运行，提交请求后取消当前任务" }, { "name": "no_downloads", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "禁用媒体文件下载" }, { "name": "deadline", "in": "query", "schema": { "type": "string" }, "description": "设置任务截止时间，超过指定时间任务将被终止。`h` 表示小时，`m` 表示分钟，`s` 表示秒。" }, { "name": "notify", "in": "query", "schema": { "type": "string", "example": "{\"type\":\"webhook\",\"endpoint\":\"https://example.com/webhook\"}" }, "description": "本请求的通知配置，为 URL 编码的 JSON 对象。单独使用时，在采集作业完成后发送通知；与 `deliver` 一起使用时，在交付完成后发送通知。" }, { "name": "deliver", "in": "query", "schema": { "type": "string", "example": "{\"type\":\"s3\",\"bucket\":\"YOUR_BUCKET\",\"credentials\":{\"aws-access-key\":\"YOUR_AWS_ACCESS_KEY\",\"aws-secret-key\":\"YOUR_AWS_SECRET_KEY\"},\"region\":\"YOUR_REGION\",\"directory\":\"brightdata/YOUR_DIRECTORY\",\"filename\":{\"template\":\"results_{[datetime]}\",\"extension\":\"json\"},\"delivery_type\":\"deliver_results\"}" }, "description": "请求级交付配置，为 URL 编码的 JSON 对象。仅对本次采集覆盖爬虫在交付偏好中配置的默认交付设置。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } }, "examples": { "request": { "value": [ { "url": "https://targetwebsite.com/product_id/" } ] } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "examples": { "response": { "value": { "collection_id": "ID_DATASET", "start_eta": "2021-11-07T13:26:22.702Z" } } } } } } } } } }, "components": { "schemas": {}, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。\n\n**认证方法:**\n1. 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users\n2. 在请求的 Authorization 头中包含 API Key\n3. 格式: `Authorization: Bearer YOUR_API_KEY`\n\n**示例:**\n```\nAuthorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df\n```\n\n了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key？", "bearerFormat": "API Key" } } } }