kintone JavaScript Client

目次

kintone JavaScript Client(@kintone/rest-api-client)とは

@kintone/rest-api-client (External link) は、kintone REST APIをJavaScriptで扱うときに必要な処理をまとめたライブラリです。
@kintone/rest-api-client(以降、本クライアント)は、Webブラウザー環境とNode.js環境をサポートしています。

本クライアントを使うと、用意されたメソッドを呼び出すだけでkintone REST APIを実行でき、コードの記述量を減らすことができます。
kintoneが提供している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 (External link) 記載の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 (External link) にあるenginesプロパティを確認してください。
たとえば次の記載の場合、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で動作を確認しています。