カテゴリー内の他の記事

レコードの一括取得

フォローする

Index

カーソルの作成

アプリに対して、レコード取得用のカーソルを作成できます。

HTTP メソッド

POST

URI

https://(サブドメイン名).cybozu.com/k/v1/records/cursor.json

ゲストスペース内のアプリの場合

https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/records/cursor.json

必要なアクセス権

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

リクエストパラメータ

パラメータ名 指定する値 必須 説明
app 数値又は文字列 必須 アプリのIDを指定します。
fields 文字列の配列 省略可 レスポンスに含めるフィールドコードを指定します。
省略した場合は、閲覧権限を持つすべてのフィールドの値が返されます。
query 文字列 省略可 レスポンスに含めるレコードの条件を指定するクエリ文字列です。
クエリ文字列内では、レコードの一括取得(クエリで条件を指定) API で使用できる演算子とオプションが使用できます。※
省略した場合は、閲覧権限を持つすべてのレコードが返されます。
※ limit または offset は指定できません。
size 数値又は文字列 省略可 1回のGETリクエストでカーソルから取得するレコード数を指定します。
省略した場合の初期値は100、上限値は500です。

リクエストの例

リクエストヘッダ

POST /k/v1/records/cursor.json HTTP/1.1
Host: example.cybozu.com:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json
  • Content-Type に application/json を指定して下さい。 指定しない場合は JSON が解釈できないため、実行時エラーとなります。

ボディ

レスポンスの例

JavaScriptサンプル

kintone REST API

XMLHttpRequest

カーソルからレコードを取得

カーソルからレコードを取得できます。

HTTP メソッド

GET

URI

https://(サブドメイン名).cybozu.com/k/v1/records/cursor.json

ゲストスペース内のアプリの場合

https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/records/cursor.json

必要なアクセス権

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

リクエストパラメータ

パラメータ名 指定する値 必須 説明
id 文字列 必須 カーソルのIDを指定します。

リクエストの例

リクエストヘッダ

GET /k/v1/records/cursor.json HTTP/1.1
Host: example.cybozu.com:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

ボディ

レスポンスの例

処理が成功すると、レコードの内容がJSON形式で返されます。 ※各フィールドの形式については フィールド形式をご確認ください。

JavaScriptサンプル

kintone REST API

XMLHttpRequest

カーソルの削除

作成したカーソルを削除できます。

HTTP メソッド

DELETE

URI

https://(サブドメイン名).cybozu.com/k/v1/records/cursor.json

ゲストスペース内のアプリの場合

https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/records/cursor.json

必要なアクセス権

なし

リクエストパラメータ

パラメータ名 指定する値 必須 説明
id 文字列 必須 カーソルのIDを指定します。

リクエストの例

リクエストヘッダ

DELETE /k/v1/records/cursor.json HTTP/1.1
Host: example.cybozu.com:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json
  • Content-Type に application/json を指定して下さい。 指定しない場合は JSON が解釈できないため、実行時エラーとなります。

ボディ

レスポンスの例

JavaScriptサンプル

kintone REST API

XMLHttpRequest

制限事項

カーソルの作成 API

  • カーソルの作成は1ドメインあたり同時に1リクエストのみ実行できます。実行中のリクエストがある場合は待機します。
  • 有効なカーソルの数は1ドメイン辺り10です。
    上限に達した場合、次のいずれかが発生するまで新しいカーソルを開くことはできません。
    • 既存のカーソルの1つからすべてのレコードを取得する
    • 既存のカーソルを明示的に閉じる
    • 既存のカーソルの有効期限が切れる
  • カーソルの有効期限は、カーソルの作成 または カーソルからレコードを取得 による最終リクエスト時刻から10分です。
  • 絞り込み条件にキーワード検索 (like, not like) を含む場合、該当するレコードが10万件に達した時点でkintoneは検索を打ち切ります。
    このとき、レスポンスヘッダに "x-cybozu-warning : Filter aborted because of too many search results." が追加されます。
  • カーソルの作成にかけられる時間は5分間です。それ以降はタイムアウトします。
    タイムアウトした場合、クライアントは query をより単純化したり、対象のレコード数が少なくなるように修正して再実行する必要があります。

カーソルからレコードを取得 API

  • カーソルから取得できるレコードはカーソル作成時に取得対象だったレコードです。
    ただし、各フィールドの値はレコード取得時のものになります。
  • カーソル作成後にアクセス権の設定が変更された場合、変更後の設定では絞り込み条件を満たさないはずのレコードが取得される場合があります。
    ただしこの場合でも、閲覧権限がないフィールドの値は見えません。
  • 各フィールドの値はレコード取得時点のものであるため、ログインユーザーの言語設定が変更されると多言語化されたフィールドが影響を受けます。
  • カーソルからレコードを取得する API で next: true が返った次のリクエストの records が空になる場合があります。

関連Tips

記事に関するフィードバック

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

Avatar
真木俊吉

カーソルからすべてのレコードを取得すると、カーソルは自動的に削除されるのですか?

それとも有効期限までは残っていて、明示的にDELETEする必要がありますか?

カーソルから全レコードを取得後に、明示的にDELETEしようとしたところ、

指定したカーソルは存在しないか、既に有効期限が切れています。のエラーが発生しました。

Avatar
cybozu Development team

真木俊吉 様

お世話になっております。
cybozu developer network 事務局です。

「制限事項」に記載があります通り、
カーソルからすべてのレコードを取得すると、カーソルは自動的に削除されます。

> 有効なカーソルの数は1ドメイン辺り10です。
> 上限に達した場合、次のいずれかが発生するまで新しいカーソルを開くことはできません。

> 既存のカーソルの1つからすべてのレコードを取得する
> ・既存のカーソルを明示的に閉じる
> ・既存のカーソルの有効期限が切れるカーソルからすべてのレコードを取得すると、カーソルは自動的に削除されます。

ログインしてコメントを残してください。