跳到主要内容
版本:5.9.0

数据集相关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应用TokenBodyString在观远平台中获得

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。  

image.png

3.2 搜索数据集列表(1034)

3.2.1 接口简介

请求方式: POST

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

3.2.2 参数说明

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

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

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内容类型HeaderString--
domain域名BodyString在观远系统中的域名,非网址的域名
email登录的邮箱BodyString如果开启了账号登录模式则该参数不传,传loginId和对应的内容
password密码BodyString原始密码经过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内容类型HeaderString
X-Auth-Token登录用的TokenHeaderString调用登录API获取
tableName数据集名称BodyString
dsId数据集IDBodyString若tableName有重名可以指定dsId
overwriteExistingData是否覆盖原始数据BodyBoolean默认为false,即追加数据
columns设置上传数据集各列属性BodyJSONname:列名 type:字段类型 isPrimaryKey:是否是主键
allColumnsSpecified是否选择所有列BodyBoolean
data待上传的数据BodyJSON
displayType标识的格式BodyString
batchFinish是否最后一批BodyBooleanbatchFinish 设为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内容类型HeaderString--
domain域名BodyString在观远系统中的域名,非网址的域名
email登录的邮箱BodyString如果开启了账号登录模式则该参数不传,传loginId和对应的内容
password密码BodyString原始密码经过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数据集IDPathString目标数据集ID
token授权tokenPathString调用登录API获取;请使用管理员账号或者数据集所有者做登录。
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

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数据账号IDString必填必填具体获取方式请查看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应用TokenString必填必填具体内容请查看《Token 鉴权》

以上参数均在BODY中传递。

参数详情补充说明:

cron:

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

参数名参数值说明类型
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 代表去重列名。

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,进入数据中心-数据账户模块,定位特定的数据账号。观远数据帮助中心创建数据集插图3.9.png

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

image.png

3.9 更新数据集字段注释

3.9.1 接口简介

请求方式:POST

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

3.9.2 参数说明

参数名参数值说明Location类型是否必填备注
token个人TokenHeaderString调用登录API获取;请使用管理员账号或者数据集所有者做登录。
Content-Type内容类型HeaderStringapplication/json
dsId数据集IDPATHString
fdID字段IDBodySring多个字段,以数组方式传递
annotation字段注释BodyString最多200个字符,超过会截取

3.9.3 请求与响应示例

POST Body Sample: 

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

Response Sample:

状态为200表示修改成功