数据集相关API
1. 数据集相关API 概述
数据集相关的 Public API,是指观远数据为在进行系统集成时可以针对数据集进行相关操作,而提供的标准化开放接口。
观远数据提供一套简便的验证机制,来供私有化部署用户进行外部系统和账户对接集成,实现集中、高效、便利的管理。本文将为您详细介绍观远数据为您提供的与数据集相关的 Public API。
2. 数据集相关API 列表速览
目前,与数据集相关的 Public API 共包含9个,列表如下:
序号 | 接口描述 | PATH |
1 | 获取数据集列表 | POST /public-api/data-source/list |
2 | 搜索数据集列表 | POST /public-api/data-source/search?q=xx&&offset=0&&limit=10 |
3 | 查询数据集的结构 | POST /public-api/data-source/:dsId/columns |
4 | 修改数据集更新方式 | POST /public-api/data-source/update-setting |
5 | 获取指定数据集有使用权限的用户列表 | POST /public-api/data-source/:dsId/get-readable-owners |
6 | 数据集上传 | POST /public-api/upload-dataset |
7 | 数据集下载 | POST /public-api/data-source/{dsid}/data|POST /public-api/data-source/{dsId}/token/{token} |
8 | 创建数据集 | POST /public-api/data-source/create-from-account |
9 | 更新数据集字段注释 | POST /public-api/data-source/:dsId/update-annotation |
3. 数据集相关API 具体说明
3.1 获取数据集列表 (1032)
3.1.1 接口简介
请求方式: POST
请求地址:POST /public-api/data-source/list
3.1.2 参数说明
参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
token | 应用Token | Body | String | 是 | 在观远平台中获得 |
3.1.3 请求与响应示例
POST Body Sample:
{
"token":"m3a369b32444b48caa873411",
}
Response Sample:
{
"result": "ok",
"response": [
{
"dsId": "fe43fdcb1b0094b65b5492dd",
"name": "dataset_name",
"displayType": "MYSQL", //数据集类型
"storageId": "mfba91c30d7c9455a99df3cd",
"domId": "demo",
"uId": "l9c85be354b674ec4a1081cc", //创建者
"parentDirId": "i5865e734b8374489abe2fc4", //所属文件夹
"cnId": "mysql", //数据连接类型
"rowCount": 1000000000, //行数
"colCount": 5, //列数
"status": "FINISHED", //更新状态
"ctime": "2018-07-11 13:50:36+0800", //创建时间
"utime": "2018-07-13 11:49:53+0800", //更新时间
"cardCount": 0 //卡片数量
},
……
]
}
其中数据库相关数据集包含config字段,tableQuery属性中包含具体的取数SQL。
3.2 搜索数据集列表(1034)
3.2.1 接口简介
请求方式: POST
请求地址:POST /public-api/data-source/search?q=xx&&offset=0&&limit=10
3.2.2 参数说明
参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
token | 应用Token | Body | String | 是 | 在观远平台中获得 |
q | 要搜索的数据集名称模糊词 | url | String | 是 | |
offset | 搜索结果的起始位置 | url | String | 否 | 默认值0 |
limit | 从起始位置取多少条 | url | String | 否 | 默认值0 |
3.2.3 请求与响应示例
POST Body Sample:
{
"token":"m3a369b32444b48caa873411",
}
Response Sample:
{
"result": "ok",
"response": {
"total": 6,
"offset": 0,
"limit": 10,
"list": [
{
"dsId": "fe43fdcb1b0094b65b5492dd",
"name": "dataset_name",
"displayType": "MYSQL", //数据集类型
"storageId": "mfba91c30d7c9455a99df3cd",
"domId": "demo",
"uId": "l9c85be354b674ec4a1081cc", //创建者
"parentDirId": "i5865e734b8374489abe2fc4", //所属文件夹
"cnId": "mysql", //数据连接类型
"rowCount": 1000000000, //行数
"colCount": 5, //列数
"status": "FINISHED", //更新状态
"ctime": "2018-07-11 13:50:36+0800", //创建时间
"utime": "2018-07-13 11:49:53+0800", //更新时间
"cardCount": 0 //卡片数量
},
……
]
}
}
3.3 查询特定数据集的数据结构(1035)
3.3.1 接口简介
请求方式:POST
请求地址:/public-api/data-source/dsId/columns
3.3.2 参数说明
参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
X-Auth-Token | 个人Token | header | String | 是 | 登录token,从sign in接口获取 |
dsId | 数据集Id | path | String | 是 |
3.3.3 请求与响应示例
POST Body Sample:
{
}
*Body不可为空,至少需要填入两个花括号,否则会报错。
Response Sample:
{
"result": "ok",
"response": [
{
"name": "Sales",
"fdType": "DOUBLE", //字段类型
"dsId": "r45d63856a81a4540822e432",
"fdId": "w951bd56ccf364f498e80300",
"metaType": "METRIC",
"seqNo": 0,
"isAggregated": false,
"calculationType": "normal",
"level": "dataset",
"isDetectionSensitive": false,
"isSensitive": false,
"annotation": "这是字段的注释"
},{
}
]
}
3.4 批量修改数据集更新方式(1036)
3.4.1 接口简介
请求方式:POST
请求地址:/public-api/data-source/update-setting
3.4.2 参数说明
参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
token | 应用Token | Body | String | 是 | 在观远平台中获得 |
propsInDetails | 数据集路径配置 | Body | JSON Object | -- | |
settingsInDetails | 数据集其他参数配置(如更新时间,更新方式) | Body | JSON Object | -- |
目前仅支持批量更新数据集的文件夹路径或者数据集的属性更新,如果只需要更新路径位置,则只传递 propsInDetails 参数即可。
propsInDetails 和 settingsInDetails 的更新互不影响,即前者更新失败,后者还是会继续执行更新,除非两个都失败则返回前者的报错。
3.4.3 请求与响应示例
POST Body Sample:
Post Body 传参时只需要传入要修改的数据集属性参数即可
{
"token": "xxxxxxxxxxxx",
// 批量更新数据集的文件夹路径
"propsInDetails": [
{"dsId": "be2e2c9bbcdf147c3a506447", "dsDir": "所在文件夹的ID"}
],
// 批量更新数据集配置
"settingsInDetails": [
{
"dsId": "be2e2c9bbcdf147c3a506447",
// 数据集更新时间
"cron": {
"cronType": "DAILY/",
"value": "{\\\"hours\\\":\\\"05\\\",\\\"minute\\\":\\\"00\\\"}"
},
// 增量更新设置
"guanIndexIncrementalUpdateSetting": {
"enabled": false,
"query": "",
// 前置清理规则
"preClean": {
"enabled": false,
"rule": ""
}
},
// 是否支持实时卡片数据
"realTimeUpdateSetting": null,
// 是否URL触发
"tokenSetting": {
"action": "disable"//“enable”表示勾选URL触发
},
// 失败重试
"retryCapable": {
"enable": false,
"retryConfig": {
"interval": 5,
"unit": "MINUTE"
}
}
}
]
}
部分参数详解:
- cron:更新时间
// 手动更新
"cron": {
"cronType": "default",
"value": ""
}
// 按周更新:每周五,六的凌晨3点更新
"cron": {
"cronType": "WEEKLY",
value: "{\"minute\":\"00\",\"hours\":\"03\",\"dow\":\"FRI,SAT\"}"
}
// 按月更新:每月6,7号的凌晨3点更新
"cron": {
"cronType": "MONTHLY",
"value": "{\"minute\":\"00\",\"hours\":\"03\",\"dom\":\"6,7\"}"
}
- realTimeUpdateSetting:是否支持实时卡片数据
// 适用于直连数据集
"realTimeUpdateSetting":{
"disableCache": false,
"enabled": true,
"interval": 600
}
- retryCapable:失败重试
"retryCapable": {
"enable": true,
"retryConfig": {
"interval": 10,
"unit": "MINUTE"
}
}
- guanIndexIncrementalUpdateSetting:增量更新设置
// 适用于GuanIndex抽取数据集
"guanIndexIncrementalUpdateSetting": {
"enabled": true,
"query": "select * from `goods_info` where date > '{{{yesterday}}}' ",
"preClean": {
"enabled": true,
"rule": "`date`<'{{{yesterday}}}'"
}
}
Response Sample:
{
"result": "ok",
"response": "Done"
}
3.5 获取指定数据集有使用权限的用户列表(1033)
3.5.1 接口简介
请求方式:POST
请求地址:/public-api/data-source/:dsId/get-readable-owners
3.5.2 参数说明
参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
token | 应用Token | Body | String | 是 | 在观远平台中获得 |
3.5.3 请求与响应示例
POST Body Sample:
{
"token":"x3a369b32444b48caa873411",
}
Response Sample:
{
"result": "ok",
"response": {
"ownerGroups": [],
"ownerUsers": [
{
"id": "s7f7076fe5ae24a57a031e9d",
"name": "高XX",
"canExport": true,
"loginId": "xxx@guandata.com",
"email": "xxx@guandata.com"
}
],
"readableGroups": [],
"readableUsers": [
{
"id": "s7f7076fe5ae24a57a031e9d",
"name": "高XX",
"canExport": true,
"loginId": "XXX@guandata.com",
"email": "XXX@guandata.com"
}
]
}
}
3.6数据上传
3.6.1 用户名密码方式登录获取合法Token
3.6.1.1 接口简介
请求方式:POST
请求地址:/public-api/sign-in
3.6.1.2 参数说明
参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
Content-Type | 内容类型 | Header | String | 是 | -- |
domain | 域名 | Body | String | 是 | 在观远系统中的域名,非网址的域名 |
登录的邮箱 | Body | String | 是 | 如果开启了账号登录模式则该参数不传,传loginId和对应的内容 | |
password | 密码 | Body | String | 是 | 原始密码经过Base64编码后的字符串 |
3.6.1.3 请求与响应示例
Header Sample:
{
"Content-Type": "application/json; charset=utf-8"
}
POST Body Sample:
{
"domain":"demo",
"email":"123@456.com",
"password":"my_password_base64_encoded"
}
注意:参数中password需要base64 encode。
Response Sample:
{
"result":"ok",
"response":
{
"token":"guanyuan token", /* 该token在后面调用其他接口时使用 */
"expireAt":"2018-02-06 00:11:12.13"
}
}
3.6.2 上传数据
3.6.2.1 接口简介
请求方式:POST
请求地址:/public-api/upload-dataset
3.6.2.2 参数说明
参数名 | 参数值 | Location | 类型 | 是否必填 | 备注 |
Content-Type | 内容类型 | Header | String | 是 | |
X-Auth-Token | 登录用的Token | Header | String | 是 | 调用登录API获取 |
tableName | 数据集名称 | Body | String | 是 | |
dsId | 数据集ID | Body | String | 否 | 若tableName有重名可以指定dsId |
overwriteExistingData | 是否覆盖原始数据 | Body | Boolean | 默认为false,即追加数据 | |
columns | 设置上传数据集各列属性 | Body | JSON | name:列名 type:字段类型 isPrimaryKey:是否是主键 | |
allColumnsSpecified | 是否选择所有列 | Body | Boolean | ||
data | 待上传的数据 | Body | JSON | 是 | |
displayType | 标识的格式 | Body | String | ||
batchFinish | 是否最后一批 | Body | Boolean | batchFinish 设为true会更新该数据集,注意不要频繁更新数据集。 |
3.6.2.3 请求与响应示例
Header Sample:
{
"Content-Type": "application/json"
"X-Auth-Token": "guanyuan token"
}
POST Body Sample:
{
"tableName": "my_table_name", /* 必选,如果需要向已存在数据集追加数据,设置相同的tableName即可。*/
"overwriteExistingData": false, /* 可选,默认为false,设置为true时,先删除原来的数据,再上传。*/
"columns": [ /* 可选,设置各字段 */
{
"name": "column1",
"type": "string", /* 可选, 如果没有设置, 则系统会自动读取前1000行来推测其列的数据类型, string, integer, double, timestamp, long, short, float, date */
"isPrimaryKey": true /* 可选,默认为false,设置主键,设置了primaryKey后,多次上传时会更新原有数据,否则,会追加到原有数据后 */
}
],
"allColumnsSpecified": false, /* 可选,默认false。为false时,会自动检查data中的字段并推测类型上传到观数,为true时,表示columns中指定了所有字段,那么,data中的多余字段会过滤掉。 */
"data": [
{
"column1": "data1_1",
"column2": "data1_2"
},
{
"column1": "data2_1",
"column2": "data2_2"
}
],
"displayType": "CSV", /* 可选,标示在观数的显示格式,包括 CSV, EXCEL, DATAFUSION, DATAFLOW, MYSQL, KR3000, PUBLIC, WEIXIN, POSTGRESQL, GREENPLUM, CARD*/
"batchFinish": false /* 可选,默认为false,分批上传时,表示是否是最后一批。设置为false时,不更新行数,也不刷新card缓存 */
}
Response Sample:
{
"result": "ok",
"response": {
"status": "finish",
"dsId": "c5bf77bf02ef54b848164c1a"
}
}
3.7 下载数据集数据
接口返回数据上限5W行。
3.7.1 获取数据集下载授权Token (1041)
3.7.1.1 接口简介
请求方式:POST
请求地址:/public-api/sign-in
3.7.1.2 参数说明
参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
Content-Type | 内容类型 | Header | String | 是 | -- |
domain | 域名 | Body | String | 是 | 在观远系统中的域名,非网址的域名 |
登录的邮箱 | Body | String | 是 | 如果开启了账号登录模式则该参数不传,传loginId和对应的内容 | |
password | 密码 | Body | String | 是 | 原始密码经过Base64编码后的字符串 |
3.7.1.3 请求与响应示例
Header Sample:
{
"Content-Type": "application/json; charset=utf-8"
}
POST Body Sample:
{
"domain":"demo",
"email":"123@456.com",
"password":"my_password_base64_encoded"
}
注意:参数中password需要base64 encode。
Response Sample:
{
"result":"ok",
"response":
{
"token":"guanyuan token", /* 该token在后面调用其他接口时使用 */
"expireAt":"2018-02-06 00:11:12.13"
}
}
3.7.2 下载数据集数据 (1042)
3.7.2.1 接口简介
请求方式:POST
请求地址:/public-api/data-source/{dsId}/token/{token}
3.7.2.2 参数说明
参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
dsId | 数据集ID | Path | String | 是 | 目标数据集ID |
token | 授权token | Path | String | 是 | 调用登录API获取;请使用管理员账号或者数据集所有者做登录。 |
cols | 需获取的列 | Body | Array | 是 | 指定欲获取的列 |
filters | 过滤条件 | Body | JSON | 否 | 指定过滤条件,包括name,filterType,filterValue name:过滤的列名; filterType:过滤类型;filterValue:过滤值 |
说明:
-
该api一次最多返回5万行数据,若数据集较大,请指定过滤条件。
-
如果cols和filters都没有指定,则请求返回数据集所有列和行。注意,即使两个参数都没有指定,请求体也不能省略,即{}。
-
其中,filterType支持以下形式: GT (>), GE (>=), LT (<), LE(<=), EQ (==), NE (!=), IN (IN LIST), NI (NOT IN LIST), STARTSWITH, NOT_STARTSWITH, ENDSWITH, NOT_ENDSWITH, CONTAINS, NOT_CONTAINS,IS_NULL, NOT_NULL
3.7.2.3 请求与响应示例
POST Body Sample:
{
"cols": [
"Category",
"Item",
"Price"
],
"filters": [
{
"name": "Price",
"filterType": "GT",
"filterValue": [
"100"
]
}
]
}
Response Sample:
{
"result": "ok",
"response": {
"columns": [
"Category",
"Item",
"Price"
],
"data": [
[
"Electronics",
"Apple TV",
"200"
],
[
"Books",
"Red and Black",
"128"
],
[
"Electronics",
"Iphone X",
"800"
],
[
"Books",
"The story of the stone",
"256"
],
]
}
}
3.8 创建数据集
支持基于数据账号创建数据库相关直连数据集和抽取(Guan-Index)数据集。
3.8.1 接口简介
请求方式:POST
请求地址:/public-api/data-source/create-from-account
3.8.2 参数说明
参数名 | 参数值说明 | 类型 | 直连数据集是否必填 | 抽取数据集是否必填 | 备注 |
acId | 数据账号ID | String | 必填 | 必填 | 具体获取方式请查看3.9.4获取数据账号ID操作示意 |
name | 数据集名称 | String | 必填 | 必填 | |
parentDirId | 目录ID,创建的数据集将放在此目录下 | String | 选填 | 选填 | 当不传时,数据集默认放在根目录下。具体值可以在浏览器访问目录后在地址栏中获取。 |
cron | 数据集定时更新设置 | JSON Object | 选填 | 选填 | 具体内容请查看参数详情补充说明,若不传则默认为手动更新 |
tableQuery | 生成数据集所使用的SQL语句 | JSON Object | 必填 | 必填 | 具体内容请查看参数详情补充说明 |
sourceType | 数据集类型,固定值 | String | 必填 | 必填 | 直连数据集:DIRECT_CONNECT_DATABASE; 抽取数据集:GUAN_INDEX |
realTimeUpdateSetting | 实时卡片数据 | JSON Object | 必填 | 不填 | 具体内容请查看参数详情补充说明 |
primaryKeyColumns | 去重主键 | List[String] | 不填 | 选填 | 填写参数格式为:["column1", "column2"] |
guanIndexIncrementalUpdateSetting | 增量更新 | JSON Object | 不填 | 选填 | 具体内容请查看参数详情补充说明 |
token | 应用Token | String | 必填 | 必填 | 具体内容请查看《Token 鉴权》 |
以上参数均在BODY中传递。
参数详情补充说明:
cron:
参数名 | 参数值说明 | 类型 |
cronType | Cron表达式类型 | String |
Value | Cron表达式 | String |
- cronType 可选值:
参数名 | 说明 |
default | 手工更新 |
DAILY | 每天 |
WEEKLY | 每周 |
MONTHLY | 每月 |
- CronDefinition 示例:
{
"cronType": "default",
"value": "\"\""
}
//时间含义:手工更新
{
"cronType": "DAILY",
"value": "{\"hours\":\"07,19\",\"minute\":\"58\"}"
}
//时间含义:每天的7:58 和19:58
{
"cronType": "WEEKLY",
"value": "{\"hours\":\"07\",\"minute\":\"00\",\"dow\":\"TUE,THU,WED\"}"
}
//时间含义:每周的周二,周三,周四的7:00
{
"cronType": "MONTHLY",
"value": "{\"hours\":\"22\",\"minute\":\"58\",\"dom\":\"7,8\"}"
}
//时间含义:每月的7号,8号的22:58
tableQuery:
参数名 | 参数值说明 | 类型 |
queryType | SQL查询类型,本接口固定传参为“query” | String |
query | 创建数据集所使用的SQL语句 | String |
table | 数据集所使用表的表名 | String |
realTimeUpdateSetting:
参数名 | 参数值说明 | 类型 |
enabled | 是否开启支持实时卡片数据 | Boolean |
interval | 目前固定为600 | Int |
disableCache | 是否开启缓存 | Boolean |
guanIndexIncrementalUpdateSetting:
参数名 | 参数值说明 | 类型 |
enabled | 是否开启增量更新 | Boolean |
query | 增量更新所使用的SQL语句 | String |
注意:当数据集类型为 Guan-Index 时,primaryKeyColumns不填为不去重,填写参数格式为:[“column1”, “column2”],column 代表去重列名。
3.8.3 请求与响应示例
POST Body Sample
抽取(Guan-Index)数据集:
{
"acId": "x2ca2ec33088145d698d49bc", //数据账户 ID
"name": "guanIndex", //数据集名称
"cron": {
"cronType": "DAILY",
"value": "{\"hours\":\"02\",\"minute\":\"00\"}"
},
"tableQuery": {
"queryType": "query",//固定值
"table": "GUANDATA.fengupsert02",// 表名名
"query": "select id1,id2,id3 from GUANDATA.fengupsert02"// 查询 sql
},
"parentDirId": "u48b02a7c87d74b759782be2",// 存放目录 Id
"sourceType": "GUAN_INDEX", // 数据集类型
"primaryKeyColumns": [
"id1"
],
"guanIndexIncrementalUpdateSetting": {
"enabled": true,
"query": "select * from \"GUANDATA\".\"fengupsert02\" "
},
"token": "123"
}
直连数据集:
{
"acId": "x2ca2ec33088145d698d49bc",
"name": "直连",
"cron": {
"cronType": "DAILY",
"value": "{\"hours\":\"02\",\"minute\":\"00\"}"
},
"tableQuery": {
"queryType": "query",
"table": "GUANDATA.fengupsert02",
"query": "select * from GUANDATA.fengupsert02"
},
"parentDirId": "u48b02a7c87d74b759782be2",
"sourceType": "DIRECT_CONNECT_DATABASE",
"realTimeUpdateSetting": {
"enabled": true,
"interval": 60,
"disableCache": false
},
"token": "123"
}
Response Sample
创建成功:
{
"result": "ok",
"response": {
"taskId": "fd5ec840-c375-11ec-a026-253acbe209d8",
"status": "已提交",
"result": "处理中"
}
}
创建失败:
{
"result": "fail",
"response": null,
"error": {
"status": 1012,
"message": "数据集名称,在目标目录中已存在,请修改",
"detail": {
"notifyType": 1
}
}
}
3.8.4 获取数据账号ID操作示意
步骤一:使用Chrome浏览器登录观远数据BI,进入数据中心-数据账户模块,定位特定的数据账号。
步骤二:按F12键盘按键,后续操作步骤顺序如下图所示:
3.9 更新数据集字段注释
3.9.1 接口简介
请求方式:POST
请求地址:/public-api/data-source/:dsId/update-annotation
3.9.2 参数说明
参数名 | 参数值说明 | Location | 类型 | 是否必填 | 备注 |
token | 个人Token | Header | String | 是 | 调用登录API获取;请使用管理员账号或者数据集所有者做登录。 |
Content-Type | 内容类型 | Header | String | 是 | application/json |
dsId | 数据集ID | PATH | String | 是 | |
fdID | 字段ID | Body | Sring | 是 | 多个字段,以数组方式传递 |
annotation | 字段注释 | Body | String | 是 | 最多200个字符,超过会截取 |
3.9.3 请求与响应示例
POST Body Sample:
{
"columns": [
{
"fdId": "shhfkeks",
"annotation":"不含税销售额" // 设置注释, 可传可不传, 最多200个字符, 超过会截取
}
]
}
Response Sample:
状态为200表示修改成功