はじめに

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

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

コード補完のイメージ

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

 

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

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

Cybozu CDN で公開しているバージョンは、こちらのページを参照してください。

なお、Cybozu CDN は定期更新のため、ライブラリの最新バージョンと一致していない可能性があります。
最新バージョンを利用したい場合は、GitHub 記載の CDNサービス unpkg の URL を指定してください。
※ unpkg はサイボウズが提供している CDN サービスではありません。
※ 本番環境では、新しいバージョンによる意図しない不具合・仕様変更を避けるため、特定のバージョンの URL を読み込むことをおすすめします。

 

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

Node.js 環境

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

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

2. require で読み込みます。

Quick Start

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

• ブラウザ環境
• 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://js.cybozu.com/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js サンプルコード（kintone-rest-api-sample.js）

4. 「アプリの設定」画面で、[アプリを更新]ボタンをクリックします。

動作確認

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

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 で提供されるメソッドやその使い方の詳細は、ドキュメントを参照してください。

更新履歴

ライブラリのアップデート情報は、こちらのページ をご参照ください。

 

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