> For the complete documentation index, see [llms.txt](https://docs.graviti.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation.md).

# 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
# 响应结果
{}
```