仪表板相关API

1. 仪表板相关API 概述

Public API，是指观远数据为系统集成提供的标准化开放接口。系统集成，通常是指将各个分离的设备(如个人电脑)、系统、功能和信息等集成到相互关联的、统一和协调的系统之中，使资源达到充分共享，实现集中、高效、便利的管理。系统集成实现的关键在于解决系统之间的互连和互操作性问题，是一个多厂商、多协议和面向各种应用的体系结构。

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

2. 仪表板相关API 列表速览

目前，与仪表板相关的 Public API 共包含6个，列表如下：

序号	接口描述	PATH
1	获取页面列表	POST /public-api/page/list
2	搜索页面	POST /public-api/page/search?q=xx&&offset=0&&limit=10
3	获取指定页面有读权限的用户列表	POST /public-api/page/:pgId/get-readable-owners
4	以树状结构获取页面列表	POST /public-api/page-tree?pgType=:pgType
5	以PDF或者图片模式导出仪表板	POST /public-api/page/export
6	获取仪表板导出文件	POST /public-api/file/download

3. 仪表板相关API 具体说明

特别说明：当前文档中的页面与仪表板含义基本一致。 页面包含仪表板与数据大屏两大类型。

3.1 获取页面列表

3.1.1 接口简介

请求方式： POST

请求地址：/public-api/page/list

3.1.2 参数说明

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

3.1.3 请求与响应示例

POST Body Sample:

{
  "token":"a430012ed74b342ef90b7275",
}

Response Sample:

{
    "result": "ok",
    "response": [
        {
            "pgId": "0ac483ab81b54ce184157100",
            "domId": "demo",
            "name": "集团总览",
            "uId": "d9f1ec1b629946b2b00f1d60",  // 页面创建者
            "pgType": "PAGE",        //页面类型："OVERVIEW"（概览）、"PAGE"（普通页面）、 "LARGE_SCREEN"(数据大屏)
            "parentDirId": "rc135f11b39a842d8b5475d4"    //页面所属文件夹ID
        },
        ……
    ]
}

3.2 根据页面名称关键词搜索页面

3.2.1 接口简介

请求方式：POST

请求地址：/public-api/page/search?q=:q&&offset=:offset&&limit=:limit

3.2.2 参数说明

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

3.2.3 请求与响应示例

POST Body Sample:

{
  "token":"a430012ed74b342ef90b7275",
}

Response Sample:

'{
    "result": "ok",
    "response": {
      "total": 6,
      "offset": 0,
      "limit": 10,
      "list": [
        {
            "pgId": "0ac483ab81b54ce184157100",
            "domId": "demo",
            "name": "集团总览",
            "uId": "d9f1ec1b629946b2b00f1d60",  // 页面创建者
            "pgType": "PAGE",        //页面类型："OVERVIEW"（概览）、"PAGE"（普通页面）、 "LARGE_SCREEN"(数据大屏)
            "parentDirId": "rc135f11b39a842d8b5475d4"，    //页面所属文件夹ID
            "meta": {
                    "authorizedOnMobile": false,//是否发布在移动端
                    "authorizedOnPC": true //是否发布在桌面
                }
        },
        ……
    ]
    }
}

3.3 获取指定页面有读权限的用户列表

3.3.1 接口简介

请求方式：POST

请求地址：/public-api/page/:pgId/get-readable-owners

3.3.2 参数说明

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

3.3.3 请求与响应示例

POST Body Sample:

{
  "token":"a430012ed74b342ef90b7275",
}

Response Sample:

{
    "result": "ok",
    "response": {
        "ownerUsers": [
            {
                "name": "zhangsan",
                "id": "h9aaad4c93bc1496891321e7",
                "email": "zhangsan@guandata.com",
                "loginId": "zhangsan"
            },
            ……
        ],
        "ownerGroups": [
            {
                "name": "zln34",
                "id": "m62d41e027dfb4e10a4b4a80"
            },
            ……
            ],
        "readableUsers": [
            ……
        ],
        "readableGroups": [
            ……
        ]
    }
}

3.4 以树状结构获取页面列表

3.4.1 接口简介

请求方式：POST

请求地址：/public-api/page-tree?pgType=:pgType

3.4.2 参数说明

参数名	参数值说明	Location	类型	是否必填	备注
token	应用Token	Body	String	是	在观远平台中获得
pgType	页面类型	URL	String	是	普通页面：PAGE;大屏页面：LARGE_SCREEN

3.4.3 请求与响应示例

POST Body Sample:

{
  "token":"a430012ed74b342ef90b7275",
}

Response Sample:

{
  "result": "ok",
  "response": {
    "id": "q40e0658fdc284e2aaa07f34",
    "parentDirId": "",
    "name": "根目录",
    "contents": [
      {
        "id": "rb0dae7523f4d464ab84f819",
        "parentDirId": "hfc8e4cb8e7e242b98d957d2",
        "name": "123_副本",
        "isPage": true,
        "ctime": "2022-04-29T11:44:21.00Z",
        "pgType": "LARGE_SCREEN"
      }
    ],
    "isPage": false, // false表示文件夹
    "ctime": "2020-01-10T13:49:36.00Z"
  }
}        

3.5 以PDF或者图片模式导出仪表板

3.5.1 接口简介

请求方式：POST

请求地址：/public-api/page/export

特别说明：① 该接口为限时免费API接口。 不排除未来额外收费可能。 ② 6.0 仅支持导出PC视图的图片与PDF。

3.5.2 参数说明

参数名	参数值说明	Location	类型	是否必填	备注
token	应用Token	Body	String	是	在观远平台中获得
pgld	页面ID	Body	String	是	页面的ID
selectorValues	筛选器值组	Body	JSON 数组	否	selectorId 筛选器ID； defaultValue：筛选器值，支持多个参数
loginId	账号	Body	String	否	如a@b.com; 如果uId也填写了，优先使用loginId
uId	用户ID	Body	String	否	系统中的ID，为一个字符串。如果LoginID与uId都不填写，则以管理员名义导出
orientation	导出模式	Body	String	是	分页模式填写 vertical  或者 horizontal ；单页模式填写导出宽度，如 1400 或者 1024
locale	语言偏好	Body	String	否	默认值zh-CN
exportType	导出类型	Body	String	否	支持PDF、IMAGE；默认PDF

如果指定了具体的用户信息，将以特定的用户名义（数据权限）导出PDF或者图片。

3.5.3 请求与响应示例

POST Body Sample:

{
    "pgId":"j02bb460a9d6e433eb5d8f6c",
    "selectorValues": [
        {
            "selectorId": "td591c7ed7b9e4f8fb95a94a",
            "defaultValue": [
                "1"
            ]
        }
    ],
    "loginId": "zhangshuaidong@guandata.com",
    "uId": "j02bb460a9d6e433eb5d8f6c",
    "token": "ebed0d48d04544349801f8de",
    "orientation": "vertical",
    "locale": "zh-CN",
    "exportType": "PDF"
}

Response Sample:

{
    "result": "ok",
    "response": {
        "taskId": "f2702d30-4bd1-11ee-adef-25b067ca21c9",
        "status": "已提交",
        "result": "处理中",
        "fileName": "j02bb460a9d6e433eb5d8f6c_dedfd07e3f72b4938a6a8eec.pdf"
    }
}

请记录 taskID，用于文件的获取（具体参考3.6所示接口）。文件导出为异步模式，需要轮询导出结果。  

3.6 获取仪表板导出文件

3.6.1 接口简介

请求方式：POST

请求地址：/public-api/file/download

3.6.2 参数说明

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

3.6.3 请求与响应示例

POST Body Sample:

{
  "token":"a430012ed74b342ef90b7275",
  "taskId": "333b60f0-4e25-11ee-85d0-0f5c5ff3eaf8",
}

Response Sample:

{
    "result": "fail",
    "response": null,
    "error": {
        "status": 40001,
        "message": "处理中",
        "detail": {
            "notifyType": 1
        }
    }
}

如果任务执行完成则会支持返回文件；如果没有顺利导出，任务结果为处理中状态。