カテゴリー内の他の記事

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

(著者:落合 雄一

はじめに

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

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

アプリの準備

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

フィールド名

フィールドタイプ

フィールドコード

閲覧アプリID

数値

閲覧アプリID

閲覧レコード番号

数値

閲覧レコード番号

閲覧者

作成者

閲覧者

閲覧日時

作成日時

閲覧日時

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

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

反映する値の取得

このアプリに格納する値として、以下2つはデータ挿入時に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 のメンバー登録が必要です。画面右上の「サインイン」ボタンよりご登録ください。
デモ環境アカウントとパスワードは、サインイン後にこちらのページでご確認ください。

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

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

Avatar
赤座 久樹

こんにちは。初めてコメントします。

REST API便利ですね!かなり色々と応用できそうです。

 

「閲覧レコード番号」のフィールドコードですが、

冒頭「アプリの準備」の表では「閲覧レコード」

コード内の「params」オブジェクトでは「閲覧レコード番号」

となっており、このままでは値が取れませんでした。

 

アプリのフィールドコードを「閲覧レコード番号」に直してうまくいきましたが、

記事内のフィールドコードもどちらかに統一をお願いしますm(_ _)m

Avatar
cybozu Development team

赤座 久樹様

いつもお世話になっております。
cybozu.com developer network事務局です。

ご報告いただきありがとうございます。

「アプリの準備」の表のフィールドコードが間違っておりました。
申し訳ございません。

表のフィールドコードを「閲覧レコード番号」に修正させていただきました。
今度ともdeveloper networkをよろしくお願い致します。

Avatar
赤座 久樹

ありがとうございました!

Avatar
津田 進

はじめまして

>作成できたら、アプリIDは後で使うので控えておいてください

と、ありますが、アプリIDは、どのタイミングで、どこで確認すればいいのでしょうか?

javascriptで、event.appId を表示する以外の方法があれば、ご教授下さい。

 

Avatar
cybozu Development team

津田進 様

いつもお世話になっております。
cybozu.com developer network事務局です

アプリを作成できましたら、アプリを開いていただいて、
ブラウザのアドレス欄にアプリIDをご確認いただけます。
例、次のMailboxというアプリのIDは113です。

 

Avatar
津田 進

了解です。

ありがとうございました。

 

ちなみに、中国語版のkintoneですね。

Avatar
cybozu Development team

津田進 様

表示言語を切り替えるのを失念しまして、失礼しました。

引き続きよろしくお願いいたします。

Avatar
二宮弘安

WebAPIで、ルックアップ項目を追加する時について質問です。

ルックアップ先にない値をルックアップ元に追加しようとすると以下のエラーになってしまいます。

{

    "code": "GAIA_LO04",

    "id": "---------------",

    "message": "フィールド「□□フィールド」の値「STSP12090」が、ルックアップの参照先のフィールドにないか、またはアプリやフィールドの閲覧権限がありません。"

}

画面上のオペレーションでは、参照されたルックアップ元のデータを消去することは可能ですが、WebAPIのこのケースにおいては回避方法はありませんでしょうか?

よろしくお願いします。

Avatar
cybozu Development team

二宮弘安 様

お世話になっております。cybozu developer network 運営でございます。

どのように「回避」したいかに依るかと思われますが、
ご提示いただいたケースの場合、
- 権限設定などでルックアップの参照先のレコードを削除させないようにする
- ユーザーにエラーを表示し、ルックアップ参照先のレコードがない場合ユーザーにルックアップを自分で入力してもらうなどのエラーハンドリングを考える
- そもそもルックアップ自体をやめ文字列フィールドなどに変更する
などが考えられます。

また、恐れ入りますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
記事から派生した技術的なご質問はcybozu developer コミュニティをご活用ください。

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

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