更改应用的图表设置

betsy_yan发表于:2021年03月09日 15:55:03更新于:2023年02月16日 14:31:10

更改应用的图表设置。
如应用中存在两个名字一样的图表,或者更新后发生了图表名字重复的情况,执行该API时会报错。

此API仅将应用的更改反映到确认应用各动作的测试环境中。
如需反映到正式环境,执行本API后,需要执行将应用的设置反映到正式环境中API

URI

https://(子域名).cybozu.cn/k/v1/preview/app/reports.json

来宾空间内的应用

https://(子域名).cybozu.cn/k/guest/(空间ID)/v1/preview/app/reports.json

HTTP 方法

PUT

必要的访问权限

应用的管理权限

请求参数

参数名称要指定的值必须说明
app
数值或字符串必须

指定应用的ID。

reports对象必须

表示图表信息的对象。

reports.{图表名称}对象

表示各个图表设置的对象。

在“{图表名称}”中指定更新前的图表名称。
指定了不存在的图表名称时,创建此为新图表。

添加或更新图表时,必须为所有现有的图表指定出它的“{图表名称}”。

如未指定,则将删除此图表。

reports.{图表名称}.chartType字符串条件必须

图表的类型。

  • BAR:条形图

  • COLUMN:柱形图

  • PIE:饼图

  • LINE:折线图

  • PIVOT_TABLE:交叉表

  • TABLE:表

  • AREA:面积图

  • SPLINE:曲线图

  • SPLINE_AREA:曲面图

指定“{图表名称}”时,必须指定此参数。

reports.{图表名称}.chartMode字符串条件必须

图表的显示模式。

  • NORMAL:簇状或无堆积

  • STACKED:堆积

  • PERCENTAGE:百分比堆积

若 chartType 是条形图(BAR)或柱形图(COLUMN),则 NORMAL 显示为簇状。

若 chartType 是面积图(AREA)或曲面图(SPLINE_AREA),则 NORMAL 显示为无堆积。

当 chartType 是 BAR、COLUMN、AREA 或 SPLINE_AREA时,则必须指定 chartMode。

reports.{图表名称}.name字符串条件必须

图表名称。

添加图表时,必需。添加时如与 reports.{图表名称} 不同,则会发生错误。

请指定1到64个字符之间。

reports.{图表名称}.index数值或字符串条件必须

图表的顺序。

按图表的值升序排列。
值重复将发生错误。

指定“{图表名称}”时必填。

reports.{图表名称}.groups数组条件必须

表示分组项目对象的数组。

按指定顺序,大项目、中项目、小项目进行设置。可在数组中指定3个元素。

reports.{图表名称}.chartType 为 PIVOT_TABLE 时,指定的数目小于1个时,则会发生错误。

添加图表时,必需。

reports.{图表名称}.groups[].code字符串条件必须

分组项目的字段代码。
指定 reports.{图表名称}.groups 参数时,必需。

reports.{图表名称}.groups[].per字符串条件必须

分组项目的时间单位。

  • YEAR:以年为单位

  • QUARTER:以季度为单位

  • MONTH:以月为单位

  • WEEK:以周为单位

  • DAY:以日为单位

  • HOUR:以1小时为单位

  • MINUTE:分钟单位

code 中指定以下字段时,则必需。
此外,可以设置的值取决于 code 指定的字段。

  • 创建时间(全部)

  • 更新时间(全部)

  • 日期与时间(全部)

  • 日期(YEAR, QUARTER, MONTH, WEEK, DAY)

  • 时间(HOUR, MINUTE)

reports.{图表名称}.aggregations数组条件必须

表示汇总方法对象的数组。

数组中最多可指定10个元素。

reports.{图表名称}.chartType 为 PIVOT_TABLE时、只能指定1个。

添加图表时,必需。

reports.{图表名称}.aggregations[].type字符串条件必须

汇总方法的类型。

  • COUNT:记录数

  • SUM:求和

  • AVERAGE:平均值

  • MAX:最大值

  • MIN:最小值

指定 reports.{图表名称}.aggregations 参数时,必需。

reports.{图表名称}.aggregations[].code字符串条件必须

汇总方法对象的字段代码。

type 不是 COUNT 时必需。

当 type 为 SUM 或 AVERAGE 时,可以指定以下字段。

  • 数值

  • 计算(数值,数值(千位分隔符))

  • 计算(时间(小时分),时间(天小时分))※仅支持TABLE

  • 数值型的Lookup

type 为 MAX、MIN 时可以指定以下字段。

  • 数值

  • 计算(数值,数值(千位分隔符))

  • 计算(日期与时间, 日期, 时间, 时间(小时分), 时间(天小时分))※仅支持TABLE

  • 日期与时间 ※仅支持TABLE

  • 日期 ※仅支持TABLE

  • 时间 ※仅支持TABLE

  • 创建时间 ※仅支持TABLE

  • 更新时间 ※仅支持TABLE

  • 数值型的Lookup

reports.{图表名称}.filterCond字符串

筛选条件。

用查询形式显示。查询形式请参考以下页面。
批量获取记录(在查询中指定条件) 

当添加时省略,则与指定“所有记录”时相同。

当更新时省略,则不更改设置。

如果指定了已删除的用户、组织、组,则返回错误。

reports.{图表名称}.sorts数组条件必须

表示排序对象的数组。

数组的元素可以指定3个。

添加图表时,必需。

reports.{图表名称}.sorts[].by字符串条件必须

排序的对象。

  • TOTAL: 汇总值

  • GROUP1:大项目

  • GROUP2:中项目

  • GROUP3:小项目

指定 reports.{图表名称}.sorts 参数时,必需。

reports.{图表名称}.sorts[].order字符串条件必须

排序的顺序。

  • ASC:升序

  • DESC:降序

指定 reports.{图表名称}.sorts 参数时,必需。

reports.{图表名称}.periodicReport对象

定期报表的设置。

设置定期报表后,除了以下参数外,无法更改其他参数。

  • reports.{图表名称}.name

  • reports.{图表名称}.index

  • reports.{图表名称}.periodicReport.active

当更新时省略,则不更改设置。

reports.{图表名称}.periodicReport.active布尔值或字符串

定期报表的执行状态。

  • true:执行中

  • false:停止中

当初始设置定期报表省略时,则为 true 。
当更新时省略,则不更改设置。

reports.{图表名称}.periodicReport.period对象条件必须

定期报表的汇总间隔。
初始设置定期报表时必需。
更新时指定或未省略与当前设置相同的设置,则会发生错误。

reports.{图表名称}.periodicReport.period.every字符串条件必须

定期报表的汇总间隔的类型。

  • YEAR:每年

  • QUARTER:每季度

  • MONTH:每月

  • WEEK:每周

  • DAY:每天

  • HOUR:每时

指定 reports.{图表名称}.periodicReport.period 参数时,必需。

reports.{图表名称}.periodicReport.period.month数值或字符串条件必须

执行汇总的月份。

该值是1到12之间的整数。

every 为 YEAR 时,必需。

reports.{图表名称}.periodicReport.period.time字符串条件必须

执行汇总的时间。

格式为 HH:mm 的形式。

every 为 YEAR、QUARTER、MONTH、WEEK、DAY 时,必需。

reports.{图表名称}.periodicReport.period.pattern字符串条件必须

执行季度汇总的月份。

  • JAN_APR_JUL_OCT:1月, 4月, 7月, 10月

  • FEB_MAY_AUG_NOV:2月, 5月, 8月, 11月

  • MAR_JUN_SEP_DEC:3月, 6月, 9月, 12月

every 为 QUARTER 时,必需。

reports.{图表名称}.periodicReport.period.dayOfMonth字符串条件必须

执行汇总的日期。

  • 该值是1到31之间的整数。

  • END_OF_MONTH:月底
    ※仅当 every 为 QUARTER、MONTH 

every 为 YEAR、QUARTER、MONTH 时,必需。

reports.{图表名称}.periodicReport.period.dayOfWeek字符串条件必须

星期几执行汇总。

  • SUNDAY

  • MONDAY

  • TUESDAY

  • WEDNESDAY

  • THURSDAY

  • FRIDAY

  • SATURDAY

every 为 WEEK 时,必需。

reports.{图表名称}.periodicReport.period.minute数值或字符串条件必须

执行汇总的分钟数。

可选的值是 0、10、20、30、40、50 。

every 为 HOUR 时,必需。

revision数值或字符串

预期应用设定的修订号。
如果省略或指定"-1",则不检查修订。


应答的范例

PUT /k/v1/preview/app/reports.json HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json


正文

{
  "app": "1",
  "reports": {
    "初始设置": {
      "chartType": "BAR",
      "chartMode": "NORMAL",
      "name": "初始设置",
      "index": "0",
      "groups": [
        {
          "code": "单选框"
        }
      ],
      "aggregations": [
        {
          "type": "COUNT"
        }
      ],
      "filterCond": "",
      "sorts": [
        {
          "by": "TOTAL",
          "order": "DESC"
        }
      ],
      "periodicReport": null
    },
    "各种图表的设置": {
      "chartType": "TABLE",
      "name": "各种图表的设置",
      "index": "1",
      "groups": [
        {
          "code": "单选框"
        },
        {
          "code": "创建时间",
          "per": "YEAR"
        },
        {
          "code": "时间",
          "per": "MINUTE"
        }
      ],
      "aggregations": [
        {
          "type": "COUNT"
        },
        {
          "type": "SUM",
          "code": "数值"
        },
        {
          "type": "AVERAGE",
          "code": "计算"
        },
        {
          "type": "MAX",
          "code": "创建时间"
        },
        {
          "type": "MIN",
          "code": "时间"
        }
      ],
      "filterCond": "记录编号 = \"1\" and 文本编辑器 like \"aaa\"",
      "sorts": [
        {
          "by": "TOTAL",
          "order": "DESC"
        },
        {
          "by": "GROUP1",
          "order": "ASC"
        },
        {
          "by": "GROUP2",
          "order": "DESC"
        }
      ],
      "periodicReport": null
    },
    "定期报表ON": {
      "chartType": "BAR",
      "chartMode": "NORMAL",
      "name": "定期报表ON",
      "index": "2",
      "groups": [
        {
          "code": "单选框"
        }
      ],
      "aggregations": [
        {
          "type": "COUNT"
        }
      ],
      "filterCond": "",
      "sorts": [
        {
          "by": "TOTAL",
          "order": "DESC"
        }
      ],
      "periodicReport": {
        "active": true,
        "period": {
          "every": "QUARTER",
          "pattern": "JAN_APR_JUL_OCT",
          "dayOfMonth": "END_OF_MONTH",
          "time": "23:30"
        }
      }
    }
  },
  "revision": "2"
}


应答

参数

参数名称値の種類説明
revision字符串更新后应用设定的修订号。
reports对象图表的信息。
reports.{图表名称}.id字符串图表的ID。

 

应答的范例

{
  "revision": "2",
  "reports": {
    "初始设置": {
      "id": "7319"
    },
    "各种图表的设置": {
      "id": "7321"
    },
    "定期报表ON": {
      "id": "7323"
    }
  }
}


JavaScript 范例

使用API请求发送 kintone REST API 请求

var body = {
  'app': kintone.app.getId(),
  'reports': {
    '初始设置': {
      'chartType': 'BAR',
      'chartMode': 'NORMAL',
      'name': '初始设置',
      'index': '0',
      'groups': [
        {
          'code': '单选框'
        }
      ],
      'aggregations': [
        {
          'type': 'COUNT'
        }
      ],
      'filterCond': '',
      'sorts': [
        {
          'by': 'TOTAL',
          'order': 'DESC'
        }
      ],
      'periodicReport': null
    },
    '各种图表的设置': {
      'chartType': 'TABLE',
      'name': '各种图表的设置',
      'index': '1',
      'groups': [
        {
          'code': '单选框'
        },
        {
          'code': '创建时间',
          'per': 'YEAR'
        },
        {
          'code': '时间',
          'per': 'MINUTE'
        }
      ],
      'aggregations': [
        {
          'type': 'COUNT'
        },
        {
          'type': 'SUM',
          'code': '数值'
        },
        {
          'type': 'AVERAGE',
          'code': '计算'
        },
        {
          'type': 'MAX',
          'code': '创建时间'
        },
        {
          'type': 'MIN',
          'code': '时间'
        }
      ],
      'filterCond': '记录编号 = \'1\' and 文本编辑器 like \'aaa\'',
      'sorts': [
        {
          'by': 'TOTAL',
          'order': 'DESC'
        },
        {
          'by': 'GROUP1',
          'order': 'ASC'
        },
        {
          'by': 'GROUP2',
          'order': 'DESC'
        }
      ],
      'periodicReport': null
    },
    '定期报表ON': {
      'chartType': 'BAR',
      'chartMode': 'NORMAL',
      'name': '定期报表ON',
      'index': '2',
      'groups': [
        {
          'code': '单选框'
        }
      ],
      'aggregations': [
        {
          'type': 'COUNT'
        }
      ],
      'filterCond': '',
      'sorts': [
        {
          'by': 'TOTAL',
          'order': 'DESC'
        }
      ],
      'periodicReport': {
        'active': true,
        'period': {
          'every': 'QUARTER',
          'pattern': 'JAN_APR_JUL_OCT',
          'dayOfMonth': 'END_OF_MONTH',
          'time': '23:30'
        }
      }
    }
  },
  'revision': '2'
};
kintone.api(kintone.api.url('/k/v1/preview/app/reports', true), 'PUT', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});


使用 XMLHttpRequest 的请求

var body = {
  'app': kintone.app.getId(),
  'reports': {
    '初始设置': {
      'chartType': 'BAR',
      'chartMode': 'NORMAL',
      'name': '初始设置',
      'index': '0',
      'groups': [
        {
          'code': '单选框'
        }
      ],
      'aggregations': [
        {
          'type': 'COUNT'
        }
      ],
      'filterCond': '',
      'sorts': [
        {
          'by': 'TOTAL',
          'order': 'DESC'
        }
      ],
      'periodicReport': null
    },
    '各种图表的设置': {
      'chartType': 'TABLE',
      'name': '各种图表的设置',
      'index': '1',
      'groups': [
        {
          'code': '单选框'
        },
        {
          'code': '创建时间',
          'per': 'YEAR'
        },
        {
          'code': '时间',
          'per': 'MINUTE'
        }
      ],
      'aggregations': [
        {
          'type': 'COUNT'
        },
        {
          'type': 'SUM',
          'code': '数值'
        },
        {
          'type': 'AVERAGE',
          'code': '计算'
        },
        {
          'type': 'MAX',
          'code': '创建时间'
        },
        {
          'type': 'MIN',
          'code': '时间'
        }
      ],
      'filterCond': '记录编号 = \'1\' and 文本编辑器 like \'aaa\'',
      'sorts': [
        {
          'by': 'TOTAL',
          'order': 'DESC'
        },
        {
          'by': 'GROUP1',
          'order': 'ASC'
        },
        {
          'by': 'GROUP2',
          'order': 'DESC'
        }
      ],
      'periodicReport': null
    },
    '定期报表ON': {
      'chartType': 'BAR',
      'chartMode': 'NORMAL',
      'name': '定期报表ON',
      'index': '2',
      'groups': [
        {
          'code': '单选框'
        }
      ],
      'aggregations': [
        {
          'type': 'COUNT'
        }
      ],
      'filterCond': '',
      'sorts': [
        {
          'by': 'TOTAL',
          'order': 'DESC'
        }
      ],
      'periodicReport': {
        'active': true,
        'period': {
          'every': 'QUARTER',
          'pattern': 'JAN_APR_JUL_OCT',
          'dayOfMonth': 'END_OF_MONTH',
          'time': '23:30'
        }
      }
    }
  },
  'revision': '2',
  // CSRF TOKEN: 在kintone上执行API(POST,PUT,DELETE)时必须设置
  '__REQUEST_TOKEN__': kintone.getRequestToken()
};
var url = 'https://{subdomain}.cybozu.cn/k/v1/preview/app/reports.json';
var xhr = new XMLHttpRequest();
xhr.open('PUT', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() {
  if (xhr.status === 200) {
    // success
    console.log(JSON.parse(xhr.responseText));
  } else {
    // error
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.send(JSON.stringify(body));