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/upload-dataset
8	数据集下载	GET /public-api/data-source/:dsId/token/:token
9	创建数据集	POST /public-api/data-source/create-from-account

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   //卡片数量
        },
        ……
    ]
}

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:

{
}

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
        },{

        }
        ]
    }

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": "所在文件夹的名称"}
  ],
  // 批量更新数据集配置
  "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 > '{{}}' ",
    "preClean": {
      "enabled": true,
      "rule": "`date`<'{{}}'"
    }
}

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 更新数据集（1040）

3.6.1 接口简介

请求方式：POST

请求地址：/public-api/upload-dataset

3.6.2 参数说明

参数名	参数值说明	Location	类型	是否必填	备注
Content-Type	内容类型	Header	String	是	--
X-Auth-Token	个人Token	Header	String	是	登录token，从sign in接口获取

3.6.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 数据上传

3.7.1 用户名密码方式登录获取合法Token

3.7.1.1 接口简介

请求方式：GET

请求地址：/public-api/sign-in

3.7.1.2 参数说明

参数名	参数值说明	Location	类型	是否必填	备注
Content-Type	内容类型	Header	String	是	--
domain	域名	Body	String	是	在观远系统中的域名，非网址的域名
email	登录的邮箱	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 上传数据

3.7.2.1 接口简介

请求方式：POST

请求地址：/public-api/upload-dataset

3.7.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.7.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.8 下载数据集数据

接口返回数据上限5W行

3.8.1 获取数据集下载授权Token (1041)

3.8.1.1 接口简介

请求方式：GET

请求地址：/api/data-source//data-fetch-token?action=

3.8.1.2 参数说明

参数名	参数值说明	Location	类型	是否必填	备注
token	个人Token	Header	String	是	调用登录API获取
Content-Type	内容类型	Header	String	是
dsId	数据集ID	Body	String	是	授权的目标数据集ID，在Web端打开对应的数据集，可以在地址栏里获取，为长度为24的字符串
action	授权动作	Body	String	否	缺省：如果数据集已经被授权则返回已有token，否则创建新token；reset：更新数据集已有授权token，返回新token；disable：授权被清除

您可以使用以上接口调用的方式获得数据集授权token。由于该token是长期有效的，很多时候你可能并不需要在程序里反复获取，因此也可以在浏览器端登录系统后，输入以上接口地址获得授权token，并将token固化在您获取数据的程序内。鉴于授权token是长期有效的，请注意数据安全，妥善保管。若发生token泄露，可调用以上接口，将action设置为reset进行重置。

3.8.1.3 请求与响应示例

Response Sample:

{
 "dataFetchToken":"guanyuan_data_fetch_token"
}

3.8.2 下载数据集数据 (1042)

3.8.2.1 接口简介

请求方式：POST

请求地址：/public-api/data-source//token/

3.8.2.2 参数说明

参数名	参数值说明	Location	类型	是否必填	备注
dsId	数据集ID	Path	String	是	目标数据集ID
token	授权token	Path	String	是	用于数据获取的token，即为当前文档 8.1 接口返回的dataFetchToken
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 startswith, not_startswith, endswith, not_endswith, contains, not_contains,is_null, not_null< />pan>

3.8.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.9 创建数据集

支持基于数据账号创建数据库相关直连数据集和抽取（Guan-Index）数据集。

3.9.1 接口简介

请求方式：POST

请求地址：/public-api/data-source/create-from-account

3.9.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.9.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.9.4 获取数据账号ID操作示意

步骤一：使用Chrome浏览器登录观远数据BI，进入数据中心-数据账户模块，定位特定的数据账号。
观远数据帮助中心创建数据集插图3.9.png

步骤二：按F12键盘按键，后续操作步骤顺序如下图所示：