kintoneアプリをMonacaから操作する（顧客リストアプリ）

kintone (キントーン) は、業務などで手軽に使えるWebデータベースアプリを提供しています。

簡易的な操作であれば、標準で提供されているビューワーアプリで十分ですが、デバイスの機能を使ったり、こだわったインターフェースを使いたい時には独自のアプリを開発することになります。

今回はkintoneアプリの一つ、顧客リストアプリのデータをMonacaアプリとして呼び出し、操作する手順を解説します。

※ 本記事の中では、Monaca有料プランでのみ利用できる機能を利用しています。

今回作成するプロジェクト

記事で紹介するプロジェクトは、下のプロジェクトインポートリンクから
ご利用のMonacaアカウントへインポートできます。

(https://monaca.mobi/ja/directimport?pid=622aec8ce788859d6a886b6f)

アプリ仕様について

今回は、Framework7をフレームワークとして利用します。

画面は次の通りです。最初に読み込まれるのはログイン画面です。

const routes = [
  // ログイン
  {
    path: '/login',
    name: 'Login',
    componentUrl: './pages/login.html'
  },
  // 顧客一覧画面
  {
    path: '/customers',
    name: 'Customers',
    componentUrl: './pages/customers.html'
  },
  // フォーム画面
  {
    path: '/form',
    name: 'Form',
    componentUrl: './pages/form.html'
  },
  // Default route (404 page). MUST BE THE LAST
  {
    path: '(.*)',
    url: './pages/404.html',
  },
];

kintoneの変数定義

以下の変数が、kintone操作用の変数です。
これは js/app.js の中で定義しています。

KINTONE_DOMAIN、KINTONE_APP_IDはそれぞれ自身のものに書き換えてください。

// kintoneのドメイン
const KINTONE_DOMAIN = 'example.cybozu.com';
// kintoneアプリのID
const KINTONE_APP_ID = '3';

ログイン処理

kintoneでは、最初にID/パスワードによるログインを行います。

ログインについては前回の記事を踏襲しています。
前回の記事は、こちらを参照してください。

(https://press.monaca.io/atsushi/9045)

この時、認証だけを行うAPIはないので、ログイン情報を使って任意のAPI（今回はアプリ情報を取得するAPI）を実行して、結果が返ってくるかどうかで認証の成否を判定しています。

認証が成功すると、一覧画面に遷移します。

// ログインボタンを押した時の処理
const login = async () => {
    // ボタン上にローディングを表示
    load()

    // 入力値を受け取る
    const username = $f7.$el.find('#username').val();
    const password = $f7.$el.find('#password').val();

    // APIリクエスト用のヘッダー文字列作成
    window.AUTH = ${username}:${password};
    try {
        // APIリクエスト
        const res = await getApp({ id: KINTONE_APP_ID });

        // レスポンスで認証情報の正しさを判定
        const text = res.data.appId === KINTONE_APP_ID ? 'ログインしました' : res.message;

        // ボタン上に表示されるローディングを非表示
        unload()

        // 一覧画面へ遷移する
        $f7router.navigate({ name: 'Customers'});
    } catch (e) {
        console.log(e.message);
    }
};

顧客一覧画面

顧客一覧画面では、kintone上のレコードを取得し、一覧形式で表示させます。

右上の更新ボタンを押したタイミングで、kintoneへ問合せてデータを読み込む形にしています。

顧客レコードを複数行表示するため、次に解説する「レコードの一括取得API」を呼出します。

kintoneレコードの一括取得

顧客一覧画面では、顧客レコードを複数行表示するため、次のレコード一括取得APIを呼出します。
(APIの詳細はこちら)

URI	HTTPメソッド
https://(サブドメイン名).cybozu.com/k/v1/records.json	GET

APIを呼び出す際に利用できるパラメータは次のとおりです。

どのアプリかを指定する「app」のみが、必須のパラメータです。

パラメータ名	指定する値	必須	説明
app	数値 or 文字列	○	アプリのID
fields	文字列の配列	x	レスポンスに含めるフィールドコードを指定します。省略時は、閲覧権限を持つすべてのフィールドの値が返されます。
query	文字列	x	レスポンスに含めるレコードの条件を指定するクエリ文字列です。クエリ文字列内では、演算子とオプションが使用できます。省略時は、閲覧権限を持つすべてのレコードが返されます。
totalCount	真偽値 or 文字列	x	「query」パラメータで指定した条件にあてはまるレコードの件数を取得する場合、「true」を指定します。省略時は、レスポンスにはtotalCountの値としてnullが返されます。

顧客データの取得

// kintoneから顧客データを読込む
const getCustomers = (params) => {
  const options = {
    method: 'get',
    params: params,
  };
  return sendRequest('/records.json', options);
}

データの取得ができたら、結果を一覧で表示します。

getCustomersの結果にあるrecordsを描画します。

この時、ユニークキーになるのが $id.value になります。

一覧画面で data-id としてユニークキーを設定した値です。

const showCustomers = (records) => {
    $f7.$el.find('.customers tbody').html(records.map(r => `
      <tr data-id=${r.$id.value}>
        <td>${r.$id.value}</td>
        <td>${r['会社名'].value}</td>
        <td>${r['担当者名'].value}</td>
      </tr>
    `).join(''));
};

一覧画面からの画面遷移

顧客一覧をタップしたら、フォーム画面に遷移します。

一覧画面にて設定したユニークキーを使ってタップされたデータを特定し、
フォーム画面にpropsとして渡しています。

const bindCustomers = (records) => {
    $f7.$el.find('.customers tbody tr').on('click', e => {
      const id = $(e.target).parents('tr').data('id');
      const record = records.find(r => r.$id.value === id);

      $f7router.navigate({
        name: 'Form',
      }, {
        props: {
          record,
        },
      });
    });
  }

フォーム表示

フォーム画面では、顧客一覧画面からレコードデータが送られている場合は、その情報を使います。

新規作成の場合は、Props がないので、空のオブジェクトを定義します。

export default (props, { $f7, $f7router }) => {
  const record = props.record || {};
    // 省略
}

データを画面表示する際には、常にキーの存在チェックをし、キーがある場合には、そのキーの value プロパティを表示します。
下の例は、キー「会社名」の確認をしています。

<input
    type="text"
    id="company"
    placeholder="会社名"
    value="${record['会社名'] ? record['会社名'].value : ''}"
/>

データの登録

データを新規保存、または更新する際には、まずkintoneのフォーマットに合わせたデータを作成します。

const company = $f7.$el.find('#company').val();
const account = $f7.$el.find('#account').val();
const params = {
    '会社名': {
        value: company,
    },
    '担当者名': {
        value: account,
    },
};

次に、kintoneのレコードにおけるユニークキーである $id の有無によって更新と新規作成を分けます。

$idが存在している場合は、既にレコードがkintone上にあるため、更新の処理を行います。

$idが存在しない場合は、まだkintone上にレコードが無いため、新規作成となります。

    let res;
    if (record.$id) {
        // 更新
        res = await updateRecord({
            app: KINTONE_APP_ID,
            id: record.$id.value,
            record: params,
        });
    } else {
        // 新規作成
        res = await addRecord({
            app: KINTONE_APP_ID,
            record: params,
        });
    }

処理の結果は、revisionというデータがあれば保存成功です。

revisionが存在しない場合は、何らかのエラーが発生しています。

const text = res.data.revision ? '保存しました' : res.message;

ここまでで基本的なkintoneのデータ操作は完了です。

データ登録のAPI

上記の説明にて出てきた関数「addRecord」や「updateRecord」は、kintoneのレコード登録/更新APIを呼びだし、処理を実行しています。

新規登録

レコードの新規登録は、次のAPIを利用しています。

APIの詳細については、こちらを確認ください。

メソッド	URL
POST	https://(サブドメイン名).cybozu.com/k/v1/record.json

APIに送信するパラメータは次のとおりです。

パラメータ「app」で、どのアプリを対象に、どのようなデータを新規で登録するかを指定します。

パラメータ名	指定する値	必須	説明
app	数値 or 文字列	○	アプリの ID を指定します。
record	Object		レコードの情報 (フィールドコードとフィールドの値) をオブジェクトで指定します。

更新

レコードの更新は、次のAPIを利用します。

APIの詳細については、こちらを確認ください。

メソッド	URL
PUT	https://(サブドメイン名).cybozu.com/k/v1/record.json

APIに送信するパラメータは、次のとおりです。

新規登録のAPIのパラメータに追加でパラメータ「id」を指定することで、
どのレコードを更新対象とするか指定します。

パラメータ名	指定する値	必須	説明
app	数値 or 文字列	○	アプリの ID を指定します。
id	数値 or 文字列	○	レコードID を指定します。
record	Object		レコードの情報 (フィールドコードとフィールドの値) をオブジェクトで指定します。