数据集相关API

1. 数据集相关API 概述

数据集相关的 Public API，是指观远数据为在进行系统集成时可以针对数据集进行相关操作，而提供的标准化开放接口。

观远数据提供一套简便的验证机制，来供私有化部署用户进行外部系统和账户对接集成，实现集中、高效、便利的管理。本文将为您详细介绍观远数据为您提供的与数据集相关的 Public API。

2. 数据集相关API 列表速览

目前，与数据集相关的 Public API 共包含13个，列表如下：

序号	接口描述	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	数据集下载	GET /api/data-source/{dsId}/data-fetch-token?action={action}
8	创建数据集	POST /public-api/data-source/create-from-account
9	更新数据集字段注释	POST /public-api/data-source/:dsId/update-annotation
10	触发数据集读取数据文件并更新	GET /public-api/data-source/refresh-with-file
11	通过 TaskID 查询数据集更新结果	GET /public-api/task/status
12	修改数据集schema	POST /public-api/data-source/edit-schema/:dsId
13	更新数据集	POST /public-api/data-source/{dsId}/refresh

3. 数据集相关API 具体说明

3.1 获取数据集列表 （1032）

接口简介

请求方式： POST

请求地址：POST /public-api/data-source/list

参数说明

参数名	参数值说明	Location	类型	是否必填	备注
token	应用Token	Body	String	是	在观远平台中获得

请求与响应示例

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）

接口简介

请求方式： POST

请求地址：POST /public-api/data-source/search?q=xx&&offset=0&&limit=10

参数说明

参数名	参数值说明	Location	类型	是否必填	备注
token	应用Token	Body	String	是	在观远平台中获得
q	要搜索的数据集名称模糊词	url	String	是
offset	搜索结果的起始位置	url	String	否	默认值0
limit	从起始位置取多少条	url	String	否	默认值0

请求与响应示例

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）

接口简介

请求方式：POST

请求地址：/public-api/data-source/dsId/columns

参数说明

参数名	参数值说明	Location	类型	是否必填	备注
X-Auth-Token	个人Token	header	String	是	登录token，从sign in接口获取
dsId	数据集Id	path	String	是

请求与响应示例

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)

接口简介

请求方式：POST

请求地址：/public-api/data-source/update-setting

参数说明

参数名	参数值说明	Location	类型	是否必填	备注
token	应用Token	Body	String	是	在观远平台中获得
propsInDetails	数据集路径配置	Body	JSON Object		--
settingsInDetails	数据集其他参数配置（如更新时间，更新方式）	Body	JSON Object		--

目前仅支持批量更新数据集的文件夹路径或者数据集的属性更新，如果只需要更新路径位置，则只传递 propsInDetails 参数即可。

propsInDetails 和 settingsInDetails 的更新互不影响，即前者更新失败，后者还是会继续执行更新，除非两个都失败则返回前者的报错。

请求与响应示例

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）

接口简介

请求方式：POST

请求地址：/public-api/data-source/:dsId/get-readable-owners

参数说明

参数名	参数值说明	Location	类型	是否必填	备注
token	应用Token	Body	String	是	在观远平台中获得

请求与响应示例

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

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

接口简介

请求方式：POST

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

参数说明

参数名	参数值说明	Location	类型	是否必填	备注
Content-Type	内容类型	Header	String	是	--
domain	域名	Body	String	是	在观远系统中的域名，非网址的域名
email	登录的邮箱	Body	String	是	如果开启了账号登录模式则该参数不传，传loginId和对应的内容
password	密码	Body	String	是	原始密码经过Base64编码后的字符串

请求与响应示例

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"
}
}

上传数据

接口简介

请求方式：POST

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

参数说明

参数名	参数值	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	设置上传数据集各列属性，支持传入alias字段别名	Body	JSON		name：列名 type：字段类型 isPrimaryKey：是否是主键
allColumnsSpecified	是否选择所有列	Body	Boolean
data	待上传的数据	Body	JSON	是
displayType	标识的格式	Body	String
batchFinish	是否最后一批	Body	Boolean		batchFinish 设为true会更新该数据集，注意不要频繁更新数据集。
parentDirId	文件夹路径指定，传入后，在该路径下创建数据集

请求与响应示例

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行.

接口简介（获取数据集下载授权Token）

请求方式：GET

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

参数名	参数值说明	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进行重置。

请求与响应示例

Response Sample:

{
	"dataFetchToken":"guanyuan_data_fetch_token"
}

接口简介（下载数据集数据接口 ）

请求方式：POST

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

参数说明：

参数名	参数值说明	Location	类型	是否必填	备注
dsId	数据集ID	Path	String	是	目标数据集ID
token	授权token	Path	String	是	用于数据获取的token，即为当前文档 3.7.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 IN LIST), STARTSWITH, NOT_STARTSWITH, ENDSWITH, NOT_ENDSWITH, CONTAINS, NOT_CONTAINS,IS_NULL, NOT_NULL

请求与响应示例

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"
      ],
      
    ]
  }
}

接口简介（获取token）

请求方式：POST

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

参数说明：

参数名	参数值说明	Location	类型	是否必填	备注
Content-Type	内容类型	Header	String	是	--
domain	域名	Body	String	是	在观远系统中的域名，非网址的域名
email	登录的邮箱	Body	String	是	如果开启了账号登录模式则该参数不传，传loginId和对应的内容
password	密码	Body	String	是	原始密码经过Base64编码后的字符串

请求与响应示例

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"
}
}

接口简介(增强接口)

请求方式：POST

请求地址：public-api/data-source/dsid/data//注：5.10.0版本以上BI开始支持该接口

参数说明：

参数名	参数值说明	Location	类型	是否必填	备注
dsId	数据集ID	Path	String	是	目标数据集ID
Content-Type	内容类型	Header	String	是	application/json
X-Auth-Token	个人Token	Header	String	是	调用登录API获取（3.7.5文档）；请使用管理员账号或者数据集所有者做登录。
filter	过滤条件	Body	JSON	否	指定过滤条件，包括name，filterType，filterValue name：过滤的列名； filterType：过滤类型；filterValue：过滤值
offset	从第几条开始	Body	String	否	从第几条开始进行查询
limit	一页显示多少条	Body	String	否	每页最多查询多少条

说明：

• 该api一次最多返回5万行数据，若数据集较大，请指定过滤条件。

其中，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

请求与响应示例

Response Sample:

{
  "offset": 0,		# 从第几条开始
  "limit": 1000,	# 一页显示多少条
  "filter": {			 # 过滤条件
    "combineType": "AND",				
    "conditions": [
      {
        "type": "condition",
        "value": {
          "name": "id",        # 字段名
          "filterType": "GT",		# 上面文档列出的 filterType
          "filterValue": [				# 字段值
            "3"
          ]
        }
      },
      {
        "type": "condition",
        "value": {
          "name": "id",
          "filterType": "LT",
          "filterValue": [
            "11"
          ]
        }
      }
    ]
  },
  "sortFactor": {	 # 排序条件
    "name": "id",
    "sortType": "asc"
  }
}

• BODY内所有参数均为可选参数

Response Sample:

{  
    "result": "ok",          # 接口被正确处理, 并且参数没有问题的标识
    "response": {
        "dsId": "b9e36c76dd8274972be0a360",		# 数据集的id
        "name": "xjd-x3",				# 数据集的名称
        "displayType": "MYSQL",				# 数据集的类型
        "storageId": "b9e36c76dd8274972be0a360",
        "domId": "demo",           # 域
        "uId": "h9aaad4c93bc1496891321e7",
        "parentDirId": "fc859e2e7483343e4a25cfd0",
        "cnId": "mysql",                    
        "acId": "neae90286a9244c8592077c6",
        "rowCount": 3,
        "colCount": 5,
        "status": "FINISHED",					# 数据集的状态
        "columns": [             # 字段类型, 用来解析字段用的
            {
                "name": "id",						# 字段名称
                "fdType": "LONG",        # 字段的类型
                "dsId": "b9e36c76dd8274972be0a360",
                "fdId": "n9535760205c44cd6a2a98d3",		# 字段id
                "metaType": "METRIC",
                "seqNo": 0,
                "isAggregated": false,
                "calculationType": "normal",
                "level": "dataset",
                "annotation": "33",
                "isDetectionSensitive": false,
                "isSensitive": false,
                "isRestricted": false
            },
            {
                "name": "name",					# 字段名称
                "fdType": "STRING",			# 字段的类型
                "dsId": "b9e36c76dd8274972be0a360",
                "fdId": "b9df4c8050c53469bbcb006b",
                "metaType": "DIM",
                "seqNo": 1,
                "isAggregated": false,
                "calculationType": "normal",
                "level": "dataset",
                "annotation": "用户名22233",
                "isDetectionSensitive": false,
                "isSensitive": false,
                "isRestricted": false
            },
            {
                "name": "cardNo",
                "fdType": "STRING",
                "alias": "cardNo",
                "dsId": "b9e36c76dd8274972be0a360",
                "fdId": "u11b6578310694df2b8c1769",
                "metaType": "DIM",
                "seqNo": 2,
                "isAggregated": false,
                "calculationType": "normal",
                "level": "dataset",
                "annotation": "银行卡号111333",
                "isDetectionSensitive": false,
                "isSensitive": false,
                "isRestricted": false
            },
            {
                "name": "abc",
                "fdType": "LONG",
                "dsId": "b9e36c76dd8274972be0a360",
                "fdId": "f3f16ea99d65c435e8f364f1",
                "metaType": "METRIC",
                "seqNo": 3,
                "isAggregated": false,
                "calculationType": "normal",
                "level": "dataset",
                "annotation": "dasdas",
                "isDetectionSensitive": false,
                "isSensitive": false,
                "isRestricted": false
            },
            {
                "name": "xxx",
                "fdType": "STRING",
                "dsId": "b9e36c76dd8274972be0a360",
                "fdId": "jf3d4d1ead71f4a2db1ed712",
                "metaType": "DIM",
                "seqNo": 4,
                "formula": "[name]",
                "isAggregated": false,
                "calculationType": "normal",
                "level": "dataset",
                "annotation": "",
                "isDetectionSensitive": false,
                "isSensitive": false,
                "isRestricted": false
            }
        ],
        "ctime": "2023-06-12 15:37:24+0800",
        "utime": "2023-06-20 11:59:27+0800",
        "version": 1,					# 数据集的版本, 更新会加1
        "cardCount": 0,
        "preview": [				# 数据集的数据, 解析的时候要按照上面的columns去解析
            [
                "6",
                "6",
                "6",
                "3",
                "6"
            ],
            [
                "7",
                "7",
                "6",
                "1",
                "7"
            ],
            [
                "8",
                "8",
                "8",
                "8",
                "8"
            ]
        ]
    }
}

3.8 创建数据集

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

接口简介

请求方式：POST

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

参数说明

参数名	参数值说明	类型	直连数据集是否必填	抽取数据集是否必填	备注
acId	数据账号ID	String	必填	必填	具体获取方式请查看本章节-第四小节的获取数据账号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 示例：

如果不想填写cron，可以直接填写值为null；要是写了列表里写了crontype，就必须有value；具体可参考如下示例

"cron":null
{
	 "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 代表去重列名。

请求与响应示例

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":"282fec60-773-11ee-8b8b-2d9ac24c8af5",
    "status":"已提交",
    "result":"处理中",
    "dsId":"o37d5f9b5975544a188e6e08"
  }
}

创建失败：

{
    "result": "fail",
    "response": null,
    "error": {
        "status": 1012,
        "message": "数据集名称，在目标目录中已存在，请修改",
        "detail": {
            "notifyType": 1
        }
    }
}

获取数据账号ID操作示意

步骤一：使用Chrome浏览器登录观远数据BI，进入数据中心-数据账户模块，定位特定的数据账号。

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

3.9 更新数据集字段注释

接口简介

请求方式：POST

请求地址：/public-api/data-source/:dsId/update-annotation

参数说明

参数名	参数值说明	Location	类型	是否必填	备注
X-Auth-Token	个人Token	Header	String	是	调用登录API获取；请使用管理员账号或者数据集所有者做登录。
Content-Type	内容类型	Header	String	是	application/json
dsId	数据集ID	PATH	String	是
fdID	字段ID	Body	Sring	是	多个字段，以数组方式传递
annotation	字段注释	Body	String	是	最多200个字符，超过会截取

请求与响应示例

POST Body Sample: 

{
    "columns": [
        {
                "fdId": "shhfkeks", 
                "annotation":"不含税销售额" // 设置注释, 可传可不传, 最多200个字符, 超过会截取
        }
    ]
}

Response Sample:

状态为200表示修改成功  

3.10  触发数据集读取数据文件并更新

核心步骤：

1. 参照下方说明，将数据文件拷贝至服务器指定位置

2. 调用API，更新特定数据集    

接口简介

请求方式：GET

请求地址：/public-api/data-source/refresh-with-file  

特别说明：

① 该接口为限时免费API接口。 不排除未来额外收费可能。

② 需要将具体的数据文件存放在服务器指定位置。

• 非 minio 环境 /home/guandata/data/guandata-store/upload_dataset/{dsid}  

• minio 环境 /home/guandata/data/minio/guandata-store/upload_dataset/{dsid}

③ 文件格式要求

• snappy压缩，写成文件组，不要写单个较大的文件

• 需对字段名中的如下特殊字符做转义处理：' ',  ',' ,  ';',  '{',  '}',  '(',  ')',  '\n',  '\t',  '=',  '.'。选用的转义字符为 '%' 故对'%' 也需要做转义。

④ 与 /public-api/data-source/:dsId/refresh-with-file 接口类似，区别在于那个接口是用个人token，当前接口是用应用token。

参数说明

参数名	参数值说明	Location	类型	是否必填	备注
token	应用Token	Header	String	是	在观远平台中获得 应用token
dsId	数据集ID	URL	String	是	数据集id
overwrite	是否覆盖历史数据	URL	Boolean	是	true 表示覆盖；false 表示新增。是否覆写
fileType	数据文件类型	URL	Option[String]	否	文件类型：PARQUET、DELTA_LAKE非必填，不填后端默认按PARQUET类型处理
preClean	支持用户传入SQL作为前置清理规则		Option[String]		前置清理规则
subDir	支持用户指定子文件夹目录，若为空，则默认按照原路径读取文件上传；若不为空，则读取原路径下的${subDir}文件夹读取文件上传。		Option[String]		若为空，则默认按照原路径读取文件上传若不为空，则读取原路径下的${subDir}文件夹读取文件上传

请求与响应示例

/public-api/data-source/refresh-with-file?dsId=j02bb460a9d6e433eb5d8f6c&overwrite=true&fileType=DELTA_LAKE  

Response Sample:

{
    "result": "ok",
    "response": {
        "taskId": "1c30f9f0-6d7f-11ee-8cc2-bd5513e186d5",
        "status": "已提交",
        "result": "处理中"
    }
}

请记录 taskID，用于查询数据更新结果（具体参考3.11所示接口）。 数据更新为异步模式，需要轮询导出结果。  

3.11 通过 TaskID 查询数据集更新结果

核心步骤：

1. 参照下方说明，将数据文件拷贝至服务器指定位置

2. 调用API，更新特定数据集    

接口简介

请求方式：GET

请求地址：/public-api/task/status

参数说明

参数名	参数值说明	Location	类型	是否必填	备注
token	应用Token	Header	String	是	在观远平台中获得
taskId	任务ID	URL	String	是	其他前置API返回的任务ID

请求与响应示例

Response Sample:

{
    "result": "ok",
    "response": {
        "taskId": "1c30f9f0-6d7f-11ee-8cc2-bd5513e186d5",
        "status": "FINISHED",
        "result": {
            "status": "FINISHED",
            "rowCount": 15
        },
        "startTime": "2023-10-18T14:25:19.000+08:00",
        "submitTime": "2023-10-18T14:25:19.000+08:00",
        "finishedTime": "2023-10-18T14:25:26.000+08:00",
        "endTime": "2023-10-18T14:25:27.000+08:00",
        "runningDuration": 7,
        "queueingDuration": 0
    }
}

如果任务执行完成，则 response.status 为 FINISHED，如果更新成功，则 response.result.status 为 FINISHED。

3.12. 修改数据集schema

支持数据集类型

API_WORKBENCH	Workbench
GUAN_INDEX	抽取数据集（数据库数据集、账户数据集、在线文档等）
WEB_UPLOAD	文件数据集
WEB_SERVICE	WEB_SERVICE直连数据集
ACCOUNT_DS
PROCEDURE	存储过程

支持的字段类型

INT, DOUBLE, STRING, TIMESTAMP, LONG, SHORT, FLOAT, DATE, BOOL

接口简介

请求方式：POST

请求地址：/public-api/data-source/edit-schema/:dsId

参数说明

请求头

参数名	参数值说明	Location	类型	是否必填	备注
X-Auth-Token	个人Token	Header	String	是	调用登录API获取；请使用管理员账号或者数据集所有者做登录。
Content-Type	内容类型	Header	String	是	application/json

请求体

{
    "domId":"demo",
    "cols":[
        {
            "name":"field1",
            "fieldType":"int",
            "operate":"add"
        },
        {
            "name":"field2",
            "operate":"delete"
        },
        {
            "name":"field3",
            "newName":"field3_1",
            "fieldType":"int",
            "operate":"modify"
        },
        {
            "name":"field4",
            "fieldType":"string",
            "operate":"modify"
        }
    ]
}

domId：即数据集域id

cols：修改的字段信息

name：字段名称

operate：枚举值，add、delete、modify，分别代表新增、删除、修改

fieldType：字段类型

newName：字段新名称

请求与响应示例

columns是字段信息

 Response Sample:

200

{"result":"ok","response":"success"}

 错误的情况

新增字段已存在等错误，error_description

{
    "result":"fail",
    "response":null,
    "error":{
        "status":5001,
        "message":"调用接口失败 : ERRORMESSAGE.METHOD_POST : /public-api/data-source/edit-schema/n4fccf81d9586460596f88dd",
        "detail":{
            "error_description":"add fileName: a1 exists, fail!"
        }
    }
}

没有权限

当传的用户token没有权限查看数据集的时候会显示这个

{
    "result": "fail",
    "response": null,
    "error": {
        "status": 1004,
        "message": "无权访问",
        "detail": {
            "notifyType": 1
        }
    }
}

未登录

{
    "result":"fail",
    "response":null,
    "error":{
        "status":1018,
        "message":"Not Login or token expired",
        "detail":{
            "notifyType":0
        }
    }
}

3.13 更新数据集

接口简介

请求方式：POST

请求地址：/public-api/data-source/{dsId}/refresh

参数说明

参数名	参数值说明	Location	类型	是否必填	备注
X-Auth-Token	个人 Token	header	String	是	登录 token，从sign in接口获取
dsId	数据集 Id	path	String	是
overwriteExistingData	是否覆盖原始数据	Body	Boolean		默认为 true，即覆盖数据
query	数据集所使用的 SQL语句	Body	String		默认使用创建时的 SQL

请求与响应示例

POST Body Sample:

{
  query: "select * from aaa",
  overwriteExistingData: true
}

Response Sample:

{    
  "response": true 
}

3.14 修改数据集字段别名

接口简介

请求方式：POST

请求地址：/public-api/data-source/:dsId/update-field-alias

注意：ETL输出、卡片、视图、账户 不允许改别名。

参数说明

header参数：

字段	类型	备注
X-Auth-Token	String	个人token

body参数：

字段	类型	备注
columns	Seq[Column]
Column
fdId	String	必填，字段id
alias	Option[String]	选填 不传：不改变原有别名 传空字符串：去除原有别名 传正常字符传：正常设置别名

请求与响应示例

示例：

{
    "result": "ok",
    "response": {}
}