kintone JavaScript Client

固定リンクがコピーされました

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

固定リンクがコピーされました

@kintone/rest-api-client（以降、本クライアント）は、kintone REST APIをJavaScriptで扱うときに必要な処理をまとめたライブラリです。
Webブラウザー環境とNode.js環境をサポートしています。
詳細は次のページを参考してください。
@kintone/rest-api-client

本クライアントを使うと、用意されたメソッドを呼び出すだけでkintone REST APIを実行でき、コードの記述量を減らすことができます。
kintoneが提供している次のkintone REST APIのほか、レコードを一括で処理できるメソッドなどの便利なメソッドも用意されています。
kintone REST API

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

コード補完のイメージ

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

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

GitHub

固定リンクがコピーされました

https://github.com/kintone/js-sdk/tree/main/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のREADMEに記載しているCDNサービスunpkg ^*1 のURLを指定してください。
README

本番環境では、新しいバージョンによる意図しない不具合・仕様変更を避けるため、特定のバージョンの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プロパティを確認してください。
package.json

たとえば次の記載の場合、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