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 (External link)

本クライアントを使うと、用意されたメソッドを呼び出すだけで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 (External link)

ライセンス

MITライセンス (External link)

ドキュメント

導入方法

ブラウザー環境

ブラウザー環境で利用する場合、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 (External link)

本番環境では、新しいバージョンによる意図しない不具合・仕様変更を避けるため、特定のバージョンの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 (External link)

たとえば次の記載の場合、Node.jsのバージョン14以上が必要です。

1
2
3
"engines": {
  "node": ">=14"
},

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

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

Quick Start

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

ブラウザー環境

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

Step1:kintoneアプリの準備
  1. 文字列(1行)フィールドを追加し、kintoneアプリを作成します。

  2. 作成したアプリでAPIトークンを生成します。
    手順の詳細は、次のページを参照してください。
    APIトークンを生成する (External link)

  3. テストデータとして、1件のレコードを追加します。

  4. 作成したレコードのURLで、レコードIDを確認します。
    URLのhttps://sample.cybozu.com/k/123/show#record=1record=の後の数字部分が、レコードIDです。
    上記の場合、レコードIDは、「1」です。

Step2:サンプルコードの作成
  1. 次の内容をテキストエディタに貼り付けます。

     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);
        }
      });
    })();
  2. 文字コードを「UTF-8」、ファイルの拡張子を「.js」にしてファイルを保存します。
    この記事ではファイル名を「kintone-rest-api-sample.js」としています。

Step3:kintoneアプリに適用

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

  1. 次の順番で、「PC用のJavaScriptファイル」にURLとファイルを指定します。

    1. https://js.cybozu.com/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js
    2. サンプルコード(kintone-rest-api-sample.js)
  2. 「アプリの設定」画面で、【アプリを更新】をクリックします。

Step4:動作確認
  1. カスタマイズを適用したアプリの一覧画面を開きます。

  2. ブラウザーの開発者ツールを開きます。

  3. レスポンス(レコードの取得結果)が出力されていることを確認します。

Node.js環境

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

Step1:kintoneアプリの準備
  1. 文字列(1行)フィールドを追加し、kintoneアプリを作成します。

  2. 作成したアプリでAPIトークンを生成します。
    手順の詳細は、次のページを参照してください。
    APIトークンを生成する (External link)

  3. テストデータとして、1件のレコードを追加します。

  4. 作成したレコードのURLで、レコードIDを確認します。
    URLのhttps://sample.cybozu.com/k/123/show#record=1record=の後の数字部分が、レコードIDです。
    上記の場合、レコードIDは、「1」です。

Step2:必要なパッケージのインストール
  1. プロジェクトのディレクトリを作成します。ここでは、例として「sample」というディレクトリ名にします。

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

    1
    2
    3
    
    cd sample
    npm init -y
    npm install @kintone/rest-api-client
Step3:サンプルコードの作成
  1. 次の内容をテキストエディタに貼り付けます。次の内容は、環境に応じて書き換えてください。

    • 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);
      }
    })();
  2. 文字コードを「UTF-8」、ファイルの拡張子を「.js」にして、「sample」ディレクトリの中にファイルを保存します。
    この記事ではファイル名を「kintone-rest-api-sample.js」としています

Step4:動作確認
  1. 環境変数にAPIトークンを設定します。
    API_TOKENは、STEP1で生成したAPIトークンに置き換えてください。

    • Windowsのコマンドプロンプトの場合

      1
      
      SET KINTONE_API_TOKEN=API_TOKEN
    • macOSの場合

      1
      
      export KINTONE_API_TOKEN=API_TOKEN
  2. 「samples」の下で、次のコマンドを実行します。

    1
    
    node kintone-rest-api-sample.js
  3. 取得したレコードの中身が出力されることを確認します。

     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 (External link)

information

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