KMS 帮助文档Appearance
Data API 接口文档
以下是 Data API 的接口文档。在开始之前，请先了解一下 Data API 基本概念。
查询方式
https://<API-Server>/<API-KEY|API-ALIAS>/<TYPE>?<Query-Params>URL占位参数：
| 参数名 | 类型 | 描述 |
|---|---|---|
| API-Server | 字符串 | 必选。数据 DSI 的域名，比如 activity.dsi.seayoo.com |
| API-KEY 或 API-ALIAS | 字符串 | 必选。指定查询数据的 key 或者别名，全局唯一 |
| TYPE | 字符串 | 可选。可选值为 ajax / script / jsonp 含义同下type参数，优先级高于 type 参数 |
jsonp vs. script
jsonp 和 script 的原理是一样的：动态生成一段 JavaScript 代码，浏览器端通过 script 标签加载和使用。不同点是：jsonp 返回的 JavaScript 代码，需要执行一个回调函数，并将数据注入到回调函数的参数中；而 script 方式返回的 JavaScript 代码，是将数据写入到一个 window 全局变量中。
URL查询参数
| 参数名 | 缩写 | 描述 |
|---|---|---|
| sn | 指定获取某个配置，设定 sn 后，所有过滤以及分页参数均失效 此时不考虑配置是否过期，一律返回该配置 | |
| group | g | 指定获取某个或多个分组的数据，多个分组需使用半角逗号分割： 比如 group=g1,g2,g3 |
| filter | 过滤 data 字段根节点的数据，格式为 filter=[字段名]:[字段值,字段值...]比如 filter=name:value1,value2 将过滤 data.name 为 value1 或者 value2 的数据项，其中 value1 和 value2 数据类型将根据 data.name 自动格式化，并且仅仅支持 string / number / null 三种数据类型以及包含这三种数据类型的单层数组（即所有子元素均是简单数据类型），区分大小写 filter也支持多组过滤，格式为 filter=[字段名]:[字段值,字段值...]<逻辑符>[字段名]:[字段值 ...] 其中<逻辑符> 可以是竖线 “|” 表示或（or）， 加号“+” 表示并且（and）； 比如： filter=a:1,2+b:3,4 表示 a为1或者2，并且，b为3或者4的记录会被选中，其他记录会被滤掉 | |
| filter:[field] | 上述 filter 的变异形式，格式为 filter:[字段名]=[字段值,字段值]。优先级低于 filter； 支持多组过滤参数，多组参数的逻辑组合为并且（and）； 比如 filter:a=1,2&filter:b=3,4 等价于 filter=a:1,2+b:3,4 | |
| range | r | 可选有效期过滤参数，对配置的有效期进行过滤，可选值有五个：left 过滤所有已经失效的配置center 过滤所有生效中的配置（默认值）right 过滤所有尚未生效的配置forward 过滤所有生效中以及待生效的配置all 返回所有配置 |
| created / updated | 格式为 [起始时间]-[结束时间]表示过滤出 created 或 updated 为指定时间范围内的记录，时间格式支持：yyyy / yyyyMM / yyyyMMdd / yyyyMMddhh / yyyyMMddhhmm / yyyyMMddhhmmss其中起始时间不足 14 位的情况下，将以 1月1日0点0分0秒进行补足； 结束时间不足 14 位的情况下，将以 12月31日23点59分59秒进行补足； 起始时间和结束时间可以忽略其中一个，表示开放时间段进行选择； 如果格式错误，则忽略此参数；当记录的 updated 属性无值时，以 created 作为默认值；时间格式为双闭区间，即 >= 起始时间 且 <= 结束时间的记录都会被选中； | |
| sort | 用于对集合数据指定排序方法，默认是 sort=order 即按照 order 字段从大到小排序； 如果是从小到大排序，需要在参数值前加一个中划线，比如 sort=-end 就是按照 end 从小到大（从早到晚）排序； 可选值有： start / end / created / order / updated 以及二级自定义字段 counter.xx 和 data.xx 字段必须是数字类型，如果类型不符，排序出的结果将可能变得不可靠，并会影响分页的准确性 如果字段为非真值，则转化为数字 0 参与排序 sort支持多个字段排序，基本格式为 order=field1,field2,field3 比如 sort=data.time,created 可以优先按照 data.time 排序，如果两条记录 data.time 相同，则比较 created；以此类推； 其中每个排序字段可以设置多个默认值字段（以竖线分割）： 比如 sort=data.updateTime|updated 就是按照 data.updateTime 排序，其中 data.updateTime 为非真值时，用 updated 的值参与排序； | |
| multi | m | 可选值：y / ny:（默认）返回所有符合要求的数据记录集合n: 仅仅返回符合要求的排序最靠前的一条记录 |
| size | s | 返回单页数据记录的最大数量，默认返回所有符合记录的数据。 可设置的最大值 100 |
| page | p | 返回数据记录指定页数的内容，默认第一页，最大值 10000 如果超过最后一页，则返回最后一页。 |
| fields | f | 过滤数据根节点的字段: group,sn,start,end,order,data,created,updated,counter 属性之间以半角逗号分割 比如 f=data,start 将仅仅返回所有数据记录中的 data 和 start 字段 区分大小写，默认不过滤 |
| dataFields | df | 过滤 data 字段根节点的字段，区分大小写，默认不过滤 |
| combo | c | 可选值：y / ny: 将 fields 参数指定的根节点数据全部合并到一起，其中系统自带的字段优先级高于 data 根节点字段，相同字段内容会被覆盖。 为了防止 key 误覆盖，必须显式设置 fields 参数后方才生效。 n: （默认）不做数据合并处理，如果 fields 参数中没有指定 data 也是此值 |
| pure | 可选值：y / n / items， 当值为 y 时仅仅对 ajax 模式有效，items 对所有模式有效y：将直接返回数据本身，而不带有 { err, data } 包装结构n：默认行为，ajax 返回会带有 { err, data } 包装结构items：在 pure=y 的基础上进一步精简，删除 pagination 信息，直接返回 items 数组。如果同时设置了 sn 或者 multi=n 则效果等同于 pure=y | |
| var / callback | 非 ajax 状态时必选，表示回调注入的入口 参数格式：字母开头，仅仅包含字母和数字 其中 jsonp 使用 callback 参数，script 使用 var 参数 | |
| label / value | 设定有效值后，格式化输出数据为 [{ label, value, key }] 形式，方便前端选择组件直接使用 label 值为 data 字段的属性名，区分大小写，支持链式取值，比如 a.b.c value 值为 data 字段的属性名，区分大小写，支持链式取值，默认是该条记录的 sn 返回数据中的 key 固定为记录的 sn 任何数据错误都不会报错，而是返回空数组 [] 设置了 label / value 后，除了 group / sn / filter 参数外，其他用于过滤数据的参数均无效 label支持设定多个字段，比如 label=name,desc 此时返回的内容，会是 data.name 和 data.desc 拼接成的字符串，并用空格连接。 value支持设定多个字段，比如 value=id,name 此时返回的数据，会多出一个 payload 字段，内容为 value 指定的多个字段内容。 此时会强制 value 和 key 均为 该条记录的 sn； 这种特殊结构的选项数据在 KMS 中直接受到支持，并将 payload 作为实际的选项值，这种方式可以突破 value 不能为 object 复合数据的限制； | |
| option | 设置 option 后，等价于设置 label=option&value=option；其优先级低于 label/value |