中文
新的库 Kintone JS SDK 现已发布。
Index
开始
今天想给大家介绍下2018年5月发布的 "kintone-node.js-sdk"。
"kintone-node.js-sdk" 是在Node.js（服务器端JavaScript）环境里使用kintone REST API，为提高生产效率而开发的库。
之前，我们在Node.js上执行kintone REST API的时候，往往需要使用Node.js标准模块中的 "https"，"request"，"request-promise"等模块。
这次发布的 "kintone-node.js-sdk"，可以不使用以上的模块，可以更方便地使用kintone REST API。
GitHub
https://github.com/kintone-labs/kintone-nodejs-sdk/
文档
https://kintone-labs.github.io/kintone-nodejs-sdk/
接下来将用例子给大家介绍 kintone-node.js-sdk 的导入和执行方法。
大家可以在可运行Node.js的环境里尝试一下。
Node.js
注意事项
本范例程序，不保证运行绝对正确。
关于代码的更改、再发布以及商业用途，请遵照相应的使用许可协议。
导入方法
安装
任意目录下执行下面的命令，安装 kintone-nodejs-sdk。
$ mkdir sample_project $ cd sample_project $ npm install --save kintone-nodejs-sdk
请根据文档，安装8.9.3以上的Node版本，5.5.1以上的npm版本。
Requirement里记载的 kintone-basejs-sdk, 会自动运行上面的命令，大家可以无视。
范例
我们使用文档里Quickstart中的简单例子，介绍下执行方法和应答。
范例代码实现了从kintone应用获取1条记录的功能。
作为准备工作，请事先制作一个kintone应用，API令牌（需要的权限＝只读）。
范例代码（文件名：sample.js）
const kintone = require('kintone-nodejs-sdk');
let APIToken = 'xxxxxxxxxxxxxxxxxx'; // your API Token
let basicUserName = 'xxxxx'; // basicAuth user name
let basicPassword = 'xxxxx'; // basicAuth password
let kintoneAuth = new kintone.Auth();
kintoneAuth.setBasicAuth(basicUserName, basicPassword);
kintoneAuth.setApiToken(APIToken);
let myDomainName = '{subdomain}.cybozu.cn';
let kintoneConnection = new kintone.Connection(myDomainName, kintoneAuth);
let kintoneRecord = new kintone.Record(kintoneConnection);
let appID = xx; // target appID
let recordID = 1;
kintoneRecord.getRecord(appID, recordID)
.then((rsp) => {
console.log(rsp);
})
.catch((err) => {
console.log(err.get());
});API令牌、认证信息、子域名、应用ID请根据手头的环境更改。
作成后的文件，请保存在 kintone-nodejs-sdk 安装时生成的目录 "sample_project" 下。
运行
在刚才范例代码保存的目录 "sample_project" 下，运行下面的命令。
$ node sample.js
如果发生错误的话，请确认一下保存 sample.js 的目录里，是否有 node_modules 这个目录。
应答例
请求成功后，会返回下面的应答。
{
"record":
{
"执行者": { "type": "STATUS_ASSIGNEE", "value": [] },
"更新人": { "type": "MODIFIER", "value": {"code": "Administrator", "name": "Administrator"} },
"创建人": { "type": "CREATOR", "value": {"code": "Administrator", "name": "Administrator"} },
"状态": { "type": "STATUS", "value": "处理中" },
"$revision": { "type": "__REVISION__", "value": "1" },
"updateNum": { "type": "NUMBER", "value": "" },
"recordNum": { "type": "RECORD_NUMBER", "value": "1" },
"更新时间": { "type": "UPDATED_TIME", "value": "2018-04-10T02:05:00Z" },
"创建时间": { "type": "CREATED_TIME", "value": "2018-04-09T02:00:00Z" },
"$id": { "type": "__ID__", "value": "1" }
}
}代码解说
Authentication
范例代码3~8行的说明。
这部分定义了连接 kintone 的认证方法。
const kintone = require('kintone-nodejs-sdk');
let kintoneAuth = new kintone.Auth();Authentication类里，可以设置密码认证、API令牌认证、Basic认证。
以下是认证的优先度。（参考：REST API共通规格）
1．密码认证
2．API令牌认证
※kintone-nodejs-sdk里没有Session认证。
密码验证
let username = 'your user name'; let password = 'your password'; kintoneAuth.setPasswordAuth(username, password);
API令牌认证
let apiTokenString = 'your token'; kintoneAuth.setApiToken(apiTokenString);
Basic认证
let username = 'your user name'; let password = 'your password'; kintoneAuth.setBasicAuth(username, password);
Connection
10,11行的Connection类，可以设置连接。
使用连接目标的域名信息，以及之前作成的认证信息、可以连接kintone环境。
let myDomainName = '{subdomain}.cybozu.cn';
let kintoneConnection = new kintone.Connection(myDomainName, kintoneAuth);
// for GuestSpace
let myDomainName = '{subdomain}.cybozu.cn';
let guestSpaceID = xx;
let kintoneConnection = new kintone.Connection(myDomainName, kintoneAuth, guestSpaceID);Record
最后关于13~24行。
let kintoneRecord = new kintone.Record(kintoneConnection);
let appID = xx; // target appID
let recordID = 1;
kintoneRecord.getRecord(appID, recordID)
.then((rsp) => {
console.log(rsp);
})
.catch((err) => {
console.log(err.get());
});这部分是实际的kintone REST API的运行处理。
上面的代码里使用了Record类的getRecord函数，来获取1条记录。
getRecord(appID, recordID)
参数
| 名称 | 数据类型 | 必须 | 说明 |
|---|---|---|---|
| appID | Integer | 〇 | 应用ID |
| recordID | Integer | 〇 | 记录编号 |
Record类里，除了获取1条记录的方法外，还有其他的方法。
关于其他方法
Record类
这是之前范例代码里所使用方法的类。
针对应用的记录，有获取、添加、编辑、删除、状态变更的方法，
也有获取、添加、删除回复的方法。
具体的方法，可以参考以下这些。
getRecord
getRecords
addRecord
addRecords
updateRecords
deleteRecords
updateRecordStatus
getComments
addComment
deleteComment
当然还有很多其他的方法。具体可以参考文档。
关于Record类
https://kintone-labs.github.io/kintone-nodejs-sdk/reference/record/
BulkRequest类
可以对多个应用，同时请求多个API。
BulkRequest中可以使用的方法可以参考下面的文档。
关于BulkRequest类
https://kintone-labs.github.io/kintone-nodejs-sdk/reference/bulk-request/
但是实际运行BulkRequest的时候，需要注意的是：
当执行BulkRequest，应答返回的时候，会执行execute函数。
可同时执行的函数，除了excecute函数以外，最多20个。
BulkRequest范例
let kintoneBulkRequest = new kintone.BulkRequest(kintoneConnection);
let responseBulkRequest = kintoneBulkRequest
.addRecord(appID, recordData)
.addRecords(appID, recordsData)
.updateRecordById(appID, updateKey, recordData, revision)
.deleteRecords(appID, recordsData)
.execute()
responseBulkRequest
.then((rsp => = {
console.log(rsp);
})
.catch((err) => {
console.log(err.get());
});App类
这个类里有获取应用信息的方法。
认证的方法不是API令牌认证，而是密码认证。
另外，还需要应用的阅览权限。
关于实现的方法，可以参考下面的文档。
关于App类
https://kintone-labs.github.io/kintone-nodejs-sdk/reference/app/
App范例
let kintoneApp = new kintone.App(kintoneConnection);
let appID = xx;
kintoneAjpp.getApp(appID)
.then((rsp) => {
console.log(rsp);
})
.catch((err) => {
console.log(err.get());
});结束
相信使用了这个SDK以后，即便是对Node.js不是特别了解的人，也可以更方便地运行kintone REST API了。
使用AWS Lambda连接kintone的时候，有各种各样的方法。
到时候请一定好好使用 kintone-nodejs-sdk。
该Tips在2018年5月版中进行过确认。
回复(1)
如果本地网络环境是使用代理服务器链接外网的话，需要在Connection中添加一个RequestOption
let kintoneConnection = new kintone.Connection(myDomainName, kintoneAuth);
kintoneConnection.addRequestOption('proxy', '{代理服务器地址}');
let kintoneRecord = new kintone.Record(kintoneConnection);