kintone JavaScript Client (@kintone/rest-api-client)(推荐使用)

aki发表于:2020年05月29日 13:59:00更新于:2024年06月03日 14:05:11

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等功能强大的编辑器时,会自动补全代码。

代码补全功能

  • 您只要写一部分代码,就会根据可使用的方法的候补来自动补全。

  • 还会显示要传递给方法的参数信息。

 0015ed5fa3662c6ff59f22d2de7578d

本文将介绍本Client的导入方法及基本的使用方法。
关于本Client提供的各方法请参考文档

GitHub

https://github.com/kintone/js-sdk/tree/main/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环境(导入)

  1. 通过Node.js使用时,在项目的根目录下执行以下命令。

    $ npm install @kintone/rest-api-client

    ※ 对于Node.js的版本要求,请参考仓库里的package.json内的engines属性。
    例:如果是像下面这样的记述,说明Node.js的版本需要10以上。

    "engines": {    
      "node": ">=10"    
    },
  2. 用require导入。

    const { KintoneRestAPIClient } = require("@kintone/rest-api-client");

Quick Start

主要介绍浏览器环境和Node.js环境下本Client的使用方法。各方法的详情请参考文档

浏览器环境(Quick Start)

以下是打开记录列表页面时,自动获取kintone的记录,并将获取的内容输出到console中的例子。

kintone应用的准备

  1. 新建kintone应用,应用中添加单行文本框。

  2. 添加1条记录,作为测试数据。

编写范例代码

  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);
        });
      });
    })();
  2. 上面代码复制到文本编辑器,文字编码选择“UTF-8”,文件扩展名为“js”,保存文件。
    此例子中,将文件另存为“kintone-rest-api-sample.js”。

上传到kintone应用

  1. 打开刚才准备的kintone应用。

  2. 依次点击“更改应用的设置” > “通过JavaScript / CSS自定义”,打开“通过JavaScript / CSS自定义”页面。

  3. 输入以下内容。输入结束后,点击“保存”按钮。

    项目
    JavaScript文件(电脑专用)

    按如下顺序指定。

     ● https://js.cybozu.com/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js

     ● 范例代码(kintone-rest-api-sample.js)

  4. 在“应用的设置”页面点击“更新应用”按钮。

动作确认

打开应用的列表。
打开浏览器的开发者工具,可以看到返回应答(记录的获取结果)。
0015ed5ea8da81fc801452e2283cf50

Node.js环境(Quick Start)

以下是获取kintone的记录,并将获取的内容显示到console的例子。

准备kintone应用

  1. 新建kintone应用,添加单行文本框。

  2. 添加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 确认过。