(レコードの一括取得)カーソルを作成する

目次

カーソルを作成する

アプリに対して、レコードを一括で取得するためのカーソルを作成します。

URL

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

HTTPメソッド

POST

必要なアクセス権

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

リクエスト

パラメーター
パラメーター名 必須 説明
app 数値または文字列 必須 アプリID
fields 配列(文字列) 省略可 レスポンスに含めるフィールドコード
省略すると、閲覧権限をもつすべてのフィールドの値が返ります。
query 文字列 省略可 レスポンスに含めるレコードの条件を指定するクエリ文字列
クエリ記法は、 クエリの書き方を参照してください。
ただし、limitoffsetは指定できません。
省略すると、閲覧権限をもつすべてのレコードが対象になります。
size 数値または文字列 省略可 1回のGETリクエストでカーソルから取得するレコード数
1から500までの数値を指定できます。
省略すると、100が設定されます。
リクエストの例
ヘッダー
1
2
3
4
{
  "X-Cybozu-API-Token": "API_TOKEN",
  "Content-Type": "application/json"
}

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

ボディ
1
2
3
4
5
6
{
  "app": 1,
  "fields": ["レコード番号", "作成者", "作成日時"],
  "query": "作成者 in (LOGINUSER()) and 作成日時 = TODAY() order by レコード番号 asc",
  "size": 500
}

レスポンス

プロパティ
プロパティ名 説明
id 文字列 作成したカーソルのカーソルID
totalCount 文字列 取得対象となるレコード数
レスポンスの例
1
2
3
4
{
  "id": "9a9716fe-1394-4677-a1c7-2199a5d28215",
  "totalCount": "123456"
}

サンプルコード

curlを使ったリクエスト
1
2
3
4
5
6
7
8
9
curl -X POST 'https://sample.cybozu.com/k/v1/records/cursor.json' \
  -H 'X-Cybozu-API-Token: API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "app": 1,
    "fields": ["レコード番号", "作成者", "作成日時"],
    "query": "作成者 in (LOGINUSER()) and 作成日時 = TODAY() order by レコード番号 asc",
    "size": 500
  }'
kintone REST APIリクエストを送信するAPIを使ったリクエスト
1
2
3
4
5
6
7
8
const body = {
  app: kintone.app.getId(),
  fields: ['レコード番号', '作成者', '作成日時'],
  query: '作成者 in (LOGINUSER()) and 作成日時 = TODAY() order by レコード番号 asc',
  size: 500
};

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

制限事項

  • 並行して複数のカーソルを作成できません。作成するためのリクエストが実行されている場合には、次のリクエストは待機されます。
  • 有効なカーソルの数は1ドメインあたり10個までです。
    上限に達した場合、次のいずれかが発生するまで新しいカーソルを作成できません。
  • カーソルの有効期限は、カーソルを作成した、またはカーソルからレコードを取得するリクエストを実行した最終時刻から10分です。
  • 絞り込み条件にキーワード検索(like, not like)を含む場合、該当するレコードが100,000件に達した時点で検索を打ち切ります。
    このとき、レスポンスヘッダーには"X-Cybozu-Warning" : "Filter aborted because of too many search results."が追加されます。
  • カーソルの作成は、5分でタイムアウトします。
    タイムアウトした場合、queryを単純なものに変更するか、対象となるレコードの数が少なくなるようなqueryを指定して、再実行してください。