Index

• 概要

• 共通事项

• 方法1: 使用记录ID的方法

• 方法2: 使用游标API的方法

• 方法3: 使用offset的方法

概要

批量获取记录的方法大致可以分成3种，需要根据实际需求选择不同的方式。
各方法的特点以及使用方法请参考此文档。

本文通过示例介绍各方法的JavaScript代码如何编写。

共通事项

• 本文中为了示范如何调用getRecords函数，使用了"案件管理"这个应用。字段代码和字段名称一致。

方法1: 使用记录ID的方法

此方法是使用批量获取记录 API ，按照记录 ID（记录编号）的升序排序，按ID顺序依次获取记录。

代码范例

获取记录的函数

/*
 * get all records function by using record id sample program
 * Copyright (c) 2019 Cybozu
 *
 * Licensed under the MIT License
 */

/*
 * @param {Object} params
 *   - app {String}: 应用ID（省略时表示当前打开的应用）
 *   - filterCond {String}: 筛选条件
 *   - sortConds {Array}: 排序条件的数组
 *   - fields {Array}: 要获取的字段的数组
 * @return {Object} response
 *   - records {Array}: 要获取的记录的数组
 */
var getRecords = function(_params) {
  var MAX_READ_LIMIT = 500;

  var params = _params || {};
  var app = params.app || kintone.app.getId();
  var filterCond = params.filterCond;
  var sortConds = params.sortConds || ['$id asc'];
  var fields = params.fields;
  var data = params.data;

  if (!data) {
    data = {
      records: [],
      lastRecordId: 0
    };
  }

  var conditions = [];
  var limit = MAX_READ_LIMIT;
  if (filterCond) {
    conditions.push(filterCond);
  }

  conditions.push('$id > ' + data.lastRecordId);

  var sortCondsAndLimit =
    ' order by ' + sortConds.join(', ') + ' limit ' + limit;
  var query = conditions.join(' and ') + sortCondsAndLimit;
  var body = {
    app: app,
    query: query
  };

  if (fields && fields.length > 0) {
    // 因为是按照$id的排序来获取的，因此如果要获取的字段中没有“$id”字段，要追加进去
    if (fields.indexOf('$id') <= -1) {
      fields.push('$id')
    }
    body.fields = fields;
  }

  return kintone.api(kintone.api.url('/k/v1/records', true), 'GET', body).then(function(r) {
    data.records = data.records.concat(r.records);
    if (r.records.length === limit) {
      // 如果获取的记录条数和limit一样，表示可能还有未获取的记录，因此要再回调getRecords，获取剩下的记录
      data.lastRecordId = r.records[r.records.length - 1].$id.value;
      return getRecords({ app:app, filterCond:filterCond, sortConds: sortConds, fields:fields, data:data });
    }
    delete data.lastRecordId;
    return data;
  });
};

调用getRecords函数的示例

• 指定了筛选条件/排序条件/要获取的字段时
  ※ 如果是使用记录 ID获取记录，sortConds要指定['$id asc']。
  

  /*
   * call getRecords function sample program
   * Copyright (c) 2019 Cybozu
   *
   * Licensed under the MIT License
   */
  
  // query如下
  // 下单确定性 in ("A") and 下单预期 >= THIS_YEAR() and $id > 0 order by $id asc, 合计desc, 公司名称 asc limit 500
  var params = {
    app: 1,
    filterCond: '下单确定性 in ("A") and 下单预期 >= THIS_YEAR()',
    // 排序条件按照['字段代码 asc或者desc']的形式指定
    sortConds: ['$id asc', '合计 desc', '公司名称 asc'],
    fields: ['记录编号', '公司名称', '对方负责人', '下单预期', '下单确定性', '产品名称', '单价', '用户数', '合计']
  };
  getRecords(params).then(function(resp) {
    console.log(resp);
  });

• 不指定时
  ※ 如果不指定应用ID，则获取当前打开的应用的记录。
  

  /*
   * call getRecords function sample program
   * Copyright (c) 2019 Cybozu
   *
   * Licensed under the MIT License
   */
  
  // query如下
  // $id > 0 order by $id asc limit 500
  getRecords().then(function(resp) {
    console.log(resp);
  });

方法2: 使用游标API的方法

此方法是使用游标API获取记录。

代码范例

获取记录的函数

/*
 * get all records function by cursor id sample program
 * Copyright (c) 2019 Cybozu
 *
 * Licensed under the MIT License
 */

// 创建游标
var postCursor = function(_params) {
  var MAX_READ_LIMIT = 500;

  var params = _params || {};
  var app = params.app || kintone.app.getId();
  var filterCond = params.filterCond;
  var sortConds = params.sortConds;
  var fields = params.fields;

  var conditions = [];
  if (filterCond) {
    conditions.push(filterCond);
  }

  var sortCondsAndLimit =
    (sortConds && sortConds.length > 0 ? ' order by ' + sortConds.join(', ') : '');
  var query = conditions.join(' and ') + sortCondsAndLimit;
  var body = {
    app: app,
    query: query,
    size: MAX_READ_LIMIT
  };
  if (fields && fields.length > 0) {
    body.fields = fields;
  }

  return kintone.api(kintone.api.url('/k/v1/records/cursor', true), 'POST', body).then(function(r) {
    return r.id;
  });
};

// 从创建的游标中获取记录
var getRecordsByCursorId = function(_params) {
  var params = _params || {};
  var id = params.id;

  var data = params.data;

  if (!data) {
    data = {
      records: []
    };
  }

  var body = {
    id: id
  };
  return kintone.api(kintone.api.url('/k/v1/records/cursor', true), 'GET', body).then(function(r) {
    data.records = data.records.concat(r.records);
    if (r.next) {
      return getRecordsByCursorId({ id: id, data: data });
    }
    return data;
  });
};

/*
 * @param {Object} params
 *   - app {String}: 应用ID（省略时表示当前打开的应用）
 *   - filterCond {String}: 筛选条件
 *   - sortConds {Array}: 排序条件的数组
 *   - fields {Array}: 要获取的字段的数组
 * @return {Object} response
 *   - records {Array}: 要获取的记录的数组
 */
var getRecords = function(_params) {
  return postCursor(_params).then(function(id) {
    return getRecordsByCursorId({ id: id });
  });
};

调用getRecords函数的示例

• 指定了筛选条件/排序条件/要获取的字段时
  

  /*
   * call getRecords function sample program
   * Copyright (c) 2019 Cybozu
   *
   * Licensed under the MIT License
   */
  
  // query如下
  // 下单确定性 in ("A") and 下单预期 >= THIS_YEAR() order by 合计 desc, 公司名称 asc
  var params = {
    app: 1,
    filterCond: '下单确定性 in ("A") and 下单预期 >= THIS_YEAR()',
    sortConds: ['合计 desc', '公司名称 asc'],
    fields: ['记录编号', '公司名称', '对方负责人', '下单预期', '下单确定性', '产品名称', '单价', '用户数', '合计'],
  };
  getRecords(params).then(function(resp) {
    console.log(resp);
  });

• 不指定时
  ※ 如果不指定应用 ID ，表示获取当前打开的应用的记录。
  

  /*
   * call getRecords function sample program
   * Copyright (c) 2019 Cybozu
   *
   * Licensed under the MIT License
   */
  
  // query 指定为 ''(空白) 
  getRecords().then(function(resp) {
    console.log(resp);
  });

方法3: 使用offset的方法

此方法是使用批量获取记录API，指定请求参数offset 依次获取记录的方法。

代码范例

获取记录的函数

/*
 * get all records function by using offset sample program
 * Copyright (c) 2019 Cybozu
 *
 * Licensed under the MIT License
 */

/*
 * @param {Object} _params
 *   - app {String}: 应用ID（省略时表示当前打开的应用）
 *   - filterCond {String}: 筛选条件
 *   - sortConds {Array}: 排序条件的数组
 *   - fields {Array}: 要获取的字段的数组
 *   - limit {Number}: 要获取的记录的条数（省略时获取符合筛选条件的所有记录）
 * @return {Object} response
 *   - records {Array}: 要获取的记录的数组
 */
var getRecords = function(_params) {
  var MAX_READ_LIMIT = 500;

  var params = _params || {};
  var app = params.app || kintone.app.getId();
  var filterCond = params.filterCond;
  var sortConds = params.sortConds;
  var limit = params.limit || -1;
  var offset = params.offset || 0;
  var fields = params.fields;
  var data = params.data;

  if (!data) {
    data = {
      records: []
    };
  }

  var willBeDone = false;
  var thisLimit = MAX_READ_LIMIT;
  // 调用getRecords函数的那方指定了记录的获取条数时
  //  willBeDone指定为true时，可在获取完指定的条数后退出。
  if (limit > 0) {
    if (thisLimit > limit) {
      thisLimit = limit;
      willBeDone = true;
    }
  }

  var conditions = [];
  if (filterCond) {
    conditions.push(filterCond);
  }

var sortCondsAndLimit = (sortConds && sortConds.length > 0 ? ' order by ' + sortConds.join(', ') : '')
    + ' limit ' + thisLimit;
  var query = conditions.join(' and ') + sortCondsAndLimit + ' offset ' + offset;
  var body = {
    app: app,
    query: query
  };
  if (fields && fields.length > 0) {
    body.fields = fields;
  }
  return kintone.api(kintone.api.url('/k/v1/records', true), 'GET', body).then(function(resp) {
      data.records = data.records.concat(resp.records);
      var _offset = resp.records.length;
      if (limit > 0 && limit < _offset) {
        willBeDone = true;
      }
      // 获取完该要获取的记录后退出
      if (_offset < thisLimit || willBeDone) {
        return data;
      }
      // 如果该获取的记录还未获取完，再调用函数获取剩余记录
      return getRecords({
        app: app,
        filterCond: filterCond,
        sortConds: sortConds,
        limit: limit - _offset,
        offset: offset + _offset,
        fields: fields,
        data: data
      });
    });
};

调用getRecords函数的示例

• 指定了筛选条件/排序条件/要获取的字段时
  

  /*
   * call getRecords function sample program
   * Copyright (c) 2019 Cybozu
   *
   * Licensed under the MIT License
   */
  
  // query如下
  // 下单确定性 in ("A") and 下单预期 >= THIS_YEAR() order by 合计 desc, 公司名称 asc limit 500 offset 0
  var params = {
    app: 1,
    filterCond: '下单确定性 in ("A") and 下单预期 >= THIS_YEAR()',
    sortConds: ['合计 desc', '公司名称 asc'],
    fields: ['记录编号', '公司名称', '对方负责人', '下单预期', '下单确定性', '产品名称', '单价', '用户数', '合计'],
  };
  getRecords(params).then(function(resp) {
    console.log(resp);
  });

• 不指定时
  ※ 不指定应用 ID时，将获取当前打开的应用的记录。

  /*
   * call getRecords function sample program
   * Copyright (c) 2019 Cybozu
   *
   * Licensed under the MIT License
   */
  
  // query如下
  // limit 500 offset 0
  getRecords().then(function(resp) {
    console.log(resp);
  });