(非推奨)kintone JS SDK

目次

caution
警告

このツールは、現在推奨されていません。
新しく公開されている kintone JavaScript Client (@kintone/rest-api-client) を利用してください。

はじめに

2019 年 3 月にリリースされた「kintone JS SDK」について紹介します。
「kintone JS SDK」とは、以前リリースされた「kintone Node.js SDK(β)」や「 kintoneUtility 」の後継となる SDK です。
従来実装されていたメソッドに加え、新たにファイル API に対応するクラスが実装されました。
また、将来的に kintoneUtility に実装されている Upsert や、一括取得などの関数が実装される予定です。

「kintone JS SDK」は「kintone Node.js SDK(β)」や「 kintone iOS SDK 」、「 kintone Java SDK 」と同じ設計思想で設計、実装されています。
そのため、以前まで「kintone Node.js SDK(β)」を使用していた方は、容易に扱える SDK となっています。

GitHub

https://github.com/kintone-labs/kintone-js-sdk/ (External link)

ドキュメント

https://kintone-labs.github.io/kintone-js-sdk/ (External link)

この記事では、kintone JS SDK の導入方法と実行を、サンプルを用いて説明します。
Node.js でも実行可能なので、Node.js で実行できる環境でもお試しください。

Node.js のダウンロード先

https://nodejs.org/ (External link)

注意事項

ソースコードの変更および再配布、商用利用等はライセンスにしたがってご利用可能です。

導入方法

JavaScript

kintone-labs/kintone-js-sdk (External link) から「kintone-js-sdk.min.js」というファイルを保存してください。

webpack

kintone JS SDK を npm インストールし、 webpack でのバンドルも可能ですが、この記事では省略します。
詳しく知りたい方はリファレンスを参照してください。
Install package from npm (External link)

Node.js

下記コマンドを任意のディレクトリーで実行してください。
kintone JS SDK のインストールが可能です。
本記事では「sample_project」というディレクトにインストールします。

1
2
3
mkdir sample_project
cd sample_project
npm install --save @kintone/kintone-js-sdk@v0.6.1

Quickstart Nodejs (External link) にあるように、Node バージョンは 8.9.3 以降、npm バージョン 5.5.1 以降でインストールしてください。

サンプル(JavaScript)

ドキュメントの Quickstart にも掲載されている簡単なサンプルコードを用いて、実行方法とレスポンスについて説明していきます。
サンプルコードでは、kintone アプリからレコードを 1 件取得する機能を実装しています。
準備として、kintone アプリを作成し、下表をもとにフィールドを追加し、閲覧権限を付与した API トークンを作成してください。

フィールドタイプ フィールドコード
文字列 (1行) text

サンプルコード

ファイル名を「sample-for-JavaScript.js」として保存してください。

 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
/*
* kintone JS SDK Sample Program (JavaScript)
* Copyright (c) 2018 Cybozu
*
* Licensed under the MIT License
* https://opensource.org/license/mit/
*/

(function() {
  'use strict';
  kintone.events.on('app.record.index.show', (event) => {

    const kintoneConnection = new kintoneJSSDK.Connection();
    const kintoneRecord = new kintoneJSSDK.Record({connection: kintoneConnection});
    const appId = kintone.app.getId();
    const recordId = 1;

    kintoneRecord.getRecord({app: appId, id: recordId}).then((rsp) => {
      console.log(rsp);
    }).catch((err) => {
      console.log(err.get());
    });

    return event;
  });
})();

kintone アプリに適用

上記のファイルと先ほどダウンロードしたファイルを「アプリの設定 > JavaScript / CSS でカスタマイズ」で以下のように適用します。

実行例

サンプルコードでは、アプリの一覧画面で動作する kintone JavaScript API を使用しているので、アプリの一覧画面に遷移してください。
ブラウザーの開発者ツールを開くと以下のようにレスポンスが確認できます。

サンプル(Node.js)

先ほど作成したアプリを使用します。

サンプルコード

ファイル名を「sample-for-Node.js」として保存してください。

 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 JS SDK Sample Program (Node.js)
* Copyright (c) 2018 Cybozu
*
* Licensed under the MIT License
* https://opensource.org/license/mit/
*/

const kintone = require('@kintone/kintone-js-sdk');

const APIToken = 'xxxxxxxxxxxxxxxxxx'; // your API Token
const basicUserName = 'xxxxx'; // basicAuth user name
const basicPassword = 'xxxxx'; // basicAuth password
const kintoneAuth = new kintone.Auth();
kintoneAuth.setBasicAuth({username: basicUserName, password: basicPassword});
kintoneAuth.setApiToken({apiToken: APIToken});

const domainName = '{subdomain}.cybozu.com';
const kintoneConnection = new kintone.Connection({domain: domainName, auth: kintoneAuth});

const kintoneRecord = new kintone.Record({connection: kintoneConnection});

const appId = 123; // target appID
const recordId = 1;

kintoneRecord.getRecord({app: appId, id: recordId}).then((rsp) => {
  console.log(rsp);
}).catch((err) => {
  // The promise function always reject with KintoneAPIExeption
  console.log(err.get());
});

以下の情報は、ご自身の環境に合わせて書き換えてください。

  • API トークン
  • 認証情報
  • サブドメイン
  • アプリ ID

12〜15 行目はベーシック認証を設定している場合のみ、記載してください。
作成したファイルは、kintone JS SDK インストール時に作成したフォルダー「sample_project」に保存してください。

実行例

先ほどのサンプルコードを保存した「sample_project」で、下記コマンドを実行してください。
エラーが発生する場合は、sample.js が保存されているディレクトリーに、「node_modules」というフォルダーが存在しているか確認してください。

1
node sample-for-Node.js

リクエストが成功すると、次のようなレスポンスが返ってきます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "record": {
    "レコード番号": { "type": "RECORD_NUMBER", "value": "1" },
    "更新者": {
      "type": "MODIFIER",
      "value": { "code": "Administrator", "name": "Administrator" }
    },
    "作成者": {
      "type": "CREATOR",
      "value": { "code": "Administrator", "name": "Administrator" }
    },
    "text": { "type": "SINGLE_LINE_TEXT", "value": "sample" },
    "$revision": { "type": "__REVISION__", "value": "1" },
    "更新日時": { "type": "UPDATED_TIME", "value": "2019-03-26T05:36:00Z" },
    "作成日時": { "type": "CREATED_TIME", "value": "2019-03-26T05:36:00Z" },
    "$id": { "type": "__ID__", "value": "1" }
  }
}

サンプルコード解説

JavaScript としての kintone JS SDK も Node.js としての kintone JS SDK もほとんど同様の書き方をするので Node.js のサンプルコードをもとにコード解説します。

Authentication

サンプルコード 9〜16 行目についての解説です。
この部分では、kintone に接続するための、認証方法について定義します。

 9
10
11
12
13
14
15
16
const kintone = require('@kintone/kintone-js-sdk');

const APIToken = 'xxxxxxxxxxxxxxxxxx'; // your API Token
const basicUserName = 'xxxxx'; // basicAuth user name
const basicPassword = 'xxxxx'; // basicAuth password
const kintoneAuth = new kintone.Auth();
kintoneAuth.setBasicAuth({username: basicUserName, password: basicPassword});
kintoneAuth.setApiToken({apiToken: APIToken});

Authentication クラスがあり、パスワード認証、API トークン認証、Basic 認証を設定できます。
認証の優先度は以下のとおりです。
参考: 認証の優先順位

  1. パスワード認証
  2. API トークン認証
  3. セッション認証(ブラウザー上のみ)

また、セッション認証を使用する場合、「sample-for-JavaScript.js」のように Auth() を宣言する必要はありません。

パスワード認証
1
2
3
const username = 'your user name';
const password = 'your password';
kintoneAuth.setPasswordAuth({username: username, password: password});
API トークン認証
1
2
const apiTokenString = 'your token';
kintoneAuth.setApiToken({apiToken: apiTokenString});
Basic 認証
1
2
3
const basicUserName = 'your user name';
const basicPassword = 'your password';
kintoneAuth.setBasicAuth({username: basicUserName, password: basicPassword});

Connection

18 行目と 19 行目の Connection クラスでは、接続について設定できます。
接続先のドメイン情報と、先ほど作成した認証情報を使って kintone 環境に接続します。

通常のスペースの場合
18
19
const domainName = '{subdomain}.cybozu.com';
const kintoneConnection = new kintone.Connection({domain: domainName, auth: kintoneAuth});
ゲストスペースの場合
1
2
3
4
// for GuestSpace
const domainName = '{subdomain}.cybozu.com';
const guestSpaceID = '123';
const kintoneConnection = new kintone.Connection({domain: domainName, auth: kintoneAuth, guestSpaceID: guestSpaceID});

セッション認証の場合は「sample-for-JavaScript.js」のように引数指定する必要はありません。
ブラウザー上で動作するが、セッション認証以外の認証方式を使う場合は、次のように実装する必要があります。

1
2
3
const kintoneAuth = new kintoneJSSDK.Auth();
kintoneAuth.setPasswordAuth({username: 'xxxx', password: 'xxxxx'});
const kintoneConnection = new kintoneJSSDK.Connection({auth: kintoneAuth});

サーバー側と違い、他のサブドメインは指定できません。

Record

最後に、21〜31 行目についてです。

21
22
23
24
25
26
27
28
29
30
const kintoneRecord = new kintone.Record({connection: kintoneConnection});

const appId = 123; // target appID
const recordId = 1;

kintoneRecord.getRecord({app: appId, id: recordId}).then((rsp) => {
  console.log(rsp);
}).catch((err) => {
  console.log(err.get());
});

この部分は、実際に kintone の REST API を実行する処理です。
サンプルでは、レコードを 1 件取得するために、Record クラスの getRecord 関数を使用しています。

getRecord 関数には次の引数を指定します。

名称 データタイプ 必須 説明
app Integer アプリ ID
id Integer レコード ID

Record クラスには、後述のとおりレコード 1 件取得以外にも、さまざまな関数が用意されています。

その他の機能について

Record クラス

先ほどのサンプルコードで使用した関数が定義されているクラスです。
アプリのレコードに対し、取得/登録/更新/削除、/ステータスの変更を実施する関数や、コメントの取得/登録/削除を実施する関数が実装されています。
実装されている関数の例として、次の関数が実装されています。

  • getRecord
  • getRecords
  • addRecord
  • addRecords
  • updateRecords
  • deleteRecords
  • updateRecordStatus
  • getComments
  • addComment
  • deleteComment

他にもさまざまな関数が用意されています。
詳細はドキュメントを確認してください。
Record (External link)

BulkRequest クラス

複数のアプリに対して、同時に複数の API をリクエストできます。
BulkRequest クラスで使用できる関数は次のドキュメントを確認してください。
Bulk Request (External link)

また、BulkRequest を実行する際は次のことに注意してください。

  • BulkRequest を実行しレスポンスを取得する場合は、 execute (External link) 関数を実行する。
  • 一度に実行できる関数は、excecute 関数をのぞいて 20 個まで。
BulkRequest サンプル
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
const kintoneBulkRequest = new kintone.BulkRequest({connection: kintoneConnection});

const responseBulkRequest = kintoneBulkRequest
  .addRecord({app: appId, record: recordData})
  .addRecords({app: appId, records: recordsData})
  .updateRecordByID({app: appId, id: recordId, record: recordData})
  .deleteRecords({app: appId, ids: recordIds})
  .execute();

responseBulkRequest.then((rsp) => {
  console.log(rsp);
}).catch((err) => {
  console.log(err.get());
});

App クラス

アプリの情報を取得する関数が定義されているクラスです。
API トークン認証ではなく、パスワード認証が必要です。
また、アプリの閲覧権限が必要です。

App クラスで使用できる関数は次のドキュメントを確認してください。
App (External link)

App サンプル
1
2
3
4
5
6
7
8
const kintoneApp = new kintone.App({connection: kintoneConnection});

const appId = 123;
kintoneApp.getApp({id: appId}).then((rsp) => {
  console.log(rsp);
}).catch((err) => {
  console.log(err.get());
});

File クラス

ファイル API に対応する関数が定義されているクラスです。
File クラスで使用できる関数は次のドキュメントを確認してください。
File (External link)

File サンプル
1
2
3
4
5
6
7
8
9
const kintoneFile = new kintone.File({connection: kintoneConnection});

const fileDownloadKey = 'your_file_Key';
const outPutFileDownloadPath = 'you_file_path';
kintoneFile.download({fileKey: fileDownloadKey, outPutFilePath: outPutFileDownloadPath}).then((rsp) => {
  console.log(rsp);
}).catch((err) => {
  console.log(err.get());
});

おわりに

Node.js SDK(β)や iOS SDK、Java SDK での実装経験の有無にかかわらず、簡単に実装できたかと思います。
今後、kintoneUtility との機能差分や、独自の関数を実装予定です。
この機会に kintone JS SDK をご活用ください。

information

この Tips は、2019 年 3 月版 kintone で動作を確認しています。