# Open API

## Api Overview

### 关于dataset的操作

| api                                                                                                                         | description   |
| --------------------------------------------------------------------------------------------------------------------------- | ------------- |
| [ListAuthStorageConfig](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#listauthstorageconfig)           | 获取授权配置列表      |
| [ListStorageConfigs](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#liststorageconfigs)                 | 获取配置列表        |
| [CreateStorageConfigOSS](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createstorageconfigoss)         | 创建OSS存储配置     |
| [CreateStorageConfigS3](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createstorageconfigs3)           | 创建S3存储配置      |
| [CreateStorageConfigAzure](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createstorageconfigazure)     | 创建Azure存储配置   |
| [CreateStorageConfigLocalFs](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createstorageconfiglocalfs) | 创建本地存储配置      |
| [DeleteStorageConfig](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#deletestorageconfig)               | 删除配置          |
| [CreateDataset](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createdataset)                           | 创建dataset     |
| [DeleteDataset](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#deletedataset)                           | 删除数据集         |
| [UpdateDataset](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#updatedataset)                           | 更新数据集         |
| [ListDataset](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#listdataset)                               | 获取dataset列表   |
| [GetDataset](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#getdataset)                                 | 获取dataset     |
| [CreateBranch](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createbranch)                             | 创建分支          |
| [DeleteBranch](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#deletebranch)                             | 删除分支          |
| [ListBranches](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#listbranch)                               | 获取分支列表        |
| [CreateDraft](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createdraft)                               | 创建draft       |
| [UpdateDraft](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#updatedraft)                               | 更新draft       |
| [ListDraft](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#listdraft)                                   | 获取draft列表     |
| [CommitDataset](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#commitdataset)                           | 提交dataset     |
| [ListCommit](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#listcommit)                                 | 获取commit列表    |
| [CreateTag](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createtag)                                   | 创建tag         |
| [DeleteTag](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#deletetag)                                   | 删除tag         |
| [ListTag](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#listtag)                                       | 获取tag列表       |
| [UpdateNote](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#updatenote)                                 | 更新数据集note信息   |
| [GetNote](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#getnote)                                       | 获取数据集note信息   |
| [GetUser](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#getuser)                                       | 获取用户信息        |
| [ListBenchmarks](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#listbenchmarks)                         | 获取benchmark列表 |
| [CreateEvaluation](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createevaluation)                     | 创建评估          |
| [ListEvaluations](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#listevaluations)                       | 获取评估列表        |
| [GetEvaluationResult](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#getevaluationresult)               | 获取评估结果        |
| [CreateOrder](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createorder)                               | 创建订单          |
| [CreateTask](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#createtask)                                 | 创建任务          |
| [DeleteTask](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#deletetask)                                 | 删除任务          |
| [StopTask](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#stoptask)                                     | 停止任务          |
| [GetTask](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#gettask)                                       | 获取任务          |
| [ListTasks](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#listtasks)                                   | 获取任务列表        |
| [RetryTask](https://docs.graviti.cn/dev-doc/tools/api-center/dataset-operation#retrytask)                                   | 重试任务          |

### 关于data的操作

| api                                                                                                        | description      |
| ---------------------------------------------------------------------------------------------------------- | ---------------- |
| [GetPolicy](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#getpolicy)                     | 获取数据上传令牌         |
| [PutCallback](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#putcallback)                 | 上传回调             |
| [MultiPutCallback](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#multicallback)          | 批量上传回调           |
| [CreateSegment](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#createsegment)             | 创建segment        |
| [DeleteSegment](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#deletesegment)             | 删除segment        |
| [ListSegment](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#listSegment)                 | 获取segment        |
| [UploadLabelCatalog](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#uploadlabelcatalog)   | 更新label catalog  |
| [GetLabelCatalog](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#getlabelcatalog)         | 获取labelcatalog   |
| [UploadSensor](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#uploadsensor)               | 上传sensor         |
| [DeleteSensor](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#deletesensor)               | 删除sensor         |
| [ListSensor](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#listsensor)                   | 获取list sensor    |
| [ListData](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#listdata)                       | 获取data           |
| [ListDataDetails](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#listdatadetails)         | 获取data详情         |
| [ListDataUri](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#listdatauri)                 | 获取数据的url         |
| [ListMaskUrls](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#listmaskurls)               | 获取标注url          |
| [GetDataUrls](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#getdataurls)                 | 根据path获取数据的url   |
| [GetTotalSize](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#gettotalsize)               | 获取所有文件大小         |
| [ListCloudFiles](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#listcloudfiles)           | 获取云端文件列表         |
| [GetCloudFileUrl](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#getcloudfileurl)         | 获取云端文件url        |
| [CloudCallback](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#cloudcallback)             | 云端回调             |
| [UploadLabel](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#uploadlabel)                 | 更新label          |
| [ListLabel](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#listlabel)                     | 获取数据集的标注标签信息     |
| [MultiUploadLabel](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#multiuploadlabel)       | 批量更新label        |
| [GetLabelStatistics](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#getlabelstatistics)   | 获取label数据        |
| [ConvertLabelFromAli](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#convertlabelfromali) | 从阿里转换数据          |
| [DeleteData](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#deletedata)                   | 删除数据             |
| [OperateData](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#operatedata)                 | 操作数据             |
| [DeleteFrame](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#deleteframe)                 | 删除数据帧            |
| [GetDiff](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#getdiff)                         | 获取两版本差异          |
| [ListSegmentDiffs](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#listsegmentdiffs)       | 获取两版本segment差异列表 |
| [GetSegmentDiff](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#getsegmentdiff)           | 获取两版本segment差异   |
| [ListDataDiffs](https://docs.graviti.cn/dev-doc/tools/api-center/data-operation#listdatadiffs)             | 获取两版本数据差异        |

## Common

### 公共参数

文档中存在的一些公共参数

| 名称              | 描述                                                                                  | 值                                                     |
| --------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
| service         | api请求地址前缀                                                                           | <https://gas.graviti.cn/gatewayv2/tensorbay-open-api> |
| your\_accesskey | 用户申请得到的accesskey, 可进入[GAS开发者中心](https://docs.graviti.cn/dev-doc/tools/api-center)获取 |                                                       |

### HTTP Headers

此模块主要介绍http的公共请求头和响应头的详细说明

#### 公共请求头（Common Request Headers）

| 名称           | 类型     | 描述                                         |
| ------------ | ------ | ------------------------------------------ |
| Content-Type | string | RFC2616中定义的HTTP请求内容类型。默认值：application/json |
| X-Token      | string | 用户申请得到的accesskey                           |

#### 公共响应头（Common Response Headers）

| 名称           | 类型     | 描述                                                                                                 |
| ------------ | ------ | -------------------------------------------------------------------------------------------------- |
| X-Request-Id | string | X-Request-Id是由graviti创建，并唯一标识这个response的UUID。如果在使用graviti服务时遇到问题，可以凭借该内容联系graviti工作人员，快速定位问题。默认值：无 |

### Error code description

#### 错误码返回格式

```
{
  "code": "error_code",
  "message": "***"
}
```

当请求发生错误的时候，服务端会返回此类格式的错误信息。 譬如获取数据集时发生404错误。

```
# 响应状态
HttpStatus 404
# 响应结果
{
    "code": "ResourceNotExist", 
    "message": "dataset not exist!"
}
```

#### 错误码

| code                 | description              |
| -------------------- | ------------------------ |
| AccessDenied         | 请求被拒绝，缺失权限...            |
| InvalidParamsValue   | 无效的请求参数，比如参数格式不对，比如造成不幂等 |
| NameConflict         | 命名冲突                     |
| RequestParamsMissing | 必传的某个参数缺失                |
| ResourceNotExist     | 请求资源时，找不到资源              |
| SystemError          | 系统错误                     |

#### 模糊查询

**对于支持模糊查询的api，遵循以下规则**

1. 支持mysql通配符查询，如%, \_等通配符
2. 若无mysql通配符，默认%{模糊查询}%,前后模糊匹配
3. 若查询字段中含有mysql通配符，自动模糊匹配失效。
4. 若仅希望通配符当作普通字符串，需要进行转义处理，此时退化为非模糊匹配。若仍需要模糊匹配，需手动构造通配符查询。

**例： result： graviti\_1, great\_graviti\_1, graviti%1**

1. name = graviti, 返回结果graviti\_1, great\_graviti\_1, graviti%1
2. name = graviti\\\_%, 返回结果graviti\_1, great\_graviti\_1
3. name = graviti\\\_, 返回结果无
4. name = graviti%, 返回graviti\_1，graviti%1
5. name = graviti\\%%, 返回graviti%1
6. name = graviti\\%, 返回无
7. name = graviti\\%1, 返回graviti%1
8. name = %graviti, 返回无