第9回 kintone REST APIを利用したレコード追加

はじめて kintone をカスタマイズする人が kintone API の基礎知識を学べるよう、チュートリアルの内容を充実させてリニューアルしました。
   リニューアル後のチュートリアルは次のページを参照してください。
   はじめよう kintone API

（著者：落合 雄一）

はじめに

前回、はじめて更新時の処理について扱ってみました！今回は、kintone REST APIを使った追加処理に挑戦してみましょう(^^)

それでは、「各ユーザーがどのアプリのどのレコードを参照したか」を残す参照ログを作成しながらkintone REST APIを学んでいきたいと思います。(^^♪

アプリの準備

参照ログを格納する、下記のようなアプリを用意します。

フィールド名	フィールドタイプ	フィールドコード
閲覧アプリID	数値	閲覧アプリID
閲覧レコード番号	数値	閲覧レコード番号
閲覧者	作成者	閲覧者
閲覧日時	作成日時	閲覧日時

閲覧者を格納するフィールド「閲覧者」にフィールドタイプ: 作成者を利用している事に注目してください。これは、ログを仕掛けた別アプリを閲覧しているユーザー＝APIを通して本アプリへデータ作成するユーザーとなるためです。また同様に「閲覧日時」も同じ理由です。

注意点として、このアプリのアクセス権でEveryoneに追加権限を設定しておく事を忘れずに。作成できたら、アプリIDは後で使うので控えておいてください。φ(￣ー￣ )ﾒﾓﾒﾓ

反映する値の取得

このアプリに格納する値として、以下２つはデータ挿入時にkintoneによって自動で適切な値が差し込まれるため、こちらで何かする事はありません。

• 閲覧者(作成者)
• 閲覧日時(作成日時)

残る「閲覧アプリID」と「閲覧レコード番号」ですが、これらはレコード詳細画面が表示された時のイベント　のeventオブジェクトのプロパティに入っているのでこれを使いましょう。

eventオブジェクトのプロパティ

プロパティ名	型	説明
appId	数値	アプリID
record	オブジェクト	レコード詳細画面が表示された時のデータを保持したレコードオブジェクト※ ※レコードオブジェクトとは、フィールドコードとフィールドの値などのレコードの情報を含むオブジェクトです。 フィールドの値は、フィールドの形式によって異なります。詳細はフィールド形式をご確認ください。
recordId	数値	レコードID
type	文字列	イベントタイプ

eventオブジェクトのプロパティについて忘れてしまった方は、第4回 レコードの値を利用してみよう(詳細画面編) をもう一度読んでみてくださいね(^^)

では、実際に取得出来るか試してみましょう。以下のスクリプトを、(先に作成したアプリではなく)閲覧ログを収集したいアプリに登録して詳細画面を開いてみてください。

上図は、第6回 テーブルの値を利用する で作成したJおじさんのアプリで実行した例です。きちんと思い通りの値が取れている事が確認出来ましたね。

kintone REST APIを利用する

さて、それではいよいよ実際のデータ登録に進みましょう。これには、kintone REST API (レコード)の レコードの登録（POST）を使う事になります。kintone上のJavaScriptでkintone REST APIを利用する手段としては kintone REST 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によって変わってきます。レコードの登録（POST）のレコードの登録（1件） のドキュメントと見比べながら、それぞれ埋めていきましょう。

pathOrUrl

引数の説明にもありますが、kintone.api.urlを利用するようにしましょう。また、kintoneのREST APIではゲストスペース内アプリの場合にパスが変わってしまうので、あとで混乱しないためにも第2引数にtrueを入れるよう習慣化しておくと良いかと思います。詳しい説明は URLを取得する（クエリ文字列無し） や ゲストスペース内アプリのレコードを、スペース内アプリに転記 にありますので、こちらも確認しておいてください。

method

今回利用するAPI(/k/v1/record.json)は、同じURLでもリクエストのHTTPメソッドによって動作が変わる仕組みになっています。

• GET: レコードの取得（1件）
• POST: レコードの登録（1件）
• PUT: レコードの更新（1件）

利用したい動作は参照ログアプリへのデータの挿入なので、この引数には'POST'を指定します。

params

レコードの登録（1件）のリクエストプロパティ を参考にJSON形式でパラメータを作成して渡しましょう。

パラメータ名	指定する値	必須	説明
app	数値又は文字列	必須	アプリの ID を指定します。
record	Object	省略可	レコードの情報(フィールドコードとフィールドの値)をオブジェクトで指定します。 フィールド値の仕様についてはフィールドの形式により異なります。 詳細については フィールド形式をご確認ください。 省略した場合は、全フィールドの値が初期値で登録されます。 存在しないフィールドコードを指定した場合、その部分は無視されます。

リクエストボディの構造

細かい事は出来上がったものを見たほうが良いかも知れませんね。以下、実際に作成したスクリプトです。参照ログを格納するアプリのIDを皆さんが実際に作成したアプリのIDに書き換えて、ログを仕掛けたいアプリ(上の例でいくと、Jおじさんアプリ)に登録してください。登録する先はいくつでも構いません。

ばっちり、レコードが挿入できました。＼(*^▽^*)ノ
分かってしまえば、何も難しい事はありませんね。

最後に

今回はより実践的な更新処理へ挑戦しつつ、はじめてkintone REST APIを利用する方法を紹介しました。kintone REST APIを利用する事で、これまでよりも高度なkintoneカスタマイズが出来るようになります。次回から、さらにこのあたりについて解説していこうと思います。

Let’s kintoneカスタマイズ＼(^o^)／

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

<<第8回 簡単な更新処理に挑戦してみよう | 第10回 kintone REST APIを利用したレコード取得>>

デモ環境

こちらのデモ環境から実際に動作を確認できます。
https://dev-demo.cybozu.com/k/14/

デモ環境の利用は、事前に cybozu developer network のメンバー登録が必要です。画面右上の「サインイン」ボタンよりご登録ください。
デモ環境アカウントとパスワードは、サインイン後にこちらのページでご確認ください。