# Dataset Operation

### ListAuthStorageConfig

**获取授权配置列表**

获取授权配置的列表

**请求路径**

> **GET** /v1/auth-storage-configs

**请求参数**

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>否</td><td>配置名</td></tr><tr><td>limit</td><td>int</td><td>否</td><td>需大于0，默认128，单次最多获取128</td></tr><tr><td>offset</td><td>int</td><td>否</td><td>默认0</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/auth-storage-configs?name=aws_1&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "configs": [
        {
            "name": "aws_1",
            "type": "s3",
            "endpoint": "s3.cn-northwest-1.amazonaws.com.cn",
            "accesskeyId": "AKIKU7KYZCWGOTEV5GNE",
            "bucketName": "graviti-210415"
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

### ListStorageConfigs

**获取配置列表**

**请求路径**

> **GET** /v1/storage-configs

**请求参数**

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>否</td><td>配置名</td></tr><tr><td>limit</td><td>int</td><td>否</td><td>需大于0，默认128，单次最多获取128</td></tr><tr><td>offset</td><td>int</td><td>否</td><td>默认0</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/storage-configs?limit=1&offset=0' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "configs":[
        {
            "name":"AliCloud-oss-cn-shanghai",
            "filePath":"",
            "type":"oss",
            "isGravitiStorage":true
        }
    ],
    "offset":0,
    "recordSize":1,
    "totalCount":1
}
```

### CreateStorageConfigOSS

**创建OSS存储配置**

**请求路径**

> **POST** /v1/storage-configs/oss

**请求参数**

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>是</td><td>配置名称</td></tr><tr><td>filePath</td><td>string</td><td>是</td><td>文件存储路径</td></tr><tr><td>accesskeyId</td><td>string</td><td>是</td><td>accesskey id</td></tr><tr><td>accesskeySecret</td><td>string</td><td>是</td><td>accesskey secret</td></tr><tr><td>endpoint</td><td>string</td><td>是</td><td>Oss 的节点</td></tr><tr><td>bucketName</td><td>string</td><td>是</td><td>oss 的 bucket 名</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/storage-configs/oss' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "configName",
   "filePath": "car",
   "accesskeyId": "AFIAU57BYHCWGOTEAV9GNE",
   "accesskeySecret": "secret",
   "endpoint": "oss-sn-hangzhou.aliyuncs.com",
   "bucketName": "testBucket"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### CreateStorageConfigS3

**创建S3存储配置**

**请求路径**

> **POST** /v1/storage-configs/s3

**请求参数**

**Body**

<table><thead><tr><th width="211.9345554898482">名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>是</td><td>配置名称</td></tr><tr><td>filePath</td><td>string</td><td>是</td><td>文件存储路径</td></tr><tr><td>accesskeyId</td><td>string</td><td>是</td><td>accesskey id</td></tr><tr><td>accesskeySecret</td><td>string</td><td>是</td><td>accesskey secret</td></tr><tr><td>endpoint</td><td>string</td><td>是</td><td>S3 的节点</td></tr><tr><td>bucketName</td><td>string</td><td>是</td><td>S3 的 bucket 名</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/storage-configs/s3' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "configName",
   "filePath": "car",
   "accesskeyId": "AFIAU57BYHCWGOTEAV9GNE",
   "accesskeySecret": "secret",
   "endpoint": "s3-sn-hangzhou.aliyuncs.com",
   "bucketName": "testBucket"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### CreateStorageConfigAzure

**创建Azure存储配置**

**请求路径**

> **POST** /v1/storage-configs/azure

**请求参数**

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>是</td><td>配置名称</td></tr><tr><td>filePath</td><td>string</td><td>是</td><td>文件存储路径</td></tr><tr><td>accesskeyId</td><td>string</td><td>是</td><td>Azure 的 account name</td></tr><tr><td>accesskeySecret</td><td>string</td><td>是</td><td>azure 的 account key</td></tr><tr><td>containerName</td><td>string</td><td>是</td><td>Azure 的 container 名</td></tr><tr><td>accountType</td><td>string</td><td>是</td><td>Azure 的 accountType</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/storage-configs/azure' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "configName",
   "filePath": "car",
   "accesskeyId": "AFIAU57BYHCWGOTEAV9GNE",
   "accesskeySecret": "secret",
   "containerName": "test_container",
   "accountType": "Azure_china"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### CreateStorageConfigLocalFs

**创建本地文件系统存储配置**

**请求路径**

> **POST** /v1/storage-configs/local

**请求参数**

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>是</td><td>配置名称</td></tr><tr><td>filePath</td><td>string</td><td>是</td><td>文件存储路径</td></tr><tr><td>endpoint</td><td>string</td><td>是</td><td>存储节点</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/storage-configs/local' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "configName",
   "filePath": "car",
   "endpoint": "192.168.1.1:8888"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### DeleteStorageConfig

**删除storage config**

> **DELETE** /v1/storage-configs/{name}

**Path**

| 名称   | 是否必须 | 描述       |
| ---- | ---- | -------- |
| name | 是    | config 名 |

**请求示例**

```
curl --location --request DELETE '{service}/v1/storage-configs/configName' \
--header 'x-token: {your_accesskey}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### CreateDataset

**创建数据集**

创建tensorbay数据集，默认支持版本管理，数据集名称不可重复

**请求路径**

> **POST** /v1/datasets

**请求参数**

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>是</td><td>数据集名字</td></tr><tr><td>alias</td><td>string</td><td>否</td><td>数据集别名</td></tr><tr><td>type</td><td>int</td><td>否</td><td>默认是0，0-普通数据集,1-融合数据集</td></tr><tr><td>configName</td><td>string</td><td>否</td><td>云配置名，根据对应配置创建数据集</td></tr><tr><td>isPublic</td><td>bool</td><td>否</td><td>数据集是否公开, 默认不公开</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/datasets' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "my first dataset",
   "alias": "dataset alias",
   "type": 0,
   "configName": "example config name",
   "isPublic": true
}'
```

**返回结果**

```
# 响应状态
HttpStatus 201
# 响应结果
{
    "id": "154e35bae8954f09969ef8c9445efd2c"
}
```

* **id**: 创建的data set的ID

### DeleteDataset

**删除dataset**

> **DELETE** /v1/datasets/{id}

**Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**请求示例**

```
curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c' \
--header 'x-token: {your_accesskey}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### UpdateDataset

**更新dataset信息**

> **PATCH** /v1/datasets/{id}

**Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>否</td><td>dataset 名称, 如果传值不可为“”空值</td></tr><tr><td>alias</td><td>string</td><td>否</td><td>数据集别名</td></tr><tr><td>isPublic</td><td>bool</td><td>否</td><td>数据集是否公开，true 对应公开， false 对应私有</td></tr><tr><td>defaultBranch</td><td>string</td><td>否</td><td>数据集默认分支名</td></tr></tbody></table>

**请求示例**

```
curl --location --request PATCH '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c' \
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "my dataset",
    "alias": "datasetAlias",
    "isPublic": false,
    "defaultBranch": "main"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### ListDataset

**获取数据集列表**

返回用户拥有的数据集列表：

* 个人用户获取个人账户下的数据集列表
* 团队用户获取所在企业下的数据集

**请求路径**

> **GET** /v1/datasets

**请求参数**

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>limit</td><td>int</td><td>否</td><td>需大于0，默认128，单次最多获取128</td></tr><tr><td>offset</td><td>int</td><td>否</td><td>默认0</td></tr><tr><td>name</td><td>string</td><td>否</td><td>数据集名称</td></tr><tr><td>needFuzzyQuery</td><td>bool</td><td>否</td><td>默认false 若为true，则支持数据集名称模糊搜索</td></tr><tr><td>needTeamDataset</td><td>bool</td><td>否</td><td>默认false，当用户为团队用户且该值为true，则返回整个团队的数据集</td></tr><tr><td>sortBy</td><td>string</td><td>否</td><td>排序的字段，默认updated_at（更新时间）, 目前支持created_at（创建时间）和updated_at,传入其他内容会返回InvalidParamsValue</td></tr><tr><td>orderBy</td><td>string</td><td>否</td><td>默认desc（倒序），合法内容为asc（顺序）和desc</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/datasets?offset=0&limit=10'\
--header 'x-token: {your_accesskey}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "datasets": [
      {
        "id": "154e35bae8954f09969ef8c9445efd2c",
        "name": "my-great-data-set",
        "alias": "dataset alias",
        "defaultBranch": "main",
        "type": 0,
        "updateTime": 1604977282,
        "owner": "",
        "commitId": "00000000000000000000000000000000",
        "coverUrl": "https://example.com/image.jpg",
        "dataSize": 100,
        "dataCount": 10,
        "tabs": {
          "labelType": [{
            "id":"06181d4e05484c1fa011f585a9e255cf", 
            "name":"BOX2D"
            }
          ]
        }
      }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

* **datasets**: 数据集列表
  * **id**: 数据集id
  * **name**: 数据集名称
  * **alias**: 数据集别名
  * **defaultBranch**: 默认分支名
  * **type**: 数据集类型，0-普通数据集，1-融合数据集
  * **owner**: 数据集所有者
  * **commitId**: 该数据集最新的提交 ID
  * **coverUrl**: 封面路径
  * **dataCount**: 默认分支上最新提交的数据数量
  * **dataSize**: 默认分支上最新提交的数据大小
  * **updateTime**: 时间戳，更新时间
  * **tabs**: 标签字典，键为类型，值为标签数组

### GetDataset

**请求路径**

> **GET** /v1/datasets/{id}

**请求参数**

**PATH**

| 名称 | 是否必须 | 描述         |
| -- | ---- | ---------- |
| id | 是    | dataset id |

**请求示例**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c'\
--header 'x-token: {your_accesskey}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "name": "my-great-data-set",
    "alias": "dataset alias",
    "coverUrl": "https://example.com/image.jpg",
    "type": 1,
    "defaultBranch": "main",
    "commitId": "00000000000000000000000000000000",
    "updateTime": 1604977282,
    "owner": "",
    "isPublic": false,
    "configName": "exampleConfigName"
}
```

### CreateBranch

**创建branch**

创建数据集新branch

**请求路径**

> **POST** /v1/datasets/{id}/branches

**请求参数** **Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>是</td><td>创建的branch名称</td></tr><tr><td>commit</td><td>string</td><td>是</td><td>从哪个commit切出branch, commit 可为 commit id, commit tag 或者 branch name</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": main2,
  "commit": "fde63f357daf46088639e9f57fd81cad"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 201
# 响应结果
{}
```

### DeleteBranch

**删除branch**

删除数据集branch

**请求路径**

> **DELETE** /v1/datasets/{id}/branches

**请求参数** **Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>是</td><td>branch名称</td></tr></tbody></table>

**请求示例**

```
curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": main2
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### ListBranches

**获取branch列表**

获取数据集的branch列表

**请求路径**

> **GET** /v1/datasets/{id}/branches

**请求参数** **Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>limit</td><td>int</td><td>否</td><td>需大于0，默认128，单次最多获取128</td></tr><tr><td>offset</td><td>int</td><td>否</td><td>默认0</td></tr><tr><td>name</td><td>string</td><td>否</td><td>分支名</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches?limit=1&offset=0' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "branches": [
        {
            "name": "main",
            "commitId": "fde63f357daf46088639e9f57fd81cad",
            "parentCommitId": "f68b1375454f459b8a486b8d1f4d9ddb",
            "title": "first commit",
            "description": "desc",
            "committer": {
                "name": "graviti",
                "date": 1616579313
            }
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

### CreateDraft

**创建数据集草稿**

创建tensorbay数据集草稿, 目前仅支持一个分支上创建一个数据集草稿

**请求路径**

> **POST** /v1/datasets/{id}/drafts

**请求参数**

**Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>title</td><td>string</td><td>是</td><td>草稿名称</td></tr><tr><td>branchName</td><td>string</td><td>否</td><td>branch 名称，缺省branch为main</td></tr><tr><td>description</td><td>string</td><td>否</td><td>草稿描述</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/drafts' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "my first draft",
  "branchName": "main"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "draftNumber": 1
}
```

* **draftNumber**: 草稿编号

### UpdateDraft

**更新数据集草稿**

**请求路径**

> **PATCH** /v1/datasets/{id}/drafts/{draftNumber}

**请求参数**

**Path**

| 名称          | 是否必须 | 描述    |
| ----------- | ---- | ----- |
| id          | 是    | 数据集ID |
| draftNumber | 是    | 草稿编号  |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>title</td><td>string</td><td>否</td><td>草稿名称</td></tr><tr><td>description</td><td>string</td><td>否</td><td>草稿描述</td></tr><tr><td>status</td><td>string</td><td>否</td><td>草稿状态, OPEN 或者 CLOSED</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/datasets/11df9efe26644d0d99c566325779b415/drafts/1' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "my first draft",
  "description": "desc change",
  "status": "OPEN"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### ListDraft

**获取数据集草稿列表**

获取数据集的草稿列表

**请求路径**

> **GET** /v1/datasets/{id}/drafts

**请求参数**

**Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>limit</td><td>int</td><td>否</td><td>需大于0，默认128，单次最多获取128</td></tr><tr><td>offset</td><td>int</td><td>否</td><td>默认0</td></tr><tr><td>branchName</td><td>string</td><td>否</td><td>基于数据分支名进行筛选</td></tr><tr><td>status</td><td>string</td><td>否</td><td>基于状态进行筛选，支持 "OPEN", "COMMITTED", "CLOSED" 和 "ALL"，默认为"OPEN"</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/drafts?limit=1&offset=0' \
--header 'x-token: {your_accesskey}'  
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
  "drafts": [
    {
      "branchName": "main",
      "title": "my first draft",
      "number": 1,
      "description": "desc",
      "status": "OPEN",
      "parentCommitId": "00000000000000000000000000000000",
      "author": "aaa",
      "updateAt": 1616579313
    }
  ],
  "offset": 0,
  "recordSize": 1,
  "totalCount": 10
}
```

### CommitDataset

**提交数据集**

将待提交状态的数据集更新为已提交状态，数据集一旦发布之后，该数据集不可再修改。

**请求路径**

> **POST** /v1/datasets/{id}/commits

**请求参数**

**Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>draftNumber</td><td>int</td><td>是</td><td>草稿编号</td></tr><tr><td>title</td><td>string</td><td>是</td><td>提交信息,字符数量应小于255</td></tr><tr><td>description</td><td>string</td><td>否</td><td>描述</td></tr><tr><td>tag</td><td>string</td><td>否</td><td>数据集版本标签，字符数量应大于2小于80</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c'\
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' \
--data-raw '{
  "draftNumber": "1",
  "title": "checkout a new version dataset",
  "description": "some desc",
  "tag": "v1.0"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
  "commitId": "fde63f357daf46088639e9f57fd81cad"
}
```

### ListCommit

**获取commit列表**

获取数据集的commit列表

**请求路径**

> **GET** /v1/datasets/{id}/commits

**请求参数** **Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>commit</td><td>string</td><td>否</td><td>commit id 或者 commit tag 或者 branch name, 缺省为默认branch</td></tr><tr><td>limit</td><td>int</td><td>否</td><td>需大于0，默认128，单次最多获取128</td></tr><tr><td>offset</td><td>int</td><td>否</td><td>默认0</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/commits?commit=main&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
  "commits": [
    {
      "parentCommitId": "0d213a06a85d46fa8662946bdb1afe7e",
      "commitId": "fde63f357daf46088639e9f57fd81cad",
      "title": "checkout a new version dataset",
      "description": "some desc",
      "dataCount": 10,
      "committer": {
        "date": 1617268600,
        "name": "graviti"
      }
    }
  ],
  "offset": 0,
  "recordSize": 1,
  "totalCount": 10
}
```

### CreateTag

**创建tag**

创建tag

**请求路径**

> **POST** /v1/datasets/{id}/tags

**请求参数** **Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>commit</td><td>string</td><td>是</td><td>commit id 或者 commit tag 或者 branch name</td></tr><tr><td>name</td><td>string</td><td>是</td><td>tag 名称,字符数量应大于2小于80</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "commit": "fde63f357daf46088639e9f57fd81cad",
  "name": "v1"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 201
# 响应结果
{}
```

### DeleteTag

**删除tag**

删除tag

**请求路径**

> **DELETE** /v1/datasets/{id}/tags

**请求参数** **Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>是</td><td>tag 名称</td></tr></tbody></table>

**请求示例**

```
curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "v1"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### ListTag

**获取tag**

获取数据集的tag列表

**请求路径**

> **GET** /v1/datasets/{id}/tags

**请求参数** **Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>否</td><td>tag 名称,若存在，返回该tag信息</td></tr><tr><td>limit</td><td>int</td><td>否</td><td>需大于0，默认128，单次最多获取128</td></tr><tr><td>offset</td><td>int</td><td>否</td><td>默认0</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags?name=v1&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "tags": [
        {
            "name": "v1",
            "commitId": "fde63f357daf46088639e9f57fd81cad",
            "parentCommitId": "f68b1375454f459b8a486b8d1f4d9ddb",
            "title": "first commit",
            "description": "some desc",
            "committer": {
                "name": "graviti",
                "date": 1617268600
            }
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

### **U**pdateNote

**更新数据集notes** 更新数据集note **请求路径**

> **PATCH** /v1/datasets/{id}/notes

**请求参数** **Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Body**

<table><thead><tr><th width="241">名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>draftNumber</td><td>int</td><td>是</td><td>draft 序号</td></tr><tr><td>binPointCloudFields</td><td>string[]</td><td>否</td><td>bin格式点云的维度名称</td></tr><tr><td>isContinuous</td><td>bool</td><td>否</td><td>是否连续</td></tr></tbody></table>

**请求示例**

```
curl --location --request PATCH '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/notes' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "draftNumber": 1,
  "fileFormat": {
    "draftNumber": 1,
    "binPointCloudFields": [
       "X",
       "Y",
       "Z",
       "Intensity"
    ],
    "isContinuous": true
}'
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### GetNote

**获取note**

获取数据集的note

**请求路径**

> **GET** /v1/datasets/{id}/notes

**请求参数** **Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>draftNumber</td><td>int</td><td>否</td><td>草稿编号,draft和commit二者必须存在一个，但不可全部存在</td></tr><tr><td>commit</td><td>string</td><td>否</td><td>当commit不为空且正确时，查询该commit的data数据</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/notes?draftNumber=1' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "isContinuous": true，
    "binPointCloudFields": [
        "X",
        "Y",
        "Z",
        "Intensity"
    ]
}
```

### GetUser

**获取用户信息**

**请求路径**

> **GET** /v1/users

**请求示例**

```
curl --location --request GET '{service}/v1/users' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "id":"f74836a28f2051d97d60944c48b766d1",
    "nickname":"Graviti",
    "email":null,
    "mobile":"1234567890",
    "description":"",
    "team":{
      "id":"xxx",
      "name":"teamName",
      "email":"team email",
      "description":"team desc"
    }
}
```

### ListBenchmarks

**获取benchmark列表**

**请求路径**

> **GET** /v1/benchmarks

**请求参数**

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>limit</td><td>int</td><td>否</td><td>需大于0，默认128，单次最多获取128</td></tr><tr><td>offset</td><td>int</td><td>否</td><td>默认0</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/benchmarks' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "benchmarks":[
        {
            "name":"test",
            "benchmarkId":"675284b0926b4b96a725ef3fed77d0aa"
        }
    ],
    "offset":0,
    "recordSize":1,
    "totalCount":1
}
```

### CreateEvaluation

**创建评估**

**请求路径**

> **POST** /v1/benchmarks/{benchmarkId}/evaluations

**请求参数**

**Path**

| 名称          | 是否必须 | 描述           |
| ----------- | ---- | ------------ |
| benchmarkId | 是    | Benchmark ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>datasetId</td><td>string</td><td>是</td><td>数据集Id</td></tr><tr><td>commitId</td><td>string</td><td>是</td><td>commit Id</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/benchmarks/675284b0926b4b96a725ef3fed77d0aa/evaluations' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "datasetId": "11df9efe26644d0d99c566325779b415",
   "commitId": "ce3be905ba0f465c84c9fc39e53a89f8"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 201
# 响应结果
{
    "evaluationId": "154e35bae8954f09969ef8c9445efd2c"
}
```

### ListEvaluations

**获取评估列表**

**请求路径**

> **GET** /v1/benchmarks/{benchmarkId}/evaluations

**请求参数**

**Path**

| 名称          | 是否必须 | 描述           |
| ----------- | ---- | ------------ |
| benchmarkId | 是    | Benchmark ID |

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>limit</td><td>int</td><td>否</td><td>需大于0，默认128，单次最多获取128</td></tr><tr><td>offset</td><td>int</td><td>否</td><td>默认0</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/benchmarks/675284b0926b4b96a725ef3fed77d0aa/evaluations' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "evaluations":[
        {
            "name":"",
            "evaluationId":"aa50f8a172bc4064abab4d98a1283080",
            "number":0,
            "createdAt":1647353362,
            "finishedAt":null,
            "author":"Graviti",
            "status":"failed"
        }
    ],
    "offset":0,
    "recordSize":1,
    "totalCount":1
}
```

### GetEvaluationResult

**获取评估结果**

**请求路径**

> **GET** /v1/benchmarks/{benchmarkId}/evaluations/{evaluationId}/results

**请求参数**

**Path**

| 名称           | 是否必须 | 描述           |
| ------------ | ---- | ------------ |
| benchmarkId  | 是    | Benchmark ID |
| evaluationId | 是    | 评估 ID        |

**请求示例**

```
curl --location --request GET '{service}/v1/benchmarks/675284b0926b4b96a725ef3fed77d0aa/evaluations/aa50f8a172bc4064abab4d98a1283080/results' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "result":{
        "categories":{
        },
        "overall":{
        }
    }
}
```

### CreateOrder

**创建订单(团队账户可用)**

**请求路径**

> **POST** /v1/orders

**请求参数**

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>datasetId</td><td>string</td><td>是</td><td>数据集Id</td></tr><tr><td>commitId</td><td>string</td><td>是</td><td>提交 ID</td></tr><tr><td>name</td><td>string</td><td>是</td><td>需求订单名称</td></tr><tr><td>deliveryTime</td><td>string</td><td>是</td><td>交付时间 例如 2021-12-14</td></tr><tr><td>labelType</td><td>string</td><td>是</td><td>标注类型 例如 BOX2D</td></tr><tr><td>serviceProvider</td><td>string</td><td>否</td><td>服务商名称 例如 格物钛</td></tr><tr><td>requirementDocumentUrl</td><td>string</td><td>否</td><td>需求文档地址</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/orders' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "datasetId": "11df9efe26644d0d99c566325779b415",
   "commitId": "ce3be905ba0f465c84c9fc39e53a89f8",
   "name": "order name",
   "deliveryTime": "2022-02-22",
   "labelType": "BOX2D"
}'
```

**返回结果**

```
# 响应状态
HttpStatus 201
# 响应结果
{
    "id": "154e35bae8954f09969ef8c9445efd2c"
}
```

### CreateTask

**创建任务**

**请求路径**

> **POST** /v1/datasets/{id}/jobs

**请求参数**

**Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Body**

<table><thead><tr><th width="231">名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>title</td><td>string</td><td>是</td><td>任务标题</td></tr><tr><td>jobType</td><td>string</td><td>是</td><td>任务类型 squashAndMerge,basicSearch</td></tr><tr><td>description</td><td>string</td><td>否</td><td>任务描述</td></tr><tr><td>maxRetries</td><td>int</td><td>否</td><td>任务最大重试次数</td></tr><tr><td>arguments</td><td>map</td><td>否</td><td>任务参数 squashAndMerge</td></tr><tr><td>├-sourceBranchName</td><td>string</td><td>是</td><td>源分支</td></tr><tr><td>├-targetBranchName</td><td>string</td><td>是</td><td>目标分支</td></tr><tr><td>├-strategy</td><td>string</td><td>否</td><td>当不是用已有操作时移动重名时的策略，可选项有：abort，override 和 skip，缺省为 abort</td></tr><tr><td>├-title</td><td>string</td><td>是</td><td>标题</td></tr><tr><td>├-description</td><td>string</td><td>否</td><td>描述</td></tr><tr><td>arguments</td><td>map</td><td>否</td><td>任务参数 basicSearch</td></tr><tr><td>├-commit</td><td>string</td><td>是</td><td>commit ID</td></tr><tr><td>├-tag</td><td>string</td><td>否</td><td>tag名</td></tr><tr><td>├-branch</td><td>string</td><td>否</td><td>分支名</td></tr><tr><td>├-draft</td><td>string</td><td>否</td><td>草稿编号</td></tr><tr><td>├-unit</td><td>string</td><td>是</td><td>搜索单位 file, frame</td></tr><tr><td>├-segmentNames</td><td>string[]</td><td>是</td><td>segment 名字列表</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/datasets/4a9e62ea88fd47b9b4b5f6bbbfe8ef64/jobs' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "title": "taskTitle",
   "jobType": "squashAndMerge",
   "arguments": {
     "sourceBranchName":"main",
     "targetBranchName":"test",
     "title":"argTitle"
   }
}'
```

**返回结果**

```
# 响应状态
HttpStatus 201
# 响应结果
{
    "jobId":"7e412ceb61c943178e70fa7b032a9d10",
    "createdAt":1647489812
}
```

### DeleteTask

**删除Job**

**请求路径**

> **DELETE** /v1/datasets/{id}/jobs/{taskId}

**请求参数** **Path**

| 名称     | 是否必须 | 描述     |
| ------ | ---- | ------ |
| id     | 是    | 数据集ID  |
| taskId | 是    | job ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>jobType</td><td>string</td><td>否</td><td>任务类型 squashAndMerge,basicSearch</td></tr></tbody></table>

**请求示例**

```
curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/jobs/7e412ceb61c943178e70fa7b032a9d10' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### StopTask

**中止Job**

**请求路径**

> **POST** /v1/datasets/{id}/jobs/{taskId}/abort

**请求参数** **Path**

| 名称     | 是否必须 | 描述     |
| ------ | ---- | ------ |
| id     | 是    | 数据集ID  |
| taskId | 是    | job ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>jobType</td><td>string</td><td>否</td><td>任务类型 squashAndMerge,basicSearch</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/jobs/7e412ceb61c943178e70fa7b032a9d10/abort' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```

### GetTask

**获取job详情**

**请求路径**

> **GET** /v1/datasets/{id}/jobs/{taskId}

**请求参数**

**Path**

| 名称     | 是否必须 | 描述     |
| ------ | ---- | ------ |
| id     | 是    | 数据集ID  |
| taskId | 是    | job ID |

**Query**

<table><thead><tr><th width="154.7142857142857">名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>jobType</td><td>string</td><td>否</td><td>任务类型 squashAndMerge,basicSearch</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/jobs/7e412ceb61c943178e70fa7b032a9d10' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "title":"task title",
    "jobId":"7e412ceb61c943178e70fa7b032a9d10",
    "jobType":"squashAndMerge",
    "arguments":{
        "description":"argDesc",
        "sourceBranchName":"branch1",
        "strategy":"abort",
        "targetBranchName":"main",
        "title":"argTitle"
    },
    "createdAt":1647489813,
    "startedAt":1647489813,
    "status":"FAILED",
    "errorMessage":"",
    "description":"task desc ",
    "result":{
        "draftNumber":4
    }
}
```

### ListTasks

**获取job列表**

**请求路径**

> **GET** /v1/datasets/{id}/jobs

**请求参数**

**Path**

| 名称 | 是否必须 | 描述    |
| -- | ---- | ----- |
| id | 是    | 数据集ID |

**Query**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>jobType</td><td>string</td><td>否</td><td>任务类型 squashAndMerge,basicSearch</td></tr><tr><td>status</td><td>string</td><td>否</td><td>Job状态, FAILED, SUCCESS</td></tr><tr><td>limit</td><td>int</td><td>否</td><td>需大于0，默认128，单次最多获取128</td></tr><tr><td>offset</td><td>int</td><td>否</td><td>默认0</td></tr></tbody></table>

**请求示例**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/jobs' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{
    "jobs":[
        {
            "title":"task title",
            "jobId":"7e412ceb61c943178e70fa7b032a9d10",
            "jobType":"squashAndMerge",
            "arguments":{
                "description":"argDesc",
                "sourceBranchName":"branch1",
                "strategy":"abort",
                "targetBranchName":"main",
                "title":"argTitle"
            },
            "createdAt":1647489813,
            "startedAt":1647489813,
            "status":"FAILED",
            "errorMessage":"",
            "description":"task desc ",
            "result":{
                "draftNumber":4
            }
        }
    ],
    "offset":0,
    "recordSize":128,
    "totalCount":1
}
```

### RetryTask

**重试Job**

**请求路径**

> **POST** /v1/datasets/{id}/jobs/{taskId}/retry

**请求参数** **Path**

| 名称     | 是否必须 | 描述     |
| ------ | ---- | ------ |
| id     | 是    | 数据集ID  |
| taskId | 是    | job ID |

**Body**

<table><thead><tr><th>名称</th><th width="150">类型</th><th width="150">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>jobType</td><td>string</td><td>否</td><td>任务类型 squashAndMerge,basicSearch</td></tr></tbody></table>

**请求示例**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/jobs/7e412ceb61c943178e70fa7b032a9d10/retry' \
--header 'x-token: {your_accesskey}' 
```

**返回结果**

```
# 响应状态
HttpStatus 200
# 响应结果
{}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.