cybozu developer network

Enhanced by Google

カテゴリー内の他の記事

kintone JS SDK

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

Index

はじめに

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/

ドキュメント

https://kintone-labs.github.io/kintone-js-sdk/

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

Node.js

https://nodejs.org/ja/

ご注意事項

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

導入方法

JavaScript

https://github.com/kintone-labs/kintone-js-sdk/tree/master/dist

「kintone-js-sdk.min.js」というファイルを保存してください。

webpack

npm インストールし、 webpack でバンドルすることも可能ですが、今回は省略させて頂きます。
詳しく知りたい方はリファレンスをご覧ください。
https://kintone-labs.github.io/kintone-js-sdk/getting-started/quickstart-browser/#install-package-from-npm

Node.js

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

ドキュメントにあるように、Nodeバージョンは8.9.3以降、npmバージョン5.5.1以降でインストールしてください。

サンプル（ JavaScript ）

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

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

サンプルコード (ファイル名 : sample-for-JavaScript.js)

kintone アプリに適用

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

001.png

実行

サンプルコードでは、アプリの一覧画面で動作する kintone JavaScript API を使用しているので、アプリの一覧画面に遷移してください。

レスポンスの例

ブラウザの開発者ツールを開くと以下のようにレスポンスが確認できます。

002.png

サンプル（ Node.js ）

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

サンプルコード (ファイル名 : sample-for-Node.js)

APIトークン、認証情報、サブドメイン、アプリIDはご自身の環境に合わせて書き換えてください。
4,5,7行目はベーシック認証を設定している場合のみ、記載してください。
作成したファイルは、kintone JS SDKインストール時に作成したフォルダ「sample_project」に保存してください。

実行

先ほどのサンプルコードを保存した「sample_project」で、下記コマンドを実行してください。

エラーが発生する場合は、sample.jsが保存されているディレクトリに、node_modulesというフォルダが存在しているか確認してください。

レスポンスの例

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

サンプルコード解説

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

Authentication

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

Authenticationクラスがあり、パスワード認証、APIトークン認証、Basic認証を設定できます。
認証の優先度は以下のとおりです。（参考：kintone REST APIの共通仕様）
1．パスワード認証
2．APIトークン認証
3．セッション認証
※セッション認証は kintone JS SDK をブラウザ上で扱う場合のみ実装可能です。
※セッション認証を使用する際は sample-for-JavaScript.js のように Auth() クラスは宣言する必要はありません。

パスワード認証

APIトークン認証

Basic認証

Connection

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

※ブラウザ上 かつ セッション認証の場合は sample-for-JavaScript.js のように引数指定する必要はありません。

ブラウザ上 かつ セッション認証以外の場合は下記のように実装する必要があります。

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

Record

最後に、13~24行目についてです。

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

getRecord({app: appId, id: recordId})

パラメータ

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

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

その他の機能について

Recordクラス

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

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

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

Recordクラスについて

https://kintone-labs.github.io/kintone-js-sdk/latest/reference/record/

BulkRequestクラス

複数のアプリに対して、同時に複数のAPIをリクエストできます。
BulkRequestで使用できる関数は下記のドキュメントをご覧ください。

BulkRequestクラスについて

https://kintone-labs.github.io/kintone-js-sdk/latest/reference/bulk-request/

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

  • BulkRequestを実行し、レスポンスを取得する際は、execute関数を実行する。
  • 一度に実行できる関数は、excecute関数を抜き、20個まで。

BulkRequestサンプル

Appクラス

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

Appクラスについて

https://kintone-labs.github.io/kintone-js-sdk/latest/reference/app/

Appサンプル

Fileクラス

ファイル API に対応する関数が定義されているクラスです。

Fileクラスについて

https://kintone-labs.github.io/kintone-js-sdk/latest/reference/file/

Fileサンプル

おわりに

これまで Node.js SDK(β) や iOS SDK、Java SDK に触れた方もそうでない人も簡単に実装できたかと思います。
今後、kintoneUtility との機能差分や、独自の関数を実装予定です。
この機会に kintone JS SDK をご活用ください。

このTipsは、2019年3月版 kintoneで確認したものになります。

記事に関するフィードバック

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

Avatar
山口

いつもお世話になっております。

上記SDKとサンプルをそのままコピーして、ローカル環境下で動作させたところ、

Error: undefined not an instance of Auth

上記エラーがレスポンスされました。

（利用環境はNode.js v10.16.3、npm 6.9.0、@kintone/kintone-js-sdk@0.5.1 ）

となっております。

原因不明なので、投稿させていただきました。

よろしくお願い申し上げます。

Avatar
cybozu Development team

山口様

お世話になっております。cybozu developer network 運営でございます。

ご質問頂きました時点（9/10）のサンプルは kintone-js-sdk v0.1.0 のサンプルコードとなっており、
山口様のご利用している v0.5.1 では動作しないサンプルとなっておりました。

記事のサンプルコードを v0.6.1 で動作するコードに修正致しましたので、再度確認頂きますようお願い致します。

以上、よろしくお願いいたします。

Avatar
PV

お世話になっております。

kintoneの標準のJavascriptAPIの場合、型定義ファイルkintone.d.tsがdts-genで公開されていますが、

kintone-js-sdkの型定義ファイルはないでしょうか？

もしくは別の方法にて、VisualStudioCode等のエディタ使用時にインテリセンスが効くようにすることは可能でしょうか？

 

PVにより編集されました
Avatar
cybozu Development team

PV様

現在、kintone-js-sdkの型定義ファイルの提供はしておりません。
ご参考情報として、来年1月以降（時期は未定です）に予定している大幅な変更時には型定義ファイルも提供の方向で開発を進めております。

 

Avatar
mharum

お世話になっております。

今月実施されるアップデート内にRESTAPIの認証に複数APIトークン対応があります。

JS　SDKのAPIトークン認証においても同様の方法でAPIトークンを定義することでアップデートと同じ動作をさせることができるのでしょうか。

（カンマ区切りで複数のAPIトークンを渡す）

Avatar
cybozu Development team

mharum 様

お世話になります。cybozu developer network 運営でございます。

本 SDK を使い、複数 API トークン認証を渡す場合は、以下のようにカンマ区切りで記載下さい。

let auth = new kintone.Auth();
const authParams = {
  apiToken: 'token1, token2'
};
auth.setApiToken(authParams);
Avatar
mharum

@cybozu Development team様

上記のAPI認証ですが、プラグイン開発のJSでも可能でしょうか。

APIを実行すると[object Object] not an instance of Connection　とエラーが発生してしまい。

 

 

Avatar
cybozu Development team

mharum 様

お世話になっております。cybozu developer network事務局です。

本SDKを利用した複数APIトークン認証は、プラグイン開発でも同様にお使いいただけます。
こちらで検証しましたが、ご連絡いただいたようなエラーは再現できませんでした。

古いバージョンのものではうまく動作しない可能性がございますので、
恐れ入りますが最新のバージョンでお試しいただけますでしょうか。
https://github.com/kintone/kintone-js-sdk/blob/master/dist/kintone-js-sdk.min.js

Avatar
ramp

お世話になっております。

このkintone JS SDKをmonacaで使用したいと思い、「kintone-js-sdk.min.js」をプロジェクトに組み込んで、上記のサンプルコードで「getRecord」を実行してみましたが、「Request failed with status code 404」のエラーが帰ってきてしまい、上手くkintoneアプリのデータを読み込む事ができませんでした。

実行結果を見ていると、「domain」が上手く渡せていないようにも思うのですが、何か原因とかお分かりであれば、ご教授いただければありがたいですm(_ _)m

rampにより編集されました
Avatar
cybozu Development team

ramp 様

お世話になっております。cybozu developer network 運営局です。

そうですね、
kintone-js-sdk.min.js を利用する場合のコードを利用されたとのことなので、ドメインの指定が必要です。
（kintone 上で動かすのを前提となっているコードなので、自動で実行している kintone 環境のドメインを取得するようになっています）

monaca から利用するにはドメインの指定が必要ですが、

> Connection
> ※ブラウザ上 かつ セッション認証の場合は sample-for-JavaScript.js のように引数指定する必要はありません。
> サーバー側と違い、他のサブドメインを指定することはできません。

となっているので、kintone-js-sdk.min.js を使えず、monaca 開発で npm でのインストールが可能であれば、Node.js での利用が必要かと思われます。

よろしくお願いいたします。

cybozu Development teamにより編集されました
Avatar
ramp

cybozu developer network 運営局様。

早速の回答ありがとうございます！
「kintone Utility Library for JavaScript」のサンプルの場合は、monacaから問題なくデータを参照できたのですが、仕様が変更になったという事でしょうか？　まだ勉強がいたらず見当違いの事を言ってたら申し訳ありません(^_^;)

その時に参考にしたサイトはこちらです。
「Monacaとkintoneで忘年会出欠アプリを作る - Qiita」
https://qiita.com/coboco/items/8758ad28fa6b77a2cea2

ちなみに、今回のサンプルコードと実行結果は以下です。
もし不具合等ございましたら、ご教授」いただきたいですm(_ _)m

【ソース】----------------------------------------------------------------------------------

//kintoneのログインIDとパスワードを指定
const paramsAuth = {
  username: "********",
  password: "********"
};
const kintoneAuth = new kintoneJSSDK.Auth();
kintoneAuth.setPasswordAuth(paramsAuth);
console.log(JSON.stringify(kintoneAuth)); //(1)

const paramsConnection = {
  domain: "********.cybozu.com",
  auth: kintoneAuth
};
const kintoneConnect = new kintoneJSSDK.Connection(paramsConnection);
console.log(JSON.stringify(kintoneConnect)); //(2)

const paramsGetRecord = {
  app: 5,
  id : 1
};
const kintoneRecord = new kintoneJSSDK.Record(kintoneConnect);
console.log(JSON.stringify(kintoneRecord)); //(3)

kintoneRecord.getRecord(paramsGetRecord)
.then((rsp) => {
  console.log(rsp);
}).catch((err) => {
  console.log(JSON.stringify(err)); //(4)
});

 

----------------------------------------------------------------------------------------------

【(1)のログ：kintoneAuthオブジェクトの内容】
渡した引数がしっかり渡されているように見えるので問題無さそうです。

"basicAuth":null,
"passwordAuth":{
  "username":"********",
  "password":"********"
},
"apiToken":null


【(2)のログ：kintoneConnectオブジェクトの内容】
「domain」が何故か上手く渡されていないように見えます。
なんとなくここが問題なのでは？と気になりますが、
解決方法は検討がつかない状況です。
「auth」の内容は上手く渡されているようなので問題なさそうです。

"domain":"",
"guestSpaceID":null,
"globalHeaders":[],
"localHeaders":[],
"options":{"proxy":false},
"auth":{
  "basicAuth":null,
  "passwordAuth":{
    "username":"********",
    "password":"********"
  },
  "apiToken":null
},
"kintoneAuth":{
  "basicAuth":null,
  "passwordAuth":{
    "username":"********",
    "password":"********"
  },
  "apiToken":null
}


【(3)のログ：kintoneRecordオブジェクトの内容】
「domain」は元々空白だったので当然こうなるでしょうが、
「auth」の「passwordAuth」までnullになってしまっています。
「domain」が空白だからこうなってしまうのか？不明です。

"connection":{
  "domain":"",
  "guestSpaceID":null,
  "globalHeaders":[],
  "localHeaders":[],
  "options":{"proxy":false},
  "auth":{
    "basicAuth":null,
    "passwordAuth":null,
    "apiToken":null
  }
}


【(4)のログ：kintoneRecord.getRecord(paramsGetRecord)の実行結果】

"originError":{
  "line":1,
  "column":33113,
  "sourceURL":"file:///var/mobile/Containers/Data/Application/2ECE7E35-BFD5-49F4-9008-53669F98A534/Library/Caches/launch/1582680736/5e44b0bee788850b55323407/www/components/kintone/kintone-js-sdk.min.js"
},
"httpErrorCode":0,
"errorResponse":{
  "id":0,
  "code":null,
  "message":"The string did not match the expected pattern.",
  "errors":{
    "line":1,
    "column":33113,
    "sourceURL":"file:///var/mobile/Containers/Data/Application/2ECE7E35-BFD5-49F4-9008-53669F98A534/Library/Caches/launch/1582680736/5e44b0bee788850b55323407/www/components/kintone/kintone-js-sdk.min.js"
  }
},
"line":15,
"column":22083,
"sourceURL":"file:///var/mobile/Containers/Data/Application/2ECE7E35-BFD5-49F4-9008-53669F98A534/Library/Caches/launch/1582680736/5e44b0bee788850b55323407/www/components/kintone/kintone-js-sdk.min.js"

rampにより編集されました
Avatar
cybozu Development team

ramp 様

お世話になっております。cybozu developer network 運営局です。

> 「kintone Utility Library for JavaScript」のサンプルの場合は、monacaから問題なくデータを参照できたのですが、仕様が変更になったという事でしょうか？

「kintone Utility Library for JavaScript」と「kintone JS SDK」は別のライブラリになるので、仕様が異なっております。

 

データを取得できない理由ですが、「kintone-js-sdk.min.js」を使うと、ドメインの指定ができません。
(kintone Utility Library for Javascript ではできていましたが、kintone JS SDKのkintone-js-sdk.min.js ではできません）
なので、以下のように書いても、domain は渡されません。

const paramsConnection = {
  domain: "********.cybozu.com",
  auth: kintoneAuth
};
const kintoneConnect = new kintoneJSSDK.Connection(paramsConnection);

kintone-js-sdk.min.js を使わず、npm install で kintone JS SDK を利用することになるかと思います。
monaca での開発する具体的な方法は、この記事のフィードバックとは異なるため、ぜひコミュニティをご活用ください。

 

※ 別件ですが、お使いの kintone 環境ですが、パスワードを変更されることをおすすめします。
一度投稿されたときに、環境情報をマスキングしてない状況で投稿されていたため、この記事をフォローしているユーザー様に届くメールでその内容が見えておりました。

cybozu Development teamにより編集されました
Avatar
ramp

cybozu developer network 運営局様。

回答ありがとうございます！
パスワードもさっき変更しました。今後は気をつけます(^_^;)

monacaのサーバー側のライブラリに「 kintone JS SDK」を追加し、
「require('@kintone/kintone-js-sdk')」で呼び出して使用する感じになるんでしょうか。

早速試してみます。丁寧な回答ありがとうございましたm(_ _)m

Avatar
ramp

cybozu developer network 運営局様。

monacaのパッケージに「 kintone JS SDK」をnpmで追加し、
「require('@kintone/kintone-js-sdk')」で呼びだそうとしたら、
「require」という関数は無いので使えない。というエラーが返ってきました。

色々調べたんですが、monacaで作成したアプリには「node.js」の実行環境が
無いのでこのような結果になるみたいです。

「 kintone JS SDK」をmonacaアプリで利用したいんですが、
結果としては不可能という事なんでしょうか？

勉強不足で至らず申し訳ありませんが、ご教授いただければありがたいですm(_ _)m

Avatar
cybozu Development team

ramp 様

お世話になっております。
cybozu developer network 運営局です。

申し訳ありません。
monaca は cybozu ではない会社さんが提供する開発プラットフォームなのでわかりかねるのですが、
npm パッケージを利用できないのであれば、「kintone JS SDK」は利用できないものかと思われます。

よろしくお願いいたします。

Avatar
ramp

cybozu developer network 運営局様。

かしこまりました。ありがとうございます。

他の方法を探ってみます。

サインインしてコメントを残してください。