初めてkintoneをカスタマイズする人がkintone APIの基礎知識を学べるよう、チュートリアルの内容を充実させてリニューアルしました。
リニューアル後のチュートリアルは次のページを参照してください。
はじめよう kintone API
はじめに
前回、初めて更新時の処理について扱ってみました!
今回は、kintone REST APIを使った追加処理に挑戦してみましょう。
それでは、「各ユーザーがどのアプリのどのレコードを参照したか」を残す参照ログを作成しながらkintone REST APIを学んでいきたいと思います。
アプリの準備
参照ログを格納する、次のようなアプリを用意します。
フィールド名 | フィールドタイプ | フィールドコード |
---|---|---|
閲覧アプリ ID | 数値 | 閲覧アプリ ID |
閲覧レコード番号 | 数値 | 閲覧レコード番号 |
閲覧者 | 作成者 | 閲覧者 |
閲覧日時 | 作成日時 | 閲覧日時 |
閲覧者を格納するフィールド「閲覧者」にフィールドタイプ:作成者を利用していることに注目してください。
これは、ログをしかけた別アプリを閲覧しているユーザー=APIを通して本アプリへデータ作成するユーザーとなるためです。
また同様に「閲覧日時」も同じ理由です。
注意点として、このアプリのアクセス権でEveryoneに追加権限を設定しておくことを忘れずに。
作成できたら、アプリIDは後で使うので控えておいてください。
反映する値の取得
このアプリに格納する値として、以下2つはデータ挿入時にkintoneによって自動で適切な値が差し込まれるため、こちらで何かすることはありません。
- 閲覧者(作成者)
- 閲覧日時(作成日時)
残る「閲覧アプリID」と「閲覧レコード番号」ですが、これらは レコード詳細画面を表示した後のイベントのイベントオブジェクトのプロパティに入っているのでこれを使いましょう。
イベントオブジェクトのプロパティ
プロパティ名 | 型 | 説明 |
---|---|---|
appId | 数値 | アプリ ID |
record | オブジェクト | レコード詳細画面が表示された時のデータを保持したレコードオブジェクト レコードオブジェクトとは、フィールドコードとフィールドの値などのレコードの情報を含むオブジェクトです。 フィールドの値は、フィールドの形式によって異なります。 詳細は フィールド形式を確認してください。 |
recordId | 数値 | レコード ID |
type | 文字列 | イベントタイプ |
イベントオブジェクトのプロパティについて忘れてしまった方は、 第 4 回 レコードの値を利用してみよう(詳細画面編)をもう一度読んでみてくださいね。
では、実際に取得できるか試してみましょう。
以下のスクリプトを、(先に作成したアプリではなく)閲覧ログを収集したいアプリに登録して詳細画面を開いてみてください。
|
|
上図は、
第6回 テーブルの値を利用するで作成したJおじさんのアプリで実行した例です。
きちんと思いとおりの値が取れていることを確認できましたね。
kintone REST API を利用する
さて、それではいよいよ実際のデータ登録に進みましょう。
これには、kintone REST API(レコード)の
1 件のレコードを登録する APIを使うことになります。
kintone上のJavaScriptでkintone REST APIを利用する手段としては
kintone REST API リクエストを送信する APIが用意されていますので、まずはここから説明していきます。
関数
kintone.api(pathOrUrl, method, params, successCallback, failureCallback)
引数
パラメーター名 | 指定する値 | 必須 | 説明 |
---|---|---|---|
pathOrUrl | 文字列 | 必須 | kintone REST API のパスもしくは、kintone.api.url() で取得したURLを指定します。例) API の URL が https://{サブドメイン名}.cybozu.com/k/v1/xxx.json の場合は、「/k/v1/xxx.json」を指定します。 「/k/v1/xxx」のように末尾の「.json」を省略した場合、パスには「.json」が自動で付与されます。 ゲストスペース内アプリでも動作させる場合は、 kintone.api.url("/k/v1/xxx.json", true) を指定してください。 |
method | 文字列 | 必須 | 使用する HTTP メソッド。 GET/POST/PUT/DELETE が指定可能です。 |
params | オブジェクト | 必須 | API に渡すパラメーターをオブジェクトで指定します。 |
successCallback | 関数 | 省略可 | API の呼び出しが成功したら実行されるコールバック関数です。 引数の型はオブジェクトになります。 省略した場合は kintone.Promise オブジェクトが返され、 successCallback に渡す引数で解決されます。 |
failureCallback | 関数 | 省略可 | API の呼び出しが失敗したら実行されるコールバック関数です。 引数にはレスポンス JSON が渡されます。 レスポンスが JSON としてパースできなかった場合は、パース前の文字列が渡されます。 省略した場合は kintone.Promise オブジェクトが返され、failureCallback に渡す引数で棄却されます。 |
各パラメーターに何を入れるかは、実際利用するkintone REST APIによって変わってきます。
1 件のレコードを登録する APIのドキュメントと見比べながら、それぞれ埋めていきましょう。
pathOrUrl
引数の説明にもありますが、kintone.api.url()
を利用するようにしましょう。
また、kintoneのREST APIではゲストスペース内アプリの場合にパスが変わってしまうので、あとで混乱しないためにも第2引数にtrue
を入れるよう習慣化しておくとよいかと思います。
詳しい説明は次のページを確認してください。
method
今回利用するAPI(/k/v1/record.json)は、同じURLでもリクエストのHTTPメソッドによって動作が変わるしくみになっています。
- GET: レコードの取得(1件)
- POST: レコードの登録(1件)
- PUT: レコードの更新(1件)
利用したい動作は参照ログアプリへのデータの挿入なので、この引数には'POST'を指定します。
params
1 件のレコードを登録する APIのリクエストプロパティを参考にJSON形式でパラメーターを作成して渡しましょう。
パラメーター名 | 指定する値 | 必須 | 説明 |
---|---|---|---|
app | 数値または文字列 | 必須 | アプリの ID を指定します。 |
record | Object | 省略可 | レコードの情報(フィールドコードとフィールドの値)をオブジェクトで指定します。 フィールド値の仕様についてはフィールドの形式により異なります。 詳細については フィールド形式を確認してください。 省略した場合は、全フィールドの値が初期値で登録されます。 存在しないフィールドコードを指定した場合、その部分は無視されます。 |
リクエストボディの構造
|
|
サンプルプログラム
細かいことはできあがったものを見たほうがよいかもしれませんね。
以下、実際に作成したスクリプトです。
参照ログを格納するアプリのIDを皆さんが実際に作成したアプリのIDに書き換えて、ログをしかけたいアプリ(上の例でいくと、Jおじさんアプリ)に登録してください。
登録する先はいくつでもかまいません。
|
|
ばっちり、レコードが挿入できました。
分かってしまえば、何も難しいことはありませんね。
最後に
今回はより実践的な更新処理へ挑戦しつつ、初めてkintone REST APIを利用する方法を紹介しました。
kintone REST APIを利用することで、これまでよりも高度なkintoneカスタマイズができます。
次回から、さらにこのあたりについて解説していこうと思います。
このTipsは、2022年7月版kintoneで動作を確認しています。
デモ環境
デモ環境で実際に動作を確認できます。
https://dev-demo.cybozu.com/k/14/
ログイン情報は cybozu developer network デモ環境で確認してください。