观远 BI

数据集相关API

创建于 2022-10-28 / 最近更新于 2024-08-29 / 18796
字体: [默认] [大] [更大]

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应用TokenBodyString在观远平台中获得

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。  

image.png

3.2 搜索数据集列表(1034)

请求方式: POST

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

参数说明

参数名参数值说明Location类型是否必填备注
token应用TokenBodyString在观远平台中获得
q要搜索的数据集名称模糊词urlString
offset搜索结果的起始位置urlString默认值0
limit从起始位置取多少条urlString默认值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个人TokenheaderString登录token,从sign in接口获取
dsId数据集IdpathString

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应用TokenBodyString在观远平台中获得
propsInDetails数据集路径配置BodyJSON Object
--
settingsInDetails数据集其他参数配置(如更新时间,更新方式)BodyJSON 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应用TokenBodyString在观远平台中获得

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内容类型HeaderString--
domain域名BodyString在观远系统中的域名,非网址的域名
email登录的邮箱BodyString如果开启了账号登录模式则该参数不传,传loginId和对应的内容
password密码BodyString原始密码经过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个人TokenHeaderString调用登录API获取
Content-Type内容类型HeaderString
dsId数据集IDBodyString授权的目标数据集ID,在Web端打开对应的数据集,可以在地址栏里获取,为长度为24的字符串
action授权动作BodyString缺省:如果数据集已经被授权则返回已有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数据集IDPathString目标数据集ID
token授权tokenPathString用于数据获取的token,即为当前文档 3.7.1 接口返回的dataFetchToken
cols需获取的列BodyArray指定欲获取的列
filters过滤条件BodyJSON指定过滤条件,包括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数据账号IDString必填必填具体获取方式请查看本章节-第四小节的获取数据账号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应用TokenString必填必填具体内容请查看《Token 鉴权》

以上参数均在BODY中传递。

参数详情补充说明:

cron:

参数名参数值说明类型
cronTypeCron表达式类型String
ValueCron表达式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:

参数名参数值说明类型
queryTypeSQL查询类型,本接口固定传参为“query”String
query创建数据集所使用的SQL语句String
table数据集所使用表的表名String

realTimeUpdateSetting:

参数名参数值说明
enabled是否开启支持实时卡片数据Boolean
interval目前固定为600Int
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,进入数据中心-数据账户模块,定位特定的数据账号。
image.png

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

image.png


3.9 更新数据集字段注释

接口简介

请求方式:POST

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

参数说明

参数名

参数值说明Location类型是否必填备注
X-Auth-Token个人TokenHeaderString

调用登录API获取

请使用管理员账号或者数据集所有者做登录。

Content-Type

内容类型HeaderStringapplication/json
dsId数据集IDPATHString
fdID字段IDBodySring多个字段,以数组方式传递
annotation字段注释BodyString最多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个人TokenHeaderString

调用登录API获取;

请使用管理员账号或者数据集所有者做登录。

Content-Type内容类型HeaderStringapplication/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": {}
}

7 人点赞过