kintone API ドキュメント

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

目次

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

固定リンクがコピーされました

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

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

*1 2020 年 7 月定期メンテナンスで、offset の上限値を 10,000 件までとする変更を実施しました。
取得したレコードの件数が 10,000 件を超える可能性のある場合には、運用・適用中のプログラムの確認、および修正対応の検討をお願いします。
詳しくは、 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 REST API リクエストを送信する 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) で設定した言語