kintone API SDK(β) for Node.js – cybozu developer network

新しいライブラリkintone JS SDK が公開されています。

Index

はじめに
導入方法
サンプル
サンプルコード解説
その他の機能について
おわりに

はじめに

2018年5月にリリースされた、「kintone-node.js-sdk」について紹介します。
「kintone-node.js sdk」とは、kintone REST APIをNode.js（サーバーサイドJavaScript）で使う上で、生産性を向上するために開発されたライブラリです。
これまで、Node.jsでkintone REST APIを実行する際は、Node.jsの標準モジュールである「https」や
他にも「request」、「request-promise」などのモジュールを使用していたと思います。
今回リリースされた「kintone-node.js-sdk」により、それらのモジュールを使わず、より簡単にkintone REST APIを実行することが可能になりました。

GitHub

https://github.com/kintone/kintone-nodejs-sdk/

ドキュメント

https://kintone.github.io/kintone-nodejs-sdk/

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

Node.js

https://nodejs.org/ja/

ご注意事項

本プログラムは、動作を保証するものではありません。
ソースコードの変更および再配布、商用利用等はライセンスに従ってご利用可能です。

導入方法

インストール

下記コマンドを任意のディレクトリで実行してください。kintone-nodejs-sdkのインストールが可能です。

ドキュメントにあるように、Nodeバージョンは8.9.3以降、npmバージョン5.5.1以降でインストールしてください。
Requirementに記載されているkintone-basejs-sdkは、上記コマンドを実行すると自動的にインストールされるのでここでは気にしなくてよいです。

サンプル

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

サンプルコード（ファイル名：sample.js）

APIトークン、認証情報、サブドメイン、アプリIDはご自身の環境に合わせて書き換えてください。
作成したファイルは、kintone-nodejs-sdkインストール時に作成したフォルダ「sample_project」に保存してください。

実行

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

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

レスポンスの例

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

サンプルコード解説

Authentication

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

Authenticationクラスがあり、パスワード認証、APIトークン認証、Basic認証を設定できます。
認証の優先度は以下のとおりです。（参考：kintone REST APIの共通仕様）
1．パスワード認証
2．APIトークン認証
※セッション認証はkintone-nodejs-sdkでは実装できません。

パスワード認証

APIトークン認証

Basic認証

Connection

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

Record

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

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

getRecord(appID, recordID)

パラメータ

名称	データタイプ	必須	説明
appID	Integer	〇	アプリID
recordID	Integer	〇	レコード番号

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

その他の機能について

Recordクラス

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

getRecord
getRecords
addRecord
addRecords
updateRecords
deleteRecords
updateRecordStatus
getComments
addComment
deleteComment

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

Recordクラスについて

https://kintone.github.io/kintone-nodejs-sdk/reference/record/

BulkRequestクラス

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

BulkRequestクラスについて

https://kintone.github.io/kintone-nodejs-sdk/reference/bulk-request/

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

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

BulkRequestサンプル

Appクラス

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

Appクラスについて

https://kintone.github.io/kintone-nodejs-sdk/reference/app/

Appサンプル

おわりに

Node.jsについてよく知らない方でも、kintone REST APIを実行しやすくなりました。
AWS Lambdaからkintoneへアクセスする際など、活用方法は様々です。
この機会にkintone-nodejs-sdkをご活用ください。

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