こんにちは、kikuです。弊社は福島県本宮市を拠点に、サイボウズのkintoneを活用した業務改善やカスタマイズ開発を行っています。
kintone REST APIの中には、アプリ情報の一括取得が行えるAPIがあります。キントーンに対してカスタマイズを行う中でアプリ情報を一覧で取得したいということがあるかもしれませんが、アプリの数が100個以上の場合は少し注意が必要です。
それは、アプリ情報一括取得APIでの取得件数の最大が100件となっているためです。
この仕様があるために、アプリ情報を全件取得したい場合にはAPIを単純にCallするだけではダメで、全件取得するようにロジックを変更する必要があります。
今回は、アプリ情報の一括取得を行うkintone REST APIを例に、APIで全件取得する方法をご紹介します。
アプリ情報の一括取得のREST APIについて
このREST APIでは、アプリの閲覧権限のあるユーザーが指定した条件にあてはまるアプリの情報を一括取得できます。cyboze developer networkによると、次のような仕様となっています。
■URI
https://(サブドメイン名).cybozu.com/k/v1/apps.json※ゲストスペース内のアプリの場合
https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/apps.json■リクエストパラメータ
パラメータ名 型 必須 説明 ids 配列 アプリID
- 各要素は1以上9223372036854775807以下の整数で数値又は文字列で指定。
- 最大100件。
- nullまたは空配列の場合はパラメータが省略されたものとみなされる。
codes 配列 アプリコード
- 各要素は1文字以上64文字以下で文字列で指定。
- 完全一致検索
- 大文字と小文字を区別
- 最大100件
- nullまたは空配列の場合はパラメータが省略されたものとみなされます
name 文字列 アプリ名またはその一部
- 最大64文字。
- 部分一致検索。
- 大文字と小文字を区別しない。
- 複数の言語でアプリ名を設定している場合は、標準のアプリ名とAPI実行ユーザーの表示言語のアプリ名が検索されます。
- nullまたは空文字列の場合はパラメータが省略されたものとみなされます。
spaceIds 配列 スペースID
- 各要素は1以上9223372036854775807以下の整数で数値又は文字列で指定。
- 最大100件。
- nullまたは空配列の場合はパラメータが省略されたものとみなされます。
limit 数値又は文字列 取得する件数
- 1以上100以下。
- 省略すると100。
offset 数値又は文字列 取得をスキップする件数
- 0以上2147483647以下。
- 省略されたら0。
■取得値（appsの中身）
プロパティ名 型 説明 appId 文字列 アプリID code 文字列 アプリコード
- 未設定の場合は空文字列。
name 文字列 アプリ名
- 言語ごとの名称を設定している場合、APIの実行ユーザーが設定している言語に応じた名称。
description 文字列 アプリの説明
- 未設定の場合は空文字列。言語ごとの名称を設定している場合、APIの実行ユーザーが設定している言語に応じた名称。
spaceId 文字列 スペース内アプリではスペースID。それ以外ではnull。 threadId 文字列 スレッド内アプリではスレッドID。それ以外ではnull。 createdAt 文字列 作成日時 creator オブジェクト 作成者情報 creator.code 文字列 作成者のコード
- 停止／削除／非利用ユーザーの場合は空文字列。
creator.name 文字列
- 停止／削除／非利用ユーザーの場合は空文字列。
modifiedAt 文字列 更新日時 modifier オブジェクト 更新者情報 modifier.code 文字列
- 停止／削除／非利用ユーザーの場合は空文字列。
modifier.name 文字列
- 停止／削除／非利用ユーザーの場合は空文字列。
アプリ情報の一括取得のREST APIを試す方法
ユーザ情報の一括取得APIを手っ取り早く試すには、Chromeを使うことで可能です。
- Chromeでkintoneの画面を開く
- F12ボタンをクリックすると、画面右側にコンソールが表示される
- 以下のコードを貼り付けてEnterボタンを押す
kintone.api(kintone.api.url(‘/k/v1/apps’, true), ‘GET’, {}, function(resp) {
// success
console.log(resp);
}, function(error) {
// error
console.log(error);
});
実際にはこのようなイメージで結果が表示されます。▼をクリックして辿っていくと各取得データを閲覧可能です。
この例だと結果表示欄の部分が「apps: (59)」となっているので、59アプリ取得されています。
参考：Chrome開発者ツール（デベロッパーツール）の便利な使い方
100件以上取得する方法
ユーザ情報の一括取得APIではソートの指定は出来ないため、アプリを作成した順にデータが取得されます。そのため、アプリ数が100件以上登録されているような場合、単純に上記のように呼び出しただけでは101個目以降のアプリ情報を取得することが出来ません（APIの仕様として、「一度に取得できるアプリ数は最大で100件」という制限があります。）。101個以上取得したい場合は、パラメータのlimitやoffsetを変えて取得する必要があります。
とはいえ1からロジックを作るのも面倒なため、サンプルコードをご紹介します。以下のコードは条件無しでアプリ情報（レスポンス内のapps）を全件取得するJavaScriptです。これに少し手を変えれば、条件指定もした形で全件取得が出来るようにもなります。
var fetchAllApps = function (opt_offset, opt_limit, opt_records) {
var offset = opt_offset || 0;
var limit = opt_limit || 100;
var allRecords = opt_records || [];
var params = {
limit: limit
, offset: offset
};
return kintone.api(kintone.api.url(‘/k/v1/apps’, true), ‘GET’, params).then(function(resp) {
allRecords = allRecords.concat(resp.apps);
if (resp.apps.length === limit) {
return fetchAllApps(offset + limit, limit, allRecords);
}
return allRecords;
});
};
fetchAllApps().then(function(apps) {
console.log(apps);
});
Chrome開発者ツール（デベロッパーツール）で上記をコピペして試していただくと、100件以上取得されているかと思います。
ここでの例はアプリの一覧ですが、他にもユーザ一覧（ユーザエクスポートAPI）、グループ一覧（グループエクスポートAPI）、組織一覧（組織えくすぽイーとAPI）などでも応用が効きますので、必要になった際は試してみてください。
まとめ
kintone REST APIの中で複数件のデータを取得するようなAPIは、今回紹介したもの以外でもデータ取得時の上限件数が決められているため、利用時は注意が必要です。
APIを使用してデータを取得する際は上限があることを意識し、上限を超えて取得したい場合は処理を考慮する必要があります。是非参考にしてみてください。
