一覧の取得

kintone は豊富な API を提供しており、これを活用することでアプリケーションのデータをプログラムから直接操作することが可能です。

特に、REST API は HTTP リクエストを通じて kintone のデータを操作するための強力なツールです。

このページでは、kintone の REST API を使用して、特定のアプリの一覧（ビュー）の設定情報を取得する方法について解説します。

APIの概要

運用環境に反映する前の設定（プレビュー環境）を取得したい場合は、/k/v1/preview/app/views.jsonを使用します。

kintone から利用する場合

kintone の JavaScript カスタマイズとして REST API を実行する場合、用意されている JavaScript API を使用することで、簡単に REST API を実行することができます。

JavaScript API のkintone.api.urlメソッドを使用することで、実行されるスペースを意識することなく、REST API のエンドポイントを取得することができます。

/**
 * kintone REST APIを使用して、アプリの一覧を取得する
 *
 * @param { { app: string | number; lang?: "default" | "user" | "ja" | "en" | "zh" }  } params
 * @return { Promise<{ views: Record<string, { builtinType?: 'ASSIGNEE'; name: string; id: string; filterCond: string; sort: string; index: string; } & ({ type: 'LIST'; fields: string[]; } | { type: 'CALENDAR'; date: string; title: string; } | { type: 'CUSTOM'; html: string; pager: boolean; device: 'DESKTOP' | 'ANY'; })>; revision: string; }> } - 取得した一覧とリビジョン番号
 */
const getViews = (params) => {
  return kintone.api(kintone.api.url('/k/v1/app/views.json', true), 'GET', params);
};

引数には参照するアプリ ID と、言語設定を指定します。言語設定は省略可能です。

戻り値のviewsには、一覧のIDではなく一覧名をキーとしたオブジェクトが含まれます。一覧の種類（type）には、表形式（LIST）、カレンダー（CALENDAR）、カスタマイズ（CUSTOM）があり、種類ごとに含まれるプロパティが異なります。

サンプルコード

(() => {
  const getViews = (params) => {
    /** 省略 */
  };

  kintone.events.on(['app.record.index.show'], async (event) => {
    const app = kintone.app.getId();
    const { views } = await getViews({ app });

    for (const view of Object.values(views)) {
      console.log(view);
    }

    return event;
  });
})();

(() => {
  const getViews = (params) => {
    /** 省略 */
  };

  kintone.events.on(['app.record.index.show'], async (event) => {
    const app = prompt('取得するアプリのIDを入力してください');
    const { views } = await getViews({ app });

    for (const view of Object.values(views)) {
      console.log(view);
    }

    return event;
  });
})();

kintone 以外から利用する場合

kintone の REST API は、Excel や GAS、Node.js など、様々な環境から利用することができます。

REST API を使用することで、kintone 以外の環境から kintone のデータを使用して、アプリケーションを動作させることが可能です。

Node.js を使用した場合

Node.js から kintone の REST API を使用する場合、ブラウザで JavaScript を実行するのとほとんど同じコードで、HTTP リクエストを送信することができます。

/**
 * kintone REST APIを使用して、アプリの一覧を取得する
 *
 * @param { { app: string | number; lang?: "default" | "user" | "ja" | "en" | "zh" }  } params
 * @return { Promise<{ views: Record<string, { builtinType?: 'ASSIGNEE'; name: string; id: string; filterCond: string; sort: string; index: string; } & ({ type: 'LIST'; fields: string[]; } | { type: 'CALENDAR'; date: string; title: string; } | { type: 'CUSTOM'; html: string; pager: boolean; device: 'DESKTOP' | 'ANY'; })>; revision: string; }> } - 取得した一覧とリビジョン番号
 */
const getViews = async (params) => {
  const url = `https://__your_subdomain__.cybozu.com/k/v1/app/views.json?${new URLSearchParams(params).toString()}`;
  const options = {
    method: 'GET',
    headers: {
      'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
    },
  };
  const response = await fetch(url, options);
  return response.json();
};

__your_subdomain__の部分と、YOUR_API_TOKENの部分を、それぞれご自身の環境に合わせて変更してください。

引数として設定しても良いですが、関数内で直接設定しても問題ありません。

前述した kintone から利用するコードと異なり、参照先のアプリがゲストスペースにある場合は、URL を/k/guest/{スペースID}/v1/app/views.jsonの形式に変更する必要があります。

API トークンには「アプリ管理」権限を付与してください。権限が不足していると、403エラーが返されます。

GAS を使用した場合

Google Apps Script (GAS) から kintone の REST API を使用する場合、UrlFetchAppクラスを使用することで、HTTP リクエストを送信することができます。

/**
 * kintone REST APIを使用して、アプリの一覧を取得する
 *
 * @param { { app: string | number; lang?: "default" | "user" | "ja" | "en" | "zh" }  } params
 * @return { { views: Record<string, { builtinType?: 'ASSIGNEE'; name: string; id: string; filterCond: string; sort: string; index: string; } & ({ type: 'LIST'; fields: string[]; } | { type: 'CALENDAR'; date: string; title: string; } | { type: 'CUSTOM'; html: string; pager: boolean; device: 'DESKTOP' | 'ANY'; })>; revision: string; } } - 取得した一覧とリビジョン番号
 */
const getViews = (params) => {
  const query = new URLSearchParams(params).toString();
  const url = `https://__your_subdomain__.cybozu.com/k/v1/app/views.json?${query}`;
  const options = {
    method: 'GET',
    headers: {
      'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
    },
  };
  const response = UrlFetchApp.fetch(url, options);
  return JSON.parse(response.getContentText());
};