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

著者名: 落合 雄一 (External link)

目次

information

初めて 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 回 レコードの値を利用してみよう(詳細画面編) をもう一度読んでみてくださいね。

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

 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 を利用する

さて、それではいよいよ実際のデータ登録に進みましょう。
これには、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 省略可 レコードの情報(フィールドコードとフィールドの値)をオブジェクトで指定します。
フィールド値の仕様についてはフィールドの形式により異なります。
詳細については フィールド形式 を確認してください。
省略した場合は、全フィールドの値が初期値で登録されます。
存在しないフィールドコードを指定した場合、その部分は無視されます。

リクエストボディの構造

 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 カスタマイズができます。
次回から、さらにこのあたりについて解説していこうと思います。

information

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

デモ環境

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

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