その他の SDK／Tools

（非推奨）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で動作を確認しています。