中文
Index
概要
@kintone/rest-api-client 是指对使用JavaScript语言进行kintone REST API自定义时的一些必要处理进行了封装的库。
有了@kintone/rest-api-client（以下称本Client），您只要调用此库提供的方法，即可执行kintone REST API，可以大大减少代码量。
除了kintone中可使用的REST API 之外，还提供了可对记录进行批量处理的方法等非常便利的方法。
另外，本Client还封装了TypeScript，使用Visual Studio Code等功能强大的编辑器时，会自动补全代码。
代码补全功能
您只要写一部分代码，就会根据可使用的方法的候补来自动补全。
还会显示要传递给方法的参数信息。
本文将介绍本Client的导入方法及基本的使用方法。
关于本Client提供的各方法请参考文档。
GitHub
https://github.com/kintone/js-sdk/tree/master/packages/rest-api-client
许可证
MIT 许可证
文档
导入方法
浏览器环境（导入）
通过浏览器使用时，通过指定Cybuzo CDN里的URL导入本Client。如要应用到kintone的应用里，需要在“通过JavaScript / CSS自定义”页面进行指定。
例）版本1.4.0时指定如下URL
https://js.cybozu.cn/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js
最新版本的URL请参考Cybozu CDN。
另外，Cybozu CDN是定期更新的（非实时更新），因此可能上面显示的最新版本与实际最新版本不一样。
如想使用实际最新发布的版本，请使用GitHub 上的CDN服务unpkg 的URL。
※ unpkg非才望子提供的CDN服务。
※最新版本上可能会发生诸如缺陷、规格更改等意料之外的事情，如要在正式环境中使用，推荐使用特定版本的URL。
导入CDN后，将作为全局对象自动添加KintoneRestAPIClient。
Node.js环境（导入）
通过Node.js使用时，在项目的根目录下执行以下命令。
$ npm install @kintone/rest-api-client
※ 对于Node.js的版本要求，请参考仓库里的package.json内的engines属性。
例：如果是像下面这样的记述，说明Node.js的版本需要10以上。"engines": { "node": ">=10" },用require导入。
const { KintoneRestAPIClient } = require("@kintone/rest-api-client");
Quick Start
主要介绍浏览器环境和Node.js环境下本Client的使用方法。各方法的详情请参考文档。
浏览器环境（Quick Start）
以下是打开记录列表页面时，自动获取kintone的记录，并将获取的内容输出到console中的例子。
kintone应用的准备
新建kintone应用，应用中添加单行文本框。
添加1条记录，作为测试数据。
编写范例代码
将以下内容粘贴到文本编辑器里。
/* * kintone JavaScript Client sample program (for kintone environment) * Copyright (c) 2020 Cybozu * * Licensed under the MIT License * https://opensource.org/licenses/mit-license.php */ (function() { 'use strict'; kintone.events.on('app.record.index.show', function(event) { // 创建Client var client = new KintoneRestAPIClient(); // 设置请求参数 var APP_ID = kintone.app.getId(); var RECORD_ID = 1; var params = { app: APP_ID, id: RECORD_ID }; // 获取记录 client.record.getRecord(params).then(function(resp) { var record = resp.record; console.log(record); }).catch(function(err) { console.log(err); }); }); })();上面代码复制到文本编辑器，文字编码选择“UTF-8”，文件扩展名为“js”，保存文件。
此例子中，将文件另存为“kintone-rest-api-sample.js”。
上传到kintone应用
打开刚才准备的kintone应用。
依次点击“更改应用的设置” > “通过JavaScript / CSS自定义”，打开“通过JavaScript / CSS自定义”页面。
输入以下内容。输入结束后，点击“保存”按钮。
项目 值 JavaScript文件（电脑专用） 按如下顺序指定。
● https://js.cybozu.com/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js
● 范例代码（kintone-rest-api-sample.js）
在“应用的设置”页面点击“更新应用”按钮。
动作确认
打开应用的列表。
打开浏览器的开发者工具，可以看到返回应答（记录的获取结果）。
Node.js环境（Quick Start）
以下是获取kintone的记录，并将获取的内容显示到console的例子。
准备kintone应用
新建kintone应用，添加单行文本框。
添加1条记录，作为测试数据。
范例代码
编写如下JavaScript文件，保存为“kintone-rest-api-sample.js”。
/*
* kintone JavaScript Client sample program (for Node.js)
* Copyright (c) 2020 Cybozu
*
* Licensed under the MIT License
* https://opensource.org/licenses/mit-license.php
*/
'use strict';
const { KintoneRestAPIClient } = require('@kintone/rest-api-client');
// 创建Client
const client = new KintoneRestAPIClient({
baseUrl: 'https://{subdomain}.cybozu.cn',
auth: {
username: process.env.KINTONE_USERNAME,
password: process.env.KINTONE_PASSWORD
}
});
// 设置请求参数
const APP_ID = 1;
const RECORD_ID = 1;
const params = {
app: APP_ID,
id: RECORD_ID
};
// 获取记录
client.record.getRecord(params).then((resp) => {
console.log(resp.record);
}).catch((err) => {
console.log(err);
});如下在环境变量里设置kintone的登录名和密码。
export KINTONE_USERNAME=kintone的登录ID export KINTONE_PASSWORD=kintone的密码
请更改代码内的如下值。
{subdomain}：您的kintone环境子域名
APP_ID：刚才创建的kintone应用的应用ID
动作确认
执行以下命令。
$ node kintone-rest-api-sample.js
可以看到记录的内容被获取过来。
{
$id: {type: "__ID__", value: "1"}
$revision: {type: "__REVISION__", value: "1"}
创建人: {type: "CREATOR", value: {…}}
创建时间: {type: "CREATED_TIME", value: "2020-05-29T01:36:00Z"}
更新人: {type: "MODIFIER", value: {…}}
更新时间: {type: "UPDATED_TIME", value: "2020-05-29T01:36:00Z"}
用户名称: {type: "SINGLE_LINE_TEXT", value: "A"}
记录编号: {type: "RECORD_NUMBER", value: "1"}
}关于验证
本Client可支持密码验证、API令牌验证、OAuth客户端验证以及会话验证。
验证信息通过KintoneRestAPIClient的参数对象的 auth属性来传递。
以下例子是在Node.js环境下（除了会话验证），从环境变量读取验证信息。
在浏览器环境下使用时，请不要将验证信息直接写在JavaScript文件里。
详情请参考安全编码指南。
密码验证
使用密码验证时，在auth属性里指定username和password。
const client = new KintoneRestAPIClient({
auth: {
username: process.env.KINTONE_USERNAME,
password: process.env.KINTONE_PASSWORD
},
...略...
});API 令牌验证
使用API令牌验证时，在auth属性里指定apiToken。
const client = new KintoneRestAPIClient({
auth: {
apiToken: process.env.KINTONE_API_TOKEN
},
...略...
});OAuth客户端验证
使用OAuth客户端进行验证时，在oAuthToken属性里指定访问令牌。
关于创建OAuth客户端和获取访问令牌的方法，请参考使用OAuth客户端。
const client = new KintoneRestAPIClient({
auth: {
oAuthToken: process.env.KINTONE_OAUTH_TOKEN
},
...略...
});会话验证
使用会话验证时，省略auth属性。
※ 会话验证仅可适用于将自定义文件上传到kintone环境的情况。
const client = new KintoneRestAPIClient();
设置了安全访问的环境
也可设置Basic验证信息和客户证书。
设置Basic验证
如您的kintone环境使用了Basic验证，需要在KintoneRestAPIClient的参数对象中添加 basicAuth属性。
const client = new KintoneRestAPIClient({
...略...,
basicAuth: { // 设置Basic验证
username: process.env.KINTONE_BASIC_USERNAME,
password: process.env.KINTONE_BASIC_PASSWORD
},
...略...
});设置客户证书
如您的kintone环境设置了SecureAccess，要在KintoneRestAPIClient的参数对象中添加clientCertAuth属性，然后指定客户证书。
关于客户证书的指定方法，可在pfx属性中指定二进制数据，也可以在pfxFilePath属性中指定文件路径。
指定二进制的方法
const client = new KintoneRestAPIClient({ ...略..., clientCertAuth: { pfx: certData, password: process.env.KINTONE_CLIENT_CERTIFICATE_PASSWORD }, ...略... });指定文件路径的方法
const client = new KintoneRestAPIClient({ ...略..., clientCertAuth: { pfxFilePath: './cert.pfx', password: process.env.KINTONE_CLIENT_CERTIFICATE_PASSWORD }, ...略... });
最后
综上所述，使用@kintone/rest-api-client可以帮助您在用JavaScript对kintone REST API进行操作时更加便利。
关于@kintone/rest-api-client 提供的方法及其使用方法，请参考文档。
更新履历
请参考此页面以获取库的更新信息。
此Tips用2020年7月版 kintone以及@kintone/rest-api-client v1.4.0 确认过。
