kintone JavaScript Client

kintone JavaScript Client（@kintone/rest-api-client）とは

@kintone/rest-api-client は、 kintone REST API を JavaScript で扱うときに必要な処理をまとめたライブラリです。
@kintone/rest-api-client（以降、本クライアント）を使うと、用意されたメソッドを呼び出すだけで kintone REST API を実行でき、コードの記述量を減らすことができます。
kintone が提供している kintone REST API のほか、レコードを一括で処理できるメソッドなどの便利なメソッドも用意されています。

本クライアントは TypeScript で実装されており、Visual Studio Code などの高機能エディタを利用すると、コード補完ができます。

コード補完のイメージ

コードの一部を書くと、自動で利用できるメソッドの候補が表示されます。
メソッドに渡すパラメーターの情報も表示されます。

この記事では、本クライアントの導入方法や基本的な使い方について説明します。
本クライアントが提供する各メソッドについては、ドキュメントを参照してください。

GitHub

https://github.com/kintone/js-sdk/tree/master/packages/rest-api-client

ライセンス

MIT ライセンス

ドキュメント

導入方法

ブラウザー環境

ブラウザー環境で利用する場合、Cybozu CDN の URL を指定して本クライアントを読み込みます。
kintone アプリに適用する場合は、「JavaScript / CSS でカスタマイズ」画面で指定します。

たとえば、バージョン 1.4.0 の場合、次の URL を指定します。
https://js.cybozu.com/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js

Cybozu CDN で公開しているバージョンは、 Cybozu CDN を参照してください。

Cybozu CDN は定期更新のため、ライブラリの最新バージョンと一致していない可能性があります。
最新バージョンを利用したい場合は、 GitHub 記載の CDN サービス unpkg ^*1 の URL を指定してください。
本番環境では、新しいバージョンによる意図しない不具合・仕様変更を避けるため、特定のバージョンの URL を読み込むことをおすすめします。

CDN を読み込むと、グローバルオブジェクトとして kintoneRestAPIClient が追加されます。

^*1 unpkg はサイボウズが提供している CDN サービスではありません。 ^

Node.js 環境

Node.js で利用する場合、プロジェクトのルート配下で次のコマンドを実行します。

1

npm install @kintone/rest-api-client

必要な Node.js のバージョンは、リポジトリの packages/rest-api-client/package.json にある engines プロパティを確認してください。
たとえば次の記載の場合、Node.js のバージョン 14 以上が必要です。

1
2
3


"engines": {
  "node": ">=14"
},

ソースコードでは、require を使って読み込みます。

1

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

Quick Start

ブラウザー環境と Node.js 環境における、本クライアントの使い方です。
メソッドの詳細は、ドキュメントを参照してください。

ブラウザ環境
Node.js 環境

ブラウザー環境

レコード一覧画面を開いたときに、kintone のレコードを取得し、取得した内容をコンソールに出力する例です。

Step1：kintone アプリの準備

文字列（1 行）フィールドを追加し、kintone アプリを作成します。
作成したアプリで API トークンを生成します。
手順の詳細は、 API トークンを生成するを参照してください。
テストデータとして、1 件のレコードを追加します。
作成したレコードの URL で、レコード ID を確認します。
URL の https://sample.cybozu.com/k/123/show#record=1 の record= の後の数字部分が、レコード ID です。
上記の場合、レコード ID は、「1」です。

Step2：サンプルコードの作成

次の内容をテキストエディタに貼り付けます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


/*
* kintone JavaScript Client sample program (for kintone environment)
* Copyright (c) 2020 Cybozu
*
* Licensed under the MIT License
* https://opensource.org/license/mit/
*/

(() => {
  'use strict';
  kintone.events.on('app.record.index.show', async (event) => {
    try {
      // クライアントの作成
      const client = new KintoneRestAPIClient();

      // リクエストパラメータの設定
      const APP_ID = kintone.app.getId();
      const RECORD_ID = 1;
      const params = {
        app: APP_ID,
        id: RECORD_ID
      };

      // レコードの取得
      const resp = await client.record.getRecord(params);
      console.log(resp.record);
    } catch (err) {
      console.log(err);
    }
  });
})();

文字コードを「UTF-8」、ファイルの拡張子を「.js」にしてファイルを保存します。
この記事ではファイル名を「kintone-rest-api-sample.js」としています。

Step3：kintoneアプリに適用

STEP1 で作成したアプリに、kintone カスタマイズファイルを適用します。
手順の詳細は、 JavaScriptやCSSでアプリをカスタマイズするを確認してください。

次の順番で、「PC 用の JavaScript ファイル」に URL とファイルを指定します。
1. https://js.cybozu.com/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js
2. サンプルコード（kintone-rest-api-sample.js）
「アプリの設定」画面で、【アプリを更新】をクリックします。

Step4：動作確認

カスタマイズを適用したアプリの一覧画面を開きます。
ブラウザーの開発者ツールを開きます。
レスポンス（レコードの取得結果）が出力されていることを確認します。

Node.js環境

kintone のレコードを取得し、取得した内容をコンソールに出力する例です。

Step1：kintone アプリの準備

文字列（1 行）フィールドを追加し、kintone アプリを作成します。
作成したアプリで API トークンを生成します。
手順の詳細は、 API トークンを生成するを参照してください。
テストデータとして、1 件のレコードを追加します。
作成したレコードの URL で、レコード ID を確認します。
URL の https://sample.cybozu.com/k/123/show#record=1 の record= の後の数字部分が、レコード ID です。
上記の場合、レコード ID は、「1」です。

Step2：必要なパッケージのインストール

プロジェクトのディレクトリーを作成します。ここでは、例として「sample」というディレクトリー名にします。
1

mkdir sample
プロジェクトのディレクトリーに移動し、kintone JavaScript Client をインストールします。
1 2 3

cd sample npm init -y npm install @kintone/rest-api-client

Step3：サンプルコードの作成

次の内容をテキストエディタに貼り付けます。次の内容は、環境に応じて書き換えてください。

16 行目：ドメイン名
23 行目：作成したアプリのアプリ ID

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


/*
* kintone JavaScript Client sample program (for Node.js)
* Copyright (c) 2020 Cybozu
*
* Licensed under the MIT License
* https://opensource.org/license/mit/
*/

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

(async () => {
  try {
    // クライアントの作成
    const client = new KintoneRestAPIClient({
      baseUrl: 'https://sample.cybozu.com',
      auth: {
        apiToken: process.env.KINTONE_API_TOKEN
      }
    });

    // リクエストパラメータの設定
    const APP_ID = 1;
    const RECORD_ID = 1;
    const params = {
      app: APP_ID,
      id: RECORD_ID
    };

    // レコードの取得
    const resp = await client.record.getRecord(params);
    console.log(resp.record);
  } catch (err) {
    console.log(err);
  }
})();

文字コードを「UTF-8」、ファイルの拡張子を「.js」にして、「sample」ディレクトリーの中にファイルを保存します。
この記事ではファイル名を「kintone-rest-api-sample.js」としています

Step4：動作確認

環境変数に API トークンを設定します。API_TOKEN は、STEP1 で生成した API トークンに置き換えてください
- Windows のコマンドプロンプトの場合
  1
  
  SET KINTONE_API_TOKEN=API_TOKEN
- macOS の場合
  1
  
  export KINTONE_API_TOKEN=API_TOKEN
「samples」の下で、次のコマンドを実行します。
1

node kintone-rest-api-sample.js

取得したレコードの中身が出力されることを確認します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
  "レコード番号": { "type": "RECORD_NUMBER", "value": "1" },
  "更新者": {
    "type": "MODIFIER",
    "value": { "code": "yamda", "name": "山田太郎" }
  },
  "作成者": {
    "type": "CREATOR",
    "value": { "code": "yamada", "name": "山田太郎" }
  },
  "$revision": { "type": "REVISION", "value": "2" },
  "更新日時": { "type": "UPDATED_TIME", "value": "2020-05-13T04:24:00Z" },
  "作成日時": { "type": "CREATED_TIME", "value": "2020-02-28T04:13:00Z" },
  "$id": { "type": "ID", "value": "1" }
}

補足事項

認証

本クライアントでは、パスワード認証、API トークン認証、OAuth クライアントを利用した認証、およびセッション認証に対応しています。

認証情報は、kintoneRestAPIClient の引数オブジェクトの auth プロパティで設定します。

以降の例では、Node.js での利用を想定して（セッション認証を除く）、環境変数から認証情報を読み込んでいます。
ブラウザー環境から利用する場合、認証情報を JavaScript ファイルにハードコーディングしないでください。
詳細はセキュアコーディングガイドラインを参照してください。

パスワード認証

パスワード認証の場合、auth プロパティに username と password を指定します。

1
2
3
4
5
6
7


const client = new KintoneRestAPIClient({
  auth: {
    username: process.env.KINTONE_USERNAME,
    password: process.env.KINTONE_PASSWORD
  },
  // ...略...
});

APIトークン認証

API トークン認証の場合、auth プロパティに apiToken を指定します。

1
2
3
4
5
6


const client = new KintoneRestAPIClient({
  auth: {
    apiToken: process.env.KINTONE_API_TOKEN
  },
  // ...略...
});

OAuthクライアントを利用した認証

OAuth クライアントを利用して認証する場合、oAuthToken プロパティに、アクセストークンを指定します。
OAuth クライアントの作成やアクセストークンの取得方法は、 OAuth クライアントを参照してください。

1
2
3
4
5
6


const client = new KintoneRestAPIClient({
  auth: {
    oAuthToken: process.env.KINTONE_OAUTH_TOKEN
  },
  // ...略...
});

セッション認証

セッション認証の場合、auth プロパティを省略します。
セッション認証は、kintone 環境にカスタマイズファイルを適用する場合のみ利用できます。

1

const client = new KintoneRestAPIClient();

セキュリティ設定を行った環境

Basic 認証情報やクライアント証明書も設定できます。

Basic 認証を設定している環境の場合

kintone 環境で Basic 認証を利用している場合、kintoneRestAPIClient の引数オブジェクトに basicAuth プロパティを追加します。

1
2
3
4
5
6
7
8


const client = new KintoneRestAPIClient({
  // ...略...,
  basicAuth: { // Basic 認証の設定
    username: process.env.KINTONE_BASIC_USERNAME,
    password: process.env.KINTONE_BASIC_PASSWORD
  },
  // ...略...
});

セキュアアクセスを設定している環境の場合

セキュアアクセスを kintone 環境に設定している場合、kintoneRestAPIClient の引数オブジェクトに clientCertAuth プロパティを追加して、クライアント証明書を指定します。

クライアント証明書を指定する方法は、pfx プロパティにバイナリデータを指定する方法と、pfxFilePath プロパティにファイルパスを指定する方法があります。

バイナリデータで指定する方法

1
2
3
4
5
6
7
8


const client = new KintoneRestAPIClient({
  // ...略...,
  clientCertAuth: {
    pfx: certData,
    password: process.env.KINTONE_CLIENT_CERTIFICATE_PASSWORD
  },
  // ...略...
});

ファイルパスで指定する方法

1
2
3
4
5
6
7
8


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 で提供されるメソッドやその使い方の詳細は、ドキュメントを参照してください。

更新履歴

ライブラリのアップデート情報は、ライブラリの CHANGELOG を参照してください。

この記事で紹介しているサンプルコードは、2020 年 7 月版 kintone および @kintone/rest-api-client v1.4.0 で動作を確認しています。

SDK & Tools