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となっています。
https://github.com/kintone-labs/kintone-js-sdk/
https://kintone-labs.github.io/kintone-js-sdk/
この記事では、kintone JS SDKの導入方法と実行を、サンプルを用いて説明します。
Node.jsでも実行可能なので、Node.jsで実行できる環境でもお試しください。
Node.js のダウンロード先
固定リンクがコピーされました
https://nodejs.org/
ソースコードの変更および再配布、商用利用等はライセンスにしたがってご利用可能です。
JavaScript
固定リンクがコピーされました
kintone-labs/kintone-js-sdk
から「kintone-js-sdk.min.js」というファイルを保存してください。
webpack
kintone JS SDKをnpmインストールし、webpackでのバンドルも可能ですが、この記事では省略します。
詳しく知りたい方はリファレンスを参照してください。
Install package from npm
下記コマンドを任意のディレクトリーで実行してください。
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
にあるように、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認証を設定できます。
認証の優先度は以下のとおりです。
参考:
認証の優先順位
- パスワード認証
- APIトークン認証
- セッション認証(ブラウザー上のみ)
また、セッション認証を使用する場合、「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});
|
サーバー側と違い、他のサブドメインは指定できません。
最後に、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件取得以外にも、さまざまな関数が用意されています。
その他の機能について
固定リンクがコピーされました
先ほどのサンプルコードで使用した関数が定義されているクラスです。
アプリのレコードに対し、取得/登録/更新/削除、/ステータスの変更を実施する関数や、コメントの取得/登録/削除を実施する関数が実装されています。
実装されている関数の例として、次の関数が実装されています。
- getRecord
- getRecords
- addRecord
- addRecords
- updateRecords
- deleteRecords
- updateRecordStatus
- getComments
- addComment
- deleteComment
他にもさまざまな関数が用意されています。
詳細はドキュメントを確認してください。
Record
BulkRequest クラス
固定リンクがコピーされました
複数のアプリに対して、同時に複数のAPIをリクエストできます。
BulkRequest
クラスで使用できる関数は次のドキュメントを確認してください。
Bulk Request
また、BulkRequestを実行する際は次のことに注意してください。
- BulkRequestを実行しレスポンスを取得する場合は、
execute
関数を実行する。
- 一度に実行できる関数は、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());
});
|
アプリの情報を取得する関数が定義されているクラスです。
APIトークン認証ではなく、パスワード認証が必要です。
また、アプリの閲覧権限が必要です。
App
クラスで使用できる関数は次のドキュメントを確認してください。
App
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());
});
|
ファイルAPIに対応する関数が定義されているクラスです。
File
クラスで使用できる関数は次のドキュメントを確認してください。
File
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をご活用ください。