kintone API SDK(β) for Node.js

cybozu发表于:2018年05月30日 10:29:04更新于:2018年06月01日 11:39:14

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/kintone-nodejs-sdk/

文档

https://kintone.github.io/kintone-nodejs-sdk/

接下来将用例子给大家介绍 kintone-node.js-sdk 的导入和执行方法。
大家可以在可运行Node.js的环境里尝试一下。

Node.js

https://nodejs.org/zh-cn/

注意事项

  • 本范例程序,不保证运行绝对正确。

  • 关于代码的更改、再发布以及商业用途,请遵照相应的使用许可协议。

导入方法

安装

任意目录下执行下面的命令,安装 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.com';
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.com';    
let kintoneConnection = new kintone.Connection(myDomainName, kintoneAuth);  


// for GuestSpace    
let myDomainName = '{subdomain}.cybozu.com';    
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)

参数

名称数据类型必须说明
appIDInteger应用ID
recordIDInteger记录编号

Record类里,除了获取1条记录的方法外,还有其他的方法。

关于其他方法

Record类

这是之前范例代码里所使用方法的类。
针对应用的记录,有获取、添加、编辑、删除、状态变更的方法,
也有获取、添加、删除回复的方法。
具体的方法,可以参考以下这些。

  • getRecord

  • getRecords

  • addRecord

  • addRecords

  • updateRecords

  • deleteRecords

  • updateRecordStatus

  • getComments

  • addComment

  • deleteComment

当然还有很多其他的方法。具体可以参考文档。

关于Record类

https://kintone.github.io/kintone-nodejs-sdk/reference/record/

BulkRequest类

可以对多个应用,同时请求多个API。
BulkRequest中可以使用的方法可以参考下面的文档。

关于BulkRequest类

https://kintone.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.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)

  • dd000

    如果本地网络环境是使用代理服务器链接外网的话,需要在Connection中添加一个RequestOption

    let kintoneConnection = new kintone.Connection(myDomainName, kintoneAuth);
    kintoneConnection.addRequestOption('proxy', '{代理服务器地址}');

    let kintoneRecord = new kintone.Record(kintoneConnection);

您需要登录后才可以回复