kintone は豊富な API を提供しており、これを活用することでアプリケーションのデータをプログラムから直接操作することが可能です。
特に、REST API は HTTP リクエストを通じて kintone のデータを操作するための強力なツールです。
このページでは、kintone の REST API を使用して、特定のレコードを 複数件取得する方法について詳しく解説します。
レコードを 1 件だけ取得する場合は、エンドポイントが異なります。詳細は以下のページを参照してください。
kintone REST APIを使用して、レコードを1件取得する方法を紹介します。レコードIDを指定して、レコード情報を取得することができます。Node.jsやGAS、Python、curlでのサンプルコードも掲載しています。
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 と、取得したいレコードの条件(query)を指定します。
結果はrecordsプロパティ(配列)を持つオブジェクトで返されます。条件に一致するレコードがない場合は空の配列になります。totalCountにtrueを指定すると、offsetやlimitに関係なく条件に一致する総件数も取得できます。
limit を省略すると 100 件しか取得できません
queryにlimitを指定しない場合、取得されるのは 100 件 です。最大 500 件まで取得するには、limit 500のように明示してください。
(() => {
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('取得するレコードの条件を入力してください');
// キャンセルされた場合は何もしない
if (query === null) {
return event;
}
const appId = kintone.app.getId();
const { records } = await getRecords({ app: appId, query });
console.log(records); // [{ フィールドコード: 値, ... }, ...]
return event;
});
})();
クエリビルダーで条件を組み立てる
query パラメータの記法は独特で、慣れるまでは戸惑いがちです。以下のクエリビルダーで実際に条件を組み立てて、生成されるクエリ文字列を確認してみてください。
レコード取得用クエリビルダー
フィールド・演算子・値を選ぶだけで、records.json に渡せる query パラメータが組み立てられます。
| レコード番号 |
|---|
| 1 |
| 2 |
| 3 |
| 4 |
| 5 |
| 6 |
※ クライアントサイドの簡易エミュレータでフィルタ・ソートしています。実際の kintone サーバーの挙動と完全には一致しません。
kintone REST APIでレコードを絞り込む際に使用するクエリの書き方を詳しく解説します。演算子、関数、オプションの使い方から、実践的なサンプルコードまで紹介します。
大量レコードを取得するときの戦略
records.json の offset には 10,000 件 という上限があります。1 万件を超えるレコードを扱う場合は、カーソル API やシーク法を検討する必要があります。下のシミュレータでレコード件数を増やしながら戦略を切り替えると、コール数の差や上限超過の挙動が一目で分かります。
kintone REST API 一括処理シミュレータ
レコード件数と戦略を選ぶと、API コールの並び・所要時間・上限超過を可視化します。
- 1
/k/v1/records.json500 件·540 msquery: offset 0 limit 500 - 2
/k/v1/records.json500 件·540 msquery: offset 500 limit 500 - 3
/k/v1/records.json500 件·540 msquery: offset 1000 limit 500
kintone のカーソル API を使って 10,000 件を超える大量レコードを安全に取得する方法を解説します。カーソルの作成・取得・削除の基本操作から、全件取得の汎用関数、運用上の注意点まで紹介します。
kintone 以外から利用する場合
kintone の REST API は、Excel や GAS、Node.js など、様々な環境から利用することができます。
REST API を使用することで、kintone 以外の環境から kintone のデータを使用して、アプリケーションを動作させることが可能です。
APIトークンを使用しましょう
kintone 以外の環境から kintone のデータを取得する場合、認証情報をリクエストに含める必要があります。
認証情報にはいくつかの種類がありますが、API トークンを選択することで、セキュリティを確保しつつ、簡単に認証情報を取得することができます。
最も簡単に使用できるのは ID とパスワードを使用した方法ですが、セキュリティ上のリスクがあるため、必要最小限の権限を付与した API トークンを使用することをおすすめします。
Node.js を使用した場合
Node.js から kintone の REST API を使用する場合、ブラウザで JavaScript を実行するのとほとんど同じコードで、HTTP リクエストを送信することができます。
/**
* 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 = async (params) => {
const { app, fields, query, totalCount } = params;
const queryParams = new URLSearchParams({ app });
// 省略された値が "undefined" という文字列として送信されないよう、指定された場合のみ追加する
if (query !== undefined) queryParams.append('query', query);
if (totalCount !== undefined) queryParams.append('totalCount', String(totalCount));
// kintone の GET では、配列は fields[0]=..., fields[1]=... の形式で渡す必要がある
(fields ?? []).forEach((field, i) => queryParams.append(`fields[${i}]`, field));
const response = await fetch(`https://__your_subdomain__.cybozu.com/k/v1/records.json?${queryParams.toString()}`, {
method: 'GET',
headers: {
'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
},
});
// fetch は 4xx/5xx でも例外にならないため、ステータスを確認する
if (!response.ok) {
throw new Error(`レコードの取得に失敗しました: ${response.status} ${await response.text()}`);
}
return response.json();
};
__your_subdomain__の部分と、YOUR_API_TOKENの部分を、それぞれご自身の環境に合わせて変更してください。
引数として設定しても良いですが、関数内で直接設定しても問題ありません。
前述した kintone から利用するコードと異なり、参照先のアプリがゲストスペースである場合は、URL を変更する必要があります。
GAS を使用した場合
Google Apps Script (GAS) から kintone の REST API を使用する場合、UrlFetchAppクラスを使用することで、HTTP リクエストを送信することができます。
/**
* 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 { { records: Record<string, any>[]; totalCount: string | null } } - レコード情報
*/
const getRecords = (params) => {
const { app, fields, query, totalCount } = params;
// fields は fields[0]=..., fields[1]=... の形式で出力する関数を用意する
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.get('fields') or []
query = params.get('query')
totalCount = params.get('totalCount')
url = f'https://__your_subdomain__.cybozu.com/k/v1/records.json'
headers = {
'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
}
params = {
'app': app,
'query': query,
}
# requests は True を "True" として送信するため、小文字の文字列に変換する
if totalCount is not None:
params['totalCount'] = 'true' if totalCount else 'false'
# 配列は fields[0]=..., fields[1]=... の形式で渡す
for i, field in enumerate(fields):
params[f'fields[{i}]'] = field
response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
return response.json()
コマンドラインを使用した場合
コマンドラインから kintone の REST API を使用する場合、curlコマンドを使用して HTTP リクエストを送信することができます。
curl -G 'https://__your_subdomain__.cybozu.com/k/v1/records.json' \
--data-urlencode 'app=1' \
--data-urlencode 'query=レコード番号 > 10 limit 500' \
-H 'X-Cybozu-API-Token: YOUR_API_TOKEN'
制限事項
kintone でレコードを複数件取得する場合、以下の制限事項があります。
- 1 回のリクエストで取得できるレコード数は最大 500 件(
limit省略時は 100 件) - GET リクエストは URL が長すぎると失敗します。条件が長い場合は、
X-HTTP-Method-Override: GETヘッダー付きの POST で、パラメータをリクエストボディに指定してください - query パラメータの offset の上限値は 10,000 件
この制限を意識することなく取得する方法については、以下のページを参照してください。
kintone REST APIには、GET, POST, PUT, DELETEそれぞれに、1度に操作できるレコードの上限が設けられています。今回は上記のレコード上限を気にすることなく、一括でレコードの作成ができる関数をご紹介します。REST APIを使用するたびにkintone.api...と入力したり、エラー処理を作るのは手がかかるため、汎用的な関数やクラスを定義している方も少なくないと思いますが、そういった時に起きてしまいがちなのが、この上限に到達してしまう問題です。