API方式连接数据源

概述

Sugar上的图表和过滤条件数据可以由用户通过API的形式来提供。Sugar会在后端通过POST的方式访问用户的API,并在请求的body中带上查询条件,下钻参数等当前图表拉取数据时需要的信息。具体的请求情况可以在「图表的调试弹框」中查看。

用户的API可以根据这些信息来返回需要展示的数据。

API的返回数据要求都是 JSON 类型,格式如下:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {...} // 具体的数据
}

数据API的安全性

有以下的方式来保证数据的安全性:

API的token

Sugar上的所有数据请求都在Sugar的后端通过 curl 的方式访问用户的API,并且用户可以设置访问的 token,设置的 token 会作为查询参数附加在API请求的头文件Header中,格式为:Sugar-Token: yourToken。这样,您在自己写的API程序中通过验证请求Header中的Sugar-Token的正确如否来决定是否返回数据,从而保证只有Sugar的后端才能访问您的API。

token可以在编辑空间信息的时候设定(当然,只有管理员才能看见和修改):

图片

想要知道图表在通过API拉取数据时到底在请求头Header中加了哪些信息,可以点击「图表的调试按钮」来查看。

访问IP限制

如果您的API访问有IP白名单方式的限制(例如百度云、阿里云等厂商的云服务器都支持「安全组」这样的访问控制),需要给Sugar的机器IP进行授权,Sugar的机器IP列表可以「参见这里」。

API宏定义

在空间设置时,您可以自定义一些宏变量,这些宏定义可以嵌入到之后使用的API中,使用宏定义的目的是方便以后的API服务迁移,例如您的API从A域名变更到B域名,使用宏定义的话就会非常方便。宏定义必须是大写字母和下划线,如下设置宏定义:

图片

在使用API方式绑定图表数据时,就可以这样使用$API_HOST$API_CHART,注意必须使用$开头:

图片

点击上图中的「调试」按钮,就能看到宏定义被替换之后真正访问的url:

图片

URL中的额外参数

在报表或大屏的URL中,您可以加入额外自定义的查询参数。Sugar会将其放入图表或过滤条件数据API POST请求的body里。

例如,您的报表URL本来是:

图片

您可以在其中加入:「&table=users&column=name&year=2018」:

图片

在过滤条件以API方式拉取数据时,点击控制面板中的调试可以看到,这几个字段被放入querys中post到了您指定的后端数据API中:

图片

在图表以API方式拉取数据时,点击控制面板中的调试可以看到,这几个字段被放入querys中与查询条件的数据conditions一起post到了您指定的后端数据API中:

图片

图表API请求中的过滤条件参数

前面说过,Sugar上的图表数据可以由用户通过API的形式来提供,Sugar平台在访问这些API时,会将过滤条件作为POST请求的body传递给后端。所有过滤条件将会汇总在一起形成一个数组「conditions」,其格式如下:

conditions=[
	{
		t: 'date',          // 过滤条件的类型
		k: 'riqi',          // 用户配置的「查询key值」
		v: '2016-04-01'     // 当前过滤条件的取值,不同类型的过滤条件,格式会不一样,详见下面文档
	},
	{...},
	...
]

如果需要知道图表在通过API拉取数据时到底POST了什么过滤条件数据到后端,可以点击「图表的调试按钮」来查看。

或者在浏览器的Network里也可以看到请求的详情。例如某一个图表数据API的过滤条件参数可能是这样的:

图片

关于每种过滤条件在body中的具体形式请参考下一节。

过滤条件API格式

Sugar支持多种类型的过滤条件,本节列出了每种过滤条件在图表数据API的body中的详细格式。

有些过滤条件本身也支持通过API方式拉取数据,如下拉单选等。其需要的API返回格式也在这里一并列出。

日期

{
	t: 'date',                 // date 表示日期类型
	k: '「查询key值」'
	v: '2016-04-01'            // 单个日期
}

日期范围

{
	t: 'dateRange',             // daterange 表示日期范围类型
	k: '「查询key值」'
	v: '2016-03-15,2016-04-01'  // 开始和截至日期,中间用英文逗号隔开
}

时间

{
	t: 'dateTime',             // dateTime 表示时间类型
	k: '「查询key值」'
	v: '2016-07-06 14:17:00'  // 单个时间
}

时间范围

{
	t: 'dateTimeRange',             // dateTimeRange 表示时间范围类型
	k: '「查询key值」'
	v: '2016-07-06 14:19:00,2016-07-06 14:29:00'  // 开始和截止时间,中间用英文逗号隔开
}

输入框

{
	t: 'text',                 // text 表示输入框类型
	k: '「查询key值」'
	v: '用户输入的值'            // 用户输入的值
}

输入框suggestion

示例API:/openapi/demo/condition?type=suggestion

POST body:

{
	searchStr:  用户当前输入的字符串
}

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: [     // 输入了search内容后返回的提示信息列表
		'数据1',
		'数据',
		...
	]
}

suggestion拉取延迟

用户在输入文字时,停顿时间超过该设定的『suggestion拉取延迟』时,才会重新拉取suggestion的数据。

图片

单选列表/下拉单选

{
	t: 'select',                 // select 表示单选列表类型
	k: '「查询key值」'
	v: 'value1'                // 用户选中的值(是value字段,而不是展示用的name字段)
}

单选列表API数据格式

示例API:/openapi/demo/condition?type=select

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: [
		{
			label: 'name1',    // 展示使用的字段
			value: 'value1'   // 具体的取值
		},
		{
			label: 'name1',    // 展示使用的字段
			value: 'value1'   // 具体的取值
		},
		...
	]
}

多选列表/下拉多选

{
	t: 'multiSelect',                 // multiSelect 表示单选列表类型
	k: '「查询key值」'
	v: ["value1", "value2"]               // 用户选中的值(是value字段,而不是展示用的name字段,是一个字符串数组)
}

多选列表API数据格式

单选列表API数据格式完全一致。

树形选择

{
    t: '"treeSelect"',           // "treeSelect" 表示树形选择
    k: '「查询key值」'
    v: ["item1", "folder2", "folder4"]         // 选中的值,可单选可多选,多选时是value数组,单选时是value字符串
}

树形选择API数据格式

示例API:/openapi/demo/condition?type=tree

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: [
		{
			name: 'name1',    // 展示的节点名称
			value: 'value1'   // 具体的取值
			children: [
				{
					name: 'name1-1',
					value: 'value1-1',
					children: [...]
				},
				{
					name: 'name1-2',
					value: 'value1-2',
				}
			]
		},
		{
			name: 'name2',    // 展示使用的字段
			value: 'value2'   // 具体的取值
		},
		...
	]
}

多重逻辑

{
	t: 'logic',               // logic 表示多重逻辑类型
	k: '「查询key值」',
	v: {
    logic: 'notIn',         // 多重逻辑的逻辑类型
    vals: ['123', 'value']  // 具体取值数组,根据逻辑类型的不同,数组元素个数不同
  }     
}

多重逻辑用来实现复杂sql语句的拼凑(如:between、like、in、not in 等),展示形式如下:

图片

目前多重逻辑支持多种逻辑类型,其对应到上面的 「v字段」格式具体如下:

等于

v: {
  logic: '=',         
  vals: ['123']  
}    

当选项为等于时,可以配置suggestion数据API, 格式同 输入框的suggestion数据格式

大于

v: {
  logic: '>',         
  vals: ['123']  
}    

大于等于

v: {
  logic: '>=',         
  vals: ['123']  
}    

小于

v: {
  logic: '<',         
  vals: ['123']  
}    

小于等于

v: {
  logic: '<=',         
  vals: ['123']  
}    

不等于

v: {
  logic: '!=',         
  vals: ['123']  
}    

等于多个

v: {
  logic: 'in',         
  vals: ['123', 'value1', 'value2']  
}    

不等于多个

v: {
  logic: 'notIn',         
  vals: ['123', 'value1', 'value2']  
}    

范围

v: {
  logic: 'between',         
  vals: ['value1', 'value2']  
}    

模糊匹配

v: {
  logic: 'like',         
  vals: ['value1']  
}    

当选项为模糊匹配时,可以配置suggestion数据API, 格式同 输入框的suggestion数据格式

以它开头

v: {
  logic: 'begin',         
  vals: ['value1']  
}    

以它结尾

v: {
  logic: 'end',         
  vals: ['value1']  
}    

数值为 null

v: {
  logic: 'null',         
  vals: []  
}    

数值不为 null

v: {
  logic: 'notNull',         
  vals: []  
} 

多重逻辑API数据格式

单选列表API数据格式完全一致。

图表API请求中的下钻参数

有关图表如何配置下钻功能,详见图表的下钻设置

在绑定了图表的下钻功能之后,Sugar在请求下钻弹出图表的数据API时会额外附加上一些下钻的具体信息,这些信息和过滤条件一样放在API请求的body中。例如,一个饼图有三个扇形区域,点击每个扇形区域时,我们在拉取弹出图表的数据API时会加上drillDowns参数用来描述用户到底是点击了哪一区域。

drillDowns参数的格式如下, 由于Sugar支持多层下钻,因此drillDowns参数是个数组,数组的每项分别表示每级下钻的信息,在后端需要使用json_decode来解析:

drillDowns=[
	{ // 第一层下钻
		"item":{"name":"Android","value":40,"url":"http://www.baidu.com"},  // 当前点击区域的信息
		"chart":"pie"    // 点击的图形种类
	},
	{ // 第二层下钻
		"item":{"name":"访问量","value":17480134,"rate":23.34,"rate_level":"green"},
		"chart":"summary"
	},
	...
]

图表API请求中的联动参数

有关图表如何配置联动功能,详见图表的联动设置

如果图表被某个上级图表设置为了联动的下级图表,当上级图表触发联动时,Sugar在请求下级图表的数据API中会额外附加上一些联动的具体信息,这些信息和过滤条件一样放在API请求的body中。例如,如果上级图表是一个饼图,点击每个扇形区域时,我们在拉取下级图表的数据API时会加上dependence参数用来描述用户到底是点击了哪一区域。

dependence参数的格式如下:

"dependence": {
    "item": {
        "subsys": "北京总部",
        "module": "市场部",
        "business": "第一小分队",
        "name": "张三",
        "value": 6672389,
        "url": "http://www.baidu.com"
    },
    "fireKey": "name"
}
  • 联动参数是一个对象,由item和fireKey组成
  • item是一个对象,里面有触发联动相关的信息,比如触发联动的表格某行的数据。
  • fireKey是一个字符串,在某种图表可以触发多种联动的情况下用来区分触发的是哪一种联动

每种图表在触发联动时传递到下层图表的参数格式不尽相同,在图表的上级图表触发联动之后,您可以点击下级图表“控制面板”中的「图表的调试按钮」来查看上层图表传递下来的具体信息。

图表API的返回格式

Sugar中的每个图表可以对应一个数据API,用户浏览报表时,选定一定的过滤条件,点击「查询」按钮将会通过API拉取相应的数据;前面说过,为了确保用户数据的安全性,Sugar上的所有数据请求都在Sugar的后端通过 curl 的方式访问产品线的API,都是使用的POST请求,POST的数据是过滤条件: conditions,并且在请求的Header中会附加Sugar-Token.

Sugar支持多种类型的展示图表,每种类型的图表所需要的后端API返回的数据格式都有所区分,下面分别列举每种图表所对应的数据API格式:

表格

API示例:/openapi/demo/chart?type=table

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		columns:[   // 定义表格的各个列
			{
				name: '表头名1',    // 显示的表头
				id: 'key1',        // 该列绑定的数据字段名称
				unit: '',          // 单位,可以不传
				textAlign: 'left', // 列中文字的对其方式,left、right、center, 可不传
				autoWrap: true,    // 文字太多时是否自动换行
				width: '200px',    // 列宽度,可不传,默认为自适应,可传:100px、25%之类
				accuracy: '2',     // 数据是小数时,保留的位数(四舍五入,不够位数会补零),可不传
				remark: '字段说明'  // 对该列的备注说明,一般不需要配置,配置后会在该列的表头上展示一个小问号(鼠标悬停时展示该备注的具体信息)
			},
			{
				name: '表头名2',    // 显示的表头
				id: 'key2',        // 该列绑定的数据字段名称
				unit: '%',         // 单位,可以不传
				textAlign: 'left', // 列中文字的对其方式,left、right、center, 可不传
				autoWrap: false,   // 文字太多时是否自动换行
				width: '',         // 列宽度,可不传,默认为自适应,可传:100px、25%之类
				accuracy: '2',     // 数据是小数时,保留的位数(四舍五入,不够位数会补零),可不传
				remark: '字段说明'  // 对该列的备注说明,一般不需要配置,配置后会在该列的表头上展示一个小问号(鼠标悬停时展示该备注的具体信息)
			},
			......
		],
		rows: [   // 表格各行的数据
			{
				key1: 12313, // key和columns中的id一一对应
				key2: '<button>本宝宝是个html</button>',
				key1_level: 'red', // 在字段名后加_level,表示展示时的字体颜色,可以是 red、green,当然可以不传,
				__showx_row_level: 'red', // 整行飘红或飘绿,优先级低于单个字段的飘红飘绿设定
				key2_ishtml: true, // 在字段名后加_ishtml,表示展示时以html内容进行解析,可以不传。
				key2_noPadding: true, // 在字段名后加_noPadding,表示展示时表格单元格内不加padding属性,使传入的dom占满单元格,可以不传。
				key2_background: '#ff6c00', // 在字段名后加_background,表示展示时表格单元格背景色,可以不传。
			},
			{
				key1: 12313, // key和columns中的id一一对应
				key2: 12312,
			},
			......
		],
		total: 99,       // total表示总行数,启动了后端分页时才需要传递total字段
		superHeaders: [  // 超级表头, 比如想对表头做一个分类或者使用2级表头多级表头等,就可以用到它,可不传
		    [      // 第一行超级表头
                [  // 第一行超级表头的具体每个item
                    'name': 'superHeader1',  // 名称
                    'colspan': 3 // 占3列
                ],
                [
                    'name': 'superHeader2',  //名称
                    'colspan': 2  // 占2列
                ],
                ...
            ],
            ...  // 后面可以加入多行行超级表头...
        ],
	}
}

表格分页

在控制面板中开启分页功能后,表格支持前后端分页。

图片

  • 前端分页:是将传过来的数据进行分页,切换页码时不会另外请求数据;

  • 后端分页:会在API的请求参数中加入 startlimit 参数,每次切换页码都会另外请求API,另外使用后端分页时返回的数据中需要含有 total 字段用来表示总行数:

    {
    	start: n, // 表示从第n行开始,n以0为起点
    	limit: x, // 每页多少行数据
    }

表格排序

在控制面板中开启排序功能后,表格支持前后端排序。

图片

  • 前端排序:是将传来的数据进行排序,排序时不会另外请求数据;

  • 后端排序:会在API的请求参数中加入 sortKeysortType 参数,每次排序都会另外请求API:

    {
    	sortKey:  'key',      // 即需要进行排序的列id
    	sortType: 'desc'      // asc、desc
    }

轮播表格

API示例:/openapi/demo/chart?type=tablePlay

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		columns:[   // 定义表格的各个列
			{
				name: '表头名1',    // 显示的表头
				id: 'key1',        // 该列绑定的数据字段名称
				unit: '',          // 单位,可以不传
				textAlign: 'left', // 列中文字的对其方式,left、right、center, 可不传
				autoWrap: true,    // 文字太多时是否自动换行
				width: '50',    	 // 列宽度,可不传,默认为均分,传50代表本列占总宽度50%
				accuracy: '2',     // 数据是小数时,保留的位数(四舍五入,不够位数会补零),可不传
				remark: '字段说明'  // 对该列的备注说明,一般不需要配置,配置后会在该列的表头上展示一个小问号(鼠标悬停时展示该备注的具体信息)
			},
			{
				name: '表头名2',    // 显示的表头
				id: 'key2',        // 该列绑定的数据字段名称
				unit: '%',         // 单位,可以不传
				textAlign: 'left', // 列中文字的对其方式,left、right、center, 可不传
				autoWrap: false,   // 文字太多时是否自动换行
				width: '',         // 列宽度,可不传,默认为均分,传50代表本列占总宽度50%
				accuracy: '2',     // 数据是小数时,保留的位数(四舍五入,不够位数会补零),可不传
				remark: '字段说明'  // 对该列的备注说明,一般不需要配置,配置后会在该列的表头上展示一个小问号(鼠标悬停时展示该备注的具体信息)
			},
			......
		],
		rows: [   // 表格各行的数据
			{
				key1: 12313, // key和columns中的id一一对应
				key2: '<button>本宝宝是个html</button>',
				key2_ishtml: true, // 在字段名后加_ishtml,表示展示时以html内容进行解析,可以不传。
				key2_background: '#ff6c00', // 在字段名后加_background,表示展示时表格单元格背景色,可以不传。
			},
			{
				key1: 12313, // key和columns中的id一一对应
				key2: 12312,
			},
			......
		]
	}
}

核心指标

API示例:/openapi/demo/chart?type=summary

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: [
    {
      name: "访问量",                   // 指标名称
      desc: '访问量是指页面被访问的次数',  // 指标描述,可不传
      unit: '',                        // 单位,可以不传
      value: 17480134,                 // 指标取值
      rate: 3.34,                      // 涨跌率,如果不需要也可不传
      rate_level: "green",             // 涨跌率字体展示的颜色,可以是green、red,可不传
      rate_tip: "周环比",               // 对涨跌率的说明,可不传
      rate2: 14.5,                     // 第二个涨跌率,如果不需要也可不传
      rate2_level: 'green',            // 第二个涨跌率字体展示的颜色,可以是green、red,可不传
      rate2_tip: '日环比'   ,           // 对第二个涨跌率的说明,可不传
      url: "http://www.baidu.com"      // 这个字段供超链接类型的下钻使用,在配置下钻时的「绑定超链接的数据字段」处填写url即可
    },
    ....
  ];
}

关于增长率这一项,Sugar 现支持2项不同的增长率,例如 日环比 和 周环比。用户不需要也可都不传,也可传一项内容。

折线图、柱状图

API示例:/openapi/demo/chart?type=line

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		categories: [    // x轴,下面以日期为例
			'2015-01-01',
			'2015-01-02',
			'2015-01-03',
			'2015-01-04',
			'2015-01-05',
			'2015-01-06',
			'2015-01-07',
			'2015-01-08'
		],
		series: [     // 用来展示的多条折线或柱状
			{
				name: '新增用户',
				data: [2334, 1214......] // 数组元素个数需要和categories一致
			},
			{
				name: '老用户',
				data: [2342, 1234......] // 数组元素个数需要和categories一致
				lineStyle: {	// 折线图时,这样配置可以将该条折线展示为虚线,不传该部分时就默认是实线
					type: 'dashed'
				}
			},
			......
		]
	}
}

象形柱状图

API示例:/openapi/demo/chart?type=barPic

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		categories: [    // x轴,下面以日期为例
			'2015-01-01',
			'2015-01-02',
			'2015-01-03',
			'2015-01-04',
			'2015-01-05',
			'2015-01-06',
			'2015-01-07',
			'2015-01-08'
		],
		series: [     // 象形柱状图只支持一个系列
			{
				name: '新增用户',
				data: [2334, 1214......] // 数组元素个数需要和categories一致
			}
		]
	}
}

3D柱状图

API示例:/openapi/demo/chart?type=bar3D

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		// x轴数据,字符串数组
		xCategories: ['苹果', '三星', '华为', 'oppo', 'vivo', '小米'],
		// y轴数据,字符串数组
		yCategories: ['2010', '2011', '2012', '2013', '2014', '2015'],
		// 每个系列柱体的数据,数组
    series: [
      {
				// 系列名称,字符串
				name: '上半年',
				// 系列数据,数组,原则上应该对应 xCategories,yCategories的所有组合
        data: [
					// 每项数据有三项,分别为:
					// X轴:应与 xCategories 内的数据对应
					// Y轴:应与 yCategories 内的数据对应
					// Z轴:应是数字或有效数字字符串
          ['苹果', '2010', 100087],
					['苹果', '2011', 100079],
					......
        ]
      },
      {
        name: '下半年',
        data: [
          ['苹果', '2010', 100079],
          ['苹果', '2011', 879],
          ......
        ]
			},
			......
    ]
	}
}

圆形柱状图

API示例:/openapi/demo/chart?type=barPolar

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		categories: [    // 径向轴取值,有多少个取值就有多少个柱子
			"魅族",
			"小米",
			"vivo",
			"oppo",
			"华为",
			"三星",
			"苹果"
		],
		"series": [
			{
				"data": [ // data里的数值代表柱子覆盖的角度,和上面的径向轴取值一一对应
					500,
					600,
					700,
					800,
					900,
					1000,
					1200
				]
			}
		]
	}
}

线柱混搭图

API示例:/openapi/demo/chart?type=lineBar

当然,其实您可以指定所有数据都是折线图,这样就可以实现双Y轴的折线图

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		categories: [    // x轴,下面以日期为例
			'2015-01-01',
			'2015-01-02',
			'2015-01-03',
			'2015-01-04',
			'2015-01-05',
			'2015-01-06',
			'2015-01-07',
			'2015-01-08'
		],
		series: [     // 用来展示的多条折线或柱状
			{
				name: '新增用户',
				type: "line 或 bar",  //表示折线或者柱状,如果不填则默认为折线
				yAxisIndex: 01, //0表示第一个Y轴, 1表示第2个Y轴, 也可不填,默认为第一个Y轴;如果有一个yAxisIndex为1则标示开启了双重Y轴,可以配置不同的单位以及数据级别不同
				data: [2334, 1214......] // 数组元素个数需要和categories一致
			},
			{
				name: '老用户',
				type: "line 或 bar",  //表示折线或者柱状,如果不填则默认为折线
				yAxisIndex: 01, //0表示第一个Y轴, 1表示第2个Y轴, 也可不填,默认为第一个Y轴;如果有一个yAxisIndex为1则标示开启了双重Y轴,可以配置不同的单位以及数据级别不同
				data: [2342, 1234......] // 数组元素个数需要和categories一致
			},
			......
		]
	}
}

饼图

API示例:/openapi/demo/chart?type=pie

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: [
		{
			name: 'chrome',
			value: 46,
			url: 'www.baidu.com' // 这个字段供超链接类型的下钻使用,在配置下钻时的「绑定超链接的数据字段」处填写url即可
		},
		{
			name: 'safari',
			value: 32,
			url: 'www.baidu.com'
		},
		{
			name: 'fireFox',
			value: 16,
			url: 'www.baidu.com'
		},
		......
	]
}

嵌套饼图

API示例:/openapi/demo/chart?type=pieNested

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: [ // 内层的饼图数据
      {
        name: 'chrome',
        value: 46
      },
      {
        name: 'ie',
        value: 32
      },
      {
        name: 'fireFox',
        value: 36
			},
			......
    ],
		[ // 外层的环形饼图数据
			// 注意外层子扇区的顺序需要与内层母扇区的顺序进行对应
			// 例如这里子扇区也是按照 chrome, ie, firefox 的顺序排列的
      {
        name: 'chrome49',
        value: 14
      },
      {
        name: 'chrome50',
        value: 32
      },
      {
        name: 'IE10',
        value: 10
      },
      {
        name: 'IE11',
        value: 22
      },
      {
        name: 'fireFox62',
        value: 20
      },
      {
        name: 'fireFox65',
        value: 6
			},
			......
    ]
}

仪表盘

API示例:/openapi/demo/chart?type=gauge

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		max: 100,      // 最大值,可不传,默认为100
		min: 0,        // 最小值,可不传,默认为0
		name: '完成率',
		unit: '%',     // 单位,可不传
		value: 89.1    // 具体取值
	}
}

地图

API示例:/openapi/demo/chart?type=map

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: [
		{
			name: '北京',
			value: 46,
			coord: [116.41989, 40.189913],	// 地点的经纬度,可不传,当地图展示类型是气泡或热力图时,用户可以自定义地点的经纬度,sugar系统只能自动匹配全国省份和城市的经纬度坐标
			url: 'www.baidu.com' // 这个字段供超链接类型的下钻使用,在配置下钻时的「绑定超链接的数据字段」处填写url即可
		},
		{
			name: '广东',
			value: 32,
			coord: [113.429877, 23.334664],	// 地点的经纬度,可不传,当地图展示类型是气泡或热力图时,用户可以自定义地点的经纬度,sugar系统只能自动匹配全国省份和城市的经纬度坐标
			url: 'www.baidu.com'
		},
		{
			name: '安徽',
			value: 16,
			url: 'www.baidu.com'
		},
		......
	]
}

雷达图

API示例:/openapi/demo/chart?type=radar

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		indicators:[
			{
				text: '顶点1',  // 顶点展示的文字
				max: 10,       // 该顶点的最大值
				min: 0         // 该顶点的最小值,可不传,默认为0
			},
			{
				text: '顶点2',  // 顶点展示的文字
				max: 20,       // 该顶点的最大值
				min: 5         // 该顶点的最小值,可不传,默认为0
			},
			{
				text: '顶点3',  // 顶点展示的文字
				max: 10,       // 该顶点的最大值
				min: 2         // 该顶点的最小值,可不传,默认为0
			},
			......
		],
		series:[
			{
				name: '预算开支',
				value: [8, 18, 9, ...] // 数组元素个数和indicators相同
			},
			{
				name: '实际开销',
				value: [9, 15, 7, ...] // 数组元素个数和indicators相同
			},
			......
		]
	}
}

漏斗图

API示例:/openapi/demo/chart?type=funnel

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		unit: '%',       // 单位,可以不传
		data: [
			{
				name: '首页',
				value: 12323,
				url: 'www.baidu.com' // 这个字段供超链接类型的下钻使用,在配置下钻时的「绑定超链接的数据字段」处填写url即可
			},
			{
				name: '首页->列表页',
				value: 23457,
				url: 'www.baidu.com'
			},
			{
				name: '首页->列表页->下单页',
				value: 23457,
				url: 'www.baidu.com'
			},
			......
		]
	}
}

字符云

API示例:/openapi/demo/chart?type=wordCloud

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: [
		{
			name: '热词1',
			value: 46,
			url: 'www.baidu.com' // 这个字段供超链接类型的下钻使用,在配置下钻时的「绑定超链接的数据字段」处填写url即可
		},
		{
			name: '热词2',
			value: 32,
			url: 'www.baidu.com'
		},
		{
			name: '热词3',
			value: 16,
			url: 'www.baidu.com'
		},
		{
			name: '热词4',
			value: 15,
			url: 'www.baidu.com'
		},
		......
	]
}

气泡图

API示例:/openapi/demo/chart?type=bubble

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: [
		{
			name: '热词1',
			value: 46,
			cat: "cat1",            // 气泡所属的类别,不同类别的气泡颜色不同,若不传,则用name作为气泡名称
			url: 'www.baidu.com' // 这个字段供超链接类型的下钻使用,在配置下钻时的「绑定超链接的数据字段」处填写url即可
		},
		{
			name: '热词2',
			value: 32,
			cat: "cat1",
			url: 'www.baidu.com'
		},
		{
			name: '热词3',
			value: 16,
			cat: "cat2",
			url: 'www.baidu.com'
		},
		{
			name: '热词4',
			value: 15,
			cat: "cat2",
			url: 'www.baidu.com'
		},
		......
	]
}

拓扑图

API示例:/openapi/demo/chart?type=topology

response:

{
	status: 0,
	msg: "",
	data: {
		nodes: [ //表示各个节点
			{
				id: 'node1',  //结点的id, 用于唯一标识1个节点,必传
				title: 'node1Title', //节点的标题,可不填,
				data: [       //节点主体的数据,可用数组表示,数组每一项会分行。
					'hello',
					'<button>world</button>'
				],  //data数据也可不填,但title和data最好保留至少1个, 当然数据也可以写为html的内容
				tooltip: 'hi, 我是tooltip' //字符串格式的tooltip
			},
			{
				id: 'node2',  //结点的id, 用于唯一标识1个节点,必传
				title: 'node2Title', //节点的标题,可不填
				data: 'hello, world', //data字段为字符串表示只占1行数据
				fontColor: '#ff0000', //自定义的字体颜色,可不传
				bgColor: 'bgColor', //自定义的背景颜色,可不传
				tooltip: ['hi', '我是tooltip'] //数组格式的tooltip
			},
			...
		],
		links: [
			{
				source: 'node1',  // 表示从id为`node1`的结点出发,必传
				target: 'node2',  // 表示到id为`node2`的结点结束,必传
				text: '15%',      // 折线上的数据,可不传
				tooltip: ['hi', '我是tooltip'] //数组格式的tooltip
			},
			{
				source: 'node1',  // 表示从id为`node1`的结点出发,必传
				target: 'node3',  // 表示到id为`node3`的结点结束,必传
				text: '15%',      // 折线上的数据,可不传
				tooltip: 'hi, 我是tooltip' //字符串格式的tooltip
			},
			...
		]
	}
}

散点图

API示例:/openapi/demo/chart?type=scatter

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	data: {
		series: [     // 用来展示的多系列数据,数据格式可以参考echarts的文档
			{
				name: '数据1',
				data: [
					{
						name: '点1',
						symbolSize: 31,   // 散点的大小
						value: [10, 20]   // X/Y轴的数值,X轴可以是日期字符串
					},
					......
				]
			},
			{
				name: '数据2',
				symbol: 'diamond', // 散点的形状,可参考echarts文档
				symbolSize: 20,    // 统一配置改系列所有点的大小
				data: [
					{
						name: '点1',
						value: [10, 30, 12, 23] // 散点图的数据支持多维,这里有四维的数据,另外两个维度将通过鼠标hover点时出现的tooltip中展示
					},
					......
				]
			},
			......
    ],
    target: ['X指标', 'Y指标', '指标3', '指标4'] // 展示多维数据的tooltip配置
	}
}

3D散点图

API示例:/openapi/demo/chart?type=scatter3D

response:

{
	status: 0,  // 0表示成功,非0表示失败
	msg: '',    // 失败时的提示信息
	// data 为一个数组,每行对应散点图中的一个点
	data: [
		// 第一项为每个维度的名称
		// 顺序为:[X轴,Y轴,Z轴,颜色映射,散点大小映射]
		// 如果不需要颜色和大小映射,则只需要[X轴,Y轴,Z轴]
		// 如果不需要大小映射,则只需要[X轴,Y轴,Z轴,颜色映射]
		// 如果不需要颜色映射,则需要[X轴,Y轴,Z轴,null,散点大小映射]
		["国家", "年份", "收入", "平均寿命", "人口"],
		// 接下来的项为数据,数据项的列的各种情况与上面名称项的列相对应
		// 每个数据的格式要求:
		// X轴,Y轴,Z轴:数字或字符串
		// 颜色映射:如果需要使用颜色映射散点类别,则传字符串;如果需要使用颜色渐变映射某连续数值维度,则传数字
		// 散点大小映射:数字
		["Australia", "1800", 815, 34.05, 351014],
		["Canada", "1800", 1314, 39, 645526],
		.....
	]
}

文本

API示例:/openapi/demo/chart?type=text

response:

{
  status: 0,
  msg: ,
  data: {
    name: '百度',
    dau: 999999999,
    mau: 1000000000,
    link: 'https://www.badiu.com'
  }
}

使用示例API绑定文本的数据,可以展示如下效果:

图片

3D飞线地图

API示例:/openapi/demo/chart?type=map3DLine

response:

{
	"status": 0,
	"msg": "",
	"data": [ // data中可以放多个系列的数据,每个系列包含多条飞线
		{
			"name": "easyJet", // 系列的名字,将会体现在图例中
			"data": [
				[[-4.499106, 36.6749], [-2.719089, 51.382669]],
				// 每条飞线的具体数据,格式为:[[起点经度,起点纬度], [终点经度, 终点纬度]]
				[[-4.499106, 36.6749], [7.529167, 47.59]],
				......
			]
		},
		{
			"name": "Southwest Airlines",
			"data": [
				[[-106.6091944, 35.0402222], [-76.668333, 39.175361]],
				[[-106.6091944, 35.0402222], [-104.673178, 39.861656]],
				......
			]
		},
		......
	]
}

3D柱状地图

API示例:/openapi/demo/chart?type=map3DBar

response:

{
	"status": 0,
	"msg": "",
	"data": [
		// 每项对应一个柱子的数据,格式为:经度,纬度,柱子数值
		[-85.5, 73.5, 1.70293863659264],
		[-78, 73, 1.224744871391589],
		....
	]
}

数字翻牌器

API示例:/openapi/demo/chart?type=flipNumber

response:

{
	"status": 0,
	"msg": "",
	"data": 1201035.2990482938
}

进度条

API示例:/openapi/demo/chart?type=progressBar

response:

{
	"status": 0,
	"msg": "",
	"data": 19.14602833247916
}

水球图

API示例:/openapi/demo/chart?type=progressBar

response:

{
	"status": 0,
	"msg": "",
	"data": 19
}

例如 data 返回 19,水球图中就会显示 19%。

河流图

API示例:/openapi/demo/chart?type=river

response:

{
		"status": 0,
		"msg": "",
		"data": {
				// legend 字段必填,代表一共有几个系列
				"legend": ['华为', '联想', '微星', '宏基', '戴尔', '惠普'],
				// data 字段是一个二维数组,每个子数组必须有三项:
				// 0:用于横轴的序列。以 - 或 / 分隔的日期,以 : 分隔的时间,符合前面格式要求的日期时间组合,数字
				// 1:数据的大小。数字或有效的数字字符串
				// 2:数据属于哪个系列,需要与 legend 中的字段对应
				"data": [
					['2015/11/08',10,'华为'],['2015/11/09',15,'华为'],['2015/11/10',35,'华为'],
					['2015/11/08',35,'联想'],['2015/11/09',36,'联想'],['2015/11/10',37,'联想'],
					['2015/11/08',21,'微星'],['2015/11/09',25,'微星'],['2015/11/10',27,'微星'],
					['2015/11/08',10,'宏基'],['2015/11/09',15,'宏基'],['2015/11/10',35,'宏基'],
					['2015/11/08',10,'戴尔'],['2015/11/09',15,'戴尔'],['2015/11/10',35,'戴尔'],
					['2015/11/08',10,'惠普'],['2015/11/09',15,'惠普'],['2015/11/10',35,'惠普']
					.....
				]
		}
}

旭日图

API示例:/openapi/demo/chart?type=sunburst

response:

{
		"status": 0,
		"msg": "",
		// data是一个数组,表示了一个树状结构
		"data": [
			{
				// 每个节点必须有name属性,其值为字符串
				"name": "Fruity",
				// 非叶子节点必须有children字段,其值为包含其子节点的数组,不需要有value字段
				"children": [
					{
						"name": "Berry",
						"children": [
							{
								"name": "Blackberry",
								// 叶子节点必须有value字段,其值为数字
								"value": 1,
							},
							{
								"name": "Raspberry",
								"value": 1,
							}
						]
				}]
			},
			{
				"name": "Sour/\nFermented",
				"children": [
					{
						"name": "Sour",
						"children": [
							{
								"name": "Sour Aromatics",
								"value": 1,
							},
							{
								"name": "Acetic Acid",
								"value": 1,
							}
						]
					}
				]
			},
			......
		]
}

矩形树图

API示例:/openapi/demo/chart?type=treemap

response:

{
		"status": 0,
		"msg": "",
		// data是一个数组,表示了一个树状结构
		"data": [
			{
				// 每个节点必须有name属性,其值为字符串
				"name": "Fruity",
				// 非叶子节点必须有children字段,其值为包含其子节点的数组,不需要有value字段
				"children": [
					{
						"name": "Berry",
						"children": [
							{
								"name": "Blackberry",
								// 叶子节点必须有value字段,其值为数字
								"value": 1,
							},
							{
								"name": "Raspberry",
								"value": 1,
							}
						]
				}]
			},
			{
				"name": "Sour/Fermented",
				"children": [
					{
						"name": "Sour",
						"children": [
							{
								"name": "Sour Aromatics",
								"value": 1,
							},
							{
								"name": "Acetic Acid",
								"value": 1,
							}
						]
					}
				]
			},
			......
		]
}

日历热力图

API示例:/openapi/demo/chart?type=calHmap

response:

{
		"status": 0,
		"msg": "",
		"data": [
			// 每一项都是一个数组,代表某天的数据,数据可以不按日期顺序返回
			// 第一个元素是日期,格式要求yyyy-mm-dd
			// 第二个元素是取值,要求是数字或有效的数字字符串
			["2019-01-01", 186],
			["2019-01-02", 877],
			......
		]
}

坐标热力图

API示例:/openapi/demo/chart?type=cartHeatmap

response:

{
		"status": 0,
		"msg": "",
		"data": {
			// y轴类目,字符串数组
			yCategories: [
				'Saturday', 'Friday', 'Thursday', 'Wednesday',
				'Tuesday', 'Monday', 'Sunday'
			],
			// x轴类目,字符串数组
			xCategories: [
				'12a', '1a', '2a', '3a', '4a', '5a', '6a',
				'7a', '8a', '9a','10a','11a','12p', '1p', 
				'2p', '3p', '4p', '5p', '6p', '7p', '8p',
				'9p', '10p', '11p'
			],
			// 数据项数组
			data: [
				// 第一项对应X轴类目,第二项对应Y轴类目,第三项为数据取值,需为数字
				["12a","Saturday",5],
				["12a","Friday",7],
				["4a","Friday",0],
				......
			]
		}
}

K线图

API示例:/openapi/demo/chart?type=candlestick

response:

{
		"status": 0,
		"msg": "",
		"data": {
			"candlestick": [	// K线数据,二维数组
				[2320.26, 2320.26, 2287.3, 2362.94],	// 某一个K线的点,必须是四项数据,分别表示:开盘价、收盘价、最低价、最高价
				[2300, 2291.3, 2288.26, 2308.38],
				......
			],
			"categories": [	// K线图的X轴数据
				"2013-01-24",
				"2013-01-25",
				......
			],
			"ma": [	// 「移动平均线」,可不传(不传时不展示移动平均线),必须是数组,可展示多条移动平均线
				{
					name: 'MA5',	// 本条移动平均线的名称
					data: [2352.936, 2378.48, ...]	// 本条移动平均线的数据
				},
				......
			],
			"volume": [	// 成交量数据,可不传(不传时不展示成交量柱图)
				23454,
				34235,
				......
			],
			"rise": [	// 涨跌额和涨跌幅,可不传,传递后会展示在鼠标hover时的tooltip中,二维数组
				[45.23, 0.0367],	// 两项数据分别表示涨跌额和涨跌幅,涨跌幅使用小数,示例即表示涨跌额是45.23,涨跌幅是3.67%
				......
			]
		}
}

桑基图

API示例:/openapi/demo/chart?type=sankey

response:

{
		"status": 0,
		"msg": "",
		"data": {
			// nodes 字段是一个数组,每项代表一个节点
			nodes: [{
				name: 'a' // name 字段,必填,字符串类型,是节点的名称,也是节点的唯一标识
			}, { 
				name: 'b'
			}, {
				name: 'a1'
			}, {
				name: 'a2'
			},
			......
			],
			// links 字段是一个数组,每项代表一个流
			links: [{
				source: 'a',   // source 字段:源节点的名称,必填,字符串,需要与 nodes 中的某个节点相对应
				target: 'a1',  // target 字段:目的节点的名称,必填,字符串,需要与 nodes 中的某个节点相对应
				value: 5       // value 字段:流的大小,必填,数字类型
			}, {
				source: 'a',
				target: 'a2',
				value: 3
			},
			....
			]
		}
}

图片轮播

API示例:/openapi/demo/chart?type=slider

response:

{
		"status": 0,
		"msg": "",
		"data": [ // data 字段内容 是一个数组
			{
				// 每个图片的标题,如没有可不传
				title: '大屏示例1',
				// 必传,图片的 url 
				url: 'https://sugar-image.gz.bcebos.com/templet-templet04.png',
				// 图片如果需要配置超链接,可传链接的 url ,如不需要可不传,注意图片超链接在编辑模式不生效,浏览模式生效
				link: 'https://sugar.baidubce.com/dashboard/aa75c47fe742c2a33c186a3d364eb6a7'
			},
			{
				title: '大屏示例2',
				url: 'https://sugar-image.gz.bcebos.com/templet-templet01-1.png',
				link: 'https://sugar.baidubce.com/dashboard/41510e632e1e1e4767b0a041030670ec'
			},
			...
		]
}

本页内容