レコードの取得(複数件)

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

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

このページでは、kintone の REST API を使用して、特定のレコードを 複数件取得する方法について詳しく解説します。

レコードを 1 件だけ取得する場合は、エンドポイントが異なります。詳細は以下のページを参照してください。

kintone から利用する場合

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

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

/**
 * kintone REST APIを使用して、指定した条件に一致するレコードを取得する
 *
 * @param { Object } params
 * @param { string | number } params.app - アプリID
 * @param { string[] } params.fields - 取得したいフィールドのフィールドコード
 * @param { string } params.query - レコードを取得する条件
 * @param { boolean } params.totalCount - 取得したレコードの総数を取得するかどうか
 * @return { Promise<{ records: Record<string, any>[]; totalCount: string | null }> } - レコード情報
 */
const getRecords = (params) => {
  const { app, fields, query, totalCount } = params;
  return kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', {
    app,
    fields,
    query,
    totalCount,
  });
};

レコードを 1 件だけ取得する場合は、record.jsonを指定しますが、複数件取得する場合は、records.jsonを指定する点に注意してください。

引数には、取得先のアプリ ID と、取得したいレコードの ID を指定します。

対象レコードが存在する場合は、recordプロパティを持つオブジェクトが返されます。

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

  kintone.events.on(['app.record.detail.show'], async (event) => {
    const appId = kintone.app.getId();
    const query = `関与開始日 > "2024-01-01" and 契約状況 in ("契約中", "契約満了")`; // レコードを取得する条件
    const { records } = await getRecords({ app: appId, query });
    console.log(records); // [{ フィールドコード: 値, ... }, ...]
    return event;
  });
})();

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

  kintone.events.on(['app.record.index.show'], async (event) => {
    const query = prompt('取得するレコードの条件を入力してください');
    const appId = kintone.app.getId();
    const { records } = await getRecords({ app: appId, query });
    console.log(records); // [{ フィールドコード: 値, ... }, ...]
    return event;
  });
})();

クエリビルダーで条件を組み立てる

query パラメータの記法は独特で、慣れるまでは戸惑いがちです。以下のクエリビルダーで実際に条件を組み立てて、生成されるクエリ文字列を確認してみてください。

大量レコードを取得するときの戦略

records.json の offset には 10,000 件 という上限があります。1 万件を超えるレコードを扱う場合は、カーソル API やシーク法を検討する必要があります。下のシミュレータでレコード件数を増やしながら戦略を切り替えると、コール数の差や上限超過の挙動が一目で分かります。

kintone 以外から利用する場合

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

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

Node.js を使用した場合

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

/**
 * kintone REST APIを使用して、IDに一致するレコードを取得する
 * @param { Object } params
 * @param { string | number } params.app - アプリID
 * @param { string[] } params.fields - 取得したいフィールドのフィールドコード
 * @param { string } params.query - レコードを取得する条件
 * @param { boolean } params.totalCount - 取得したレコードの総数を取得するかどうか
 * @return { Promise<{ records: Record<string, any>[]; totalCount: string | null }> } - レコード情報
 */
const getRecords = (params) => {
  const { app, fields, query, totalCount } = params;
  const queryParams = new URLSearchParams({ app, fields, query, totalCount }).toString();
  return fetch(`https://__your_subdomain__.cybozu.com/k/v1/records.json?${queryParams}`, {
    method: 'GET',
    headers: {
      'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
    },
  }).then((res) => res.json());
};

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

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

前述した kintone から利用するコードと異なり、参照先のアプリがゲストスペースである場合は、URL を変更する必要があります。

GAS を使用した場合

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

/**
 * kintone REST APIを使用して、IDに一致するレコードを取得する
 * @param { Object } params
 * @param { string | number } params.app - アプリID
 * @param { string[] } params.fields - 取得したいフィールドのフィールドコード
 * @param { string } params.query - レコードを取得する条件
 * @param { boolean } params.totalCount - 取得したレコードの総数を取得するかどうか
 * @return { Promise<{ records: Record<string, any>[]; totalCount: string | null }> } - レコード情報
 */
const getRecords = (params) => {
  const { app, fields, query, totalCount } = params;
  const queryParams = yourCustomQueryParamsFunction({ app, fields, query, totalCount });
  const url = `https://__your_subdomain__.cybozu.com/k/v1/records.json?${queryParams}`;
  const options = {
    method: 'GET',
    headers: {
      'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
    },
  };
  const response = UrlFetchApp.fetch(url, options);
  return JSON.parse(response.getContentText());
};

GAS では、UrlFetchAppクラスを使用して、HTTP リクエストを送信します。

また、URLSearchParamsクラスが用意されていないため、クエリパラメータを作成する関数を別途用意する必要があります。

python を使用した場合

Python から kintone の REST API を使用する場合、requestsライブラリを使用することで、HTTP リクエストを送信することができます。

import requests

def get_records(params):
    app = params['app']
    fields = params['fields']
    query = params['query']
    totalCount = params['totalCount']
    url = f'https://__your_subdomain__.cybozu.com/k/v1/records.json'
    headers = {
        'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
    }
    params = {
        'app': app,
        'fields': fields,
        'query': query,
        'totalCount': totalCount,
    }
    response = requests.get(url, headers=headers, params=params)
    return response.json()

コマンドラインを使用した場合

コマンドラインから kintone の REST API を使用する場合、curlコマンドを使用して HTTP リクエストを送信することができます。

curl -X GET 'https://__your_subdomain__.cybozu.com/k/v1/records.json?app=1&query=レコード番号 > 10' \
  -H 'X-Cybozu-API-Token: YOUR_API_TOKEN'

制限事項

kintone でレコードを複数件取得する場合、以下の制限事項があります。

• 1 回のリクエストで取得できるレコード数は最大 500 件
• query パラメータの offset の上限値は 10,000 件

この制限を意識することなく取得する方法については、以下のページを参照してください。