カテゴリー内の他の記事

kintone JavaScript Client (@kintone/rest-api-client)

Index

はじめに

@kintone/rest-api-client は、 kintone REST API を JavaScriptで扱う際に必要な処理をまとめたライブラリです。

@kintone/rest-api-client(以降、本クライアント)を使うと、用意されたメソッドを呼び出すだけで kintone REST API を実行できるので、コードの記述量を減らすことができます。
kintone で利用可能な REST API のほか、レコードを一括処理できるメソッドなどの便利なメソッドも用意されています。
また、本クライアント は TypeScript で実装されており、Visual Studio Code などの高機能エディタを利用すると、コード補完ができます。

コード補完のイメージ

  • コードの一部を書くと、自動で利用できるメソッドの候補が表示されます。
  • メソッドに渡すパラメータの情報も表示されます。

rest-api-client_completion.gif

 

この記事では、本クライアントの導入方法や基本的な使い方について説明します。
本クライアントが提供する各メソッドについては、ドキュメントをご参照ください。

GitHub

https://github.com/kintone/js-sdk/tree/master/packages/rest-api-client

ライセンス

MIT ライセンス

ドキュメント

導入方法

ブラウザ環境

ブラウザ環境で利用する場合、Cybozu CDN の URL を指定して本クライアントを読み込みます。 kintone アプリに適用する場合は、「JavaScript / CSS でカスタマイズ」画面で指定します。

例)バージョン 1.4.0 の場合
https://js.cybozu.com/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js

最新バージョンの URL は、Cybozu CDN のページを参照してください。

CDN を読み込むと、グローバルオブジェクトとして KintoneRestAPIClient が追加されます。

Node.js 環境

  1. Node.js で利用する場合、プロジェクトのルート配下で次のコマンドを実行します。

    ※ 必要な Node.js のバージョンは、リポジトリの package.json にある engines プロパティを確認してください。
    例:次の記載の場合、Node.js のバージョンは 10 以上が必要です。

  2. require で読み込みます。

Quick Start

ブラウザ環境と Node.js 環境における、本クライアントの使い方です。 各メソッドの詳細は、ドキュメントを参照してください。

ブラウザ環境

レコード一覧画面を開いたときに、kintone のレコードを取得し、取得した内容をコンソールに出力する例です。

kintone アプリの準備

  1. 文字列 (1行) フィールドを追加し、kintone アプリを作成します。
  2. テストデータとして、レコードを1件追加します。

サンプルコードの作成

  1. 次の内容をテキストエディタに貼り付けます。
  2. 文字コードを「UTF-8」、ファイルの拡張子を「.js」にしてファイルを保存します。
    この記事ではファイル名を kintone-rest-api-sample.js としています

kintone アプリに適用

  1. kintone アプリの準備で作成したアプリを開きます。
  2. [アプリの設定] > [JavaScript / CSSでカスタマイズ]の順にクリックし、「JavaScript / CSSでカスタマイズ」画面を開きます。
  3. 次の内容を入力します。入力が終わったら、[保存]ボタンをクリックします。
    項目
    PC用のJavaScriptファイル 次の順で指定します。
    • https://unpkg.com/@kintone/rest-api-client@1.2.0/umd/KintoneRestAPIClient.min.js
    • サンプルコード(kintone-rest-api-sample.js)
  4. 「アプリの設定」画面で、[アプリを更新]ボタンをクリックします。

動作確認

カスタマイズしたアプリの一覧画面を開きます。
ブラウザの開発者ツールを開くと、レスポンス(レコードの取得結果)が出力されていることを確認します。
browser-result.png

Node.js 環境

kintone のレコードを取得し、取得した内容をコンソールに出力する例です。

kintone アプリの準備

  1. 文字列(1行)フィールドを追加し、kintone アプリを作成します。
  2. テストデータとして、レコードを1件追加します。

サンプルコード

次の内容で JavaScript ファイルを作成します。ここではファイル名を kintone-rest-api-sample.js とします。

  • 次のように、環境変数に kintone のログイン名およびパスワードを設定してください。
  • コード内の次の値を変更してください。
    • {subdomain}: 利用している kintone 環境のサブドメイン
    • APP_ID: 作成した kintone アプリのアプリ ID

動作確認

次のコマンドを実行します。

取得したレコードの中身が出力されることを確認します。

認証について

本クライアントでは、パスワード認証、API トークン認証、OAuth クライアントを利用した認証、およびセッション認証に対応しています。

認証情報は、KintoneRestAPIClient の引数オブジェクトの auth プロパティで設定します。

以降の例では、Node.js での利用を想定して(セッション認証を除く)、環境変数から認証情報を読み込んでいます。
ブラウザ環境から利用する場合、認証情報を JavaScript ファイルにハードコーディングしないでください。
詳細はセキュアコーディングガイドラインを参照してください。

パスワード認証

パスワード認証の場合、auth プロパティに username と password を指定します。

API トークン認証

API トークン認証の場合、auth プロパティに apiToken を指定します。

OAuth クライアントを利用した認証

OAuth クライアントを利用した認証を行う場合、oAuthToken プロパティに、アクセストークンを指定します。
OAuth クライアントの作成やアクセストークンの取得方法は、OAuth クライアントの設定をご参照ください。

セッション認証

セッション認証の場合、auth プロパティを省略します。

※ セッション認証は、kintone 環境にカスタマイズファイルを適用する場合のみ利用できます。

セキュリティ設定を行った環境

Basic 認証情報やクライアント証明書も設定できます。

Basic 認証を設定する

kintone 環境で Basic 認証を利用している場合、KintoneRestAPIClient の引数オブジェクトに basicAuth プロパティを追加します。

クライアント証明書を設定する

セキュアアクセスを kintone 環境に設定している場合、KintoneRestAPIClient の引数オブジェクトに clientCertAuth プロパティを追加して、クライアント証明書を指定します。

クライアント証明書を指定する方法は、pfx プロパティにバイナリデータを指定する方法と、pfxFilePath プロパティにファイルパスを指定する方法があります。

  • バイナリデータで指定する方法
  • ファイルパスで指定する方法

おわりに

@kintone/rest-api-client を使うと、JavaScript プログラムで kintone REST API を扱いやすくなります。
@kintone/rest-api-client で提供されるメソッドやその使い方の詳細は、ドキュメントを参照してください。

更新履歴

  • 2020年2月18日 v1.0.0 リリース
  • 2020年4月1日 v1.1.0 リリース
  • 2020年4月13日 v1.2.0 リリース

このTipsは、2020年4月版 kintone および @kintone/rest-api-client v1.2.0 で確認したものになります。

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

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

Avatar
新貝博幸

kintone-js-sdk が deprecated になった背景や事情を公開可能な範囲で教えて頂けませんでしょうか。

今後は kintone-js-sdk の機能追加アップデートは行われず、@kintone/rest-api-client がそれに取って代わると言う事になるかと思いますが、

kintone-js-sdk も1年ほど前にリリースされたばかりでもう deprecated となるのはなかなか衝撃です。

 

Avatar
cybozu Development team

新貝博幸 様

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

>kintone-js-sdk が deprecated になった背景や事情を公開可能な範囲で教えて頂けませんでしょうか。

背景としまして、
kintone-js-sdkはこれまでバージョン0.x系という位置づけで開発を続けてまいりましたが、
その間多くのユーザーの皆さまからフィードバックをいただきました。

バージョン1.0をリリースするにあたり、
これまでにフィードバックいただいた部分の改善および、
利便性の向上を目的としてTypeScriptでの刷新を行うことにいたしました。

ライブラリの位置づけや基本的な機能はkintone-js-sdkを引き継いでいます。
今後の対応としては、本クライアントを継続的に開発・サポートしていきます。

今後とも、どうぞよろしくお願いいたします。

Avatar
新貝博幸

cybozu Development team 様

 

ご返信ありがとうございます。

こちらもさっそく @kintone/rest-api-client を試してみています。

コード補完が利くようになったり裏で bulkRequest API を叩くメソッド類の戻り値が整理されたりと

多くのメリットを感じています。

その分これまで kintone-js-sdk を使用していたプロジェクトでの置き換えは

多少慎重にならざるを得ないところはありますが、

全般としてとても使いやすくなったと感じています。

今後も長く安定して @kintone/rest-api-client が継続していく事を期待しております。

 

Avatar
naoki watanabe

ライブラリのご提供ありがとうございます。

IE11で試したところエラーとなりましたが、こちらのライブラリはIE11は動作保証外でしょうか?

(kintoneUtility や、kintone-js-sdk はIE11でも動作していた記憶があります)

今後は当ライブラリを継続してアップデートしていくとの事ですので、ご確認、対応のご検討を頂ければ幸いです。

 

以下にJSの適用状態、エラーのキャプチャを添付いたします。

<JS適用状態>

<発生エラー>

Avatar
Tanizaki

はじめまして。

kintone Utility for JavaScriptでレコードの一括作成や一括編集などを使っておりました。

こちらが後継のライブラリとの認識でよろしいでしょうか?

また、7月にoffsetの上限対応のお知らせが来ておりますが、こちらは1万件以上の処理に影響はありますでしょうか?

宜しくお願いいたします。

Avatar
cybozu Development team

naoki watanabe 様

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

>こちらのライブラリはIE11は動作保証外でしょうか?

本クライアントを開発しているチームに確認しているので、
お待たせしてしまい恐縮ですが、しばらくお待ち下さい。

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

Avatar
cybozu Development team

Tanizaki 様

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

>こちらが後継のライブラリとの認識でよろしいでしょうか?
はい、ご認識の通りです。

> 7月にoffsetの上限対応のお知らせが来ておりますが、こちらは1万件以上の処理に影響はありますでしょうか?

●以下のメソッドを利用する場合、
  offset 方式でのレコード一括取得になるので、1万件以上のレコード取得時に影響を受けます。
 ・getAllRecordsWithOffset
 ・getAllRecords において、引数でorderByを指定している、かつ withCursor に false を指定している場合

●1万件以上のレコードを取得する場合、
  カーソルAPIを利用する getAllRecordsWithCursor
  または ID方式を利用する getAllRecordWithID を利用してください。

  それぞれの方式の違いは、offset の制限値を考慮したレコード一括取得についてをご参考ください。

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

Avatar
Tanizaki

cybozu developer network 事務局様

ご返信ありがとうございます。

運用中のものを確認したところkintone Utility for JavaScriptで「getAllRecordsByQuery」「postRecord」「deleteAllRecordsByQuery」

のメソッドを使用しておりました。こちらもおそらくoffset上限の影響を受けるものと認識しております。

このまま影響のある部分を ID方式に変更するのか、kintone JavaScript Clientに移行後 ID方式に変更するのかでどのような違いがでてきますでしょうか?

 

 

Avatar
cybozu Development team

naoki watanabe 様

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

>こちらのライブラリはIE11は動作保証外でしょうか?
 回答は下記になります:

・IE11は動作保証しています。
 →エラーの原因は現在調査中です。

・エラーの回避方法:
 →naoki watanabe 様の環境で発生しているエラーは、
  サンプルコードの13行目 を「var client = new KintoneRestAPIClient({baseUrl: 'https://{subdomain}.cybozu.com'}) ; 」
  にすることで回避できるはずなので、お手数ですが試して頂いてもよろしいでしょうか。

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

Avatar
cybozu Development team

Tanizaki 様

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

頂いたご質問の回答は下記になります:

ーーーーーーーーーーーーーーーーー
●kintone Utility for JavaScriptの利用について

kintone Utility for JavaScript はすでに開発が終了しており、
セキュリティ対応や不具合修正、kintone アップデートに伴う機能追加は行われません。
そのため、kintone Utility for JavaScript に、
カーソルAPIを使ってレコードを一括取得するメソッドや、ID方式でレコードを一括取得できるメソッドはありません。

kintone Utility for JavaScript のままで、
ID方式でレコードを一括取得する場合、
レコードを一括取得するAPI を実行する処理を、1からご自身で実装する必要があります。

なお、記載いただいたメソッドのうち、
offset の影響を受けるレコードを一括取得するAPI を実行しているメソッドは、
「getAllRecordsByQuery()」と、「deleteAllRecordsByQuery()」です。
そのため、これらメソッドを利用する箇所では、
kintone Utility for JavaScript で提供しているメソッドは使わない実装が必要です。

●kintone JavaScript Clientの利用について

kintone JavaScript Client を利用する場合、
インターフェース等も異なるため全体的にコードの修正が必要です。

ただし、先ほどコメントさせていただいたとおり、
kintone JavaScript Client には ID方式でレコードを一括取得できるgetAllRecordsWithId()があるので、
レコードを一括取得するAPI を実行する処理を、1から実装する必要はありません。

また、kintone JavaScript Client は今後継続的に開発・サポートされるライブラリなので、
kintone JavaScript Client への移行をオススメいたします。

ーーーーーーーーーーーーーーーーー
長文になってしまい大変恐縮ですが、
ご確認のほどよろしくお願いいたします。

Avatar
naoki watanabe

cybozu developer network 事務局 様

ご回答頂きありがとうございます。

IE11も動作保証対象との事で安心しました。

また、エラーの回避方法の共有も頂き、ありがとうございます。

こちらの環境でも正常に動作することを確認致しました。

Avatar
mharum

cybozu developer network 事務局様

 

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

こちらのライブラリですが、メーカーとして通常のRESTAPI同様にメーカーとして動作保証されるものでしょうか。

それともJS SDKのようにメーカーとしては保証外?となりますでしょうか。

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