> ## Documentation Index
> Fetch the complete documentation index at: https://brightdata-ipv6-release.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义数据集 API

此更新可使您以更精确、更简化的方式请求和管理您的数据采集，从而根据您的特定需求更有效地生成数据集。

了解何时使用每个 API:

## 没有客户定义视图的初始采集:

3 个主要 API 端点在数据采集工作流程中具有不同的用途，可促进高效获取定制数据集的结构化流程。

### 请求采集:

端点: `POST` [https://api.brightdata.com/datasets/request\_collection](https://api.brightdata.com/datasets/request_collection)

**参数:**

<ParamField query="dataset_id" type="string" required>
  数据集 ID
</ParamField>

<ParamField query="type" type="string" required>
  `discover_new` 或 `url_collection`
</ParamField>

<ParamField body="inputs" type="array">
  Array - json
</ParamField>

<ParamField body="file" type="multipart">
  multipart - csv
</ParamField>

```sh 示例 theme={null}
curl "https://api.brightdata.com/datasets/request_collection?dataset_id=gd_l1viktl72bvl7bjuj0&type=discover_new" -H "Authorization: Bearer API_TOKEN" -H "Content-Type: application/json" -k -d '[{"id":"user-id"}]'
```

处理可能需要几分钟时间，具体取决于输入的数量。 当您请求查找（`discover_new`）时，找到所有链接 (PDP) 可能需要一些时间。

***

### 查看以上采集的状态:

端点:  `GET` [https://api.brightdata.com/datasets/request\_collection](https://api.brightdata.com/datasets/request_collection)

**参数:**

<ParamField query="request_id" type="string" required>
  从先前的 API 获取。
</ParamField>

<ParamField query="freshness_ms" type="string" required>
  设置数据新鲜度。

  如果数据在此期限内（例如，请求在 1 周之前采集，5 天前采集），则会发生 0 次新的抓取。

  * 1 周: 604,800,000 毫秒
  * 1 个月: 2,592,000,000 毫秒
</ParamField>

```sh 示例 theme={null}
curl -k "https://api.brightdata.com/datasets/request_collection?request_id=REQUEST_ID&freshness_ms=2592000000" -H "Authorization: Bearer API_TOKEN" 
```

说明发现的记录数量和新鲜度的响应:

```json theme={null}
{
    "dataset_id": request_job.dataset_id,
    "total_lines": 100,
    "fresh_count": 30,
    "name": "linkedin_companies custom input",
    "status": "done",
    "request_id": "XXXX",
}
```

请求仍在运行:

```json theme={null}
{
    "total_lines": 100,
    "status": "running",
}
```

一个（或多个）输入有问题: 在这种情况下，此 url 以 URL 形式发送

```json theme={null}
{
    "request_id": "xxxx",  
    "error": "Validation failed",
    "error_code": "validation",
    "validation_errors": [
        {
            "line": "{\"URL\":\"https://www.tiktok.com/search?q=tjd\"}",
            "index": 1,
            "errors": [
                ["url", "Required field"]
            ]
        }
    ]
}
```

***

### 启动采集:

端点:  `POST` [https://api.brightdata.com/datasets/initiate\_collection](https://api.brightdata.com/datasets/initiate_collection)

**参数:**

<ParamField body="request_id" type="string" required>
  您正在查询的采集请求的唯一标识符。
</ParamField>

<ParamField body="freshness_ms" type="string" required>
  以毫秒为单位的时间，表示所需的数据新鲜度。
</ParamField>

<ParamField body="request_id" type="string" required>
  以毫秒为单位的时间，表示所需的数据新鲜度。
</ParamField>

```sh 示例 theme={null}
curl -X POST -k "https://api.brightdata.com/datasets/initiate_collection" -d '{"request_id":"j_ln2x567b2961de0d1x","freshness_ms":2592000000}' -H "Authorization: Bearer API_TOKEN" -H "content-type: application/json"
```

## 定义视图后的采集:

***

### 启动采集:

端点:  `POST` [https://api.brightdata.com/datasets/initiate](https://api.brightdata.com/datasets/initiate)

**参数:**

<ParamField query="dataset_id" type="string" required />

<ParamField query="view" type="string" required />

<ParamField query="type" type="string" required>
  `discover_new` 或 `url_collection`
</ParamField>

<ParamField body="inputs" type="array">
  Array - json
</ParamField>

<ParamField body="file" type="multipart">
  multipart - csv
</ParamField>

```sh 示例 theme={null}
curl "https://api.brightdata.com/datasets/initiate?dataset_id=XXX_DATASET_ID&type=url_collection&view=XXX_VIEW_ID" -H "Authorization: Bearer API_TOKEN" -H "Content-Type: application/json" -k -d '[{"id":"user-id"}]'
```

数据集将传送到为此视图配置的设置。

现在，利用这些增强的功能，用户可以更有效地定制其数据采集流程，确保生成的数据集符合其项目要求。

***

### 如何检索已采集的快照结果

```sh theme={null}
curl "https://api.brightdata.com/datasets/snapshots/snapshot_id/download" -H "Authorization: Bearer API_TOKEN" 
```