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

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

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

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

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

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

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

• 閲覧者（作成者）
• 閲覧日時（作成日時）

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

(() => {
  'use strict';
  kintone.events.on('app.record.detail.show', (event) => {
    // アプリIDの取得
    const appId = event.appId;

    // レコード番号の取得
    const recordId = event.recordId;

    alert('appId: ' + appId + ', recordId: ' + recordId);
  });
})();

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

さて、それではいよいよ実際のデータ登録に進みましょう。
これには、kintone REST API（レコード）の 1 件のレコードを登録する APIを使うことになります。
kintone上のJavaScriptでkintone REST APIを利用する手段としては kintone REST API リクエストを送信する APIが用意されていますので、まずはここから説明していきます。

kintone.api(pathOrUrl, method, params, successCallback, failureCallback)

各パラメーターに何を入れるかは、実際利用するkintone REST APIによって変わってきます。
1 件のレコードを登録する APIのドキュメントと見比べながら、それぞれ埋めていきましょう。

引数の説明にもありますが、kintone.api.url()を利用するようにしましょう。
また、kintoneのREST APIではゲストスペース内アプリの場合にパスが変わってしまうので、あとで混乱しないためにも第2引数にtrueを入れるよう習慣化しておくとよいかと思います。
詳しい説明は次のページを確認してください。

• API の URL を取得する API
• ゲストスペース内アプリのレコードを、スペース内アプリに転記

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
    "app": "(アプリのID)",
    "record": {
        "(フィールドコード)": {
            "value": "(フィールド値)"
        },
        "(テーブルのフィールドコード)": {
            "value": [
                {
                    "value": {
                        "(フィールドコード)": {
                            "value": "(フィールド値)"
                        }
                    }
                }
            ]
        }
    }
}

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

(() => {
  'use strict';
  kintone.events.on('app.record.detail.show', (event) => {
    // アプリIDの取得
    const appId = event.appId;
    // レコード番号の取得
    const recordId = event.recordId;
    // リクエストプロパティ(JSON)
    const params = {
      app: 1, // ← 参照ログを格納するアプリのIDに書き換えてください
      record: {
        閲覧アプリID: {value: appId},
        閲覧レコード番号: {value: recordId}
      }
    };

    // kintone REST API リクエスト ～ レコードの登録（POST）
    kintone.api(
      kintone.api.url('/k/v1/record', true), // - pathOrUrl
      'POST', // - method
      params, // - params
      (resp) => { // - callback
        // (特に何もしない)
      },
      (resp) => { // - errback
        // (特に何もしない)
      }
    );
  });
})();

ばっちり、レコードが挿入できました。
分かってしまえば、何も難しいことはありませんね。

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

このTipsは、2022年7月版kintoneで動作を確認しています。

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

ログイン情報は cybozu developer network デモ環境で確認してください。