検索
Close
カテゴリー内の他の記事

レコードの一括取得

作成日
更新日

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 数値又は文字列 省略可 １回の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リクエストを送信する 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リクエストを送信する 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リクエストを送信する 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

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

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

Avatar
真木俊吉

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

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

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

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

Avatar
cybozu Development team

真木俊吉 様

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

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

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

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

Avatar
Yuka_Sawaki

カーソルが削除される条件について、2点質問です。

 

1.

> ・既存のカーソルの1つからすべてのレコードを取得する

上記について、クエリでの条件指定で対象レコードの一部のみ取得した場合も自動で削除されるのでしょうか？

（例：全レコードが100件あり、条件にひっかかるレコードが50件のみだった場合）

 

2.

> ・既存のカーソルを明示的に閉じる

上記について、現在有効なカーソルのidを知る方法はカーソル作成リクエストで返ってきたidのみでしょうか？

有効なカーソルのid一覧を取得するリクエストなどはあるのでしょうか？

Avatar
cybozu Development team

Yuka_Sawaki 様

お世話になっております。
cybozu developer network 運営でございます。

以下回答になります、ご確認お願い致します。

1. について

カーソル作成時のクエリで条件にあたるレコードが100件、（カーソルの移動範囲が100件）
その後、カーソルからレコードを取得する処理で、上記の100件50件しか取得しない場合、（カーソルが50件分しか移動しない場合）
明示的に削除しない限り、カーソルは 有効期限 が過ぎるまで削除されません。

2. について

カーソル id については作成時のレスポンスのみで取得可能です。

Avatar
miyamae yuya

カーソルのクエリについて質問です.

フォームの種類がドロップダウンや文字列(複数行)など,

いくつかのフォームの種類に対して,  query: `order by フィールドコード desc`をすると以下のようなエラーが起きてしまいます.

```

[info] com.cybozu.kintone.client.exception.KintoneAPIException: an error occurred while receiving data
[info] at com.cybozu.kintone.client.connection.Connection.request(Connection.java:187)
[info] at com.cybozu.kintone.client.module.recordCursor.RecordCursor.createCursor(RecordCursor.java:36)

```

 

order by に対しているフォームの種類があるのでしょうか？

 

以下のライブラリを使用しております.

環境
java-sdk: 0.5.0

java 8

 

Avatar
cybozu Development team

miyamae yuya様

お世話になっております。
cybozu developer network 運営でございます。

フォームの種類がドロップダウンや文字列(複数行)など,
いくつかのフォームの種類に対して, query: order by フィールドコード descをすると以下のようなエラーが起きてしまいます.

こちらのエラーについてですが、文字列（複数行）フィールドは、order byに対応しておりません。
order byに対応しているフィールドについては、一覧でソートできるフィールドと同一です。
詳しくはこちらをご覧ください。

また、developer networkの記事内に、クエリのorder byに対応しているフィールドについて記載がなく、
お手数をおかけしてしまい申し訳ございません。
こちらにつきましては、随時修正作業を行っていく予定です。

ご確認のほどよろしくお願いいたします。

Avatar
cybozu Development team

nicole de Japon様

お世話になっております。
cybozu developer network 運営でございます。

以下回答になります、ご確認お願い致します。

1.について
　記事内にも記載がある通り、GET の body に指定する id はカーソルの id です。

2.について
　はい。Promiseを利用して実行することができます。
　当方でも、提示いただいたコードをもとに検証を行い、実行することができました。

　また、コーディングに関する技術的なご質問はcybozu developer コミュニティをぜひご活用ください。

よろしくお願い致します。

Avatar
cybozu Development team

nicole de Japon様

お世話になっております。
cybozu developer network 運営でございます。

コードを確認したところ、for文内のresp.totalCount の指定が間違っているかと思われます。
resp2.totalCount のお間違いではないでしょうか

また、本コメント欄は、記事へのフィードバックを目的としており、サポートの場ではありません。
以後、記事に直接関係のないご質問はcybozu developer コミュニティをご利用ください。

cybozu developer networkでは、動かない？そんな時はデバッグをしてみよう！入門編などの
デバック方法に関する記事も公開しております。
併せてご確認いただければと思います。

よろしくお願いいたします。

cybozu Development teamにより編集されました
Avatar
えりか

カーソルについて質問です。

現在使用しているカーソルの数は取得できるのでしょうか。

また、カーソルAPIでのカーソルから取得できるすべてのレコードを取得すると、そのカーソルは自動的に削除されるとあるのですが、

レコードが取得できなかった場合(0件だった場合)は、カーソルは自動的に削除されないのでしょうか

えりかにより編集されました
Avatar
cybozu Development team

えりか 様

お世話になっております。cybozu developer network 運営でございます。

カーソルの数を取得するAPIはございませんが、10個を超えてカーソルを作成すると、429 (Too Many Requests) とエラーが返ってきますので、既存のカーソルを削除いただくか時間を置いて再実行いただくなどの対応が必要です。
制限事項にあるように、カーソルは最終アクセスから10分で有効でなくなり削除されます。

検索結果が0件だった場合、即時に自動的に削除はされませんが、
前述とおなじく、明示的に削除しない場合、最終リクエスト時刻から10分で削除されます。

よろしくお願い致します。

Avatar
高橋智樹

お世話になっております。
契約しているプランでは「1アプリで1日に実行できるAPIリクエスト数」が
10000回リクエスト可能なのですが、上限を超えてしまった場合、
１日経過する以外で解除する方法はないのでしょうか？

Avatar
cybozu Development team

高橋智樹 様
お世話になっております。cybozu developer network 運営でございます。

１日経過する以外で解除する方法はないのでしょうか？

記載して頂いたとおり、解除することはできません。
定常的に API のリクエスト数が 10,000回を超えるような場合には、サイボウズの API 相談窓口までお問い合わせください。
お問い合わせ方法：https://jp.cybozu.help/general/ja/id/020261.html

ご確認のほど、よろしくお願い致します。

Avatar
LEESEHYUK

お世話になっております。

添付ファイルについてですが、

リクエストのボディのqueryに入れれるのはファイル名のみで、

取得できるのはファイル名（拡張子含まない）が完全一致しているレコードのみでしょうか。

ご確認のほど、よろしくお願いいたします。

Avatar
cybozu Development team

LEESEHYUK 様

お世話になっております。cybozu developer network 運営でございます。

添付ファイルの検索で使える演算子はlike / not likeのみになっており、完全一致ではありません。
詳細は「query」パラメータで利用可能な演算子と関数をご確認ください。

よろしくお願い致します。

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