複数のレコードを取得する

目次

複数のレコードを取得する

クエリで条件を指定して、複数のレコードを取得します。

  • 一度に取得できるレコードは、500件までです。
    取得できるレコード数は、queryパラメーターのlimitで指定します。
    queryパラメーターのlimit
    limitの初期値は、100件です。
  • queryパラメーターのoffsetの上限値は10,000件です。
    queryパラメーターのoffset *1
  • クエリで文字列を検索する場合は単語検索です。詳しくは次のページを参照してください。
    検索キーワード入力時の注意事項 (External link)
  • クエリで検索した結果のレコードが100,000件以上存在するとき、絞り込みは中断されます。
    その場合、レスポンスヘッダーの「X-Cybozu-Warning」に「Filter aborted because of too many search results」が追加されます。

*1 2020年7月定期メンテナンスで、offsetの上限値を10,000件までとする変更を実施しました。
取得したレコードの件数が10,000件を超える可能性のある場合には、運用・適用中のプログラムの確認、および修正対応の検討をお願いします。
詳しくは、次のTipsを参照してください。
offsetの制限値を考慮したkintoneのレコード一括取得について ^

URL

通常のアプリ
https://sample.cybozu.com/k/v1/records.json
ゲストスペースのアプリ
https://sample.cybozu.com/k/guest/GUEST_SPACE_ID/v1/records.json

HTTPメソッド

GET

必要なアクセス権

  • アプリのレコード閲覧権限
  • 値を取得するレコードの閲覧権限
  • 値を取得するフィールドの閲覧権限

リクエスト

パラメーター
パラメーター名 必須 説明
app 数値または文字列 必須 アプリID
fields 文字列の配列 省略可 レスポンスに含めるフィールドコード
省略すると、閲覧権限のあるすべてのフィールドの値が返ります。
リクエストボディでfieldsを指定する場合、指定できるフィールドコードの数は1,000件までです。
クエリ文字列でfieldsを指定する場合、fieldsに指定できる添字は、0から99までです。
query 文字列 省略可 レスポンスに含めるレコードの条件を指定するクエリ文字列
クエリ記法の詳細は次のページを参照してください。
クエリの書き方
省略すると、閲覧権限のあるすべてのレコードを取得します。
totalCount 真偽値または文字列 省略可 queryで指定した条件に一致するレコードの件数を取得かどうか
  • true:件数を取得する
  • false:件数を取得しない
リクエストの例(URLにパラメーターを含める場合)

URLエンコードしたパラメーターをHTTPのクエリ文字列として送信します。

URL

たとえば、APIのクエリ文字列として、次のパラメーターを指定するとします。

1
app=1&query=更新日時 > "2012-02-03T09:00:00+0900" and 更新日時 < "2012-02-03T10:00:00+0900" order by レコード番号 asc limit 10 offset 1&fields[0]=レコード番号&fields[1]=作成日時&fields[2]=ドロップダウン

この場合のURLは、次のようになります。

https://sample.cybozu.com/k/v1/records.json?app=1&query=%e6%9b%b4%e6%96%b0%e6%97%a5%e6%99%82%20%3E%20%222012-02-03T09%3A00%3A00%2B0900%22%20and%20%e6%9b%b4%e6%96%b0%e6%97%a5%e6%99%82%20%3C%20%222012-02-03T10%3A00%3A00%2B0900%22%20order%20by%20%e3%83%ac%e3%82%b3%e3%83%bc%e3%83%89%e7%95%aa%e5%8f%b7%20asc%20limit%2010%20offset%201&fields%5B0%5D=%e3%83%ac%e3%82%b3%e3%83%bc%e3%83%89%e7%95%aa%e5%8f%b7&fields%5B1%5D=%e4%bd%9c%e6%88%90%e6%97%a5%e6%99%82&fields%5B2%5D=%e3%83%89%e3%83%ad%e3%83%83%e3%83%97%e3%83%80%e3%82%a6%e3%83%b3

ヘッダー
1
2
3
{
  "X-Cybozu-API-Token": "API_TOKEN"
}

リクエストヘッダーの詳細は共通仕様を参照してください。
kintone REST APIの共通仕様

リクエストの例(リクエストボディにパラメーターを含める場合)
URL

https://sample.cybozu.com/k/v1/records.json

ヘッダー
1
2
3
4
{
  "X-Cybozu-API-Token": "API_TOKEN",
  "Content-Type": "application/json"
}

リクエストヘッダーの詳細は共通仕様を参照してください。
kintone REST APIの共通仕様

ボディ

クエリの演算子で値を指定するときに必要な"(ダブルクオート)をエスケープをする場合は、\(バックスラッシュ)でエスケープします。
クエリの演算子

1
2
3
4
5
{
  "app": 1,
  "query": "更新日時 > \"2012-02-03T09:00:00+0900\" and 更新日時 < \"2012-02-03T10:00:00+0900\" order by レコード番号 asc limit 10 offset 1",
  "fields": ["レコード番号", "作成日時", "ドロップダウン"]
}

レスポンス

プロパティ
プロパティ名 説明
records 配列(オブジェクト) レコードの一覧
フィールドの形式は次のページを参照してください。
フィールド形式
totalCount 文字列 レコードの件数
リクエストパラメーターのtotalCountに「false」を指定または省略した場合、「null」が返ります。

サンプルコード

curlを使ったリクエスト
1
2
curl -X GET 'https://sample.cybozu.com/k/v1/records.json?app=1&query=%e6%9b%b4%e6%96%b0%e6%97%a5%e6%99%82%20%3E%20%222012-02-03T09%3A00%3A00%2B0900%22%20and%20%e6%9b%b4%e6%96%b0%e6%97%a5%e6%99%82%20%3C%20%222012-02-03T10%3A00%3A00%2B0900%22%20order%20by%20%e3%83%ac%e3%82%b3%e3%83%bc%e3%83%89%e7%95%aa%e5%8f%b7%20asc%20limit%2010%20offset%201&fields%5B0%5D=%e3%83%ac%e3%82%b3%e3%83%bc%e3%83%89%e7%95%aa%e5%8f%b7&fields%5B1%5D=%e4%bd%9c%e6%88%90%e6%97%a5%e6%99%82&fields%5B2%5D=%e3%83%89%e3%83%ad%e3%83%83%e3%83%97%e3%83%80%e3%82%a6%e3%83%b3' \
  -H 'X-Cybozu-API-Token: API_TOKEN'
kintone.api()を使ったリクエスト

kintone.api()の詳細は、次のページを参照してください。
kintone REST APIリクエストを送信する

1
2
3
4
5
6
7
const body = {
  app: kintone.app.getId(),
  query: '更新日時 > "2012-02-03T09:00:00+0900" and 更新日時 < "2012-02-03T10:00:00+0900" order by レコード番号 asc limit 10 offset 1',
  fields: ['レコード番号', '作成日時', 'ドロップダウン']
};

await kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', body);

補足

  • レコードのデータの言語は認証方式によって決まります。

    • APIトークン認証:「Administrator」の表示言語
    • それ以外の認証方式:APIを実行したユーザーの表示言語

    言語設定が「Webブラウザーの設定に従う」の場合、リクエストヘッダーの「Accept-Language」の有無によって、取得する言語が変わります。
    リクエストヘッダー

    • ヘッダーあり:「Accept-Language」ヘッダーで指定した言語
    • ヘッダーなし:cybozu.com共通管理のロケールの設定で設定した言語
      ロケールの設定 (External link)